feat: 业务库切换 MySQL + 修复定时任务运行详情递归与重名 500
- 业务 ORM 数据支持 MySQL 后端(asyncmy),新增 PortableJSON/
BeijingDateTime 可移植列类型、迁移脚本与切库脚本
- 修复 GET /api/scheduled-tasks/runs/{id} 的 _load_run 无限递归
(误调用自身,应委托 service.get_run)导致的 RecursionError 500
- 定时任务名按用户唯一:create/update/admin_update 主动校验,
冲突抛 DuplicateTaskNameError,路由转 409 而非裸 IntegrityError 500
- 补充回归测试 test_scheduled_task_run_lookup / _name_uniqueness
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
d6f018e581
commit
358d5c72a6
40 files changed
+2128
-190
No files matched your search
@@ -0,0 +1,230 @@
|
||||
# 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 天内会话使用。归档功能正式实现时,需要把“归档文件缺失”作为可预期异常处理。
|
||||
Reference in new issue
Block a user