zclaw_openfang/docs/audit-2026-03-30.md

ZCLAW 全面项目审计报告

审计日期: 2026-03-30 审计范围: 系统架构、代码质量、性能、安全、业务功能、用户体验 审计基准: v0.7.0，基于 F16/S2/S4/S8 完成后的代码状态 审计方法: 5 个并行子代理 + 直接代码分析

---

一、执行摘要

总体评级: B+ (良好)

维度	评级	关键发现
系统架构	A-	10 Crate 分层清晰，SaaS 独立，feature gate 全覆盖
代码质量	B	0 编译警告，453 测试，但多文件超限，53 处 Promise<any>
安全性	B	Cookie 已实现，SQL 全参数化，但登出未撤 token，无 TLS
性能	B	连接池健康检查完备，但 SSE 不响应 shutdown，表无自动清理
业务功能	A-	93 API，9 Hands，66 Skills，前后端对齐，SaaS 定时任务执行未闭环

关键数字

指标	数值
Rust 代码行数	54,380
SaaS API 端点	93 (10 模块)
Tauri 命令	106
测试数量	453 (254 unit + 199 async)
Hands	9
Skills	66 SKILL.md
Pipeline YAML	7
编译警告	0 (项目自有)
TypeScript 错误	0

---

二、系统架构审计

2.1 Crate 分层 ✅

L1: zclaw-types (无 zclaw 依赖) ✅
L1.5: zclaw-growth (仅依赖 types) — 目录在 L5 但依赖在 L1
L2: zclaw-memory (→ types)
L3: zclaw-runtime (→ types, memory, growth)
L4: zclaw-kernel (→ types, memory, runtime, protocols, hands, skills)
L5: zclaw-skills (→ types), zclaw-hands (→ types, runtime), zclaw-protocols (→ types)
    zclaw-pipeline (→ types, runtime, kernel, skills, hands)
独立: zclaw-saas (仅依赖 zclaw-types) ✅

架构代理验证结果:

• ✅ 无循环依赖（DAG）
• ✅ SaaS 独立于 Kernel
• ✅ workspace members 完整
• ✅ multi-agent feature 传播链正确: desktop → kernel → protocols/a2a
• ✅ wasm feature gate 完整
• ✅ dev-server feature gate 完整
• ℹ️ zclaw-growth 目录位置与依赖层级不一致（不影响功能）
• ℹ️ zclaw-pipeline 声明了 zclaw-kernel 依赖但代码中未直接 import

2.2 数据流完整性 ✅

链路	状态	覆盖
Desktop UI → Store → Tauri → Kernel → LLM/Hands/Skills	✅ 完整	106 个 Tauri 命令
Admin V2 → Axios → SaaS API → PostgreSQL	✅ 完整	12 个 service 文件
Pipeline YAML → Executor → LLM/Skill/Hand Actions	✅ 完整	三种 Action driver 均已接通

---

三、代码质量审计

3.1 编译状态 ✅

• cargo check --workspace: 0 项目警告
• admin-v2 tsc --noEmit: 通过
• desktop tsc --noEmit: 通过

3.2 大文件审计 ⚠️

Rust 文件（>800 行）:

文件	行数	建议
kernel_commands.rs	2185	按功能域拆分
lib.rs (desktop)	1518	命令定义独立
kernel.rs	1490	拆分 a2a/scheduler 子模块
pipeline_commands.rs	1391	按 stage 拆分
generation.rs	1080	逻辑连贯，可保持
quiz.rs	1027	题目模板导致
openai.rs	912	拆分 streaming 子模块
director.rs	912	拆分 turn/submission
loop_runner.rs	896	拆分 tool execution
store.rs	804	拆分 query builder

TypeScript 文件（>800 行）:

文件	行数	类型安全
intelligence-client.ts	1471	低风险
kernel-client.ts	1343	低风险
saas-client.ts	1290	低风险
gateway-client.ts	1227	53 处 Promise<any>
gateway-api.ts	672	同上

3.3 unwrap() 使用 ⚠️

• 68 个 Rust 文件含 unwrap()，生产代码约 108 处
• store.rs 独占 75 处（最高风险）
• P0 风险: extraction_adapter.rs:306-310 链式 unwrap（LLM 返回异常格式时 panic）
• P1 风险: context_builder.rs 多处 HashMap get_mut().unwrap()

3.4 TypeScript 类型安全

• 0 处 @ts-ignore / @ts-nocheck
• 53 处 Promise<any> 在 gateway-client.ts + gateway-api.ts（最大类型安全盲区）
• 6 处静默 catch(() => {})（saasStore.ts 3 处应添加日志）
• 33 处 #[allow(dead_code)]（半数标注 "reserved"，需定期审视）

3.5 测试覆盖

Crate	测试数	评价
zclaw-saas	111	良好
zclaw-growth	75	良好
zclaw-pipeline	59	良好
zclaw-types	57	良好
zclaw-runtime	42	中等
zclaw-kernel	41	需提升
zclaw-skills	22	需提升
zclaw-hands	21	需提升
zclaw-memory	20	需提升
zclaw-protocols	5	不足

---

四、安全审计

4.1 安全发现汇总

级别	ID	问题	文件
HIGH	SEC-02	saas-config.toml 含明文 DB 密码	saas-config.toml:16
HIGH	SEC-03	ShellSkill SKILL.md 命令注入信任模型	skills/runner.rs:125
HIGH	SEC-04	服务端无 TLS 终止	saas/main.rs:72
HIGH	SEC-05	JWT debug fallback 密钥硬编码	saas/config.rs:238
MED	SEC-06	登出未撤销服务端 refresh token	saas/auth/handlers.rs:506
MED	SEC-07	注册端点无验证码/邀请机制	saas/auth/handlers.rs:54
MED	SEC-08	角色权限缓存无 TTL/失效	saas/auth/handlers.rs:397
MED	SEC-09	登录缺少专门暴力破解保护	saas/auth/handlers.rs:160
MED	SEC-10	生产 CORS 配置含 localhost	saas-config.toml:12
MED	SEC-11	Cookie Secure 在非 HTTPS 环境失效	saas/auth/handlers.rs:29
MED	SEC-13	TOTP 加密密钥从 JWT Secret 派生	saas/config.rs:285
LOW	SEC-14	PythonSkill 脚本路径信任模型	skills/runner.rs:83
LOW	SEC-15	Rate limit 信任 X-Forwarded-For	saas/middleware.rs:109

4.2 安全优势

项目	状态
SQL 注入防护	✅ 100% 参数化，0 字符串拼接
密码哈希	✅ Argon2id + spawn_blocking
Refresh Token Rotation	✅ 一次性使用 + SHA-256 hash 存储
API Key 加密	✅ AES-256-GCM + 随机 nonce
错误信息处理	✅ 500 不泄露内部细节
审计日志	✅ 覆盖所有关键操作 + IP
TOTP 暴力破解保护	✅ 5 次失败锁定 10 分钟
XSS 防护	✅ 唯一 innerHTML 用 DOMPurify
账号隔离	✅ 所有查询强制 account_id
CORS 安全	✅ 生产强制白名单

---

五、性能审计

5.1 严重性能问题

问题	影响	文件
SSE 流不检查 CancellationToken	graceful shutdown 等待最长 5 分钟	relay/service.rs
数据表无自动清理	operation_logs/usage_records/relay_tasks 无限增长	scheduler.rs
连接池偏小 (max=20)	高并发 SSE 场景不足	db.rs:12
Scheduler 循环不监听 shutdown token	后台 task 不会被取消	scheduler.rs:55,78,111

5.2 中等性能问题

问题	文件
relay_tasks 缺 (account_id, status) 复合索引	relay/handlers.rs:31
SSE usage 跳过后 task 永久 "processing"	relay/service.rs:302
OTA 提示词 N+1 查询（每模板 2 次）	prompt/service.rs:242
totp_fail_counts 无清理机制	state.rs:26
operation_logs COUNT(*) 无时间范围	account/handlers.rs:144

5.3 性能优势

项目	设计
连接池健康检查	80% 水位 503 + 3s 超时
TCP keepalive	60s/10s/3次 + SO_LINGER 1s
SSE 背压	bounded channel(128)
SSE 并发限制	Semaphore(16)
DashMap 死锁	RefMut 在 await 前释放
前端无轮询	TanStack Query 按需触发

---

六、业务功能审计

6.1 SaaS API 完整度 ✅

模块	端点数	CRUD
auth (含 TOTP)	9	完整认证流程
account (含 tokens/devices/logs/stats)	12	✅
provider	6	✅ C/R/U/D
model	5	✅ C/R/U/D
api_keys (含 rotate)	5	✅
relay (含 key pool)	9	✅
config/migration	12	✅ + sync/diff/pull
role + permission_template	11	✅
prompt (含 versions/rollback)	10	✅
agent_template	5	✅
scheduled_task	5	✅
telemetry	4	✅
health	1	✅
总计	93	完整

6.2 前后端对齐 ✅

• Admin V2: 12 个 service 文件 → 后端路由全部匹配
• baseURL /api/v1 + Vite proxy → 无断链
• withCredentials: true → Cookie 自动发送
• 后端就绪但无 Admin UI: Role 管理、TOTP、Prompt 版本、定时任务管理

6.3 功能缺口

功能	后端	前端 Admin	状态
Role CRUD	✅ 4 端点	❌	后端就绪
Permission Template	✅ 4 端点	❌	后端就绪
TOTP 2FA	✅ 3 端点	❌	后端就绪
Prompt 版本管理	✅ 4 端点	❌	后端就绪
定时任务管理	✅ 5 端点	❌	后端就绪
SaaS 定时任务执行	⚠️ 仅状态管理	—	未闭环
Kernel 定时任务执行	✅ TriggerManager	✅	完整闭环

6.4 Approval 流程 ✅

完整闭环: 触发 → 检查 → 创建审批 → 前端通知 → 审批/拒绝 → 执行 → 结果通知

---

七、待改进项（按优先级）

P0 — 必须修复

ID	问题	影响
P0-1	SSE 流不检查 CancellationToken	停机等待最长 5 分钟
P0-2	数据表无自动清理 (logs/usage/relay_tasks)	磁盘耗尽 + 查询退化
P0-3	store.rs 75 处 unwrap	数据库异常导致 panic
P0-4	extraction_adapter.rs 链式 unwrap	LLM 异常输出导致 panic
P0-5	登出未撤销服务端 refresh token	XSS 后 token 仍可用

P1 — 应该修复

ID	问题	影响
P1-1	kernel_commands.rs 2185 行	可维护性
P1-2	gateway-client.ts 53 处 Promise<any>	类型安全盲区
P1-3	连接池 max=20 偏小	高并发不足
P1-4	relay_tasks 缺复合索引	查询性能
P1-5	Scheduler 循环不响应 shutdown	优雅停机不完整
P1-6	saas-config.toml 含明文密码	安全风险
P1-7	Cookie Secure 在 localhost 失效	开发环境认证失败
P1-8	登录缺暴力破解保护	安全风险
P1-9	zclaw-protocols 仅 5 个测试	回归风险

P2 — 可以改进

ID	问题	影响
P2-1	多个文件 >800 行	代码组织
P2-2	角色权限缓存无失效机制	降权不即时生效
P2-3	sqlx-postgres 0.7.4 未来兼容性	编译噪音
P2-4	SaaS 定时任务执行未闭环	功能不完整
P2-5	scheduled_tasks 路径缺 /v1 前缀	API 一致性
P2-6	OTA 提示词 N+1 查询	性能

---

八、架构优势

1. SaaS 独立部署 — 不依赖 Kernel，可独立扩展
2. Feature gate 分离 — multi-agent 功能可选
3. Cookie + Header 双路径认证 — 向后兼容 + 安全
4. 声明式 Scheduler — TOML 配置驱动
5. 参数化 SQL 全覆盖 — 零注入风险
6. 连接池健康检查 — 80% 水位自动降级
7. Argon2id 密码哈希 — 业界最佳实践
8. 审计日志全覆盖 — 所有关键操作 + IP
9. SSE 背压设计 — bounded channel 防内存溢出

---

审计完成。5 个并行子代理深度审计，覆盖架构/代码/安全/性能/业务全维度。