iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
7de294375b047472efbb37e2a322db4d524dfe3e
zclaw_openfang/docs/features/08-saas-platform/00-saas-overview.md
iven 7de294375b
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
feat(auth): 添加异步密码哈希和验证函数 
refactor(relay): 复用HTTP客户端和请求体序列化结果

feat(kernel): 添加获取单个审批记录的方法

fix(store): 改进SaaS连接错误分类和降级处理

docs: 更新审计文档和系统架构文档

refactor(prompt): 优化SQL查询参数化绑定

refactor(migration): 使用静态SQL和COALESCE更新配置项

feat(commands): 添加审批执行状态追踪和事件通知

chore: 更新启动脚本以支持Admin后台

fix(auth-guard): 优化授权状态管理和错误处理

refactor(db): 使用异步密码哈希函数

refactor(totp): 使用异步密码验证函数

style: 清理无用文件和注释

docs: 更新功能全景和审计文档

refactor(service): 优化HTTP客户端重用和请求处理

fix(connection): 改进SaaS不可用时的降级处理

refactor(handlers): 使用异步密码验证函数

chore: 更新依赖和工具链配置
2026-03-29 21:45:29 +08:00

251 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ZCLAW SaaS 平台 — 总览
> 最后更新: 2026-03-29 | 实施状态: Phase 1-4 全部完成 + 架构重构完成，9 个后端模块 + Worker + Scheduler + Admin 管理后台 + 桌面端完整集成
## 架构概述
ZCLAW SaaS 平台为桌面端用户提供云端能力，包括模型中转（Key 池）、账号管理、配置同步、Prompt OTA、Agent 模板和遥测收集。
```text
桌面端 (Tauri/React)
│
├── Mode A: Tauri Kernel (本地直连 LLM)
├── Mode B: Gateway WebSocket (本地中转)
└── Mode C: SaaS Cloud ──→ Rust/Axum 后端 (端口 8080) ──→ 上游 LLM Provider
│
├── Admin Web (Next.js 管理后台)
└── PostgreSQL (数据持久化)
```
## 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Rust + Axum + sqlx + PostgreSQL | JWT + API Token 双认证，RBAC 权限 |
| Admin | Next.js 14 + shadcn/ui + Tailwind | 暗色 OLED 主题，20+ 页面 |
| 桌面端 | React 18 + Zustand + TypeScript | saas-client.ts 30+ API 方法 |
| 安全 | Argon2id + TOTP 2FA (AES-256-GCM) + RBAC | 速率限制 + 操作审计 + SSRF 防护 |
## 数据库
- **引擎**: PostgreSQL (sqlx 异步驱动)
- **Schema 版本**: v6 (TIMESTAMPTZ 时间戳类型)
- **数据表**: 25 张 (accounts, providers, models, relay_tasks, prompt_templates, agent_templates, telemetry_reports 等)
- **种子数据**: 3 个系统角色 (super_admin, admin, user)，3 个内置 Prompt 模板
- **迁移系统**: 声明式 SQL 文件 (`crates/zclaw-saas/migrations/`)，按文件名排序执行
- **连接池**: 50 max / 5 min 连接，10s 获取超时，300s 空闲超时，1800s 最大生命周期
## 功能模块
| 模块 | 完成度 | API 路由数 | 核心能力 |
|------|--------|-----------|----------|
| 认证 (Auth) | 100% | 8 | JWT + API Token 双认证、注册/登录、密码修改、/me、TOTP 2FA (AES-256-GCM 加密) |
| 账号 (Account) | 100% | 12 | CRUD + 角色管理 + 角色提升防护 + 设备注册/心跳 + 操作日志 + Dashboard 统计 |
| 模型配置 (Model Config) | 100% | 14 | Provider/Model/Key CRUD + Key 轮换 + 用量统计 (按天/按模型聚合) |
| 中转 (Relay) | 100% | 9 | SSE 流式 + JSON 响应 + Key 池管理 + RPM/TPM 限制 + 指数退避重试 + SSRF 防护 |
| 配置迁移 (Migration) | 100% | 9 | 配置 CRUD + 分析 + 种子数据 (21 项默认) + push/merge 同步 + diff 对比 + 增量拉取 |
| 角色 (Role) | 100% | 7 | Role CRUD + 系统角色保护 + 权限模板 + 批量应用 |
| Prompt OTA | 100% | 8 | 模板 + 版本管理 + OTA 批量检查 + 版本回滚 + 不可变版本历史 |
| Agent 模板 | 100% | 5 | 模板 CRUD + tools/capabilities/model 绑定 + 可见性控制 |
| 遥测 (Telemetry) | 100% | 4 | 批量 Token 用量上报 + 模型聚合统计 + 每日统计 + 审计摘要 |
| **Worker 系统** | 100% | — | 5 个 Worker (log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used)，mpsc 异步调度，自动重试 |
| **声明式 Scheduler** | 100% | — | TOML 配置定时任务，灵活间隔 (30s/5m/1h/1d)，run_on_start，内置 DB 清理 |
| **合计** | — | **76+** | — |
## API 端点一览
### 公开端点 (无需认证)
- `POST /api/v1/auth/register` — 注册
- `POST /api/v1/auth/login` — 登录 (支持 TOTP 验证)
- `GET /api/health` — 健康检查
### 认证 (Auth)
- `GET /api/v1/auth/me` — 当前用户信息
- `POST /api/v1/auth/refresh` — 刷新 Token
- `PUT /api/v1/auth/password` — 修改密码
- `POST /api/v1/auth/totp/setup` — 生成 TOTP 密钥，返回 otpauth:// URI
- `POST /api/v1/auth/totp/verify` — 验证 TOTP 码并启用 2FA
- `POST /api/v1/auth/totp/disable` — 禁用 2FA (需密码确认)
### 账号管理 (Account)
- `GET /api/v1/accounts` — 列出账号 (admin，分页 + 角色/状态/搜索过滤)
- `GET /api/v1/accounts/:id` — 获取账号
- `PATCH /api/v1/accounts/:id` — 更新账号 (自更新有限字段，admin 可设置角色)
- `PATCH /api/v1/accounts/:id/status` — 更新状态 (admin: active/disabled/suspended)
- `GET /api/v1/tokens` — 列出 API Token
- `POST /api/v1/tokens` — 创建 API Token (权限限制为创建者子集)
- `DELETE /api/v1/tokens/:id` — 撤销 Token
- `GET /api/v1/devices` — 列出当前用户设备
- `POST /api/v1/devices/register` — 注册/更新设备 (UPSERT)
- `POST /api/v1/devices/heartbeat` — 设备心跳
- `GET /api/v1/logs/operations` — 操作日志 (admin，分页)
- `GET /api/v1/stats/dashboard` — 仪表盘统计 (admin)
### Provider / Model / Key 管理
- `GET/POST /api/v1/providers` — Provider 列表/创建
- `GET/PATCH/DELETE /api/v1/providers/:id` — 单个 Provider
- `GET /api/v1/providers/:id/models` — Provider 下的模型列表
- `GET/POST /api/v1/models` — Model 列表/创建
- `GET/PATCH/DELETE /api/v1/models/:id` — 单个 Model
- `GET/POST /api/v1/keys` — 账号 API Key 列表/创建
- `POST /api/v1/keys/:id/rotate` — 轮换 API Key
- `DELETE /api/v1/keys/:id` — 撤销 API Key
- `GET /api/v1/usage` — 用量统计 (按日期/模型/Provider 过滤)
### 中转 (Relay)
- `GET /api/v1/relay/models` — 可用中转模型
- `POST /api/v1/relay/chat/completions` — OpenAI 兼容聊天中转 (SSE/JSON)
- `GET /api/v1/relay/tasks` — 中转任务列表 (分页 + 状态过滤)
- `GET /api/v1/relay/tasks/:id` — 获取单个任务
- `POST /api/v1/relay/tasks/:id/retry` — 重试失败任务 (admin)
- `GET /api/v1/providers/:provider_id/keys` — Provider Key 池列表 (admin)
- `POST /api/v1/providers/:provider_id/keys` — 添加 Key 到池 (admin)
- `PUT /api/v1/providers/:provider_id/keys/:key_id/toggle` — 切换 Key 启停 (admin)
- `DELETE /api/v1/providers/:provider_id/keys/:key_id` — 删除池中 Key (admin)
### 配置迁移 (Migration)
- `GET /api/v1/config/items` — 列出配置项 (分页 + 分类/来源过滤)
- `GET /api/v1/config/items/:id` — 获取配置项
- `POST /api/v1/config/items` — 创建配置项 (admin)
- `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，21 项默认含 11 项安全策略)
- `POST /api/v1/config/sync` — 配置同步 (push/merge 模式)
- `POST /api/v1/config/diff` — 配置差异对比 (只读)
- `GET /api/v1/config/sync-logs` — 同步日志 (分页)
- `GET /api/v1/config/pull` — 批量拉取配置 (支持 since 增量)
### 角色 (Role)
- `GET /api/v1/roles` — 列出角色
- `GET/POST /api/v1/roles/:id` — 角色 CRUD (系统角色不可修改/删除)
- `PUT/DELETE /api/v1/roles/:id` — 更新/删除角色 (admin)
- `GET /api/v1/permission-templates` — 权限模板列表
- `POST /api/v1/permission-templates` — 创建模板 (admin)
- `POST /api/v1/permission-templates/:id/apply` — 批量应用模板到账号
### Prompt OTA
- `POST /api/v1/prompts/check` — OTA 批量检查更新 (设备上报版本，返回差量)
- `GET /api/v1/prompts` — 列出模板 (分页 + 分类/来源/状态过滤)
- `POST /api/v1/prompts` — 创建模板 + 初始 v1
- `GET /api/v1/prompts/:name` — 按名称获取模板
- `PUT /api/v1/prompts/:name` — 更新模板元数据
- `DELETE /api/v1/prompts/:name` — 归档模板
- `GET /api/v1/prompts/:name/versions` — 版本历史
- `GET /api/v1/prompts/:name/versions/:version` — 获取特定版本
- `POST /api/v1/prompts/:name/versions` — 发布新版本 (自动递增)
- `POST /api/v1/prompts/:name/rollback/:version` — 回滚到指定版本
### Agent 模板
- `GET /api/v1/agent-templates` — 列出模板 (分页 + 分类/来源/可见性过滤)
- `POST /api/v1/agent-templates` — 创建模板
- `GET /api/v1/agent-templates/:id` — 获取模板
- `POST /api/v1/agent-templates/:id` — 更新模板
- `DELETE /api/v1/agent-templates/:id` — 归档模板
### 遥测 (Telemetry)
- `POST /api/v1/telemetry/report` — 批量上报 Token 用量 (每次最多 500 条)
- `GET /api/v1/telemetry/stats` — 模型聚合统计 (请求次数/Token/延迟/成功率)
- `GET /api/v1/telemetry/daily` — 每日使用量聚合 (按设备去重)
- `POST /api/v1/telemetry/audit` — 批量审计日志摘要 (仅动作类型和计数)
## 安全特性
| 特性 | 实现 |
|------|------|
| 密码存储 | Argon2id + 随机盐 |
| TOTP 2FA | AES-256-GCM 加密密钥 + 兼容旧版明文格式 |
| JWT | RS256/HS256，支持过期 Token 刷新 |
| API Token | `zclaw_` 前缀，SHA-256 哈希存储 |
| RBAC | 三级系统角色 + 自定义角色 + 权限模板 |
| 角色提升防护 | 自更新时禁止修改 role 字段 |
| 速率限制 | 滑动窗口 per-account (可配置 RPM) |
| SSRF 防护 | 私有 IP/回环/元数据端点/十六进制 IP/DNS 解析检查 |
| Key 池安全 | RPM/TPM 限制 + 429 自动冷却 + Retry-After 支持 |
| 审计日志 | 所有写操作记录，500 错误不暴露内部细节 |
## 中转 (Relay) 核心流程
```text
客户端请求 → Auth 中间件 → Relay Handler
│
├── 1. select_best_key() — 选择最优 Key (非冷却 + 未超 RPM/TPM + 优先级)
│ └── Key 池耗尽 → 回退到 Provider 级单 Key
│
├── 2. execute_relay() — 向上游发送请求
│ ├── SSE 流式: 捕获流事件中的 usage，异步记录
│ └── JSON: 从响应提取 usage，同步记录
│
├── 3. 重试策略 — max_attempts (默认 3)
│ ├── 429: 标记 Key 冷却 → 立即切换下一个 Key (不等待)
│ └── 其他错误: 指数退避重试
│
└── 4. SSRF 防护 — 验证 Provider URL，阻断私有网络请求
```
## 配置同步模式
| 模式 | 行为 | 使用场景 |
|------|------|---------|
| push | 客户端覆盖 SaaS 值，缺失则创建 | 新设备首次同步 |
| merge | 仅填充 SaaS 空值，冲突时 SaaS 优先 | 多设备合并 |
| diff | 只读对比，返回差异列表 | 同步前预览 |
| pull | 批量拉取，支持 since 增量 | 定期同步 |
## 关键文件索引
### 后端 (crates/zclaw-saas/)
| 文件 | 职责 |
|------|------|
| `src/main.rs` | 服务启动 + 路由注册 + 后台任务 (速率限制清理 + 设备清理) |
| `src/db.rs` | 数据库初始化 + Schema v6 + TIMESTAMPTZ 迁移 + 25 张表 + Admin 引导 |
| `src/state.rs` | AppState (PgPool + Config + JWT Secret + 速率限制 DashMap + WorkerDispatcher) |
| `src/config.rs` | SaaSConfig (Server/Database/Auth/Relay/RateLimit/Scheduler)，多环境配置加载 |
| `src/error.rs` | SaasError 16 种变体 + HTTP 状态码映射 |
| `src/middleware.rs` | Request-ID + API-Version + 速率限制中间件 |
| `src/common.rs` | PaginatedResponse<T> + 分页工具函数 |
| `src/auth/` | JWT + API Token 双认证 + TOTP 2FA + 密码管理 |
| `src/account/` | 账号 CRUD + 设备管理 + Dashboard + API Token |
| `src/model_config/` | Provider/Model/AccountKey CRUD + 用量统计 |
| `src/relay/` | SSE/JSON 中转 + Key 池 + 重试 + SSRF 防护 |
| `src/relay/key_pool.rs` | Key 池选择算法 + RPM/TPM 跟踪 + 冷却管理 |
| `src/migration/` | 配置 CRUD + 同步 (push/merge) + diff + 增量 pull |
| `src/role/` | 角色 CRUD + 权限模板 + 批量应用 |
| `src/prompt/` | Prompt 模板 + 版本管理 + OTA 检查 + 回滚 |
| `src/agent_template/` | Agent 模板 CRUD + 可见性控制 |
| `src/telemetry/` | Token 用量上报 + 模型统计 + 每日统计 + 审计摘要 |
| `src/workers/` | Worker 系统 (5 Worker: log_operation, cleanup_rate_limit, cleanup_refresh_tokens, record_usage, update_last_used) |
| `src/scheduler.rs` | 声明式 Scheduler (TOML 定时任务配置 + DB 清理任务) |
| `migrations/` | SQL 迁移文件 (Schema v6, TIMESTAMPTZ) |
### Admin 管理后台 (admin/)
| 文件 | 职责 |
|------|------|
| `src/lib/api-client.ts` | 类型化 HTTP 客户端 (自动 Token 刷新 + 重试) |
| `src/lib/types.ts` | 全部 TypeScript 类型定义 |
| `src/lib/auth.ts` | JWT Token 管理 (localStorage) |
| `src/app/(dashboard)/layout.tsx` | Dashboard 布局 + 导航 |
| `src/app/(dashboard)/providers/page.tsx` | Provider 管理 |
| `src/app/(dashboard)/config/page.tsx` | 配置管理 |
| `src/app/(dashboard)/usage/page.tsx` | 用量统计 |
| `src/app/(dashboard)/prompts/` | Prompt 模板管理 |
| `src/app/(dashboard)/agent-templates/` | Agent 模板管理 |
| `src/app/login/page.tsx` | 登录页 |
### 桌面端 (desktop/src/)
| 文件 | 职责 |
|------|------|
| `lib/saas-client.ts` | SaaS HTTP 客户端 (30+ API 方法 + 自动重试 + 离线检测) |
| `store/saasStore.ts` | SaaS 状态管理 (登录/设备/心跳/配置同步/遥测) |
| `lib/telemetry-collector.ts` | 遥测数据采集器 |
| `components/SaaS/SaaSStatus.tsx` | 连接状态 + 可用模型 |
| `components/SaaS/SaaSSettings.tsx` | 设置页 (密码/TOTP/迁移) |
| `components/LoginPage.tsx` | 登录/注册 UI |
---
**最后更新**: 2026-03-28
Reference in New Issue View Git Blame Copy Permalink