8b9d506893
Phase 0: 知识库
- docs/knowledge-base/loco-rs-patterns.md — loco-rs 10 个可借鉴模式研究
Phase 1: 数据层重构
- crates/zclaw-saas/src/models/ — 15 个 FromRow 类型化模型
- Login 3 次查询合并为 1 次 AccountLoginRow 查询
- 所有 service 文件从元组解构迁移到 FromRow 结构体
Phase 2: Worker + Scheduler 系统
- crates/zclaw-saas/src/workers/ — Worker trait + 5 个具体实现
- crates/zclaw-saas/src/scheduler.rs — TOML 声明式调度器
- crates/zclaw-saas/src/tasks/ — CLI 任务系统
Phase 3: 性能修复
- Relay N+1 查询 → 精准 SQL (relay/handlers.rs)
- Config RwLock → AtomicU32 无锁 rate limit (state.rs, middleware.rs)
- SSE std::sync::Mutex → tokio::sync::Mutex (relay/service.rs)
- /auth/refresh 阻塞清理 → Scheduler 定期执行
Phase 4: 多环境配置
- config/saas-{development,production,test}.toml
- ZCLAW_ENV 环境选择 + ZCLAW_SAAS_CONFIG 精确覆盖
- scheduler 配置集成到 TOML
68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
# zclaw-saas 架构重构完成记录
|
||
|
||
> 记录时间: 2026-03-29
|
||
> 本文档记录借鉴 loco-rs 模式对 zclaw-saas 后端进行的架构重构和性能优化。
|
||
|
||
## 重构概要
|
||
|
||
### Phase 0: 知识库
|
||
- `docs/knowledge-base/loco-rs-patterns.md` — loco-rs 10 个可借鉴模式研究
|
||
|
||
### Phase 1: 数据层重构
|
||
- `crates/zclaw-saas/src/models/` — 15 个 `#[derive(sqlx::FromRow)]` 类型化模型文件
|
||
- 替代了所有 `(String, String, ...)` 元组解构
|
||
- 编译期字段检查，消除运行时字段错位风险
|
||
- 3 次登录查询合并为 1 次 `AccountLoginRow` 查询
|
||
- Relay handler N+1 查询修复（精准 SQL 替代全量加载）
|
||
|
||
### Phase 2: Worker + Scheduler 系统
|
||
- `crates/zclaw-saas/src/workers/` — Worker trait + 5 个具体实现
|
||
- `LogOperationWorker` — 异步操作日志
|
||
- `CleanupRefreshTokensWorker` — 过期 token 清理
|
||
- `CleanupRateLimitWorker` — 限流条目清理
|
||
- `RecordUsageWorker` — 异步使用量记录
|
||
- `UpdateLastUsedWorker` — API token last_used_at 更新
|
||
- `crates/zclaw-saas/src/scheduler.rs` — TOML 声明式调度器
|
||
- 支持 `5m`/`1h`/`24h` 时间间隔格式
|
||
- 从配置文件加载，无需改代码调整调度
|
||
- `crates/zclaw-saas/src/tasks/` — CLI 任务系统
|
||
|
||
### Phase 3: 性能修复
|
||
| 问题 | 修复 | 文件 |
|
||
|------|------|------|
|
||
| Relay N+1 查询 | 精准 SQL 替代 `list_models()` 全量加载 | `relay/handlers.rs` |
|
||
| Config RwLock 竞争 | `Arc<AtomicU32>` 无锁 rate limit 读取 | `state.rs`, `middleware.rs` |
|
||
| SSE `std::sync::Mutex` | `tokio::sync::Mutex` 异步安全 | `relay/service.rs` |
|
||
| Login 3 次查询 | 合并为 1 次 `AccountLoginRow` 查询 | `auth/handlers.rs` |
|
||
| `/auth/refresh` 阻塞清理 | 迁移到 Scheduler 定期执行 | `auth/handlers.rs` |
|
||
|
||
### Phase 4: 多环境配置
|
||
- `config/saas-development.toml` — 开发环境
|
||
- `config/saas-production.toml` — 生产环境
|
||
- `config/saas-test.toml` — 测试环境
|
||
- `ZCLAW_ENV` 环境变量选择配置
|
||
- `ZCLAW_SAAS_CONFIG` 精确路径覆盖（最高优先级）
|
||
|
||
## 配置加载优先级
|
||
|
||
```
|
||
ZCLAW_SAAS_CONFIG (精确路径)
|
||
> ZCLAW_ENV (环境选择 config/saas-{env}.toml)
|
||
> saas-config.toml (默认)
|
||
```
|
||
|
||
## Scheduler 配置示例
|
||
|
||
```toml
|
||
[scheduler]
|
||
jobs = [
|
||
{ name = "cleanup_refresh_tokens", interval = "1h", task = "cleanup_refresh_tokens", run_on_start = false },
|
||
{ name = "cleanup_devices", interval = "24h", task = "cleanup_devices", run_on_start = true },
|
||
]
|
||
```
|
||
|
||
## 已知限制 / 待改进
|
||
- `log_operation()` 仍为同步调用（操作日志不是性能瓶颈，后续可按需迁移）
|
||
- TEXT 时间戳未迁移到 TIMESTAMPTZ（需要 SQL 迁移系统，影响范围大）
|
||
- 内联 SQL schema 未迁移到 `sqlx-cli` migrations
|