Codex
6.9 KiB
PJ2026-010506 租户隔离
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010506 租户隔离需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010506 |
| 短名 | 租户隔离 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0105 用户管理 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留租户隔离的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
租户隔离负责 HWLAB 多用户和后续组织协同中的数据、任务、资源和管理操作边界，使用户不能越权读取或操作其他用户、组织或租户的账户、任务、usage、ledger、API key、workspace 和硬件资源。
D601 v0.3 当前已具备个人用户、admin/普通用户角色、受保护 Web/API session、admin-only 管理入口和用户账务隔离基础；本课题在该基线上定义组织、项目、工作台和跨模块资源隔离的目标能力。
2.2 范围内
- 用户、组织、项目、工作台、Agent session、HWPOD 资源、usage 和 ledger 的归属上下文。
- 普通用户、管理员、组织成员和内部服务之间的访问边界。
- 用户自服务、admin 管理、API key 调用和内部任务回写中的越权防护。
- 跨模块 principal、tenant context 和 ownership metadata 的传递。
- 越权拒绝、审计摘要和敏感信息脱敏。
2.3 范围外
- 组织、成员和组织项目模型归 PJ2026-010507 组织管理。
- 页面可见性和路由守卫归 客户端。
- Agent run、workspace 和 session 生命周期归 Agent编排。
- 物理硬件资源事实和租约归 硬件池。
3. 术语表
| 术语 | 定义 |
|---|---|
| tenant context | 一次请求或任务所属的用户、组织、项目和工作台上下文。 |
| ownership metadata | 数据或资源记录上用于判断归属的用户、组织或项目字段。 |
| 越权访问 | 调用者访问或操作不属于其权限范围的数据、任务、资源或账务。 |
| admin override | 管理员在授权范围内查看或操作用户数据的受控路径。 |
| isolation decision | 根据 principal 和 ownership metadata 得出的 allow/deny 结论。 |
4. 系统边界和接口
本规格把租户隔离作为用户管理的横向访问边界看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 客户端、Agent编排、硬件池、HarnessRL、账单后台、平台管理员和内部服务。 |
| 外部输入 | principal、tenant context、ownership metadata、请求动作、目标资源、admin 操作和组织成员关系。 |
| 受控资源 | 用户数据、组织数据、项目、工作台、Agent session、workspace、API key、usage、ledger、reservation 和硬件资源引用。 |
| 外部输出 | allow/deny 决策、越权错误、admin override 审计、脱敏摘要和下游 tenant context。 |
| 用户接口 | Web/API 访问检查、admin API、业务 API、CLI 错误输出。 |
| 系统边界 | 租户隔离负责访问边界和 ownership 判断；不定义组织业务模型、任务执行事实、硬件事实或页面布局。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01050601 | 数据归属 | 本规格 6.1 | 用户、组织、项目和资源 ownership | 账号会话、组织管理 | 全部业务模块 |
| PJ2026-01050602 | 访问约束 | 本规格 6.2 | allow/deny 和 admin override | 数据归属、权限配额 | Web/API/CLI |
| PJ2026-01050603 | 上下文传递 | 本规格 6.3 | tenant context 跨模块传递 | Agent编排、硬件池、客户端 | 计量账本、HarnessRL |
| PJ2026-01050604 | 越权审计 | 本规格 6.4 | 越权错误和审计摘要 | 访问约束、账单后台 | admin、运营排障 |
6. 原子需求
6.1 USER-TENANT-REQ-001 数据归属
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-TENANT-REQ-001 | 数据归属 | PJ2026-01050601 数据归属 | 组织管理、账号会话 |
租户隔离应为用户、组织、项目、工作台、任务、资源、usage 和 ledger 提供稳定 ownership metadata，使访问判断有明确归属依据。
没有归属上下文的数据不能默认公开给全部用户。历史个人账号数据在进入组织模型后也必须有明确迁移或默认归属规则。
6.2 USER-TENANT-REQ-002 访问约束
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-TENANT-REQ-002 | 访问约束 | PJ2026-01050602 访问约束 | 权限配额、客户端 |
租户隔离应根据 principal、role、组织成员关系、请求动作和目标资源归属输出访问 allow/deny 决策。
客户端路由、页面隐藏和 CLI 参数过滤不能替代服务端访问约束。admin override 必须由角色权限允许，并保留可审计摘要。
6.3 USER-TENANT-REQ-003 上下文传递
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-TENANT-REQ-003 | 上下文传递 | PJ2026-01050603 上下文传递 | Agent编排、硬件池、HarnessRL |
租户隔离应把 tenant context 传递给 Agent、HWPOD、CaseRun、usage 和 ledger 相关模块，使执行事实和消费事实都能回到正确用户或组织。
下游模块可以消费 tenant context，但不得在本地重新发明不兼容的用户、组织或租户模型。
6.4 USER-TENANT-REQ-004 越权审计
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-TENANT-REQ-004 | 越权审计 | PJ2026-01050604 越权审计 | 账单后台、平台运维 |
租户隔离应为越权拒绝、admin override 和敏感资源访问提供脱敏审计摘要，使管理员能定位访问问题而不泄露用户 Secret 或私有数据。
审计摘要只能记录必要的 userId、organizationId、resource id、动作、状态和错误码，不得输出 API key secret、session token、password hash、DB DSN 或 provider token。