36a1c87d87
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
问题: 旧 wiki 按文档类型组织（architecture/data-flows/file-map）， 修复 Butler Router 需要读 4 个文件才能拼凑全貌。 且 SaaS Relay 主路径 vs 本地降级的优先级描述不准确。 重构为模块化结构，每个模块页自包含： - 设计思想: 为什么这样设计 - 代码逻辑: 数据流 + 关键代码 - 关联模块: 依赖关系 新增模块页: - routing.md: 客户端路由 (明确 SaaS Relay 是主路径，不是本地模式) - chat.md: 聊天系统 (3种实现 + Token Pool 中转机制) - butler.md: 管家模式 (路由/冷启动/痛点/双模式UI) - memory.md: 记忆管道 (提取→FTS5→检索→注入) - saas.md: SaaS平台 (认证/Token池/计费/Admin) - middleware.md: 中间件链 (14层 + 优先级) - hands-skills.md: Hands(9) + Skills(75) - pipeline.md: Pipeline DSL 删除旧文件: architecture.md, data-flows.md, module-status.md, file-map.md (内容已分布到对应模块页中) 添加 .gitignore 排除 Obsidian 工作区状态文件
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
---
|
||
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 + OsRng 盐验证密码
|
||
→ 签发 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 + OsRng 随机盐
|
||
TOTP 加密: AES-256-GCM + 随机 Nonce
|
||
```
|
||
|
||
### Token 刷新
|
||
|
||
```
|
||
POST /api/v1/auth/refresh
|
||
→ 验证 refresh_token (单次使用)
|
||
→ 旧 refresh_token 撤销到 DB (rotation 校验)
|
||
→ 签发新 access + refresh token
|
||
```
|
||
|
||
### SaaS API 分布
|
||
|
||
12 个路由模块，140 端点:
|
||
|
||
| 模块 | 端点数 | 说明 |
|
||
|------|--------|------|
|
||
| auth | ~10 | 登录/注册/刷新/2FA |
|
||
| relay | ~5 | 聊天中转/模型列表/任务 |
|
||
| billing | 10 | 配额/订阅/支付 |
|
||
| knowledge | 23 | 知识库 CRUD + pgvector |
|
||
| model_config | ~8 | Provider + 模型管理 |
|
||
| account | ~8 | 用户管理 |
|
||
| agent_template | ~8 | Agent 模板 |
|
||
| role | 11 | 角色 + 权限 |
|
||
| telemetry | ~5 | 用量统计 |
|
||
| prompt | ~5 | Prompt 模板 |
|
||
| scheduled_task | 5 | 定时任务 CRUD |
|
||
| migration | ~2 | Schema 迁移 |
|
||
|
||
### 数据表 (34 个)
|
||
|
||
核心: users, agents, conversations, messages, billing_*, knowledge_*, model_configs, roles, permissions, scheduled_tasks, telemetry, agent_templates, saas_schema_version
|
||
|
||
### Workers (7 个)
|
||
|
||
| Worker | 职责 |
|
||
|--------|------|
|
||
| log_operation | 操作日志 |
|
||
| cleanup_rate_limit | 限流记录清理 |
|
||
| cleanup_refresh_tokens | 刷新 token 清理 |
|
||
| record_usage | 用量记录 |
|
||
| update_last_used | 模型最后使用更新 |
|
||
| aggregate_usage | 用量聚合 |
|
||
| generate_embedding | 内容分块 (Phase 2 embedding deferred) |
|
||
|
||
## 关联模块
|
||
|
||
- [[routing]] — SaaS Relay 是 Tauri 的主路径
|
||
- [[chat]] — 聊天请求经过 SaaS relay 中转
|
||
- [[memory]] — knowledge_chunks 表有 pgvector 索引
|
||
|
||
## 关键文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `crates/zclaw-saas/src/auth/handlers.rs` | 认证端点 |
|
||
| `crates/zclaw-saas/src/relay/` | 聊天中转 |
|
||
| `crates/zclaw-saas/src/billing/` | 计费 |
|
||
| `crates/zclaw-saas/src/knowledge/` | 知识库 (23 API) |
|
||
| `crates/zclaw-saas/src/workers/` | 7 个后台 Worker |
|
||
| `crates/zclaw-saas/migrations/` | SQL 迁移 (34 表) |
|
||
| `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 加密密钥
|