iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
d40c4605b22a453648cf8598db189135143fcfe3
zclaw_openfang/docs/knowledge-base/architecture-refactoring.md
iven 8b9d506893 refactor(saas): 架构重构 + 性能优化 — 借鉴 loco-rs 模式 
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
2026-03-29 19:21:48 +08:00

2.7 KiB
Raw Blame History

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 配置示例

[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