# DeerFlow 后台离线镜像部署简明指南

本文档只部署后台 Docker 镜像，不包含前端。

## 1. 部署前准备

目标服务器需要已安装并启动 Docker：

```bash
docker --version
docker info
```

将交付目录 `deerflow-backend` 放到服务器任意位置。以下统一以 `/data/deerflow-backend` 为例：

```bash
DEPLOY_DIR=/data/deerflow-backend
cd "$DEPLOY_DIR"
chmod +x start-backend-docker.sh
```

如果交付的是压缩包，解压后确保目录中能看到以下文件：

```text
dist/deerflow-backend-offline.tar
start-backend-docker.sh
config.yaml
```

## 2. 导入镜像并启动

首次部署执行一次镜像导入：

```bash
cd "$DEPLOY_DIR"
docker load -i dist/deerflow-backend-offline.tar
```

启动后台，默认端口为 `8001`：

```bash
./start-backend-docker.sh 8001
```

例如使用 `9001` 端口：

```bash
./start-backend-docker.sh 9001
```

以后重启只需要再次执行同一条启动命令。脚本会自动删除旧容器并创建新容器：

```bash
./start-backend-docker.sh 8001
```

查看运行状态和日志：

```bash
docker ps --filter name=deerflow-backend
docker logs -f deerflow-backend
```

健康检查：

```bash
curl http://127.0.0.1:8001/health
```

## 3. 必须知道的文件位置

首次启动后，实际生效的配置和数据均在 `docker-data` 中。不要只修改部署根目录的模板文件。

```text
$DEPLOY_DIR/docker-data/config/config.yaml              # 主配置
$DEPLOY_DIR/docker-data/config/.env                      # 密码、地址等环境变量
$DEPLOY_DIR/docker-data/config/extensions_config.json    # MCP/扩展配置
$DEPLOY_DIR/docker-data/.deer-flow/agents                # 智能体及每个 SOUL.md
$DEPLOY_DIR/docker-data/skills                            # 技能目录
$DEPLOY_DIR/docker-data/.deer-flow/data                  # SQLite 数据
```

修改 `config.yaml`、`.env`、智能体或技能后，重新执行启动命令即可生效：

```bash
cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
```

## 4. 配置 MySQL

本部署支持 MySQL 保存业务数据，同时 SQLite 保留聊天/checkpointer 数据，不使用 PostgreSQL。

先在 MySQL 中创建数据库：

```sql
CREATE DATABASE deerflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

编辑 `$DEPLOY_DIR/docker-data/config/config.yaml`，将数据库部分改为：

```yaml
database:
  backend: mysql
  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
```

再编辑 `$DEPLOY_DIR/docker-data/config/.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 服务器地址
3306                MySQL 端口
deerflow            MySQL 数据库名
```

若 MySQL 安装在 Docker 宿主机上，可把地址写为 `host.docker.internal`：

```bash
MYSQL_DATABASE_URL=mysql+asyncmy://deerflow:数据库密码@host.docker.internal:3306/deerflow?charset=utf8mb4
```

密码中有特殊字符时必须进行 URL 编码，例如：`@` 写为 `%40`，`#` 写为 `%23`，`%` 写为 `%25`。

配置完成后启动：

```bash
cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
```

## 5. 导入智能体和技能

停止服务后复制文件，复制完成再启动。智能体目录中每个智能体必须同时保留 `config.yaml` 和 `SOUL.md`。

```bash
docker rm -f deerflow-backend

cp -a /path/to/agents/. "$DEPLOY_DIR/docker-data/.deer-flow/agents/"
cp -a /path/to/skills/. "$DEPLOY_DIR/docker-data/skills/"

cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
```

复制时使用 `源目录/.` 的形式，避免产生 `agents/智能体ID/智能体ID/SOUL.md` 的多一层目录问题。

## 6. SQLite 聊天数据

聊天和 checkpointer 的 SQLite 文件位于：

```text
$DEPLOY_DIR/docker-data/.deer-flow/data/deerflow.db
```

替换 SQLite 数据库前必须先停止容器，并同时复制 `deerflow.db`、`deerflow.db-wal`、`deerflow.db-shm`（存在时）。替换后再执行启动命令。