zclaw_openfang/wiki/saas.md

title, updated, status, tags

title	updated	status	tags
SaaS 平台	2026-04-11	active	module saas auth billing

SaaS 平台

从 index 导航。关联模块: routing chat

设计思想

核心定位: SaaS 是 Tauri 桌面端的中枢，不是独立 Web 应用。

关键决策:

1. Token Pool — 桌面端不持有 LLM API Key，SaaS 维护共享 Key 池，RPM/TPM 轮换
2. JWT + Cookie 双通道 — Tauri 用 OS keyring 存 JWT，浏览器用 HttpOnly cookie
3. 计费闭环 — 配额实时递增 → 聚合器调度 → mock 支付路由
4. Admin V2 — 15 页管理后台，管理模型/用户/计费/知识库

代码逻辑

认证流

用户登录 (POST /api/v1/auth/login)
  → Argon2id + OsRg 盐验证密码
  → 签发 JWT (Claims: user_id, role, pwv)
  → set_auth_cookies():
      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
      zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly)
      Secure: dev=false, prod=true | SameSite=Strict

前端存储:
  → Tauri: OS keyring → saasStore.token
  → 浏览器: HttpOnly Cookie (JS 不可读)
  → localStorage: saasUrl + account 信息 (非敏感)

Token 池 + 限流

SaaS Relay 收到 LLM 请求 (POST /api/v1/relay/chat/completions)
  → 验证 JWT → 提取 user_id
  → 从 Token Pool 选择可用 Key (RPM/TPM 轮换)
  → 转发请求到真实 LLM API
  → 记录 usage (record_usage worker)
  → 返回响应

限流规则:
  → /api/auth/login: 5次/分钟/IP (防暴力) + 持久化到 PostgreSQL
  → /api/auth/register: 3次/小时/IP (防刷注册)
  → 公共端点: 20次/分钟/IP

密码安全

JWT password_version (pwv):
  → JWT Claims 含 pwv 字段
  → 每次验证 JWT 时比对 Claims.pwv vs DB.pwv
  → 修改密码 → DB.pwv 递增 → 所有旧 JWT 自动失效

密码存储: Argon2id + OsRg 随机盐
TOTP 加密: AES-256-GCM + 随机 Nonce

Token 刷新

POST /api/v1/auth/refresh
  → 验证 refresh_token (单次使用)
  → 旧 refresh_token 撤销到 DB (rotation 校验)
  → 签发新 access + refresh token

SaaS 模块结构（代码验证）

15 个模块目录 (crates/zclaw-saas/src/):

account/  agent_template/  auth/  billing/  knowledge/
migration/  model_config/  models/  prompt/  relay/
role/  scheduled_task/  tasks/  telemetry/  workers/

SaaS API 分布

121 个 .route() 调用，12 个路由模块 (main.rs .merge() 注册):

模块	路由注册	说明
auth	handlers.rs	登录/注册/刷新/2FA
relay	relay/	聊天中转/模型列表/任务
billing	billing/ + callback_routes	配额/订阅/支付
knowledge	knowledge/	知识库 CRUD + pgvector (最大模块)
model_config	model_config/	Provider + 模型管理
account	account/	用户管理
agent_template	agent_template/	Agent 模板
role	role/	角色 + 权限
telemetry	telemetry/	用量统计
prompt	prompt/	Prompt 模板
scheduled_task	scheduled_task/	定时任务 CRUD
migration	migration/	Schema 迁移

数据表 (38 CREATE TABLE)

32 个 SQL 迁移文件，38 个 CREATE TABLE 语句。

核心表: users, agents, conversations, messages, billing_, knowledge_, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version, user_profiles, trajectory_records

Workers (7 个)

Worker	文件	职责
log_operation	workers/	操作日志
cleanup_rate_limit	workers/	限流记录清理
cleanup_refresh_tokens	workers/	刷新 token 清理
record_usage	workers/	用量记录
update_last_used	workers/	模型最后使用更新
aggregate_usage	workers/	用量聚合
generate_embedding	workers/	内容分块 (embedding deferred)

关联模块

• routing — SaaS Relay 是 Tauri 的主路径
• chat — 聊天请求经过 SaaS relay 中转
• memory — knowledge_chunks 表有 pgvector 索引

关键文件

文件	职责
crates/zclaw-saas/src/main.rs	路由注册入口 (12个 .merge())
crates/zclaw-saas/src/auth/handlers.rs	认证端点
crates/zclaw-saas/src/relay/	聊天中转
crates/zclaw-saas/src/billing/	计费
crates/zclaw-saas/src/knowledge/	知识库
crates/zclaw-saas/src/workers/	7 个后台 Worker
crates/zclaw-saas/migrations/	SQL 迁移 (32 文件)
admin-v2/src/pages/	15 页管理后台
desktop/src/lib/saas-client.ts	前端 SaaS API 客户端
desktop/src/store/saasStore.ts	SaaS 认证状态

安全

完整审计: docs/features/SECURITY_PENETRATION_TEST_V1.md

• CORS 白名单 (生产缺失拒绝启动)
• Cookie Secure (dev=false, prod=true)
• JWT 签名密钥 >= 32 字符 (release fallback 拒绝启动)
• 独立 TOTP 加密密钥