feat: standardize DeerFlow offline deployment

This commit is contained in:
吉鑫升 committed 2026-08-27 22:06:43 +08:00
1 parent 1764d0d5f2
commit d9a94245fc
37 files changed
+3761 -2

No files matched your search

@@ -0,0 +1,45 @@
# 01 部署前准备
## 服务器要求
- Linux x86_64/amd64。
- Docker Engine 和独立命令 `docker-compose` 已安装且运行正常;脚本优先使用它,并兼容 Compose v2 插件作为回退。
- 建议至少 8 核 CPU、16 GiB 内存、20 GiB 可用磁盘;镜像加载期间需要同时容纳压缩包、解压目录和 Docker 镜像层。
- 可访问外部 MySQL 8.x;部署账号需要连接、建库和建表权限。
- 可从 Docker 容器访问 OpenAI 兼容的 DeerFlow 对话模型接口。
目标机部署过程不需要访问互联网、镜像仓库、npm 或 pip。`PUBLIC_HOST` 对应的前端和后端端口需要在防火墙放行。
本包不包含 WeKnora 以及其 PostgreSQL、Redis、DocReader、独立远程 Sandbox 镜像,也不包含模型权重。默认本地沙箱位于 DeerFlow 后端容器内,Office/PDF 依赖已经随该镜像离线交付。
## 部署前检查
```bash
uname -m # 应为 x86_64
docker version
docker-compose version # 目标服务器使用此命令
docker info
df -h
```
还需要系统命令:`bash`、`tar`、`gzip`、`sha256sum`、`curl`。部署用户可以直接使用 Docker;否则命令前加 `sudo`。
准备并确认以下网络方向:
- 浏览器 → `FRONTEND_PORT`。
- 浏览器 → `BACKEND_PORT`(前端运行时会直连 Gateway)。
- DeerFlow 后端容器 → 外部 MySQL。
- DeerFlow 后端容器 → OpenAI 兼容模型接口。
- 如果启用 Tavily、Serper 或业务接口,还需按实际调用方向访问相应地址。
同一服务器上的服务不能从容器里使用 `127.0.0.1` 访问宿主机。应使用宿主机内网 IP;Docker 支持 `host-gateway` 时也可使用 `host.docker.internal`。
## 文件校验
把压缩包和同名 `.sha256` 放在同一目录:
```bash
sha256sum -c deerflow-linux-amd64-offline-*.tar.gz.sha256
```
显示 `OK` 后再解压。校验失败不要继续部署,应重新传输文件。
@@ -0,0 +1,86 @@
# 02 deploy.env 配置说明
唯一人工配置源:
```text
config/deploy.env
```
`data/generated/` 下的 Compose 环境、DeerFlow `config.yaml` 和前端 `runtime-config.js` 每次启动都会自动生成,不要修改。
必须修改:
```dotenv
PUBLIC_HOST=10.10.10.10
FRONTEND_PORT=5174
BACKEND_PORT=8001
MYSQL_HOST=10.10.10.20
MYSQL_PORT=3306
MYSQL_DATABASE=deerflow
MYSQL_USER=deerflow
MYSQL_PASSWORD=your-real-password
DEERFLOW_MODEL_COUNT=2
DEERFLOW_MODEL_1_NAME=qwen3-32b
DEERFLOW_MODEL_1_DISPLAY_NAME=通用模型
DEERFLOW_MODEL_1_MODEL=qwen3-32b
DEERFLOW_MODEL_1_BASE_URL=http://10.10.10.25:8000/v1
DEERFLOW_MODEL_1_API_KEY=your-real-key-1
DEERFLOW_MODEL_1_SUPPORTS_VISION=false
DEERFLOW_MODEL_1_SUPPORTS_THINKING=false
DEERFLOW_MODEL_2_NAME=qwen-vl
DEERFLOW_MODEL_2_DISPLAY_NAME=视觉模型
DEERFLOW_MODEL_2_MODEL=qwen-vl
DEERFLOW_MODEL_2_BASE_URL=http://10.10.10.26:8000/v1
DEERFLOW_MODEL_2_API_KEY=your-real-key-2
DEERFLOW_MODEL_2_SUPPORTS_VISION=true
DEERFLOW_MODEL_2_SUPPORTS_THINKING=false
```
同宿主机 MySQL 不要填 `127.0.0.1`;应填宿主机内网 IP,或在 Docker 的 `host-gateway` 正常时填写 `host.docker.internal`。
字段解释:
| 字段 | 必填 | 说明 |
|---|---:|---|
| `PUBLIC_HOST` | 是 | 用户访问的服务器 IP 或域名,只填主机名,不带协议和路径 |
| `FRONTEND_PORT` | 是 | 页面端口,默认示例 `5174` |
| `BACKEND_PORT` | 是 | Gateway 端口,默认示例 `8001`,不能与前端端口相同 |
| `MYSQL_HOST` | 是 | 外部 MySQL 主机名、内网 IP 或 `host.docker.internal` |
| `MYSQL_PORT` | 是 | MySQL 监听端口 |
| `MYSQL_DATABASE` | 是 | 仅允许字母、数字和下划线;账号需有建库/建表权限 |
| `MYSQL_USER` / `MYSQL_PASSWORD` | 是 | DeerFlow 数据库账号和密码 |
| `DEERFLOW_MODEL_COUNT` | 是 | 启用的模型数量,范围 1~20;第 1 个模型是系统默认模型 |
| `DEERFLOW_MODEL_N_NAME` | 是 | DeerFlow 内部唯一名称,不能与其他模型重复 |
| `DEERFLOW_MODEL_N_DISPLAY_NAME` | 否 | 页面显示名称,留空时使用 `NAME` |
| `DEERFLOW_MODEL_N_MODEL` | 否 | 发给模型服务的真实 model id,留空时使用 `NAME` |
| `DEERFLOW_MODEL_N_BASE_URL` | 是 | OpenAI 兼容根地址,通常以 `/v1` 结尾 |
| `DEERFLOW_MODEL_N_API_KEY` | 是 | 对应模型接口 Key;内网无鉴权时也需填写接口接受的占位值 |
| `DEERFLOW_MODEL_N_SUPPORTS_VISION` | 否 | 是否支持图片输入,默认 `false` |
| `DEERFLOW_MODEL_N_SUPPORTS_THINKING` | 否 | 是否支持 thinking,默认 `false` |
| `DEERFLOW_MODEL_N_SUPPORTS_REASONING_EFFORT` | 否 | 是否接受 reasoning effort,默认 `false` |
| `DEERFLOW_MODEL_N_REQUEST_TIMEOUT` | 否 | 单次请求超时秒数,默认 `600`,范围 1~3600 |
| `DEERFLOW_MODEL_N_MAX_RETRIES` | 否 | 模型请求重试次数,默认 `2`,范围 0~10 |
| `DEERFLOW_MODEL_N_STREAM_USAGE` | 否 | 是否在流式响应中统计用量,默认 `true` |
| `DEERFLOW_MODEL_N_MAX_TOKENS` | 否 | 最大输出 token;留空表示由接口默认值决定 |
| `DEERFLOW_MODEL_N_TEMPERATURE` | 否 | 温度,范围 0~2;留空表示由接口默认值决定 |
| `DEERFLOW_MODEL_N_USE_RESPONSES_API` | 否 | OpenAI Responses API 开关,普通兼容接口保持 `false` |
`N` 从 1 开始连续编号。例如 `DEERFLOW_MODEL_COUNT=3` 时,必须完整填写模型 1、2、3;模型 4 之后即使保留示例也会被忽略。要增加模型,复制最后一个模型块、把编号加 1,并同步修改 `DEERFLOW_MODEL_COUNT`。要删除模型,按连续编号整理后减小 `COUNT`。
所有模型默认使用 `langchain_openai:ChatOpenAI`。如果确实需要自定义 provider,可增加 `DEERFLOW_MODEL_N_USE=包路径:类名`;对应 Python 包必须已经内置,或通过 `source/wheelhouse` 离线安装。
Tavily、Serper、任务深链和所有 `VITE_*` 业务接口均为可选项,不使用就保持空值。示例保留地址和 `example` 密钥会被启动脚本拒绝,防止误部署。
任务深链不接真实系统时保持 `TASK_DEEPLINK_MOCK_MODE=true`。接真实系统时改为 `false`,并填写对应的 `TASK_*_URL` 与前端业务 `VITE_*` 地址。URL 必须是完整 `http://` 或 `https://` 地址,不要在 URL 内嵌账号密码,也不要附带查询参数。
`deploy.env` 是简单 `KEY=VALUE` 文件:一个配置占一行,不要在等号两侧加空格,不支持多行值;值包含 `#` 时不要写行尾注释。修改后执行 `--restart`,脚本会重新渲染并覆盖 `data/generated/`,然后重建前后端容器,因此不要直接编辑生成文件。`--restart` 不执行数据库预检、不加载镜像;首次部署仍使用 `--start`。
运行时生成的 MySQL SQLAlchemy 地址固定为 `mysql+aiomysql://...`。用户名和密码会自动 URL 编码,不要自己在 `MYSQL_PASSWORD` 中把 `@`、`#` 等字符改成 `%xx`。
DeerFlow 登录 JWT 密钥首次启动自动随机生成到 `data/state/runtime-secrets.json`,无需人工配置;该文件应随数据库和数据目录一起备份。
本包没有 WeKnora 配置项。运行配置始终把 WeKnora 地址置空,并关闭 LLMWiki 本地同步和向量索引。
@@ -0,0 +1,46 @@
# 03 一键部署与启停
```bash
tar -xzf deerflow-linux-amd64-offline-*.tar.gz
cd deerflow-linux-amd64-offline-*
cp -a config/deploy.env config/deploy.env.before-edit
vi config/deploy.env
sudo ./OFFLINE_INSTALL.sh --start
```
启动会依次执行:检查镜像、必要时校验并加载离线镜像、校验 `deploy.env`、生成运行配置、使用 aiomysql 预检 MySQL、从 `source/wheelhouse` 安装已声明的离线依赖、使用 `docker-compose up -d --no-build` 启动、等待前后端健康。脚本不使用 Compose v2 专属的 `--pull never`;镜像缺失时会先从包内加载,因此不会现场构建、联网下载 pip 包或拉取镜像。
第一次加载镜像耗时取决于磁盘速度。出现“所需 DeerFlow 镜像已存在”表示标签完全匹配,脚本会跳过 `docker load`。启动完成后会打印页面地址,也可以手工检查:
```bash
curl -f http://127.0.0.1:8001/health
curl -I http://127.0.0.1:5174/
sudo ./OFFLINE_INSTALL.sh --status
```
如果修改过端口,请把示例端口替换成 `deploy.env` 中的值。
```bash
# 只停止,保留镜像和数据
sudo ./OFFLINE_INSTALL.sh --stop
# 修改 deploy.env 后重新渲染并启动
sudo ./OFFLINE_INSTALL.sh --restart
sudo ./OFFLINE_INSTALL.sh --status
sudo ./OFFLINE_INSTALL.sh --logs
sudo ./OFFLINE_INSTALL.sh --logs deerflow-backend
# 不连接数据库,单独验证沙箱中的 Word/Excel/PPT/PDF 依赖
sudo ./OFFLINE_INSTALL.sh --office-check
```
`--logs` 会持续跟踪日志,按 `Ctrl+C` 只退出日志查看,不会停止服务。前端服务名为 `deerflow-frontend`,后端服务名为 `deerflow-backend`。
`--restart` 会重新校验/渲染 `deploy.env`、检查 wheelhouse 指纹、验证挂载源码,然后强制重建前后端容器并等待健康。它不执行 MySQL 预检,不执行 `docker load/build/pull/rmi`,不删除网络和卷。容器重建是为了让新增挂载、依赖和环境变量可靠生效;数据库、用户文件、浏览器上下文和 wheelhouse 安装结果都在持久卷中保留。仅修改智能体、技能或知识文件后也使用 `--restart`。
脚本没有删除命令。需要卸载时应先完整备份,然后由运维人员明确执行 Compose `down` 或卷清理,不要把它与日常停止混用。
## 开机自启
Compose 服务设置为 `restart: unless-stopped`。手工执行 `--stop` 后 Docker 不会自动拉起它,需要恢复时执行 `--start`;如果只是重启服务器且此前没有手工停止,Docker 服务启动后通常会自动恢复容器。
@@ -0,0 +1,62 @@
# 04 技能与智能体位置
## 智能体
```text
agents-skills/deerflow-agents/<agent-name>/config.yaml
agents-skills/deerflow-agents/<agent-name>/SOUL.md
```
运行时挂载到 `/app/backend/.deer-flow/agents`。
每个智能体使用独立、可读的目录名。`config.yaml` 定义名称、模型、工具和技能等配置,`SOUL.md` 定义角色提示词。额外模板或资源放在同一目录内并使用相对路径。不要使用 32 位十六进制目录名,这类名称保留给运行时用户智能体。
```text
agents-skills/deerflow-agents/my-agent/
├── config.yaml
└── SOUL.md
```
## 技能
```text
agents-skills/deerflow-skills/public/<skill-name>/SKILL.md
agents-skills/deerflow-skills/custom/<skill-name>/SKILL.md
```
技能需要脚本时放在对应技能目录的 `scripts/` 下。运行时整个目录挂载到 `/app/backend/skills`。
推荐结构:
```text
agents-skills/deerflow-skills/custom/my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
```
`SKILL.md` 是入口说明;脚本放 `scripts/`,资料放 `references/`,静态模板放 `assets/`。技能中如果写死了环境 URL/IP,应在迁移前替换成目标环境地址。
## 本地知识文件
```text
agents-skills/deerflow-knowledge/
```
运行时挂载到 `/app/backend/knowledge`。修改上述目录后执行 `--restart`。不要进入镜像内部改文件;升级前备份整个 `agents-skills/`。
本地知识目录只是随容器挂载的文件位置,不等同于 WeKnora 知识库,也不会自动创建向量库。具体智能体或技能需要通过自身配置读取这些文件。
更新后检查:
```bash
find agents-skills/deerflow-agents -maxdepth 2 -type f | sort
find agents-skills/deerflow-skills -maxdepth 3 -type f | sort
sudo ./OFFLINE_INSTALL.sh --restart
sudo ./OFFLINE_INSTALL.sh --logs deerflow-backend
```
YAML 或 Markdown 格式错误通常会出现在后端日志中。上线前先复制原目录作为回退副本,不要在运行中的容器文件系统里直接修改,重建容器会丢失该修改。
本发行包没有 `agents-skills/weknora-skills/`,也不会启动 WeKnora。
@@ -0,0 +1,32 @@
# 05 数据备份与恢复
需要成套备份:
- `config/deploy.env`。
- `data/state/runtime-secrets.json`。
- `agents-skills/`。
- 外部 MySQL 中的 DeerFlow 数据库。
- Docker 卷 `cmzs-deerflow_deerflow-data`、`cmzs-deerflow_deerflow-browser-context`、`cmzs-deerflow_deerflow-users`。
备份前执行 `sudo ./OFFLINE_INSTALL.sh --stop`,数据库和卷恢复完成后再执行 `--start`。不要重新生成丢失的 JWT 密钥后继续使用旧登录数据。
## 卷备份示例
先确认实际卷名:
```bash
docker volume ls --filter name=cmzs-deerflow
```
以 `deerflow-data` 为例导出到当前目录:
```bash
docker run --rm \
-v cmzs-deerflow_deerflow-data:/source:ro \
-v "$PWD":/backup \
alpine:3.20 sh -c 'cd /source && tar -czf /backup/deerflow-data.tar.gz .'
```
纯离线目标机不一定有 `alpine:3.20`,该命令仅在镜像已存在时使用;否则使用运维环境已有的备份工具。MySQL 应使用 `mysqldump` 或单位数据库备份平台独立备份。
恢复时必须保证应用已停止,先恢复数据库,再恢复三个卷、`agents-skills/`、`deploy.env` 和 `runtime-secrets.json`,最后执行 `--start`。恢复后检查用户登录、智能体列表、历史会话和文件访问。
@@ -0,0 +1,54 @@
# 06 故障排查与校验
外层包校验:
```bash
sha256sum -c deerflow-linux-amd64-offline-*.tar.gz.sha256
```
包内镜像校验:
```bash
sha256sum -c SHA256SUMS
```
常用排查:
```bash
sudo ./OFFLINE_INSTALL.sh --status
sudo ./OFFLINE_INSTALL.sh --logs deerflow-backend
docker image inspect "$(head -n 1 images/deerflow-image-list.txt)"
```
查看两个容器的退出码和健康状态:
```bash
docker-compose --project-name cmzs-deerflow \
--env-file data/generated/compose.env \
-f compose/docker-compose.yml ps -a
```
- MySQL 预检失败:检查监听地址、账号来源网段、建库权限和防火墙。生成地址应以 `mysql+aiomysql://` 开头,可用 `grep '^MYSQL_DATABASE_URL=' data/generated/compose.env` 确认(不要把含密码的结果发给他人)。
- 日志出现 `No module named aiomysql`:确认 `source/wheelhouse/aiomysql-0.3.2-py3-none-any.whl` 和 `requirements.txt` 中的 aiomysql 兼容组三行都存在,然后执行 `--restart`。
- 日志出现 `ping() missing ... reconnect`:不要只升级 aiomysql;恢复 `aiomysql==0.3.2`、`PyMySQL==1.2.0`、`SQLAlchemy==2.0.51` 三行及对应 wheel,再执行 `--restart`。
- wheelhouse 报 `No matching distribution found`:缺少传递依赖 wheel,或 wheel 不是 Python 3.12/Linux amd64 版本;按文档 13 补齐。
- Docker 创建网络失败并提示 `iptables` 不存在:先修复宿主机 Docker/iptables 安装,不要修改包内文件绕过。
- 模型调用失败:确认模型地址能从容器访问;宿主机服务不要填 `127.0.0.1`。
- 再次启动仍执行 `docker load`:说明镜像标签缺失或镜像清单不匹配。
- 页面能打开但请求失败:确认浏览器能访问 `BACKEND_PORT`,并检查 `data/generated/frontend/runtime-config.js` 中由 `PUBLIC_HOST` 生成的地址。
- 端口已占用:用 `ss -lntp` 查占用,修改两个端口后执行 `--restart`。
- 容器反复重启:查看后端最后 300 行日志,重点检查 MySQL 表创建、配置 YAML 和模型配置。
- 技能/智能体没有出现:核对目录层级、文件权限和名称,再重启后端。
- Word、Excel 或 PPT 上传后没有生成 Markdown:先执行 `sudo ./OFFLINE_INSTALL.sh --office-check`;通过后再检查后端上传日志和 `uploads.auto_convert_documents` 是否为 `true`。
`--stop` 后镜像应继续存在;脚本不会执行 `docker rmi` 或删除数据卷。
## 安全和内容检查
`config/deploy.env` 和 `data/state/runtime-secrets.json` 权限应为 `600`。不要把解压后的真实配置目录上传到公共文件服务器,也不要把运行时生成文件重新制作成分发包。
```bash
grep -vE '^[[:space:]]*(#|$)' images/deerflow-image-list.txt
```
清单应严格只有 DeerFlow Backend 和 Frontend,不应看到 WeKnora、ParadeDB、Redis 或 DocReader 镜像。
@@ -0,0 +1,51 @@
# 07 升级与版本回退
日常只修改 `.py`、`.tsx`、`.ts`、样式和页面资源时,优先使用 `11-只替换前后端源码.md` 的源码覆盖层机制。它不传输 Docker 基础层,在部署服务器上基于已保存镜像离线生成很薄的新镜像。
涉及 Compose、部署控制文件或普通镜像增量包时,使用本包自带的通用增量机制,不再解压一套完整基线包:
```bash
tar -xzf deerflow-update-*.tar.gz
cd /当前正在使用的DeerFlow部署目录
sudo ./UPDATE_INSTALL.sh --apply /增量包解压目录
```
增量更新只加载发生变化的镜像并更新白名单控制文件,保留现有 `config/deploy.env`、JWT 密钥、智能体、custom 技能、知识文件、Docker 卷和旧镜像。详细制作规范、变更分类及校验清单见 `09-后续增量更新发版手册.md`。
应用时会把旧控制文件备份到 `data/updates/backups/`。需要回退时:
```bash
sudo ./UPDATE_INSTALL.sh --rollback \
/当前部署目录/data/updates/backups/<对应备份目录>
```
该操作恢复旧镜像引用和控制文件;不会反向恢复数据库。若新版本执行过不兼容数据库迁移,必须同时恢复升级前数据库备份。
## 完整基线包切换(仅用于跨大版本或基线损坏)
不同版本完整离线包解压到不同目录,不要覆盖旧目录。升级前备份旧包的 `config/deploy.env`、`data/state/runtime-secrets.json`、`agents-skills/`、外部 MySQL 和三个 Docker 卷。
推荐步骤:
```bash
cd /旧包目录
sudo ./OFFLINE_INSTALL.sh --stop
cd /新包目录
# 按旧配置逐项填写新版本 deploy.env;不要直接覆盖,以免漏掉新增字段
vi config/deploy.env
# 复制经人工确认的智能体、技能、知识文件
sudo ./OFFLINE_INSTALL.sh --start
```
同一个 Compose 项目名会复用现有数据卷。新版本首次启动可能自动创建或迁移数据库表,必须先完成数据库备份。不要在没有数据库备份的情况下来回切换应用版本。
回退时停止新包,在数据库兼容且已备份的前提下启动旧包。若新版本执行了不可逆数据库迁移,应先恢复升级前数据库和卷快照,再启动旧包。
```bash
cat VERSION.json
cat images/deerflow-image-list.txt
sha256sum -c SHA256SUMS
```
旧镜像不会被 `--stop` 删除,因此通常可以直接回退;只有运维人员明确清理镜像后才需要重新加载旧包镜像。
@@ -0,0 +1,43 @@
# 08 离线验收清单
## 安装前
- 外层 `.sha256` 校验为 `OK`。
- `uname -m` 为 `x86_64`。
- Docker Engine、`docker-compose` 正常。
- 外部 MySQL 和模型接口可从服务器/容器网络访问。
- `config/deploy.env` 中没有 `192.0.2.*` 或 `example` 示例值。
## 首次启动
```bash
sudo ./OFFLINE_INSTALL.sh --start
sudo ./OFFLINE_INSTALL.sh --status
curl -f http://127.0.0.1:<BACKEND_PORT>/health
curl -I http://127.0.0.1:<FRONTEND_PORT>/
sudo ./OFFLINE_INSTALL.sh --office-check
```
确认两个容器均为运行/健康状态,浏览器能打开页面,登录和一次最小模型问答成功。
## 停止与再次启动
```bash
sudo ./OFFLINE_INSTALL.sh --stop
docker image inspect "$(sed -n '1p' images/deerflow-image-list.txt)"
docker image inspect "$(sed -n '2p' images/deerflow-image-list.txt)"
sudo ./OFFLINE_INSTALL.sh --start
```
停止后两个镜像仍能 inspect;再次启动日志应显示跳过 `docker load`,容器重新健康,历史数据仍在。
## 功能与内容
- 智能体目录可见,命名智能体能加载。
- 自定义技能放入 `agents-skills/deerflow-skills/custom/` 后重启可见。
- 前后端端口与 `deploy.env` 一致。
- 未配置的业务接口保持空值,不意外访问旧 UAT/生产地址。
- 镜像清单只有两个 DeerFlow 镜像,不存在 WeKnora 相关服务。
- Office 自检输出 `OFFICE_RUNTIME_SELF_CHECK=PASS`,Word、Excel、PowerPoint 样例均能生成并重新解析。
验收完成后保留:离线包、同名 `.sha256`、实际 `deploy.env` 的受控备份、数据库/卷备份和验收记录。
@@ -0,0 +1,141 @@
# 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 或数据目录。
- 本次包含的技能/智能体文件及覆盖策略。
- 升级命令、验证结果、回退命令和数据库回退要求。
@@ -0,0 +1,53 @@
# 10 Office 文档处理与自检
本包的默认沙箱是 DeerFlow 后端容器内的 `LocalSandboxProvider`。Office 依赖必须安装在后端镜像的 `/opt/venv` 和操作系统层;只安装在宿主机上没有作用。
## 已内置能力
- Word:DOC、DOCX、ODT。
- Excel:XLS、XLSX、ODS。
- PowerPoint:PPT、PPTX、ODP。
- PDF:文本抽取和 Markdown 转换。
- Python:MarkItDown、python-docx、openpyxl、pandas、python-pptx、xlrd、lxml、mammoth。
- 系统工具:LibreOffice Headless、Pandoc、Poppler、`file`、中文 Noto 字体。
现代 DOCX/XLSX/PPTX 直接由 Python 组件读取;旧 DOC/XLS/PPT 和 OpenDocument 文件先用独立 LibreOffice 临时配置转换为现代格式,再提取为 Markdown。独立临时配置可避免多个上传任务同时转换时争用 LibreOffice 用户目录锁。
`config/deerflow/config.base.yaml` 默认设置:
```yaml
uploads:
auto_convert_documents: true
pdf_converter: auto
```
运行配置由脚本生成,正常部署无需再手工修改 YAML。
## 不依赖数据库的自检
```bash
sudo ./OFFLINE_INSTALL.sh --office-check
```
脚本会在后端镜像中生成最小 DOCX、XLSX、PPTX,再分别转换并检查标记文本,同时检查 LibreOffice、Pandoc、Poppler、`file` 和中文字体。通过时输出:
```text
OFFICE_RUNTIME_SELF_CHECK=PASS
```
该命令只检查镜像和沙箱依赖,不读取 MySQL,也不启动前后端服务。
## 上传后的处理路径
1. 原文件保存到当前用户、当前会话的 `uploads/`。
2. 支持的文档自动转换为同名 `.md`。
3. Agent 同时收到原文件和 Markdown 虚拟路径。
4. Agent 优先读取 `.md` 做总结、问答和内容抽取;需要生成/修改文件时,可在本地沙箱使用上述 Python 库和系统工具,产物应写入 `/mnt/user-data/outputs/`。
如果自检通过但某个文件失败,应查看:
```bash
sudo ./OFFLINE_INSTALL.sh --logs deerflow-backend
```
损坏、加密、带复杂宏或受密码保护的 Office 文件可能仍无法自动解析。此时原文件会保留,但不会保证生成有效 Markdown;应先解除密码或另存为标准 DOCX/XLSX/PPTX 后重新上传。
@@ -0,0 +1,172 @@
# 11 只替换前后端源码
本流程专门用于日常持续修改源码。完整离线包及其两个镜像作为固定“依赖基线”长期保存,后续更新包不再包含 Docker 镜像基础层,只包含:
- 脱敏后的完整后端源码;
- 脱敏后的完整前端源码;
- 发版机编译好的前端 `dist` 静态文件;
- 两个很小的离线覆盖层 Dockerfile;
- 目标版本、镜像标签、SHA-256 和一键应用脚本。
部署机收到源码更新包后,以本机已经加载的旧镜像为 `FROM`,离线生成新的代码层镜像。Python、Office、LibreOffice、Pandoc、字体、浏览器、Nginx 等依赖都沿用固定基线,不重新安装,也不执行 `docker pull`。
## 一、固定基线
当前固定依赖基线为:
```text
deerflow-linux-amd64-offline-20260827-010119.tar.gz
源码提交:8d3eeaac45a79daf31f6ee6e0bf18ba6bc7c4e0b
```
正式包、`.sha256` 和 `SOURCE_BASELINE.json` 必须长期保留。`latest` 链接可以以后指向其他版本,但 `base` 链接和带时间戳的文件不得覆盖或删除。
`SOURCE_BASELINE.json` 锁定以下后端运行依赖文件:
```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
offline-backend-20260512/backend/Dockerfile.backend-offline
deploy/linux-docker-offline/Dockerfile.backend
```
任意锁定文件发生变化,源码增量构建会立即终止。此时必须制作新的完整依赖基线,不能强行覆盖,否则很容易出现源码已经引用新包、镜像里却没有该依赖的问题。
## 二、制作源码更新包
在能够完成前端构建的 Linux amd64 发版机上执行:
```bash
cd /源码根目录
# 前后端都更新
sudo ./deploy/linux-docker-offline-deerflow-only/build-source-update.sh \
/源码根目录 \
/当前正在运行的DeerFlow部署目录 \
/opt/deerflow-source-build \
all
```
只更新后端:
```bash
sudo ./deploy/linux-docker-offline-deerflow-only/build-source-update.sh \
/源码根目录 /当前部署目录 /opt/deerflow-source-build backend
```
只更新前端:
```bash
sudo ./deploy/linux-docker-offline-deerflow-only/build-source-update.sh \
/源码根目录 /当前部署目录 /opt/deerflow-source-build frontend
```
构建结果位于:
```text
/opt/deerflow-source-build/dist/deerflow-source-update-<时间>-<commit前8位>.tar.gz
```
制作脚本会完成以下检查:
1. 当前部署版本和当前镜像标签可解析;
2. 当前镜像确实存在且为 `linux/amd64`;
3. `SOURCE_BASELINE.json` 中的所有依赖文件哈希完全一致;
4. 后端四个 Python 依赖清单与正在使用的后端镜像逐字节一致;
5. `config.yaml`、`extensions_config.json` 和 `runtime-config.js` 已脱敏;
6. 前端 `pnpm build` 成功并生成 `dist/index.html`;
7. 包内和包外 SHA-256、gzip 完整性正确。
前端浏览器不能直接运行 TSX/TypeScript,因此前端源码仍会保存在更新包中供审计,但部署时实际覆盖的是同一次构建产生的 `dist`。前端依赖安装只发生在发版机的构建缓存层,不会进入部署机,也不会在部署时访问网络。
## 三、部署机一键应用
把源码更新包放到部署服务器,先校验并解压:
```bash
sha256sum -c deerflow-source-update-*.tar.gz.sha256
tar -xzf deerflow-source-update-*.tar.gz
cd deerflow-source-update-*
```
只检查版本链、校验值和基线镜像,不切换服务:
```bash
sudo ./APPLY_SOURCE_UPDATE.sh --check /当前正在运行的DeerFlow部署目录
```
一键应用并启动:
```bash
sudo ./APPLY_SOURCE_UPDATE.sh --apply /当前正在运行的DeerFlow部署目录
```
希望应用后暂不启动:
```bash
sudo ./APPLY_SOURCE_UPDATE.sh --apply /当前正在运行的DeerFlow部署目录 --no-start
cd /当前正在运行的DeerFlow部署目录
sudo ./OFFLINE_INSTALL.sh --start
```
应用顺序为:校验全部文件 → 校验当前版本和镜像 ID → 离线构建代码层镜像 → 后端导入与 Office 自检 → 备份控制文件 → `docker-compose stop` → 切换镜像标签 → 使用原 `deploy.env` 渲染 → 启动和健康检查。
旧服务会一直运行到新覆盖层镜像构建和自检完成,停机时间仅发生在最后切换阶段。脚本不执行 `down`、`rmi`、`volume rm`,不会删除旧镜像和已加载镜像。
## 四、保留与不覆盖的内容
源码更新不会覆盖:
- `config/deploy.env`;
- `data/state/runtime-secrets.json`;
- 外部 MySQL 数据;
- Docker 命名卷;
- 用户智能体目录;
- `skills/custom/`;
- 本地知识文件;
- 已加载的旧镜像。
后端 `config.yaml`、`extensions_config.json` 和前端 `runtime-config.js` 只更新脱敏模板,启动时仍由唯一配置源 `config/deploy.env` 重新生成实际运行配置。
技能、智能体或知识文件若需要单独发版,继续按 `04-技能与智能体位置.md` 指定目录投放,不要混入普通源码覆盖流程。
## 五、连续更新和回退
每次更新都以“服务器当前正在运行的部署目录”为基线制作,版本按顺序推进:
```text
完整依赖基线 A → 源码版本 B → 源码版本 C → 源码版本 D
```
每个源码包都带完整后端源码和完整前端静态文件,不是二进制差分;但必须按照清单中的 `BASE_RELEASE` 应用,防止误把旧包覆盖到错误版本。
应用前的控制文件备份位于:
```text
/当前部署目录/data/updates/backups/
```
源码更新备份与原 `UPDATE_INSTALL.sh` 兼容,回退命令:
```bash
cd /当前部署目录
sudo ./UPDATE_INSTALL.sh --rollback \
/当前部署目录/data/updates/backups/<对应备份目录>
```
旧镜像始终保留,因此回退不需要重新 `docker load`。如果某次源码修改同时包含数据库结构或不可逆数据迁移,必须先备份数据库,并另行提供数据库回退步骤;源码脚本不会自动回滚数据库。
## 六、什么时候不能用源码替换
出现以下任一情况必须重新制作完整依赖基线:
- Python 依赖、`uv.lock` 或 harness 依赖变化;
- 新增或修改 apt/system package;
- 修改 Office、LibreOffice、Pandoc、字体或浏览器运行依赖;
- 更换 Python 基础镜像、CPU 架构;
- 修改 Docker 数据卷布局并需要迁移数据;
- 当前固定基线镜像或 `SOURCE_BASELINE.json` 丢失。
普通 `.py`、`.tsx`、`.ts`、`.css`、前端 npm 业务依赖、页面资源和后端业务逻辑更新可以继续使用源码覆盖包。前端 npm 依赖会在发版机重新编译进静态文件,不要求部署机安装 Node.js。
@@ -0,0 +1,66 @@
# 直接覆盖源码并重启(最简单方式)
当前部署已经把前后台代码作为宿主机目录挂载到容器。日常修改源码时不需要重新打镜像,也不需要重新加载离线镜像。
## 需要替换的目录
在 DeerFlow 部署目录中只替换以下内容:
```text
source/
├── backend/
│ ├── app/ # 替换为 offline-backend-20260512/backend/app
│ ├── packages/ # 替换为 offline-backend-20260512/backend/packages
│ └── tests/ # 替换为 offline-backend-20260512/backend/tests
├── frontend/
│ └── dist/ # 替换为 frontend-web 执行 pnpm build 后的 dist
└── wheelhouse/ # 离线 Python wheel 与 requirements.txt;日常源码替换不要删除
```
注意:后端目录名是 `tests`,不是 `test`。
## 前端怎么生成 dist
在开发或构建机器执行:
```bash
cd frontend-web
pnpm install
pnpm build
```
只把生成的 `frontend-web/dist/` 内容上传到部署目录的 `source/frontend/dist/`。服务器不需要 Node.js,也不会在启动时安装 npm 依赖。
## 替换完成后重启
进入服务器当前 DeerFlow 部署目录:
```bash
sudo ./OFFLINE_INSTALL.sh --restart
```
该脚本只执行以下操作:
1. 检查四个代码目录和前端 `index.html`;
2. 从 `deploy.env` 重新生成数据库、模型和前端运行配置;
3. 检查 `source/wheelhouse`,仅在内容变化时离线安装依赖;
4. 使用一次性容器检查后端 Python 导入;
5. 依次重建并重启后端、前端容器;
6. 等待两个服务健康。
它不会执行数据库预检,不会 `docker load`,不会构建、拉取或删除镜像,也不会修改 `config/deploy.env`、数据库业务数据、技能、智能体或知识文件。容器会重建以应用新增的挂载和环境变量,但数据库卷、用户数据卷、浏览器上下文卷和 Python 依赖卷均保留。
## 哪些修改不能这样更新
如果修改了以下内容,不能只覆盖源码:
- 后端 `pyproject.toml`、`uv.lock`、`requirements-offline.txt` 中涉及无法通过纯 Python wheel 提供的依赖;
- 系统软件、Python/Office/浏览器依赖;
- Nginx 镜像运行环境;
- Dockerfile 或容器启动命令。
这些修改涉及系统运行环境,需要重新制作基础镜像包。新增普通纯 Python/C-extension wheel 时,可按 `docs/13-wheelhouse离线新增依赖与多模型.md` 操作,无需重做镜像;单纯修改后端 `app/packages/tests` 和前端页面代码可以直接覆盖。
## 建议的安全替换方式
上传时先放到临时目录,确认完整后再改名覆盖,避免服务运行期间读到上传一半的文件。替换之前可复制一份旧目录作为备份;若新代码有问题,恢复旧目录后再次运行 `OFFLINE_INSTALL.sh --restart`。
@@ -0,0 +1,98 @@
# wheelhouse 离线新增依赖与多模型配置
## 一、数据库固定使用 aiomysql
部署脚本生成的连接地址为:
```text
mysql+aiomysql://用户名:编码后的密码@主机:端口/数据库?charset=utf8mb4
```
镜像和 `source/wheelhouse` 都预置兼容组:
```text
aiomysql==0.3.2
PyMySQL==1.2.0
SQLAlchemy==2.0.51
```
这三个版本必须作为整体保留,避免出现 SQLAlchemy 的 `ping(reconnect)` 适配错误。人工只填写 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_DATABASE`、`MYSQL_USER`、`MYSQL_PASSWORD`;不要直接编辑生成的数据库 URL。
## 二、以后怎样离线增加 Python 依赖
部署目录:
```text
source/wheelhouse/
├── requirements.txt
├── README.txt
├── *.whl
└── SHA256SUMS
```
后端镜像是 Python 3.12、Linux amd64。新增的 wheel 必须匹配该平台;常见可用标签是 `py3-none-any`、`cp312-manylinux2014_x86_64` 或兼容的 manylinux x86_64。Windows wheel、macOS wheel、ARM64 wheel、源码包 `.tar.gz` 均不能使用。
在联网的 Linux amd64/Python 3.12 机器下载示例:
```bash
mkdir -p new-wheels
python3.12 -m pip download \
--only-binary=:all: \
--platform manylinux2014_x86_64 \
--implementation cp \
--python-version 312 \
--abi cp312 \
--dest new-wheels \
'your-package==1.2.3'
```
将 `new-wheels/` 中目标包及其全部依赖的 `.whl` 上传到 `source/wheelhouse/`,然后在 `source/wheelhouse/requirements.txt` 增加:
```text
your-package==1.2.3
```
执行:
```bash
./OFFLINE_INSTALL.sh --restart
```
脚本只使用 `--no-index --find-links /app/wheelhouse`,不会访问互联网。它会计算 `requirements.txt` 和所有 wheel 的指纹;内容未变化时跳过安装,内容变化时安装到持久卷 `deerflow-python-vendor`。重建、停止或重启容器不会丢失已安装依赖,也不会修改基础镜像。
如果安装时报 `No matching distribution found`,通常是缺少传递依赖 wheel、wheel 平台不匹配,或 `requirements.txt` 中版本与文件名不一致。补齐后再次执行 `--restart` 即可;安装失败时后端不会被切换到半完成的新进程。
## 三、配置多个模型
`config/deploy.env` 是唯一配置源。示例文件已经给出三套模型块,使用:
```dotenv
DEERFLOW_MODEL_COUNT=2
DEERFLOW_MODEL_1_NAME=general-model
DEERFLOW_MODEL_1_DISPLAY_NAME=通用模型
DEERFLOW_MODEL_1_MODEL=provider-real-model-id
DEERFLOW_MODEL_1_BASE_URL=http://10.10.10.25:8000/v1
DEERFLOW_MODEL_1_API_KEY=replace-with-real-key-1
DEERFLOW_MODEL_1_SUPPORTS_VISION=false
DEERFLOW_MODEL_1_SUPPORTS_THINKING=false
DEERFLOW_MODEL_2_NAME=vision-model
DEERFLOW_MODEL_2_DISPLAY_NAME=视觉模型
DEERFLOW_MODEL_2_MODEL=provider-vision-model-id
DEERFLOW_MODEL_2_BASE_URL=http://10.10.10.26:8000/v1
DEERFLOW_MODEL_2_API_KEY=replace-with-real-key-2
DEERFLOW_MODEL_2_SUPPORTS_VISION=true
DEERFLOW_MODEL_2_SUPPORTS_THINKING=false
```
规则:
1. 支持 1~20 个模型,编号必须从 1 连续排列;
2. 第 1 个模型是默认模型;
3. `NAME` 必须唯一;`MODEL` 是上游接口实际接收的 model id;
4. 每个模型可使用不同地址和 API Key;
5. `DISPLAY_NAME` 只影响页面显示;
6. 修改完成后执行 `./OFFLINE_INSTALL.sh --restart` 即可重新生成 `config.yaml` 并生效,无需手工改 YAML。
完整的超时、重试、最大 token、温度、视觉、thinking 和 Responses API 字段见 `docs/02-deploy.env配置说明.md`。