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

142 lines
6.3 KiB
Markdown

# 09 后续增量更新发版手册
本文约定以当前完整离线包作为“基线包”。基线只安装一次;后续常规版本发布为 `deerflow-update-<基线>-to-<目标版本>.tar.gz`,不再重复制作并传输整套前后端基础包。
如果日常更新仅为前后端源码,优先使用 `11-只替换前后端源码.md` 的源码覆盖包。源码覆盖包不执行 `docker save`,因此不会重复携带基础镜像层;本文的通用镜像增量机制保留给依赖、Compose 或控制文件变化。
## 一、哪些内容需要重新打包
| 变更内容 | 增量包包含内容 | 不需要重复包含 |
|---|---|---|
| 仅文档、Compose、渲染脚本 | `payload/` 文件 | 任意 Docker 镜像 |
| 仅技能、命名智能体 | 经审查的增量文件和说明 | 前后端镜像;不得覆盖用户 custom 数据 |
| 仅前端源码 | 新前端镜像 | 后端镜像、数据库、数据卷 |
| 仅后端源码,依赖清单未变 | 新后端代码镜像 | 前端镜像、数据库、数据卷 |
| Python/系统依赖或基础镜像变化 | 新后端完整镜像 | 前端镜像及整套基线目录 |
| 前后端都变化 | 两个新镜像 | 配置、历史数据和旧镜像 |
判断后端依赖是否变化时,至少比较:
```text
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
```
只要其中任一文件变化,就按“后端依赖变化”构建,禁止把新代码强行覆盖到旧依赖镜像。
## 二、增量包固定结构
```text
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` 示例:
```dotenv
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. 只导出发生变化的镜像。例如仅后端变化:
```bash
docker image inspect <新后端镜像>
docker save <新后端镜像> | gzip -1 > images/update-images-linux-amd64.tar.gz
```
4. 在 `payload/` 放入新的 `VERSION.json`、两行镜像清单和必要控制文件。严禁放入下列路径:
```text
config/deploy.env
data/
agents-skills/deerflow-agents/ 中的用户智能体
agents-skills/deerflow-skills/custom/
agents-skills/deerflow-knowledge/
```
5. 如果新增 `deploy.env` 配置项,只更新 `config/deploy.env.example` 或提供 `config/deploy.env.additions.example`,并在发版说明中写明;更新脚本永远不会自动覆盖真实 `deploy.env`。
6. 生成包内校验:
```bash
find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
```
7. 打包并生成外层校验:
```bash
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
```
8. 在无外网环境至少验证:外层校验、包内校验、镜像 `docker load`、`linux/amd64` 架构、Office 自检、配置渲染以及旧镜像仍存在。
说明:Docker 标准 `save/load` 会携带目标镜像需要的层;依赖变化时后端增量包仍可能较大,但它不再重复包含未变化的前端镜像、配置目录和整套基线包。纯控制文件或技能更新可以非常小。
## 四、部署机应用步骤
```bash
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`。
如果希望先应用、人工检查后再启动:
```bash
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` 更新包或交付新的完整基线。
控制文件回退命令:
```bash
sudo ./UPDATE_INSTALL.sh --rollback \
/当前部署目录/data/updates/backups/<A_before_B_时间>
```
`--stop` 和增量更新都保留旧镜像,因此正常回退无需再次 `docker load`。数据库回退不由脚本自动完成:每次涉及表结构或数据迁移的发版,都必须提供迁移说明、升级前备份和明确的回退兼容结论。
## 六、每次发版必须记录
- 基线版本、目标版本和源码 commit。
- 新旧前后端镜像标签、镜像 ID、架构和 SHA256。
- 是否修改依赖、`deploy.env` 字段、数据库结构、Compose 或数据目录。
- 本次包含的技能/智能体文件及覆盖策略。
- 升级命令、验证结果、回退命令和数据库回退要求。