2026-09-07 18:24:55 +08:00

5.3 KiB

Raw Blame History

Windows 本地版：业务库切换 MySQL 发版说明

适用场景：Windows 机器上直接在 offline-backend-20260512/backend 目录本地启动后端，不使用 Docker。

原本地启动方式保持不变：

cd offline-backend-20260512\backend
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001

单独新增切换脚本：

cd offline-backend-20260512
.\switch_database_to_mysql.ps1

一、切换后的数据布局

迁移到 MySQL 的业务表：

users
threads_meta
runs
run_events
feedback
agents
skills
scheduled_tasks
scheduled_task_runs
scheduled_task_subscriptions
scheduled_task_delivery_profiles
scheduler_threads
llm_call_metrics
notifications
recommended_questions
tags
tag_assignments
thread_shares

继续留在 SQLite：

checkpoints
writes

Windows 本地默认 SQLite 路径：

offline-backend-20260512\backend\.deer-flow\data\deerflow.db

如果你的本地 DEER_FLOW_HOME 或 SQLite 路径不是默认值，执行切换脚本时用 -SqliteDb 指定真实文件。

二、前置条件

本机需要：

Python 3.12+
uv
Windows 能访问的 MySQL

MySQL 建议提前建库：

CREATE DATABASE deerflow
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

如果 MySQL 就在 Windows 本机，连接串可以使用 127.0.0.1：

mysql+asyncmy://user:password@127.0.0.1:3306/deerflow?charset=utf8mb4

切换脚本会在本地 backend 的 uv 环境中安装：

asyncmy==0.2.10

如果本机不能访问公网 pip，请先在当前 PowerShell 配置内网 pip 私服：

$env:PIP_INDEX_URL='http://your-pip-mirror/simple'
$env:PIP_TRUSTED_HOST='your-pip-mirror'
$env:UV_INDEX_URL='http://your-pip-mirror/simple'
$env:UV_TRUSTED_HOST='your-pip-mirror'

三、发版步骤

先启动一次后端，让 SQLite schema 自动升级到当前代码版本：

cd offline-backend-20260512\backend
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001

确认服务正常后按 Ctrl + C 停止后端。

回到发版目录，执行一键切换：

cd offline-backend-20260512
$env:MYSQL_DATABASE_URL='mysql+asyncmy://user:password@127.0.0.1:3306/deerflow?charset=utf8mb4'
.\switch_database_to_mysql.ps1

也可以直接用参数传入：

.\switch_database_to_mysql.ps1 -MysqlDatabaseUrl 'mysql+asyncmy://user:password@127.0.0.1:3306/deerflow?charset=utf8mb4'

如果 SQLite 不在默认路径：

.\switch_database_to_mysql.ps1 `
  -SqliteDb 'D:\deerflow-data\data\deerflow.db' `
  -MysqlDatabaseUrl 'mysql+asyncmy://user:password@127.0.0.1:3306/deerflow?charset=utf8mb4'

如果目标 MySQL 表已有旧数据，并确认要清空后重迁：

.\switch_database_to_mysql.ps1 `
  -TruncateTarget 1 `
  -MysqlDatabaseUrl 'mysql+asyncmy://user:password@127.0.0.1:3306/deerflow?charset=utf8mb4'

切换完成后，继续用原本地启动方式：

cd backend
$env:PYTHONPATH='.'
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001

四、脚本会自动做什么

switch_database_to_mysql.ps1 会自动：

检查 uv、配置文件、迁移脚本、SQLite 文件是否存在。
备份：

backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\config.yaml.bak
backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\env.bak
backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\deerflow.db.bak

将 MYSQL_DATABASE_URL 写入 .env。
如果 backend\.venv 不存在，自动执行 uv venv。
执行 uv pip install asyncmy==0.2.10。
创建/升级 MySQL schema。
从 SQLite 迁移业务表到 MySQL。
校验每张业务表行数。
修改 config.yaml：

database:
  backend: mysql
  mysql_url: $MYSQL_DATABASE_URL
  pool_size: 10
  echo_sql: false

checkpointer:
  type: sqlite
  connection_string: D:\...\offline-backend-20260512\backend\.deer-flow\data\deerflow.db

五、验证

启动后端后检查：

(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8001/health).StatusCode

功能验证：

登录/退出
历史会话列表
打开旧会话
新建对话
定时任务
分享链接
后端日志无 MySQL driver 或连接错误

六、回滚

停止本地后端进程后恢复备份：

Copy-Item backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\config.yaml.bak config.yaml -Force
Copy-Item backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\env.bak .env -Force
Copy-Item backend\.deer-flow\backups\mysql-switch-YYYYMMDD_HHMMSS\deerflow.db.bak backend\.deer-flow\data\deerflow.db -Force

重新启动本地后端即可。

七、归档文件存储

后续 90 天前对话归档建议放在：

offline-backend-20260512\backend\.deer-flow\archives\conversations

如果你设置了自定义 DEER_FLOW_HOME，则放在：

%DEER_FLOW_HOME%\archives\conversations

Windows 本地版不涉及 Docker 挂载。这个目录只需要跟随你的本地数据目录一起备份即可。

归档文件被手动删除一部分时，正确行为应是该历史会话无法恢复并返回明确提示，不应该影响系统启动或 90 天内会话使用。归档功能正式实现时，需要把“归档文件缺失”作为可预期异常处理。

5.3 KiB Raw Blame History Unescape Escape