Files
deerflow-code/docs/DeerFlow纯离线标准发版与部署.md
T

8.1 KiB
Raw Blame History

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. 每次发版前更新源码

发版工作区必须没有未提交的业务源码修改。未跟踪的本地构建产物不得混入包中。

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,然后执行:

./OFFLINE_INSTALL.sh --restart

安装器按 requirements.txt + wheel 文件 的哈希判断是否需要重新安装,全程使用 --no-index,不会访问互联网。

5. 构建标准完整包

推荐在联网的 Linux AMD64 Docker 构建服务器执行。以下示例把构建工作区和输出 放在 /opt/codex-build,不会修改现网部署目录:

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 正式发版时必须从当前前端源码完整构建。

输出文件为:

${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz
${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz.sha256

6. 发版前强制校验

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 一起复制到目标服务器后执行:

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 重新生成。

常用命令:

./OFFLINE_INSTALL.sh --start
./OFFLINE_INSTALL.sh --restart
./OFFLINE_INSTALL.sh --stop
./OFFLINE_INSTALL.sh --status

8. 只替换源码的更新方式

后端可以覆盖交付目录中的:

source/backend/app/
source/backend/packages/
source/backend/tests/

前端先在构建机执行 pnpm build,再覆盖:

source/frontend/dist/

覆盖完成后只执行:

./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 提交流程

部署逻辑变化必须同时更新本文件及交付包内对应文档。提交前执行:

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 只能包含明确的假地址 和示例凭据。