142 lines
6.3 KiB
Markdown
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 或数据目录。
|
|
- 本次包含的技能/智能体文件及覆盖策略。
|
|
- 升级命令、验证结果、回退命令和数据库回退要求。
|