aios/docs/aios-v2/adr/ADR-004-multi-tenant-isolation.md

ADR-004：多租户隔离采用默认拒绝模型

• 状态：已采纳
• 日期：2026-07-20
• 影响范围：Web/API、Control Plane、OpenClaw、Hermes、Persistence、Audit、Execution Evidence、Logs、Metrics、Secret

1. 背景

AIOS V2 同时承载多个租户的用户请求、控制面状态、OpenClaw 命令、Hermes 队列、执行证据、审计和 GitOps 状态。任何一层缺失租户边界，都可能造成数据泄露、跨租户任务执行或错误回写。

2. 决策

多租户隔离采用：

显式租户上下文
+
默认拒绝
+
全链路传播
+
负向测试

所有资源、命令、Job、证据和审计记录都必须显式绑定 tenant_id。缺少上下文、上下文不匹配或无法确认所有权时，系统必须 fail closed。

3. 权威上下文

控制请求至少包含：

• tenant_id；
• principal_id；
• trace_id；
• policy_version；
• 可选 session_id。

执行请求增加：

• task_id；
• command_id 或 job_id；
• idempotency_key。

Hermes 额外包含：

• cell_id；
• profile_id；
• worker_id。

4. 各层执行规则

Web/API

• 可信代理必须删除客户端同名 X-AIOS-* Header 后重新注入；
• 浏览器不得自行选择或覆盖租户；
• 未认证身份断言必须拒绝。

Control Plane

• Tenant、Agent、Task、Audit 全部带不可为空的 tenant_id；
• 跨租户读取返回拒绝或“未找到”；
• 不泄露其他租户资源存在性。

OpenClaw

• 签名覆盖 tenant/task/trace/action/payload/idempotency/time；
• Result 身份字段必须与命令完全一致；
• 跨租户 status/cancel 返回“未找到”。

Hermes

• Job 按 tenant/cell/profile 分区；
• Worker 只能 claim 自己的分区；
• Worker ID 不得在未授权分区之间迁移；
• Result 必须匹配 tenant/task/trace。

Persistence

• 候选版使用显式租户字段；
• 生产数据库必须提供 RLS 或物理隔离策略；
• 备份、恢复和迁移必须保持租户边界。

Audit 与 Evidence

• 仅按当前租户查询；
• 不记录明文 Secret；
• 统一包含 tenant/task/trace。

Cache、Memory、Artifact、Logs、Metrics

• Key 或标签必须包含租户命名空间；
• 查询和导出必须受租户权限限制；
• 不允许使用无租户前缀的全局缓存保存业务数据。

5. 备选方案

方案 A：仅在 API 层检查租户

拒绝原因：后台任务、Runtime、缓存和结果回写仍可能跨租户。

方案 B：仅依赖数据库隔离

拒绝原因：命令、队列、审计和文件系统仍需要显式边界。

方案 C：发生冲突时自动推断租户

拒绝原因：推断可能产生跨租户副作用，必须默认拒绝。

6. 正面影响

• 安全模型一致；
• Runtime 无法绕过租户边界；
• 负向测试可自动化；
• 审计和问题定位更明确。

7. 负面影响与风险

• 所有接口和模型都需要传播租户上下文；
• 日志、指标和缓存设计更复杂；
• 候选 SQLite 只有逻辑隔离，生产仍需更强存储证据；
• 身份代理配置错误可能破坏入口隔离。

8. 测试要求

至少覆盖：

• Tenant B 读取 Tenant A Task；
• Tenant B 查询或取消 Tenant A OpenClawCommand；
• Worker 跨 tenant/cell/profile claim；
• Runtime 返回错误 tenant/task/trace；
• Evidence 和 Audit 跨租户查询；
• 缺少 Tenant Context 的请求；
• 客户端伪造身份 Header。

9. 合规检查

任何新模块没有以下内容时不得进入 Candidate：

• 显式 tenant_id；
• 所有权检查；
• 跨租户负向测试；
• 审计映射；
• 文档与追踪矩阵更新。

10. 实现与测试映射

• Control Plane：active-runtime/app/aios_v2/control_plane.py
• OpenClaw：active-runtime/app/aios_openclaw/
• Hermes：active-runtime/app/aios_hermes/
• Evidence：active-runtime/app/aios_v2/execution_tracking.py
• 测试：tests/aios_v2_candidate/test_candidate_flow.py