feat: standardize DeerFlow offline deployment

2026-08-27 22:06:43 +08:00
1 parent 1764d0d5f2
commit d9a94245fc
@@ -0,0 +1,218 @@
+# DeerFlow 纯离线标准发版与部署
+
+本文定义本仓库后续唯一的 Linux AMD64 离线发版方式。每次发版都必须从最新
+`master` 构建，使用
+`deploy/linux-docker-offline-deerflow-only/build-release.sh`，最终包只包含
+DeerFlow 后端和前端两张镜像，不包含 WeKnora 服务或镜像。
+
+## 1. 标准能力基线
+
+标准离线包必须同时具备以下能力：
+
+- `config/deploy.env` 是唯一需要人工修改的配置源；生成文件不得手工修改。
+- MySQL 使用 SQLAlchemy 异步 URL `mysql+aiomysql://`。
+- 基础兼容版本为 `aiomysql 0.3.2`、`PyMySQL 1.2.0`、
+  `SQLAlchemy 2.0.51`。
+- `deploy.env` 支持 1～20 个模型；编号为 1 的模型是默认模型。
+- `source/wheelhouse` 支持完全离线增加 Python 依赖，安装结果保存在 Docker
+  named volume 中。
+- 后端镜像内置 DOC/DOCX、XLS/XLSX、PPT/PPTX、PDF 处理能力，以及
+  LibreOffice、Pandoc 和中文字体。
+- `OFFLINE_INSTALL.sh --stop` 只停止容器，不删除已加载镜像、数据目录或
+  named volume。
+- `OFFLINE_INSTALL.sh --restart` 不重新 load 镜像；它重新渲染配置、检测
+  wheelhouse、校验源码并重建容器，使覆盖后的前后端源码生效。
+- 启动脚本兼容 `docker-compose` 和 `docker compose`。
+
+## 2. 仓库中的标准目录
+
+| 路径 | 用途 |
+|---|---|
+| `deploy/linux-docker-offline-deerflow-only/` | 标准构建脚本、运行模板、测试和交付文档 |
+| `deploy/linux-docker-offline/Dockerfile.backend` | 后端基础镜像构建文件 |
+| `deploy/linux-docker-offline/Dockerfile.frontend` | 前端基础镜像构建文件 |
+| `deploy/linux-docker-offline/sanitize_release_sources.py` | 发布源码清理器 |
+| `offline-backend-20260512/wheelhouse/` | 随包携带的 Linux AMD64 / Python 3.12 基础 wheel |
+| `offline-backend-20260512/backend/` | 后端源码 |
+| `frontend-web/` | 前端源码 |
+
+不要使用历史的 DeerFlow + WeKnora 全量部署模板发本项目的标准包。
+
+## 3. 每次发版前更新源码
+
+发版工作区必须没有未提交的业务源码修改。未跟踪的本地构建产物不得混入包中。
+
+```bash
+git switch master
+git fetch origin master
+git merge --ff-only origin/master
+git status --short --branch
+git log -1 --format='%H %ad %s' --date=iso-strict
+```
+
+必须记录最终提交的完整 SHA。构建服务器如果使用不带 `.git` 的源码快照，应通过
+`DEERFLOW_COMMIT_OVERRIDE` 写入同一个 SHA。
+
+## 4. wheelhouse 维护
+
+基础 wheel 位于 `offline-backend-20260512/wheelhouse/`。最终包构建时会把它们
+复制到 `source/wheelhouse/`，并保留运行模板中的 `requirements.txt` 和说明文件。
+
+增加依赖时：
+
+1. 下载与 Linux AMD64、Python 3.12 匹配的 wheel，以及它的全部传递依赖。
+2. 把 wheel 放入 `offline-backend-20260512/wheelhouse/`。
+3. 在
+   `deploy/linux-docker-offline-deerflow-only/release-template/source/wheelhouse/requirements.txt`
+   中加入精确版本，例如 `some-package==1.2.3`。
+4. 重新生成并核对 `offline-backend-20260512/wheelhouse/SHA256SUMS`。
+5. 运行发布渲染测试，再构建完整包。
+
+不能放源码包、Windows wheel、macOS wheel，不能只放顶层依赖而遗漏传递依赖。
+
+部署完成后临时增加依赖时，也可以直接把 wheel 放进已解压交付目录的
+`source/wheelhouse/`，更新其中的 `requirements.txt`，然后执行：
+
+```bash
+./OFFLINE_INSTALL.sh --restart
+```
+
+安装器按 `requirements.txt + wheel 文件` 的哈希判断是否需要重新安装，全程使用
+`--no-index`，不会访问互联网。
+
+## 5. 构建标准完整包
+
+推荐在联网的 Linux AMD64 Docker 构建服务器执行。以下示例把构建工作区和输出
+放在 `/opt/codex-build`，不会修改现网部署目录：
+
+```bash
+RELEASE_STAMP="$(date +%Y%m%d-%H%M%S)"
+COMMIT_SHA="$(git rev-parse HEAD)"
+SHORT_SHA="$(git rev-parse --short=8 HEAD)"
+BUILD_ROOT="/opt/codex-build/deerflow-full-${RELEASE_STAMP}-${SHORT_SHA}"
+
+RELEASE_STAMP="$RELEASE_STAMP" \
+DEERFLOW_COMMIT_OVERRIDE="$COMMIT_SHA" \
+DEERFLOW_DIRTY_OVERRIDE=false \
+bash deploy/linux-docker-offline-deerflow-only/build-release.sh \
+  "$(pwd)" "$BUILD_ROOT"
+```
+
+不要设置 `DEERFLOW_FRONTEND_RUNTIME_BASE` 来复用旧前端镜像，除非本次只修改
+`runtime-config.js`。从新 `master` 正式发版时必须从当前前端源码完整构建。
+
+输出文件为：
+
+```text
+${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz
+${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz.sha256
+```
+
+## 6. 发版前强制校验
+
+```bash
+python3 -m py_compile \
+  deploy/linux-docker-offline-deerflow-only/release-template/scripts/render_runtime.py \
+  deploy/linux-docker-offline-deerflow-only/release-template/scripts/preflight_mysql.py \
+  deploy/linux-docker-offline-deerflow-only/release-template/scripts/install_wheelhouse.py
+
+python3 deploy/linux-docker-offline-deerflow-only/test_release_renderer.py "$(pwd)"
+bash -n deploy/linux-docker-offline-deerflow-only/build-release.sh
+
+cd "${BUILD_ROOT}/dist"
+sha256sum -c "deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz.sha256"
+gzip -t "deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz"
+```
+
+还必须确认：
+
+- `images/deerflow-image-list.txt` 恰好只有 DeerFlow 后端、前端两行。
+- `VERSION.json` 的提交 SHA 与本次 `master` 一致。
+- 包含 `source/wheelhouse`、`scripts/install_wheelhouse.py` 和第 13 章文档。
+- 后端镜像能导入 `aiomysql`、`PyMySQL`、`SQLAlchemy`。
+- 后端镜像 Office 自检输出 `OFFICE_RUNTIME_SELF_CHECK=PASS`。
+- 配置渲染后数据库驱动为 `mysql+aiomysql`。
+
+## 7. 新机器完全离线部署
+
+把 `.tar.gz` 和 `.sha256` 一起复制到目标服务器后执行：
+
+```bash
+sha256sum -c deerflow-linux-amd64-offline-*.tar.gz.sha256
+tar -xzf deerflow-linux-amd64-offline-*.tar.gz
+cd deerflow-linux-amd64-offline-*
+cp config/deploy.env.example config/deploy.env
+vi config/deploy.env
+./OFFLINE_INSTALL.sh --start
+```
+
+至少修改：
+
+- `PUBLIC_HOST`、前后端端口；
+- MySQL 地址、端口、数据库名、用户名、密码；
+- `DEERFLOW_MODEL_COUNT`；
+- 每个 `DEERFLOW_MODEL_N_*` 模型块；
+- 实际需要启用的搜索、认证和外部业务接口配置。
+
+禁止直接修改 `data/generated/compose.env`、生成后的 `config.yaml` 或前端
+`runtime-config.js`；它们会在下次启动或重启时被 `deploy.env` 重新生成。
+
+常用命令：
+
+```bash
+./OFFLINE_INSTALL.sh --start
+./OFFLINE_INSTALL.sh --restart
+./OFFLINE_INSTALL.sh --stop
+./OFFLINE_INSTALL.sh --status
+```
+
+## 8. 只替换源码的更新方式
+
+后端可以覆盖交付目录中的：
+
+```text
+source/backend/app/
+source/backend/packages/
+source/backend/tests/
+```
+
+前端先在构建机执行 `pnpm build`，再覆盖：
+
+```text
+source/frontend/dist/
+```
+
+覆盖完成后只执行：
+
+```bash
+./OFFLINE_INSTALL.sh --restart
+```
+
+如果 Python 依赖或系统依赖发生变化，不能只替换源码：Python wheel 应同步更新
+`source/wheelhouse`；LibreOffice、Pandoc、字体或系统库变化必须重新构建后端镜像并
+发布新的完整包。
+
+## 9. 数据、停止与回退
+
+- `--stop` 不删除镜像、数据或依赖 volume。
+- 业务数据和生成配置保存在交付目录的 `data/`，升级前必须整体备份。
+- 新版本应解压到新的版本目录，不要直接覆盖旧版本目录。
+- 回退时停止新目录，在旧目录执行 `./OFFLINE_INSTALL.sh --start`。
+- 不执行 `docker compose down -v`，除非明确要销毁数据并已经完成备份。
+
+服务器交付目录建议统一使用 `/opt/deerflow-offline-delivery/`；至少保留当前版本和
+上一个已验证版本，并保留各自的 SHA256 文件。
+
+## 10. Git 提交流程
+
+部署逻辑变化必须同时更新本文件及交付包内对应文档。提交前执行：
+
+```bash
+git status --short
+git diff --check
+python3 deploy/linux-docker-offline-deerflow-only/test_release_renderer.py "$(pwd)"
+```
+
+禁止提交真实 `deploy.env`、数据库密码、模型 API Key、运行数据、生成配置、
+Docker 镜像 tar 或最终离线 `.tar.gz`。仓库中的 `deploy.env` 只能包含明确的假地址
+和示例凭据。