zclaw_openfang/docs/features/SYSTEM_ARCHITECTURE.md

ZCLAW 多端系统架构文档

版本: 1.2 | 日期: 2026-04-01 | 状态: 已更新 (DeerFlow 视觉复刻 + 安全审计 V1 修复 + Admin V2 迁移)

---

目录

1. 系统总览
2. 端口与协议分配
3. 技术栈选型
4. 数据流向
5. SaaS 后端 API 接口清单
6. 桌面端内部通信
7. 权限体系
8. 各端交互逻辑
9. 部署与启动
10. 接口设计背景与业务价值

---

1. 系统总览

ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 4 个独立服务/端 组成：

┌─────────────────────────────────────────────────────────────────┐
│                        ZCLAW 系统架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  Desktop App  │  │  Admin V2    │  │  SaaS Backend        │  │
│  │  (Tauri+React)│  │  (Vite+AntD) │  │  (Axum + PostgreSQL) │  │
│  │  Port: 1420   │  │  Port: 5173  │  │  Port: 8080          │  │
│  │               │  │              │  │                      │  │
│  │  内核模式:     │  │  管理后台     │  │  REST API            │  │
│  │  Tauri IPC    │  │  JWT 鉴权     │  │  JWT + API Token     │  │
│  │               │  │              │  │  RBAC 权限            │  │
│  │  网关模式:     │  │              │  │                      │  │
│  │  WS :50051    │  │              │  │  ┌────────────────┐  │  │
│  │  WS :4200     │  │              │  │  │  PostgreSQL     │  │  │
│  │               │  │              │  │  │  Port: 5432    │  │  │
│  │  SaaS 模式:   │  │              │  │  └────────────────┘  │  │
│  │  HTTPS REST   │  │              │  │                      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐                             │
│  │  ZCLAW 网关   │  │  LLM 服务商  │                             │
│  │  (独立二进制) │  │  (外部)      │                             │
│  │  Port: 4200   │  │  OpenAI 等   │                             │
│  │  Port: 50051  │  │              │                             │
│  └──────────────┘  └──────────────┘                             │
└─────────────────────────────────────────────────────────────────┘

核心设计理念

• 双模式架构: 桌面端支持「本地内核」(离线/低延迟) 和「远程网关」(团队协作) 两种运行模式
• 统一 LLM 接入: 4 条 LLM 路径 (直连 OpenAI、直连火山引擎、SaaS 中转、网关透传)
• 集中管控: SaaS 后端统一管理账号、模型、服务商、Prompt 模板、配置同步
• 安全审计: 完整的操作日志 + TOTP 2FA + JWT + RBAC

---

2. 端口与协议分配

端口	服务	协议	用途	启动方式
1420	Vite Dev Server	HTTP	桌面端前端开发服务 (仅 dev)	pnpm tauri dev
3000	Next.js Dev Server	HTTP	旧 Admin 管理后台 (已废弃)	pnpm dev (admin/)
5173	Vite Dev Server	HTTP	Admin V2 管理后台开发服务	pnpm dev (admin-v2/)
4200	ZCLAW Gateway/Kernel	WebSocket + REST	网关备用端口	ZCLAW 二进制
50051	ZCLAW Gateway	WebSocket + REST	网关主端口	ZCLAW 二进制
5432	PostgreSQL	PostgreSQL Wire	SaaS 后端数据库	Docker/start-all.ps1
8080	SaaS Backend	HTTP REST	管理后台 API + 中转代理	start-saas.ps1
4444	ChromeDriver	WebDriver HTTP	浏览器 Hand 自动化	start-all.ps1
N/A	Tauri IPC	invoke()	桌面端内部进程通信	内嵌

---

3. 技术栈选型

3.1 桌面端 (Desktop)

层级	技术	选型理由
桌面框架	Tauri 2.x	Rust 原生性能，小体积，安全 IPC
前端框架	React 18 + TypeScript	生态丰富，类型安全
状态管理	Zustand	轻量、灵活、无 boilerplate
样式方案	Tailwind CSS	原子化 CSS，暗色主题友好
数据存储	SQLite (本地)	离线优先，FTS5 全文搜索

3.2 Admin V2 管理后台

层级	技术	选型理由
框架	React 19 + Vite 8	纯 SPA，快速构建
语言	TypeScript 5.9	类型安全
UI 组件	Ant Design 6 + Pro Components	企业级组件库，暗色主题
状态管理	Zustand 5	轻量灵活
数据获取	TanStack React Query 5	缓存+去重+自动重验证
路由	React Router 7	SPA 路由
HTTP	Axios	拦截器 + 401 自动刷新
样式	Tailwind CSS v4	原子化 CSS
测试	Vitest + Testing Library + MSW	完整测试覆盖

Admin V2 迁移说明: 从 Next.js + SWR + shadcn/ui 迁移到 Vite + React Query + Ant Design Pro，认证改为 HttpOnly Cookie 模式，11 个管理页面全部重写，含 71 个测试用例。

3.3 SaaS 后端

层级	技术	选型理由
Web 框架	Axum	Rust 高性能异步 Web 框架
数据库	PostgreSQL	关系型，复杂查询支持好
ORM	sqlx	编译时 SQL 检查，零开销
认证	JWT + TOTP	无状态鉴权 + 双因素认证
加密	AES-256-GCM	API Key 加密存储
后台任务	Worker trait + mpsc Channel	异步非阻塞，支持自动重试
定时任务	声明式 Scheduler (TOML)	无需改代码调整调度时间
连接池	sqlx PgPool (50 max / 5 min)	高并发，自动管理生命周期
迁移系统	SQL 文件 + Schema 版本控制	TIMESTAMPTZ 类型，向后兼容
多环境	ZCLAW_ENV (dev/prod/test)	配置隔离，环境变量覆盖

3.4 核心运行时 (Rust Workspace)

zclaw-types        → 基础类型 (AgentId, Message, Error)
zclaw-memory       → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
zclaw-runtime      → 运行时 (LLM 驱动, 11 层中间件, 工具, Agent 循环)
zclaw-kernel       → 核心协调 (注册, 调度, 事件, 9 Hands, 76 Skills)
zclaw-skills       → 技能系统 (SKILL.md 解析, 语义路由, DAG 编排)
zclaw-hands        → 自主能力 (9 个内置 Hand 实现)
zclaw-protocols    → 协议支持 (MCP, A2A)
zclaw-pipeline     → 流水线引擎 (v1/v2 DSL, Smart Presentation)
zclaw-growth       → 成长系统 (记忆提取/检索/注入, OpenViking 分层)
zclaw-saas         → SaaS 后端 (独立服务, 8080 端口, 58 API)

---

4. 数据流向

4.1 Admin V2 管理后台数据流

用户操作 → React UI → React Query → request.ts (Axios) → Vite Proxy → SaaS 后端 (:8080)
                ↑                                                          ↓
                └── React Query Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘

关键路径:

• Admin V2 所有请求通过 vite.config.ts proxy 代理到 localhost:8080
• API 基路径: /api/v1/* (前端) → http://localhost:8080/api/v1/* (后端)
• React Query 缓存: 自动去重 + stale-while-revalidate 模式
• SSE 端点 (/relay/chat/completions) 超时配置 10 分钟

4.2 桌面端数据流 (Tauri 模式)

React UI → Zustand Store → invoke() IPC → Rust Tauri Commands → Kernel → LLM/Tools/Skills/Hands
                                                       ↓
                                                  SQLite (~/.zclaw/data.db)

4.3 桌面端数据流 (网关模式)

React UI → gateway-client.ts → WebSocket (:50051) → ZCLAW Gateway → Kernel
                              → REST API (/api/*) →

4.4 桌面端数据流 (SaaS 模式)

React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
          llm-service.ts  → relay/chat/completions → Provider → LLM API

4.5 LLM 请求路由 (4 条路径)

┌─────────────┐    ┌─ Direct OpenAI ────→ api.openai.com
│             │    ├─ Direct Volcengine ─→ volcengine endpoint
│  llm-service│────┤
│             │    ├─ SaaS Relay ────────→ saas.zclaw.com/relay → Provider
│             │    └─ Gateway ───────────→ invoke('agent_chat') or REST
└─────────────┘

---

5. SaaS 后端 API 接口清单

5.0 通用规范

• Base URL: http://localhost:8080/api/v1
• 认证方式: Authorization: Bearer <JWT_TOKEN> 或 Authorization: Bearer zclaw_<API_KEY>
• Content-Type: application/json
• 分页响应格式: { items: T[], total: number, page: number, page_size: number }
• 错误响应格式: { error: string, message: string }
• HTTP 状态码: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Error

5.1 公开接口 (无需认证)

#	方法	路径	用途	业务价值
1	GET	/api/health	健康检查	运维监控探针，检测 DB 连通性
2	POST	/api/v1/auth/register	用户注册	自助开户，降低运营成本
3	POST	/api/v1/auth/login	用户登录	身份验证入口，支持 TOTP 2FA
4	POST	/api/v1/auth/refresh	Token 刷新	无感续期，单次使用 refresh_token

POST /api/v1/auth/login

请求:

{
  username: string      // 接受用户名或邮箱
  password: string      // 8-128 字符
  totp_code?: string    // 6 位数字，启用 TOTP 时必填
}

响应:

{
  token: string         // JWT access token
  refresh_token: string // 单次使用 refresh token
  account: AccountPublic
}

5.2 认证自服务接口 (需登录)

#	方法	路径	用途
5	GET	/api/v1/auth/me	获取当前用户信息
6	PUT	/api/v1/auth/password	修改密码
7	POST	/api/v1/auth/totp/setup	生成 TOTP 密钥
8	POST	/api/v1/auth/totp/verify	激活 TOTP 2FA
9	POST	/api/v1/auth/totp/disable	关闭 TOTP 2FA

5.3 账号管理接口 (Admin)

#	方法	路径	用途	权限
10	GET	/api/v1/accounts	账号列表 (支持搜索/筛选/分页)	account:admin
11	GET	/api/v1/accounts/:id	账号详情	account:admin
12	PATCH	/api/v1/accounts/:id	更新账号信息	account:admin
13	PATCH	/api/v1/accounts/:id/status	变更账号状态	account:admin
14	GET	/api/v1/logs/operations	操作日志列表	account:admin
15	GET	/api/v1/stats/dashboard	仪表盘统计聚合	account:admin
16	GET	/api/v1/devices	用户设备列表	认证用户
17	POST	/api/v1/devices/register	注册/更新设备	认证用户
18	POST	/api/v1/devices/heartbeat	设备心跳	认证用户

GET /api/v1/accounts 查询参数:

{
  page?: number          // 页码，默认 1
  page_size?: number     // 每页条数，默认 20
  search?: string        // 搜索用户名/邮箱/显示名
  role?: string          // 按角色筛选: super_admin | admin | user
  status?: string        // 按状态筛选: active | disabled | suspended
}

GET /api/v1/stats/dashboard 响应:

{
  total_accounts: number
  active_accounts: number
  tasks_today: number
  active_providers: number
  active_models: number
  tokens_today_input: number
  tokens_today_output: number
}

5.4 服务商管理接口

#	方法	路径	用途	权限
19	GET	/api/v1/providers	服务商列表	认证用户
20	GET	/api/v1/providers/:id	服务商详情	认证用户
21	POST	/api/v1/providers	创建服务商	provider:manage
22	PATCH	/api/v1/providers/:id	更新服务商	provider:manage
23	DELETE	/api/v1/providers/:id	删除服务商	provider:manage
24	GET	/api/v1/providers/:id/models	服务商下的模型列表	认证用户

Provider 数据结构:

{
  id: string
  name: string               // 唯一标识名，如 "openai"
  display_name: string       // 显示名，如 "OpenAI"
  base_url: string           // API 基地址
  api_protocol: 'openai' | 'anthropic'
  enabled: boolean
  rate_limit_rpm?: number    // 每分钟请求限制
  rate_limit_tpm?: number    // 每分钟 Token 限制
  created_at: string
  updated_at: string
}

5.5 模型管理接口

#	方法	路径	用途	权限
25	GET	/api/v1/models	模型列表	认证用户
26	GET	/api/v1/models/:id	模型详情	认证用户
27	POST	/api/v1/models	创建模型	model:manage
28	PATCH	/api/v1/models/:id	更新模型	model:manage
29	DELETE	/api/v1/models/:id	删除模型	model:manage

Model 数据结构:

{
  id: string
  provider_id: string
  model_id: string           // 如 "gpt-4o"
  alias: string              // 显示别名
  context_window: number     // 上下文窗口大小
  max_output_tokens: number  // 最大输出 Token
  supports_streaming: boolean
  supports_vision: boolean
  enabled: boolean
  pricing_input: number      // $/1M tokens
  pricing_output: number     // $/1M tokens
}

5.6 API Key 管理接口

#	方法	路径	用途	权限
30	GET	/api/v1/keys	当前用户的 API Key 列表	认证用户
31	POST	/api/v1/keys	创建 API Key	认证用户
32	POST	/api/v1/keys/:id/rotate	轮换 API Key	认证用户
33	DELETE	/api/v1/keys/:id	撤销 API Key	认证用户

5.7 Key Pool 管理接口 (Admin)

#	方法	路径	用途	权限
34	GET	/api/v1/providers/:id/keys	服务商 Key Pool 列表	provider:manage
35	POST	/api/v1/providers/:id/keys	添加 Key 到 Pool	provider:manage
36	PUT	/api/v1/providers/:id/keys/:keyId/toggle	启用/禁用 Key	provider:manage
37	DELETE	/api/v1/providers/:id/keys/:keyId	删除 Key	provider:manage

业务价值: Key Pool 实现多 API Key 智能轮转，自动绕过 429 限流，提升整体吞吐量。

5.8 中转代理接口 (Relay)

#	方法	路径	用途	权限
38	POST	/api/v1/relay/chat/completions	LLM 中转请求	relay:use
39	GET	/api/v1/relay/tasks	中转任务列表	认证用户
40	GET	/api/v1/relay/tasks/:id	任务详情	认证用户
41	POST	/api/v1/relay/tasks/:id/retry	重试失败任务	relay:admin
42	GET	/api/v1/relay/models	可用模型列表	认证用户

POST /api/v1/relay/chat/completions — 核心中转接口

请求: OpenAI 兼容格式

{
  model: string
  messages: Array<{ role: string, content: string }>
  temperature?: number
  max_tokens?: number
  stream?: boolean         // 支持 SSE 流式响应
  // ... 其他字段透传给服务商
}

响应:

• 非流式: application/json — 原始服务商响应
• 流式: text/event-stream — SSE 事件流

业务价值: 统一入口代理多家 LLM 服务商，自动 Key Pool 轮转、429 处理、用量计费。

5.9 用量统计接口

#	方法	路径	用途
43	GET	/api/v1/usage	用量统计 (按天/按模型)

查询参数:

{
  from?: string          // ISO 8601 开始日期
  to?: string            // ISO 8601 结束日期
  provider_id?: string   // 按服务商筛选
  model_id?: string      // 按模型筛选
  group_by?: 'day' | 'model'
  days?: number          // 最近 N 天
}

响应:

{
  total_requests: number
  total_input_tokens: number
  total_output_tokens: number
  by_model: Array<{ model_id, count, input_tokens, output_tokens }>
  by_day: Array<{ day, count, input_tokens, output_tokens }>
}

5.10 配置管理接口

#	方法	路径	用途	权限
44	GET	/api/v1/config/items	配置项列表	认证用户
45	GET	/api/v1/config/items/:id	配置项详情	认证用户
46	POST	/api/v1/config/items	创建配置项	config:write
47	PATCH	/api/v1/config/items/:id	更新配置项	config:write
48	DELETE	/api/v1/config/items/:id	删除配置项	config:write
49	GET	/api/v1/config/analysis	配置分析	认证用户
50	POST	/api/v1/config/seed	种子配置	config:write
51	POST	/api/v1/config/sync	双向配置同步	config:write
52	POST	/api/v1/config/diff	配置差异比较	认证用户
53	GET	/api/v1/config/sync-logs	同步日志	认证用户
54	GET	/api/v1/config/pull	批量拉取配置	认证用户

业务价值: 集中管理所有运行参数（服务器、Agent、记忆、LLM、安全策略），支持桌面端双向同步，推送/拉取/合并三种模式。

5.11 角色与权限接口

#	方法	路径	用途	权限
55	GET	/api/v1/roles	角色列表	account:read
56	GET	/api/v1/roles/:id	角色详情	account:read
57	POST	/api/v1/roles	创建角色	account:admin
58	PUT	/api/v1/roles/:id	更新角色	account:admin
59	DELETE	/api/v1/roles/:id	删除角色	account:admin
60	GET	/api/v1/roles/:id/permissions	角色权限列表	account:read
61	GET	/api/v1/permission-templates	权限模板列表	account:read
62	GET	/api/v1/permission-templates/:id	权限模板详情	account:read
63	POST	/api/v1/permission-templates	创建权限模板	account:admin
64	DELETE	/api/v1/permission-templates/:id	删除权限模板	account:admin
65	POST	/api/v1/permission-templates/:id/apply	批量应用权限模板	account:admin

5.12 Prompt 模板管理接口

#	方法	路径	用途	权限
66	GET	/api/v1/prompts	模板列表	prompt:read
67	POST	/api/v1/prompts	创建模板	prompt:write
68	GET	/api/v1/prompts/:name	模板详情	prompt:read
69	PUT	/api/v1/prompts/:name	更新模板元数据	prompt:write
70	DELETE	/api/v1/prompts/:name	归档模板	prompt:admin
71	GET	/api/v1/prompts/:name/versions	版本历史	prompt:read
72	GET	/api/v1/prompts/:name/versions/:v	特定版本	prompt:read
73	POST	/api/v1/prompts/:name/versions	发布新版本	prompt:write
74	POST	/api/v1/prompts/:name/rollback/:v	回滚版本	prompt:admin
75	POST	/api/v1/prompts/check	OTA 更新检查	认证用户

POST /api/v1/prompts/check — OTA 更新检查

请求:

{
  device_id: string
  versions: Record<string, number>  // { "reflection": 3, "compaction": 2 }
}

响应:

{
  updates: Array<{
    name: string
    version: number
    system_prompt: string
    user_prompt_template?: string
    variables: PromptVariable[]
    source: string
    min_app_version?: string
  }>
  server_time: string
}

业务价值: 集中管理 Prompt 模板，桌面端每 30 分钟检查更新，无需发版即可优化提示词。

5.13 Agent 模板管理接口

#	方法	路径	用途	权限
76	GET	/api/v1/agent-templates	Agent 模板列表	model:read
77	POST	/api/v1/agent-templates	创建 Agent 模板	model:manage
78	GET	/api/v1/agent-templates/:id	模板详情	model:read
79	POST	/api/v1/agent-templates/:id	更新模板	model:manage
80	DELETE	/api/v1/agent-templates/:id	归档模板	model:manage

AgentTemplate 数据结构:

{
  id: string
  name: string
  description?: string
  category: string
  source: 'builtin' | 'custom'
  model?: string
  system_prompt?: string
  tools: string[]
  capabilities: string[]
  temperature?: number
  max_tokens?: number
  visibility: 'public' | 'team' | 'private'
  status: 'active' | 'archived'
  current_version: number
}

5.14 遥测接口

#	方法	路径	用途	权限
81	POST	/api/v1/telemetry/report	上报遥测数据	认证用户
82	GET	/api/v1/telemetry/stats	按模型统计	认证用户
83	GET	/api/v1/telemetry/daily	按天统计	认证用户
84	POST	/api/v1/telemetry/audit	上报审计摘要	认证用户

POST /api/v1/telemetry/report 请求:

{
  device_id: string
  app_version: string
  entries: Array<{
    model_id: string
    input_tokens: number
    output_tokens: number
    latency_ms?: number
    success: boolean
    error_type?: string
    timestamp: string
    connection_mode: 'tauri' | 'saas'
  }>  // 最多 500 条/请求
}

业务价值: 桌面端批量上报本地 LLM 用量，管理员可在后台查看所有设备的 Token 消耗、延迟、成功率。

---

6. 桌面端内部通信

6.1 Tauri Commands 清单

桌面端通过 invoke() IPC 暴露以下命令组：

命令组	文件	命令数	用途
进程管理	lib.rs	10	zclaw_start/stop/restart, doctor, health_check
内核操作	kernel_commands.rs	34	agent_create/chat_stream, skill_execute, hand_execute, trigger, workflow
工作流	pipeline_commands.rs	10	pipeline_run/progress/cancel, route_intent
浏览器自动化	browser_commands.rs	22	navigate/click/fill/screenshot/evaluate
智能层	intelligence_commands.rs	35	memory/identity/reflection/heartbeat/autonomy
持久记忆	memory_commands.rs	14	memory_store/get/search/export/graph
Viking 存储	viking_commands.rs	13	viking_add/find/grep/read
CLI 工具	cli_commands.rs	13	doctor/health/export/import
安全存储	secure_storage.rs	4	store/get/delete/list
LLM 管理	llm_commands.rs	3	list_providers/test_connection

6.2 WebSocket 事件类型

方向	事件	说明
Server→Client	text_delta	流式文本片段
Server→Client	phase	阶段切换 (thinking/tool)
Server→Client	tool_call / tool_result	工具调用与结果
Server→Client	hand	Hand 自主能力触发
Server→Client	error	错误通知
Client→Server	message	发送消息
Client→Server	auth_challenge / auth_response	Ed25519 握手
双向	ping / pong	心跳 (30s 间隔)

---

7. 权限体系

7.1 角色定义

角色	权限范围
super_admin	全部权限 (admin:full)
admin	账号管理、服务商/模型管理、中转管理、配置读写、Prompt 读写发布
user	模型读取、中转使用、配置读取、Prompt 读取

7.2 权限清单

权限	说明
admin:full	超级权限，绕过所有检查
account:admin	账号管理 (列表、状态变更、角色分配)
account:read	读取账号、角色、权限模板
provider:manage	创建/更新/删除服务商、管理 Key Pool
model:manage	创建/更新/删除模型、Agent 模板
model:read	读取模型、Agent 模板
relay:use	使用中转 (chat completions)
relay:admin	查看任意中转任务、重试失败任务
config:write	创建/更新/删除配置项、同步、种子
prompt:read	读取 Prompt 模板和版本
prompt:write	创建/更新 Prompt 模板和版本
prompt:admin	归档 Prompt、回滚版本

---

8. 各端交互逻辑

8.1 Admin 管理后台 ↔ SaaS 后端

┌───────────────────────────────────────────────────────────┐
│  Admin V2 浏览器 (localhost:5173)                          │
│                                                           │
│  ┌──────────┐  React Query ┌──────────────┐              │
│  │ React UI │◄────────────►│ Axios        │              │
│  │ 11 页面   │  Cache       │ Cookie 认证   │              │
│  └──────────┘             └──────┬───────┘              │
│                                  │ axios()                │
└──────────────────────────────────┼────────────────────────┘
                                   │
                    Vite Proxy     │ /api/* → localhost:8080/api/*
                                   │
┌──────────────────────────────────┼────────────────────────┐
│  SaaS Backend (:8080)            │                        │
│                           ┌──────▼───────┐               │
│                           │  Axum Router  │               │
│                           │  中间件栈:     │               │
│                           │  1. Auth      │               │
│                           │  2. RateLimit │               │
│                           │  3. RequestID │               │
│                           │  4. Version   │               │
│                           └──────┬───────┘               │
│                                  │                        │
│                    ┌─────────────▼──────────────┐        │
│                    │  Handlers (58 个端点)       │        │
│                    │  auth/account/model/relay/  │        │
│                    │  config/prompt/telemetry/   │        │
│                    └─────────────┬──────────────┘        │
│                                  │                        │
│                    ┌─────────────▼──────────────┐        │
│                    │  PostgreSQL (:5432)          │        │
│                    └─────────────────────────────┘        │
└───────────────────────────────────────────────────────────┘

8.2 桌面端交互矩阵

场景	通信方式	目标	数据
本地对话	Tauri IPC invoke()	Kernel	消息、Agent、Skills
流式响应	Tauri Event listen()	Kernel	stream:chunk 事件
远程对话	WebSocket :50051	ZCLAW Gateway	消息、事件流
SaaS 登录	HTTPS REST	SaaS :8080	JWT 认证
LLM 中转	HTTPS REST	SaaS :8080/relay	OpenAI 兼容请求
Prompt OTA	HTTPS REST	SaaS :8080/prompts/check	版本号 → 更新
配置同步	HTTPS REST	SaaS :8080/config/sync	双向键值对
遥测上报	HTTPS REST	SaaS :8080/telemetry/report	批量用量数据

---

9. 部署与启动

9.1 完整启动顺序

# start-all.ps1 启动顺序:
1. PostgreSQL    → :5432 (Docker 或本地服务)
2. SaaS Backend  → :8080 (zclaw-saas.exe)
3. ChromeDriver  → :4444 (可选, 用于 Browser Hand)
4. Desktop Dev   → :1420 (Tauri dev)

9.2 SaaS 后端配置

配置加载优先级

ZCLAW_SAAS_CONFIG (精确路径) > ZCLAW_ENV (环境选择) > ./saas-config.toml (默认)

环境配置文件:

• ZCLAW_ENV=development -> config/saas-development.toml
• ZCLAW_ENV=production -> config/saas-production.toml
• ZCLAW_ENV=test -> config/saas-test.toml

环境变量覆盖:

• ZCLAW_DATABASE_URL — 覆盖数据库 URL (避免配置文件存密码)
• ZCLAW_SAAS_JWT_SECRET — JWT 签名密钥 (生产环境必须设置)
• ZCLAW_TOTP_ENCRYPTION_KEY — TOTP/AES-256-GCM 加密密钥 (hex 64 字符)
• ZCLAW_SAAS_DEV — 开发模式 (允许使用不安全的默认密钥)

配置结构

# saas-config.toml
[server]
host = "0.0.0.0"
port = 8080
cors_origins = []

[database]
url = "postgres://postgres:123123@localhost:5432/zclaw"

[auth]
jwt_expiration_hours = 24
totp_issuer = "ZCLAW SaaS"
refresh_token_hours = 168  # 7 天

[relay]
max_queue_size = 1000
max_concurrent_per_provider = 5  # 预留
batch_window_ms = 50             # 预留
retry_delay_ms = 1000
max_attempts = 3

[rate_limit]
requests_per_minute = 60
burst = 10

# 声明式定时任务 (新增)
[[scheduler.jobs]]
name = "cleanup-refresh-tokens"
interval = "1h"
task = "cleanup_refresh_tokens"
run_on_start = false

[[scheduler.jobs]]
name = "cleanup-rate-limit"
interval = "5m"
task = "cleanup_rate_limit"
run_on_start = false

连接池参数

参数	值	说明
max_connections	50	最大并发连接数
min_connections	5	最小空闲连接数
acquire_timeout	10s	获取连接超时
idle_timeout	300s	空闲连接回收
max_lifetime	1800s	连接最大生命周期

Worker 系统

Worker	职责	触发方式
LogOperationWorker	异步写入操作日志	Handler 派发
CleanupRefreshTokensWorker	清理过期 Refresh Token	Scheduler 定时
CleanupRateLimitWorker	清理过期限流条目	Scheduler 定时
RecordUsageWorker	记录 Token 用量	Relay Handler 派发
UpdateLastUsedWorker	更新 Key 最后使用时间	Relay Handler 派发

SQL 迁移系统

• Schema 版本: v6
• 迁移目录: crates/zclaw-saas/migrations/
• 时间戳类型: TIMESTAMPTZ (新库)，向后兼容 TEXT (旧库)
• 迁移文件按文件名排序执行

---

10. 接口设计背景与业务价值

10.1 中转代理 (Relay) — 核心收入引擎

背景: 多家 LLM 服务商 API 各不相同，用户需统一入口。

设计价值:

• OpenAI 兼容接口降低接入成本
• Key Pool 智能轮转绕过限流
• 自动 429 处理 + 冷却恢复
• 按账号精确计费 (input/output tokens)

10.2 Prompt OTA — 无感更新

背景: Prompt 工程需要频繁迭代，但桌面端发版周期长。

设计价值:

• 集中管理 reflection/compaction/extraction 等核心 Prompt
• 桌面端每 30 分钟自动检查更新
• 版本化 + 回滚能力
• min_app_version 兼容性控制

10.3 配置同步 — 多设备一致

背景: 用户多台设备需保持配置一致。

设计价值:

• push/pull/merge 三种同步模式
• 乐观锁 (client_timestamps) 冲突检测
• 只读 diff 不修改数据
• 同步日志可追溯

10.4 Key Pool — 高可用保障

背景: 单个 API Key 容易触发限流 (429)。

设计价值:

• 多 Key 按优先级智能选择
• 429 自动冷却 + 切换
• RPM/TPM 限额独立配置
• 配额重置周期支持

10.5 遥测上报 — 数据驱动优化

背景: 桌面端本地 LLM 用量无法直接观测。

设计价值:

• 批量上报 (500 条/次) 减少请求
• 按模型聚合: Token 消耗、延迟、成功率
• 按天聚合: 请求量、设备活跃度
• 审计摘要: 操作类型 + 结果

---

文档统计: 58 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务 | 5 个 Workers | 声明式 Scheduler | SQL Schema v8