代码部署说明

This commit is contained in:
董宏凯 committed 2026-07-11 18:58:16 +08:00
1 parent 221e947488
commit 55b5c2cc9f
7 files changed
+727

No files matched your search

@@ -0,0 +1,403 @@
# DeerFlow 后台离线部署说明
本文档只说明“后台服务”的离线部署,不包含前端。
## 1. 当前服务器文件位置
当前已经在服务器上准备好的部署目录是:
```bash
/opt/deerflow-backend
```
主要文件和目录如下:
```text
/opt/deerflow-backend/
├── dist/deerflow-backend-offline.tar # 离线 Docker 镜像包
├── start-backend-docker.sh # 启动脚本
├── save-backend-image.sh # 镜像导出脚本
├── build-backend-image.sh # 在线构建脚本
├── config.yaml # 默认配置模板
├── extensions_config.json # 默认扩展配置模板
├── langgraph.json # LangGraph 配置
├── .env # 环境变量文件,没有则启动脚本会创建空文件
├── .deer-flow/agents/ # 默认智能体模板目录
├── skills/ # 默认技能模板目录
└── docker-data/ # 实际运行时挂载数据,启动后生成
```
当前服务器已验证:
```bash
cd /opt/deerflow-backend
./start-backend-docker.sh 8001
```
健康检查:
```bash
curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/api/health
```
## 2. 客户现场更换部署目录
客户现场可以换任意部署目录,不需要改脚本。把整个 `deerflow-backend` 目录放到目标位置即可。
示例:客户现场部署到 `/data/deerflow-backend`
```bash
DEPLOY_DIR=/data/deerflow-backend
mkdir -p "$DEPLOY_DIR"
# 将交付的 deerflow-backend 目录内容放到 $DEPLOY_DIR
cd "$DEPLOY_DIR"
chmod +x *.sh
```
加载离线镜像:
```bash
docker load -i dist/deerflow-backend-offline.tar
```
启动后台,端口可改:
```bash
./start-backend-docker.sh 8001
```
如果客户现场要用 `9001` 端口:
```bash
./start-backend-docker.sh 9001
```
脚本会自动把当前目录作为代码目录,把数据放到:
```text
$DEPLOY_DIR/docker-data
```
## 3. 数据、配置、智能体、技能目录
启动后,实际可修改的文件都在宿主机目录,不在容器内部。
默认目录如下:
```text
$DEPLOY_DIR/docker-data/config # 配置目录
$DEPLOY_DIR/docker-data/.deer-flow # 运行时目录:智能体、用户数据、SQLite 数据
$DEPLOY_DIR/docker-data/skills # 技能目录
$DEPLOY_DIR/docker-data/knowledge # 知识库目录
$DEPLOY_DIR/docker-data/logs # 日志目录
```
配置文件位置:
```text
$DEPLOY_DIR/docker-data/config/config.yaml
$DEPLOY_DIR/docker-data/config/extensions_config.json
$DEPLOY_DIR/docker-data/config/langgraph.json
$DEPLOY_DIR/docker-data/config/.env
```
智能体目录:
```text
$DEPLOY_DIR/docker-data/.deer-flow/agents
```
技能目录:
```text
$DEPLOY_DIR/docker-data/skills/public
$DEPLOY_DIR/docker-data/skills/custom
```
SQLite 聊天/checkpointer 数据库目录:
```text
$DEPLOY_DIR/docker-data/.deer-flow/data
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data
```
注意:当前部署使用 **MySQL 业务库 + SQLite 聊天/checkpointer 库**,不使用 PostgreSQL。SQLite 运行时可能同时有以下文件,备份或替换时要一起处理:
```text
deerflow.db
deerflow.db-wal
deerflow.db-shm
```
## 4. 客户现场加载智能体和技能
推荐流程:
1. 先启动一次,让目录自动生成。
2. 停止容器。
3. 复制客户的智能体、技能、SQLite 聊天库文件,并配置 MySQL 地址。
4. 再启动容器。
命令示例:
```bash
cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
docker rm -f deerflow-backend
```
复制智能体:
```bash
mkdir -p "$DEPLOY_DIR/docker-data/.deer-flow/agents"
cp -a /path/to/customer-agents/. "$DEPLOY_DIR/docker-data/.deer-flow/agents/"
```
复制技能:
```bash
mkdir -p "$DEPLOY_DIR/docker-data/skills/public"
mkdir -p "$DEPLOY_DIR/docker-data/skills/custom"
cp -a /path/to/customer-skills/public/. "$DEPLOY_DIR/docker-data/skills/public/"
cp -a /path/to/customer-skills/custom/. "$DEPLOY_DIR/docker-data/skills/custom/"
```
重新启动:
```bash
cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
```
如果只更新技能或智能体,不换数据库,也可以复制后直接重启:
```bash
docker restart deerflow-backend
```
## 5. 修改或替换 SQLite 聊天/checkpointer 数据库
SQLite 只保存聊天运行时、LangGraph checkpointer、部分本地运行数据。业务表使用 MySQL,MySQL 地址见第 6 节。
最稳的方式是停容器后整体替换运行时目录:
```bash
cd "$DEPLOY_DIR"
docker rm -f deerflow-backend
mv docker-data/.deer-flow docker-data/.deer-flow.bak.$(date +%Y%m%d%H%M%S)
cp -a /path/to/customer-dot-deer-flow "$DEPLOY_DIR/docker-data/.deer-flow"
./start-backend-docker.sh 8001
```
如果只替换数据库文件,至少要处理这两个目录里的 `deerflow.db*`:
```text
$DEPLOY_DIR/docker-data/.deer-flow/data/deerflow.db*
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data/deerflow.db*
```
操作示例:
```bash
cd "$DEPLOY_DIR"
docker rm -f deerflow-backend
mkdir -p docker-data/.deer-flow/data
mkdir -p docker-data/.deer-flow/.deer-flow/data
cp -a /path/to/db-main/deerflow.db* docker-data/.deer-flow/data/
cp -a /path/to/db-runtime/deerflow.db* docker-data/.deer-flow/.deer-flow/data/
./start-backend-docker.sh 8001
```
不要在容器运行时直接覆盖 SQLite 文件,容易损坏 WAL 数据。
## 6. 修改配置和数据库配置
默认配置会在第一次启动时复制到:
```text
$DEPLOY_DIR/docker-data/config/config.yaml
```
要改配置,改这个文件,不要进容器改。
本项目现场部署按 **MySQL + SQLite** 使用:
- MySQL:业务表,例如用户、智能体、技能、任务、菜单、按钮、敏感词、轻应用等。
- SQLite:聊天运行时和 LangGraph checkpointer,继续放在挂载出来的 `.deer-flow` 目录。
- 不使用 PostgreSQL,不要配置 `database.backend: postgres`,也不要配置 `POSTGRES_URL`。
MySQL 地址主要改两个文件:
```text
$DEPLOY_DIR/docker-data/config/config.yaml
$DEPLOY_DIR/docker-data/config/.env
```
`config.yaml` 里的数据库配置建议改成:
```yaml
database:
backend: mysql
sqlite_dir: .deer-flow/data
mysql_url: $MYSQL_DATABASE_URL
pool_size: 20
max_overflow: 20
pool_timeout: 30
echo_sql: false
checkpointer:
type: sqlite
connection_string: .deer-flow/data/deerflow.db
```
然后在 `.env` 里写 MySQL 连接地址:
```bash
MYSQL_DATABASE_URL=mysql+asyncmy://deerflow:密码@192.168.1.10:3306/deerflow?charset=utf8mb4
```
把上面示例里的内容换成客户现场真实值:
```text
deerflow # MySQL 用户名
密码 # MySQL 密码
192.168.1.10 # MySQL 服务器 IP
3306 # MySQL 端口
deerflow # MySQL 数据库名
```
如果 MySQL 就装在 Docker 宿主机这台服务器上,容器里不要写 `127.0.0.1`,建议写:
```bash
MYSQL_DATABASE_URL=mysql+asyncmy://deerflow:密码@host.docker.internal:3306/deerflow?charset=utf8mb4
```
如果密码里有特殊字符,需要做 URL 编码,常见示例:
```text
@ 写成 %40
# 写成 %23
% 写成 %25
空格 写成 %20
```
MySQL 数据库建议提前建好:
```sql
CREATE DATABASE deerflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
如果 MySQL 用户有建库权限,服务启动时也会尝试自动创建缺失的数据库。客户现场更稳的做法是先建库、导入 MySQL 备份,再启动后台。
如果客户现场已有 MySQL 备份,先在客户 MySQL 中导入:
```bash
mysql -h 192.168.1.10 -P 3306 -u deerflow -p deerflow < deerflow_mysql.sql
```
SQLite 聊天库仍按第 5 节复制到:
```text
$DEPLOY_DIR/docker-data/.deer-flow/data/deerflow.db*
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data/deerflow.db*
```
如果需要把数据目录单独放到别的位置,不需要改 `config.yaml`,启动时指定 `DATA_DIR` 更稳:
```bash
cd "$DEPLOY_DIR"
DATA_DIR=/data/deerflow-backend-data ./start-backend-docker.sh 8001
```
此时实际目录变成:
```text
/data/deerflow-backend-data/config
/data/deerflow-backend-data/.deer-flow
/data/deerflow-backend-data/skills
/data/deerflow-backend-data/knowledge
/data/deerflow-backend-data/logs
```
如果客户现场部署目录变化,只需要换 `DEPLOY_DIR` 或把整包放到新目录;MySQL 地址仍然只改 `$DEPLOY_DIR/docker-data/config/.env`,SQLite/智能体/技能仍然跟着 `DATA_DIR` 走。
如果要改 `.env`,位置是:
```text
$DEPLOY_DIR/docker-data/config/.env
```
修改配置后重启:
```bash
cd "$DEPLOY_DIR"
docker rm -f deerflow-backend
./start-backend-docker.sh 8001
```
## 7. 常用运维命令
查看容器:
```bash
docker ps -a --filter name=deerflow-backend
```
查看日志:
```bash
docker logs -f --tail 200 deerflow-backend
```
停止:
```bash
docker rm -f deerflow-backend
```
重启:
```bash
docker restart deerflow-backend
```
重新启动并换端口:
```bash
cd "$DEPLOY_DIR"
./start-backend-docker.sh 9001
```
检查接口:
```bash
curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/api/health
```
## 8. 交付清单
客户离线部署至少需要:
```text
deerflow-backend/
├── dist/deerflow-backend-offline.tar
├── start-backend-docker.sh
├── config.yaml
├── extensions_config.json
├── langgraph.json
├── .env
├── .deer-flow/agents/
├── skills/
└── 其他后台代码文件
```
客户机器需要提前安装好 Docker。离线部署时不需要再下载 Python 依赖,依赖已经包含在 Docker 镜像里。