feat: standardize DeerFlow offline deployment
This commit is contained in:
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`。
|
||||
Reference in new issue
Block a user