8.1 KiB
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 和说明文件。
增加依赖时:
- 下载与 Linux AMD64、Python 3.12 匹配的 wheel,以及它的全部传递依赖。
- 把 wheel 放入
offline-backend-20260512/wheelhouse/。 - 在
deploy/linux-docker-offline-deerflow-only/release-template/source/wheelhouse/requirements.txt中加入精确版本,例如some-package==1.2.3。 - 重新生成并核对
offline-backend-20260512/wheelhouse/SHA256SUMS。 - 运行发布渲染测试,再构建完整包。
不能放源码包、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 只能包含明确的假地址
和示例凭据。