iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
bd12bdb62b8bfe60cc3c35824325951aa98e4af8
zclaw_openfang/wiki/saas.md
iven 27b98cae6f
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
docs: wiki 全量更新 — 2026-04-14 代码验证驱动 
关键数字修正:
- Rust 77K行(274 .rs)、Tauri 189命令、SaaS 137 routes
- Admin V2 17页、SaaS 16模块(含industry)、@reserved 22
- SQL 20迁移/42表、TODO/FIXME 4个、dead_code 16

内容更新:
- known-issues: V13-GAP 全部标记已修复 + 三端联调测试结果
- middleware: 14层 runtime + 10层 SaaS HTTP 完整清单
- saas: industry模块、路由模块13个、数据表42个
- routing: Store含industryStore、21个Store文件
- butler: 行业配置接入ButlerPanel、4内置行业
- log: 三端联调+V13修复记录追加
2026-04-14 22:15:53 +08:00

4.9 KiB
Raw Blame History

title, updated, status, tags
title updated status tags
SaaS 平台 2026-04-14 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 模块结构（代码验证）

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

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

SaaS API 分布

137 个 .route() 调用，13 个路由模块 (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
industry industry/ 行业配置管理 (V13 新增)
migration migration/ Schema 迁移

数据表 (42 CREATE TABLE)

20 个 SQL 迁移文件，42 个 CREATE TABLE 语句。

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

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 路由注册入口 (13个 .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 迁移 (20 文件)
admin-v2/src/pages/ 17 页管理后台
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 加密密钥