Files
deerflow-code/deploy/linux-docker-offline-deerflow-only/docs/09-后续增量更新发版手册.md
T

6.3 KiB

09 后续增量更新发版手册

本文约定以当前完整离线包作为“基线包”。基线只安装一次;后续常规版本发布为 deerflow-update-<基线>-to-<目标版本>.tar.gz,不再重复制作并传输整套前后端基础包。

如果日常更新仅为前后端源码,优先使用 11-只替换前后端源码.md 的源码覆盖包。源码覆盖包不执行 docker save,因此不会重复携带基础镜像层;本文的通用镜像增量机制保留给依赖、Compose 或控制文件变化。

一、哪些内容需要重新打包

变更内容 增量包包含内容 不需要重复包含
仅文档、Compose、渲染脚本 payload/ 文件 任意 Docker 镜像
仅技能、命名智能体 经审查的增量文件和说明 前后端镜像;不得覆盖用户 custom 数据
仅前端源码 新前端镜像 后端镜像、数据库、数据卷
仅后端源码,依赖清单未变 新后端代码镜像 前端镜像、数据库、数据卷
Python/系统依赖或基础镜像变化 新后端完整镜像 前端镜像及整套基线目录
前后端都变化 两个新镜像 配置、历史数据和旧镜像

判断后端依赖是否变化时,至少比较:

offline-backend-20260512/backend/pyproject.toml
offline-backend-20260512/backend/uv.lock
offline-backend-20260512/backend/requirements-offline.txt
offline-backend-20260512/backend/packages/harness/pyproject.toml
deploy/linux-docker-offline/Dockerfile.backend

只要其中任一文件变化,就按“后端依赖变化”构建,禁止把新代码强行覆盖到旧依赖镜像。

二、增量包固定结构

deerflow-update-<base>-to-<target>/
├── UPDATE_MANIFEST.env
├── SHA256SUMS
├── images/
│   └── update-images-linux-amd64.tar.gz   # 没有镜像变化时可省略
└── payload/
    ├── VERSION.json
    ├── images/deerflow-image-list.txt
    ├── OFFLINE_INSTALL.sh                 # 有变化才放
    ├── UPDATE_INSTALL.sh                  # 有变化才放
    ├── compose/                           # 有变化才放
    ├── scripts/                           # 有变化才放
    ├── config/deerflow/                   # 模板变化才放
    ├── config/frontend/                   # 模板变化才放
    └── docs/                              # 发版说明和迁移说明

UPDATE_MANIFEST.env 示例:

FORMAT_VERSION=1
BASE_RELEASE=deerflow-linux-amd64-offline-20260826-xxxxxx
TARGET_RELEASE=deerflow-linux-amd64-offline-20260915-xxxxxx
TARGET_BACKEND_IMAGE=cmzs/deerflow-backend-offline:20260915-xxxxxx-abcdef12
TARGET_FRONTEND_IMAGE=cmzs/deerflow-frontend-offline:20260826-xxxxxx-b2c60bb2

即使某一端镜像没有变化,目标清单也必须写出它当前继续使用的完整标签。payload/VERSION.json 与 payload/images/deerflow-image-list.txt 必须使用同一组标签。

三、发版机制作步骤

  1. 固定源码 commit,记录 git rev-parse HEAD,确认不误带未提交文件。
  2. 对照上表判断变更组件;依赖变化时重建完整后端镜像,源码变化且依赖完全一致时可以使用代码刷新 Dockerfile。
  3. 只导出发生变化的镜像。例如仅后端变化:
docker image inspect <新后端镜像>
docker save <新后端镜像> | gzip -1 > images/update-images-linux-amd64.tar.gz
  1. 在 payload/ 放入新的 VERSION.json、两行镜像清单和必要控制文件。严禁放入下列路径:
config/deploy.env
data/
agents-skills/deerflow-agents/ 中的用户智能体
agents-skills/deerflow-skills/custom/
agents-skills/deerflow-knowledge/
  1. 如果新增 deploy.env 配置项,只更新 config/deploy.env.example 或提供 config/deploy.env.additions.example,并在发版说明中写明;更新脚本永远不会自动覆盖真实 deploy.env。
  2. 生成包内校验:
find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
  1. 打包并生成外层校验:
tar -czf deerflow-update-<base>-to-<target>.tar.gz deerflow-update-<base>-to-<target>/
sha256sum deerflow-update-<base>-to-<target>.tar.gz \
  > deerflow-update-<base>-to-<target>.tar.gz.sha256
  1. 在无外网环境至少验证:外层校验、包内校验、镜像 docker load、linux/amd64 架构、Office 自检、配置渲染以及旧镜像仍存在。

说明:Docker 标准 save/load 会携带目标镜像需要的层;依赖变化时后端增量包仍可能较大,但它不再重复包含未变化的前端镜像、配置目录和整套基线包。纯控制文件或技能更新可以非常小。

四、部署机应用步骤

sha256sum -c deerflow-update-*.tar.gz.sha256
tar -xzf deerflow-update-*.tar.gz

cd /当前DeerFlow基线部署目录
sudo ./UPDATE_INSTALL.sh --apply /增量包解压目录

脚本顺序为:校验基线版本和 SHA256 → 备份控制文件 → docker-compose stop → 加载变更镜像 → 应用白名单文件 → 使用原 deploy.env 重新渲染并启动。它不执行 down、rmi 或 volume rm。

如果希望先应用、人工检查后再启动:

sudo ./UPDATE_INSTALL.sh --apply /增量包解压目录 --no-start
sudo ./OFFLINE_INSTALL.sh --office-check
sudo ./OFFLINE_INSTALL.sh --start

五、回退与版本链

每个增量包只允许从清单指定的 BASE_RELEASE 应用,不能跳版本。连续升级必须按顺序执行:A → B → C。如果要从 A 直接到 C,应另外制作 A → C 更新包或交付新的完整基线。

控制文件回退命令:

sudo ./UPDATE_INSTALL.sh --rollback \
  /当前部署目录/data/updates/backups/<A_before_B_时间>

--stop 和增量更新都保留旧镜像,因此正常回退无需再次 docker load。数据库回退不由脚本自动完成:每次涉及表结构或数据迁移的发版,都必须提供迁移说明、升级前备份和明确的回退兼容结论。

六、每次发版必须记录

  • 基线版本、目标版本和源码 commit。
  • 新旧前后端镜像标签、镜像 ID、架构和 SHA256。
  • 是否修改依赖、deploy.env 字段、数据库结构、Compose 或数据目录。
  • 本次包含的技能/智能体文件及覆盖策略。
  • 升级命令、验证结果、回退命令和数据库回退要求。