wsk/deerflow-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b638b541d0
deerflow-code/offline-backend-20260512/backend/后台离线部署说明.md
gozeros b638b541d0 初始化
2026-09-07 18:24:55 +08:00

9.6 KiB
Raw Blame History

DeerFlow 后台离线部署说明

本文档只说明“后台服务”的离线部署，不包含前端。

1. 当前服务器文件位置

当前已经在服务器上准备好的部署目录是：

/opt/deerflow-backend

主要文件和目录如下：

/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/                            # 实际运行时挂载数据，启动后生成

当前服务器已验证：

cd /opt/deerflow-backend
./start-backend-docker.sh 8001

健康检查：

curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/api/health

2. 客户现场更换部署目录

客户现场可以换任意部署目录，不需要改脚本。把整个 deerflow-backend 目录放到目标位置即可。

示例：客户现场部署到 /data/deerflow-backend

DEPLOY_DIR=/data/deerflow-backend
mkdir -p "$DEPLOY_DIR"

# 将交付的 deerflow-backend 目录内容放到 $DEPLOY_DIR
cd "$DEPLOY_DIR"
chmod +x *.sh

加载离线镜像：

docker load -i dist/deerflow-backend-offline.tar

启动后台，端口可改：

./start-backend-docker.sh 8001

如果客户现场要用 9001 端口：

./start-backend-docker.sh 9001

脚本会自动把当前目录作为代码目录，把数据放到：

$DEPLOY_DIR/docker-data

3. 数据、配置、智能体、技能目录

启动后，实际可修改的文件都在宿主机目录，不在容器内部。

默认目录如下：

$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                   # 日志目录

配置文件位置：

$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

智能体目录：

$DEPLOY_DIR/docker-data/.deer-flow/agents

技能目录：

$DEPLOY_DIR/docker-data/skills/public
$DEPLOY_DIR/docker-data/skills/custom

SQLite 聊天/checkpointer 数据库目录：

$DEPLOY_DIR/docker-data/.deer-flow/data
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data

注意：当前部署使用 MySQL 业务库 + SQLite 聊天/checkpointer 库，不使用 PostgreSQL。SQLite 运行时可能同时有以下文件，备份或替换时要一起处理：

deerflow.db
deerflow.db-wal
deerflow.db-shm

4. 客户现场加载智能体和技能

推荐流程：

  1. 先启动一次，让目录自动生成。
  2. 停止容器。
  3. 复制客户的智能体、技能、SQLite 聊天库文件，并配置 MySQL 地址。
  4. 再启动容器。

命令示例：

cd "$DEPLOY_DIR"
./start-backend-docker.sh 8001
docker rm -f deerflow-backend

复制智能体：

mkdir -p "$DEPLOY_DIR/docker-data/.deer-flow/agents"
cp -a /path/to/customer-agents/. "$DEPLOY_DIR/docker-data/.deer-flow/agents/"

复制技能：

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/"

重新启动：

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

如果只更新技能或智能体，不换数据库，也可以复制后直接重启：

docker restart deerflow-backend

5. 修改或替换 SQLite 聊天/checkpointer 数据库

SQLite 只保存聊天运行时、LangGraph checkpointer、部分本地运行数据。业务表使用 MySQL，MySQL 地址见第 6 节。

最稳的方式是停容器后整体替换运行时目录：

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*：

$DEPLOY_DIR/docker-data/.deer-flow/data/deerflow.db*
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data/deerflow.db*

操作示例：

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. 修改配置和数据库配置

默认配置会在第一次启动时复制到：

$DEPLOY_DIR/docker-data/config/config.yaml

要改配置，改这个文件，不要进容器改。

本项目现场部署按 MySQL + SQLite 使用：

  • MySQL：业务表，例如用户、智能体、技能、任务、菜单、按钮、敏感词、轻应用等。
  • SQLite：聊天运行时和 LangGraph checkpointer，继续放在挂载出来的 .deer-flow 目录。
  • 不使用 PostgreSQL，不要配置 database.backend: postgres，也不要配置 POSTGRES_URL。

MySQL 地址主要改两个文件：

$DEPLOY_DIR/docker-data/config/config.yaml
$DEPLOY_DIR/docker-data/config/.env

config.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 连接地址：

MYSQL_DATABASE_URL=mysql+asyncmy://deerflow:密码@192.168.1.10:3306/deerflow?charset=utf8mb4

把上面示例里的内容换成客户现场真实值：

deerflow        # MySQL 用户名
密码            # MySQL 密码
192.168.1.10    # MySQL 服务器 IP
3306            # MySQL 端口
deerflow        # MySQL 数据库名

如果 MySQL 就装在 Docker 宿主机这台服务器上，容器里不要写 127.0.0.1，建议写：

MYSQL_DATABASE_URL=mysql+asyncmy://deerflow:密码@host.docker.internal:3306/deerflow?charset=utf8mb4

如果密码里有特殊字符，需要做 URL 编码，常见示例：

@  写成 %40
#  写成 %23
%  写成 %25
空格 写成 %20

MySQL 数据库建议提前建好：

CREATE DATABASE deerflow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

如果 MySQL 用户有建库权限，服务启动时也会尝试自动创建缺失的数据库。客户现场更稳的做法是先建库、导入 MySQL 备份，再启动后台。

如果客户现场已有 MySQL 备份，先在客户 MySQL 中导入：

mysql -h 192.168.1.10 -P 3306 -u deerflow -p deerflow < deerflow_mysql.sql

SQLite 聊天库仍按第 5 节复制到：

$DEPLOY_DIR/docker-data/.deer-flow/data/deerflow.db*
$DEPLOY_DIR/docker-data/.deer-flow/.deer-flow/data/deerflow.db*

如果需要把数据目录单独放到别的位置，不需要改 config.yaml，启动时指定 DATA_DIR 更稳：

cd "$DEPLOY_DIR"
DATA_DIR=/data/deerflow-backend-data ./start-backend-docker.sh 8001

此时实际目录变成：

/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，位置是：

$DEPLOY_DIR/docker-data/config/.env

修改配置后重启：

cd "$DEPLOY_DIR"
docker rm -f deerflow-backend
./start-backend-docker.sh 8001

7. 常用运维命令

查看容器：

docker ps -a --filter name=deerflow-backend

查看日志：

docker logs -f --tail 200 deerflow-backend

停止：

docker rm -f deerflow-backend

重启：

docker restart deerflow-backend

重新启动并换端口：

cd "$DEPLOY_DIR"
./start-backend-docker.sh 9001

检查接口：

curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/api/health

8. 交付清单

客户离线部署至少需要：

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