---
title: SaaS 平台
updated: 2026-04-11
status: active
tags: [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 加密密钥