代码提交

2026-07-15 16:13:03 +08:00
1 parent 27e6b0b23e
commit d7ad0624b7
@@ -0,0 +1,172 @@
+# 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`（存在时）。替换后再执行启动命令。
+