# 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 镜像里。