跳到主要内容

SayClaw 文档-代码一致性审计（2026-03-05）

审计范围：sayclaw、sayclaw-docs、sayclaw-infra、sayclaw-ops、sayclaw-admin、sayclaw-backend、sayclaw-app、sayclaw-portal

1. 结论摘要​

  • 文档体系完整，覆盖认证、实例、调度、告警、审计、邀请码等核心模块。
  • 代码侧存在多仓功能重叠与实现形态分裂，导致维护成本升高。
  • 需优先处理安全与一致性问题（密钥、鉴权、CORS、仓库边界）。

2. 关键发现​

P0（必须立即修复）​

  1. 敏感信息硬编码风险

    • 发现默认 DB DSN / JWT Secret / 管理员口令 fallback。
    • 风险：泄露后可直接造成后台与数据层失陷。

  2. 鉴权链路不统一

    • 部分接口依赖自定义 JWT 解析，缺少标准 OIDC/IAP 验签一致性。
    • 风险：越权与伪造 Token 风险提升。

  3. CORS 过宽

    • Access-Control-Allow-Origin: * 在生产接口出现。
    • 风险：跨站滥用与令牌泄露面扩大。

P1（本周内完成）​

  1. 仓库职责重叠

    • sayclaw-backend 与 sayclaw-portal 存在 portal API 重叠实现。
    • sayclaw-app 与 monorepo 中 portal 前端能力重叠。

  2. 文档与实现口径不一致

    • 阶段状态（Phase 2/3/4）与实际代码推进存在偏差。
    • 队列模型命名并存（task_queue / admin_tasks），治理成本上升。

  3. 前端工程形态不统一

    • 既有工程化前端，也有单 HTML + CDN 形态，且含 .bak 文件。

P2（迭代优化）​

  1. 任务状态机、告警规则与用量统计口径统一。
  2. CI 增补 secret scanning / SAST / migration check / 覆盖率门槛。

3. 建议优先级​

  1. 先安全后功能：先清密钥与鉴权，再做 Phase4 功能扩展。
  2. 先统一后迭代：先冻结单一事实源（仓库与接口），再新增需求。
  3. 先文档纠偏再推进开发：文档先与现实对齐，避免团队误解。

4. 责任分配建议​

  • CTO/Owner：拍板仓库收敛路径与鉴权标准。
  • Tech Lead：落地安全修复与 API 契约统一。
  • Operator/QA：回归矩阵、发布清单、审计核查。

5. 验收标准​

  • 不再存在生产可用默认密钥。
  • 所有后台接口通过统一鉴权中间件。
  • 8 仓职责边界文档化且可追溯。
  • 文档路线图与代码现状一致（误差 < 1 个迭代）。