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

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

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

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

单独新增切换脚本：

```powershell
cd offline-backend-20260512
.\switch_database_to_mysql.ps1
```

## 一、切换后的数据布局

迁移到 MySQL 的业务表：

```text
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：

```text
checkpoints
writes
```

Windows 本地默认 SQLite 路径：

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

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

## 二、前置条件

本机需要：

```text
Python 3.12+
uv
Windows 能访问的 MySQL
```

MySQL 建议提前建库：

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

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

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

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

```text
asyncmy==0.2.10
```

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

```powershell
$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 自动升级到当前代码版本：

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

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

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

```powershell
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
```

也可以直接用参数传入：

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

如果 SQLite 不在默认路径：

```powershell
.\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 表已有旧数据，并确认要清空后重迁：

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

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

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

## 四、脚本会自动做什么

`switch_database_to_mysql.ps1` 会自动：

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

```text
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
```

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

```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
```

## 五、验证

启动后端后检查：

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

功能验证：

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

## 六、回滚

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

```powershell
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 天前对话归档建议放在：

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

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

```text
%DEER_FLOW_HOME%\archives\conversations
```

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

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