zclaw_openfang/docs/features/08-saas-platform/00-saas-overview.md

ZCLAW SaaS 平台 — 总览

最后更新: 2026-03-27 | 实施状态: Phase 1-4 + P2 全部完成

架构概述

ZCLAW SaaS 平台为桌面端用户提供云端能力，包括模型中转、账号管理、配置同步和团队协作。

桌面端 (Tauri/React)
    │
    ├── Mode A: Tauri Kernel (本地直连)
    ├── Mode B: Gateway WebSocket
    └── Mode C: SaaS Cloud ──→ Rust/Axum 后端 ──→ 上游 LLM Provider
                                │
                                ├── Admin Web (Next.js 管理后台)
                                └── PostgreSQL (数据持久化)

技术栈

层级	技术	说明
后端	Rust + Axum + sqlx + PostgreSQL	JWT + API Token 双认证
Admin	Next.js 14 + shadcn/ui + Tailwind	暗色 OLED 主题
桌面端	React 18 + Zustand + TypeScript	saas-client.ts HTTP 通信
安全	argon2 + TOTP 2FA + RBAC	速率限制 + 操作审计

功能模块

模块	完成度	核心能力
认证 (Auth)	100%	JWT + API Token + 密码修改 + /me + TOTP 2FA
账号 (Account)	100%	CRUD + 角色管理 + 自角色限制 + 设备管理
模型配置 (Model Config)	95%	Provider/Model/Key CRUD + 用量记录
中转 (Relay)	95%	SSE 流式 + 任务记录 + 指数退避重试 + Admin 重试
配置迁移 (Migration)	90%	CRUD + 同步日志 + push/merge + diff
Admin UI	95%	10 个 CRUD 页面 + Dashboard
桌面端集成	95%	登录/注册/状态/密码/设备/离线/迁移向导

API 端点一览

公开端点 (无需认证)

• POST /api/v1/auth/register — 注册
• POST /api/v1/auth/login — 登录
• GET /api/health — 健康检查

认证端点

• GET /api/v1/auth/me — 当前用户信息
• POST /api/v1/auth/refresh — 刷新 Token
• PUT /api/v1/auth/password — 修改密码

TOTP 双因素认证 (P2)

• POST /api/v1/auth/totp/setup — 生成 TOTP 密钥，返回 otpauth:// URI
• POST /api/v1/auth/totp/verify — 验证 TOTP 码并启用 2FA
• POST /api/v1/auth/totp/disable — 禁用 2FA (需密码确认)

账号管理

• GET /api/v1/accounts — 列出账号 (admin)
• GET /api/v1/accounts/:id — 获取账号
• PUT /api/v1/accounts/:id — 更新账号
• PATCH /api/v1/accounts/:id/status — 更新状态 (admin)
• GET /api/v1/stats/dashboard — 仪表盘统计 (admin)

API Token

• GET /api/v1/tokens — 列出 Token
• POST /api/v1/tokens — 创建 Token
• DELETE /api/v1/tokens/:id — 撤销 Token

设备管理

• POST /api/v1/devices/register — 注册/更新设备 (UPSERT)
• POST /api/v1/devices/heartbeat — 设备心跳
• GET /api/v1/devices — 列出设备

模型配置

• GET/POST /api/v1/providers — Provider CRUD
• GET/POST/PUT/DELETE /api/v1/providers/:id — 单个 Provider
• GET/POST /api/v1/models — Model CRUD
• GET/POST/PUT/DELETE /api/v1/models/:id — 单个 Model
• GET/POST/DELETE /api/v1/keys — API Key CRUD

中转 (Relay)

• GET /api/v1/relay/models — 可用中转模型
• POST /api/v1/relay/chat/completions — 聊天中转 (SSE/JSON)
• GET /api/v1/relay/tasks — 中转任务列表
• GET /api/v1/relay/tasks/:id — 获取单个任务
• POST /api/v1/relay/tasks/:id/retry — 重试失败任务 (admin)

配置

• GET /api/v1/config/items — 列出配置项
• POST /api/v1/config/items — 创建配置项
• GET /api/v1/config/items/:id — 获取配置项
• PUT /api/v1/config/items/:id — 更新配置项 (admin)
• DELETE /api/v1/config/items/:id — 删除配置项 (admin)
• GET /api/v1/config/analysis — 配置分析
• POST /api/v1/config/seed — 种子配置 (admin)
• POST /api/v1/config/sync — 配置同步 (push/merge)
• POST /api/v1/config/diff — 配置差异对比 (只读)
• GET /api/v1/config/sync-logs — 同步日志

审计

• GET /api/v1/logs/operations — 操作日志 (admin)
• GET /api/v1/usage — 用量统计

关键文件索引

后端 (crates/zclaw-saas/)

文件	职责
src/main.rs	服务启动 + ConnectInfo 注入
src/db.rs	数据库初始化 + Schema + Admin 引导
src/state.rs	AppState (DB + Config)
src/config.rs	配置结构体
src/error.rs	SaasError 枚举 + IntoResponse
src/middleware.rs	速率限制中间件
src/auth/mod.rs	JWT + API Token 中间件 + 路由
src/auth/handlers.rs	登录/注册/刷新/me/密码 (含 TOTP 登录验证)
src/auth/totp.rs	TOTP 2FA (setup/verify/disable)
src/auth/types.rs	AuthContext + Request/Response 类型
src/account/handlers.rs	账号 CRUD + Dashboard + 设备
src/model_config/handlers.rs	Provider/Model/Key CRUD
src/relay/handlers.rs + service.rs	SSE 中转 + 任务管理 + 指数退避重试
src/migration/handlers.rs + service.rs	配置 CRUD + 同步

Admin (admin/)

文件	职责
src/lib/api-client.ts	类型化 HTTP 客户端
src/lib/auth.ts	JWT 管理
src/app/(dashboard)/	10 个 CRUD 页面

桌面端 (desktop/src/)

文件	职责
lib/saas-client.ts	SaaS HTTP 客户端 (重试 + 离线检测)
store/saasStore.ts	SaaS 状态 (登录/设备/心跳)
components/SaaS/SaaSLogin.tsx	登录/注册 UI
components/SaaS/SaaSStatus.tsx	连接状态 + 可用模型
components/SaaS/SaaSSettings.tsx	设置页 (密码/迁移)
components/SaaS/ConfigMigrationWizard.tsx	3 步配置迁移向导