404 lines
9.6 KiB
Markdown
404 lines
9.6 KiB
Markdown
# 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 镜像里。
|