173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
# 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`（存在时）。替换后再执行启动命令。
|
||
|