4.5 KiB
4.5 KiB
模块:控制面 API(apps/api)
职责
apps/api 是平台的唯一事实来源:项目与成员、愿望与运行、租约与证据、发布与审批、额度与用量、连接器与模型代理。它自己不跑模型、不跑测试,而是把长时间工作交给 Temporal(apps/worker)和目标环境的 Runner。
启动与组装顺序
入口 apps/api/src/main.ts:24 的 bootstrap():
requireDeploymentMode(process.env)(main.ts:25):部署模式必须显式声明,默认拒绝(fail closed),不靠NODE_ENV推断。- 删除迁移用管理员凭据(
main.ts:27-28),并对数据库角色做安全检查store.assertSafeRole()(apps/api/src/db/store.ts:108-110):超级用户或BYPASSRLS角色会让租户隔离失效,因此拒绝启动。 - 若派发开启,强制要求 Temporal TLS 文件与租户命名空间(
main.ts:30-34),避免通过未认证或共享命名空间派发。 - 组装
Services(new ControlPlane(store)),启动后台技能沉淀与资源对账 worker。
代码地图
| 文件 | 职责 | 关键点 |
|---|---|---|
apps/api/src/main.ts |
启动、依赖组装、后台循环 | 206 行;fail-closed 配置校验 |
apps/api/src/http.ts |
REST 路由与 DTO 校验 | 933 行;NestJS 控制器;/v1 与 /internal |
apps/api/src/domain/control-plane.ts |
运行状态机 | 1564 行;submit:358、lease:931、transition:1076、evidence:1213 |
apps/api/src/domain/releases.ts |
发布绑定、审批、回滚 | 724 行;releaseBinding:42、request:280、decide:435、rollback:662 |
apps/api/src/domain/runner-broker.ts |
Runner 注册、任务队列、回执 | 508 行;register:54、poll:127、result:290 |
apps/api/src/domain/provider-proxy.ts |
模型网关代理与短期令牌 | 933 行;原始密钥不进入执行环境 |
apps/api/src/domain/local-poc.ts |
POC 绑定与构建证据校验 | assertPocBuild;POC_BINDING_REQUIRED 等错误码 |
apps/api/src/domain/integration-lease.ts |
每项目单一集成者 | 与 fencing token 配合 |
apps/api/src/domain/entitlements.ts |
套餐限额与并发预留 | 与 usage.ts 配合 |
apps/api/src/domain/skills.ts |
项目技能沉淀 | 423 行;后台 harvest |
apps/api/src/domain/lessons.ts |
运行经验注入 | 90 行 |
apps/api/src/mcp.ts |
MCP Streamable HTTP 服务 | 8 个工具;OAuth 资源元数据 |
apps/api/src/auth.ts、internal-auth.ts |
人类会话与内部身份 | 身份类型见 packages/contracts/src/index.ts:85 |
apps/api/src/dispatcher.ts |
Outbox → Temporal 派发 | 多副本安全 |
apps/api/src/db/store.ts |
PostgreSQL 事务与 RLS 上下文 | 每个事务 set_config('app.tenant_id', …)(:116) |
apps/api/src/db/migrate.ts、migrations/ |
版本化迁移 | npm run db:migrate |
apps/api/src/telemetry.ts |
OpenTelemetry 与指标 | Prometheus |
数据层约束
- 每个租户事务在进入时设置
app.tenant_id与app.actor_id(apps/api/src/db/store.ts:116-119),RLS 策略据此过滤;应用层另有检查,两者都不能省。 - Outbox 表把「状态已提交」与「工作流已派发」解耦:
outbox()只取未投递且到期的记录,按run.signal→workspace.reconcile→ 其他排序(apps/api/src/db/store.ts:264),投递成功写delivered_at,失败累加attempts并退避。 - 清理策略:已投递 outbox 保留 7 天,幂等记录 30 天(
apps/api/src/db/store.ts:84)。
测试集
| 测试 | 覆盖 |
|---|---|
tests/control-plane.test.ts |
提交、租约、阶段迁移、证据 |
tests/control-hardening.test.ts |
取消/补充/暂停的级联失效、越权、租约边界 |
tests/local-loop.test.ts |
本地端到端主链路 |
tests/local-poc-delivery.test.ts |
POC 发布绑定、签名回执、回滚 |
tests/entitlements-usage.test.ts |
配额与计量 |
tests/internal-auth.test.ts、tests/auth-expiry.test.ts |
身份与过期 |
tests/path-rules.test.ts |
后端路径规则 |
tests/mcp.test.ts |
MCP 工具契约 |
修改时的检查清单
- 改状态迁移:必须同时更新
packages/contracts的 schema、tests/control-plane.test.ts与前端等待指引。 - 改证据结构:确认历史证据仍能反序列化;证据是审计资产。
- 改发布绑定字段:会让既有审批失效,需要在 PR 中说明。
- 新增路由:
/v1面向人类与连接器,/internal面向 worker/verifier,权限模型不同,不能混用。