P11 · 如何管理多租户、组织与工作空间隔离？ - Multi-tenancy & Isolation
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何为 Agent Platform 建立可验证的租户、组织、工作空间及项目边界，使身份、数据、计算、工具、凭证、预算与共享在多租户环境中既能隔离又能受控协作？
专题导读
本篇属 Technical Architecture。多租户（Multi-tenancy）是一个平台实例服务多个独立客户或管理主体的架构能力。Agent Platform 的多租户问题比普通 CRUD SaaS 更复杂：Agent 可以自主调用工具、检索知识、生成衍生资产、长时间执行工作流，并通过外部连接器对真实系统产生副作用。因此，仅在业务表增加 tenant_id 不能构成完整隔离。
本文以“隔离边界 - 身份上下文 - 授权决策 - 数据与运行资源 - 跨边界共享 - 验证”为主线，给出可分阶段实现的参考架构。本文中的 SQL、API、策略和测试均为设计示例，不代表已经部署或通过测试。重点是平台技术架构，具体权限与配额治理在 P12 深入研究。
研究结论
- 租户是首要安全与计费边界，组织、工作空间、项目是可配置的业务管理边界。 不应假设每个产品都必须一租户一组织，或将工作空间等同于租户。
- 隔离是跨层性质。 身份、元数据、对象存储、检索、缓存、队列、执行沙箱、密钥、日志、账单都必须有可检验的隔离策略。
- 租户上下文应由可信身份与资源归属解析得出。 客户端传入的
tenant_id只能作为待验证选择器，不能成为授权事实。 - 授权采用默认拒绝与对象级判定。 仅有角色检查、前端隐藏或数据库行级策略都不足以覆盖外部工具调用与衍生资产。
- 共享必须建模为显式授权对象。 跨租户引用、复制、导出和公开发布具有不同的权限、撤销与数据生命周期语义。
- 异步运行必须固定安全上下文，但授权不应永久冻结。 Run 记录启动身份与资源版本；实际读取和产生副作用前仍需检查当前有效授权及撤销状态。
- 物理隔离等级应基于威胁模型选择。 共享数据库、独立 schema、独立数据库或专属计算池各有成本与安全取舍，不存在普适最优解。
- 隔离应通过对抗性测试证明。 需要覆盖 IDOR/BOLA、搜索索引串租、队列误投、缓存键碰撞、凭证串用、日志泄露及跨租户侧信道。
01 · 定义、边界与威胁模型
1.1 核心术语
| 概念 | 定义 | 典型职责 | 是否天然安全边界 |
|---|---|---|---|
| Tenant 租户 | 平台中具有独立数据、策略与资源核算范围的客户或管理主体 | 数据归属、计费、治理 | 是，需由系统强制实施 |
| Organization 组织 | 人员与管理结构的逻辑集合 | 成员、团队、管理员 | 取决于产品模型 |
| Workspace 工作空间 | 协作与资产组织单元 | Agent、Workflow、资源与成员协作 | 是授权作用域，不必是物理隔离边界 |
| Project 项目 | 工作空间内的业务任务与成果集合 | 研究任务、文件、交付 | 通常是细粒度授权范围 |
| Principal 主体 | 发起或代表操作的用户、服务、Agent 运行身份 | 认证与授权 | 身份边界 |
| Resource 资源 | Agent、Run、资产、连接、密钥引用等 | 所有权与共享 | 必须具有归属及访问策略 |
| Membership 成员关系 | 主体在租户、组织或工作空间中的关系 | 角色授予 | 授权事实之一 |
| Grant 授权 | 主体对指定资源或范围的许可 | 受控共享 | 需要校验有效期和撤销 |
设计提醒： tenant_id、organization_id、workspace_id、project_id 不是可互换字段。允许一个用户加入多个租户；组织可能对应一个租户，也可能存在复杂集团结构。应在产品规则确定后才固化层级约束。
1.2 与相邻专题的分工
- P1 Control Plane： 请求准入、身份上下文传递、授权协调；P11 明确隔离域和跨域约束。
- P2 Execution Plane： Worker、沙箱、任务执行；P11 明确执行资源隔离、运行身份与网络/文件边界。
- P3 Agent Registry： Agent 定义和版本；P11 规定注册对象归属、可见性和共享规则。
- P5 Deployment & Runtime： 实例部署和运行生命周期；P11 决定实例是否共享、如何限流及隔离。
- P6 Workflow： 工作流调度；P11 约束节点运行权限与跨工作空间引用。
- P7 Resource & Integration： 模型、工具、连接器；P11 明确连接归属、凭证作用域和调用隔离。
- P10 Data & Assets： 资产版本与交付；P11 明确资产归属、访问控制、共享与导出边界。
- P12 Platform Governance： 权限策略、配额和治理策略的统一管理与执行。
1.3 主要威胁
攻击者可能是未认证外部用户、低权限租户成员、被提示注入操纵的 Agent、恶意插件、被盗服务凭证或遭入侵的 Worker。需要考虑横向越权（读取另一租户对象）、纵向越权（普通成员调用管理员能力）、跨租户检索泄露、共享缓存污染、密钥错误注入、执行容器逃逸、恶意工作流触发外部副作用，以及管理员操作导致的大范围误共享。
攻击面既包括 HTTP API，也包括 WebSocket/SSE、Webhook、后台作业、异步事件、数据库管理脚本、对象存储预签名 URL、向量检索过滤器、模型调用上下文与日志平台。
02 · 租户与组织层级的领域建模
2.1 参考层级
flowchart TB
P[Platform] --> T1[Tenant A]
P --> T2[Tenant B]
T1 --> O1[Organization]
O1 --> W1[Workspace: Research]
O1 --> W2[Workspace: Product]
W1 --> PR1[Project 1]
W1 --> PR2[Project 2]
T2 --> O2[Organization B]
O2 --> W3[Workspace B]
U[User Principal] -. Membership A .-> T1
U -. Membership B .-> T2该图是一种可选产品模型。如果初期 Studio 只有个人工作空间，可以先采用 tenant → workspace → project，暂不引入组织实体；预留未来迁移路径即可。
2.2 核心实体
erDiagram
TENANT ||--o{ ORGANIZATION : contains
TENANT ||--o{ WORKSPACE : owns
ORGANIZATION |o--o{ WORKSPACE : groups
WORKSPACE ||--o{ PROJECT : contains
PRINCIPAL ||--o{ MEMBERSHIP : has
TENANT ||--o{ MEMBERSHIP : scopes
WORKSPACE ||--o{ MEMBERSHIP : scopes
PROJECT ||--o{ RESOURCE : owns
TENANT ||--o{ RESOURCE : owns
RESOURCE ||--o{ RESOURCE_GRANT : shared_by
PRINCIPAL ||--o{ RESOURCE_GRANT : receives在关系模型中，Membership 的作用域可能是租户、组织、工作空间或项目。不要同时要求每个作用域外键非空；应以显式 scope_type + scope_id 并配合强校验，或使用分表表示不同作用域，以避免难以维护的多态外键。共享授权应独立于资源原始所有权。
2.3 生命周期
租户一般经历 provisioning → active → suspended → closing → deleted。停用租户时必须阻止新的 Run、连接调用和新授权；进行中的 Run 是取消、排空还是继续执行，应由明确策略决定。删除需要遵循保留政策、法律保全、外部副本和备份周期，不得承诺立即彻底擦除所有历史数据。
工作空间归档不应直接删除资产；成员移除也不应自动改变历史 Run 的审计记录。组织迁移、工作空间所有权转移和租户合并属于高风险管理操作，需要专门的审批与迁移流程。
03 · 隔离等级与部署拓扑
| 方案 | 数据拓扑 | 优势 | 风险与成本 | 适用条件 |
|---|---|---|---|---|
| 共享库共享表 | 所有租户共享表，以 tenant_id 分区 | 运营简单、资源利用率高 | 应用过滤遗漏造成串租；需要 RLS/测试 | 初期 SaaS，租户规模较多 |
| 共享库独立 Schema | 每租户独立 schema | 逻辑结构隔离较强 | 迁移和连接管理复杂；并非物理隔离 | 中等租户规模、定制需求 |
| 独立数据库 | 每租户独立数据库 | 备份、密钥与恢复边界更清晰 | 成本、连接与运维开销高 | 合规或重要客户 |
| 专属运行池 | 计算与 Worker 按租户分配 | 降低计算侧干扰与风险 | 容量利用率低 | 高风险工具、特殊数据 |
| 独立环境/集群 | 数据与计算均独立 | 隔离强、可定制 | 交付运维复杂 | 高合规或专有部署 |
可采用混合租户模型：默认共享控制面与元数据，敏感租户使用专属数据库或执行池。但混合模型增加路由、迁移、观测和故障恢复复杂度。共享数据库的 RLS 是纵深防御手段，而非取代应用授权的全部机制。
3.1 噪声邻居问题
即使数据完全隔离，某租户的大量模型调用、长任务或向量索引查询也可能耗尽队列、数据库连接、Worker、GPU 或外部 API 配额，导致其他租户延迟上升。需要按租户设置并发上限、队列权重、预算、速率限制和超时；监测 p95/p99 排队延迟及资源占用。P12 进一步讨论治理策略。
04 · 身份、会话与可信租户上下文
4.1 身份与作用域解析
用户可能拥有多个租户成员身份。请求中的“当前租户”应由已认证主体的成员关系校验得到：
Authenticated principal
→ enumerate valid tenant memberships
→ validate selected tenant and workspace
→ resolve resource ownership
→ evaluate permission + policy
→ execute with scoped security context禁止直接信任 X-Tenant-ID 或请求体中的 tenant_id 来决定访问权限。API 可以接受这些字段作为选择器，但必须通过服务端重新解析。内部服务调用需采用可验证的服务身份和有界的委托令牌，避免将用户原始访问令牌无差别传播到所有 Worker。
4.2 运行安全上下文
{
"principal_id": "usr_123",
"principal_type": "user",
"tenant_id": "tnt_a",
"workspace_id": "wsp_research",
"project_id": "prj_2026",
"run_id": "run_456",
"delegation_id": "dlg_789",
"policy_revision": "pol_17",
"issued_at": "2026-10-31T12:00:00Z",
"expires_at": "2026-10-31T12:15:00Z"
}此结构是内部参考契约，不是可直接信任的用户输入。policy_revision 有利于审计，但不意味着执行期间所有授权永久有效。长任务应使用短期工作负载凭证，并在敏感操作时重新校验授权、连接状态及撤销事件。
4.3 身份委托与 Agent
Agent 不是天然可信用户。应区分 Agent 的定义身份、Deployment 的服务身份、一次 Run 的执行身份，以及发起人的委托权限。工具调用采用最小权限：允许 Agent 访问某个知识库，不等于允许读取同租户全部知识库；允许检索邮箱，不等于允许发送邮件。
05 · 授权模型：RBAC、ABAC 与 ReBAC
- RBAC 根据角色授予能力，如 tenant_admin、workspace_editor、project_viewer。
- ABAC 根据属性决策，如数据分类、环境、操作类型、当前审批状态。
- ReBAC 根据资源关系授权，如某人是项目成员、某资产被明确分享给另一工作空间。
实际平台可以组合使用：RBAC 负责粗粒度角色，资源关系负责对象级共享，ABAC 负责敏感操作限制。关键操作应遵循 deny by default；任何 allow 都应附带明确主体、资源、动作、作用域与条件。
5.1 权限矩阵示例
| 动作 | 租户管理员 | 工作空间编辑者 | 项目查看者 | Agent 运行身份 |
|---|---|---|---|---|
| 创建工作空间 | 允许 | 视策略 | 拒绝 | 拒绝 |
| 编辑本空间 Agent Draft | 允许 | 允许 | 拒绝 | 拒绝 |
| 启动项目 Workflow | 允许 | 允许 | 视策略 | 需显式授权 |
| 查看项目资产 | 允许* | 允许* | 允许* | 仅绑定资源 |
| 读取连接器凭证原文 | 拒绝 | 拒绝 | 拒绝 | 拒绝 |
| 调用已授权外部工具 | 依策略 | 依策略 | 拒绝 | 逐次判定 |
| 跨租户共享资产 | 审批后 | 视策略 | 拒绝 | 默认拒绝 |
* 表示仍受数据分类、对象级限制和法律/合规策略约束；管理员不必天然拥有所有敏感数据的读取权。
5.2 决策流程
sequenceDiagram
participant C as Client
participant A as API
participant I as Identity
participant Z as Policy Engine
participant D as Data Service
C->>A: GET /assets/{id}
A->>I: authenticate and resolve membership
I-->>A: principal + verified scope
A->>D: resolve asset owner and classification
D-->>A: owner tenant + scope + metadata
A->>Z: authorize(principal, read, asset, context)
Z-->>A: allow / deny + reason
alt allow
A->>D: scoped read
D-->>A: asset
A-->>C: 200
else deny
A-->>C: 403 or non-disclosing 404
end不要依靠资源 ID 不可猜测来替代授权。对不存在和无权访问的对象是否统一返回 404，应根据接口安全策略与运维可观测性决定。
06 · 数据库隔离与数据访问
6.1 参考 SQL（PostgreSQL）
CREATE TABLE tenants (
id UUID PRIMARY KEY,
status TEXT NOT NULL CHECK (status IN ('provisioning','active','suspended','closing')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE workspaces (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL REFERENCES tenants(id),
name TEXT NOT NULL,
UNIQUE (tenant_id, id)
);
CREATE TABLE projects (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
workspace_id UUID NOT NULL,
name TEXT NOT NULL,
FOREIGN KEY (tenant_id, workspace_id)
REFERENCES workspaces(tenant_id, id),
UNIQUE (tenant_id, id)
);
CREATE TABLE assets (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
project_id UUID NOT NULL,
classification TEXT NOT NULL DEFAULT 'internal',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
FOREIGN KEY (tenant_id, project_id)
REFERENCES projects(tenant_id, id)
);
CREATE INDEX assets_tenant_project_idx ON assets(tenant_id, project_id);复合外键使项目和资产不能在数据库层意外跨租户引用。生产环境仍需根据真实模型完善删除策略、索引、审计和迁移。
6.2 行级安全策略
ALTER TABLE assets ENABLE ROW LEVEL SECURITY;
ALTER TABLE assets FORCE ROW LEVEL SECURITY;
CREATE POLICY assets_tenant_isolation ON assets
USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);重要限制： 以上仅是示意。若会话变量未设置，强制转换可能产生错误；数据库所有者、超级用户及具有 BYPASSRLS 的角色具有特殊行为，必须严格限制。应在事务中设置可信租户上下文（例如 SET LOCAL），避免连接池复用导致上下文残留。对跨租户管理员查询使用单独的受审计访问路径，而不是随意关闭 RLS。
6.3 数据层防线
读、写、更新、删除、批量导入、后台修复和报表查询都要携带作用域。ORM 的默认过滤器容易被原生 SQL、关联查询或维护脚本绕过；应使用复合外键、RLS、授权中间件、数据库最小权限和跨租户测试形成纵深防御。
07 · 对象存储、检索、缓存与日志隔离
7.1 对象存储
对象键可采用 tenants/{tenant_id}/assets/{asset_id}/versions/{version_id} 形式，但路径前缀不是安全机制。应以服务端授权后签发的短时下载凭证、对象存储策略、服务身份及加密密钥隔离实现控制。预签名 URL 泄露后通常在过期前可被持有者使用，因此应限制有效期、下载范围，并按敏感度选择代理下载。
7.2 搜索与向量检索
检索必须在查询阶段应用可信租户过滤，并在返回前再次做对象级授权。单纯在向量搜索后按 tenant_id 过滤，可能带来召回率下降和侧信道风险；对高敏感租户考虑物理独立索引。Embedding 本身可能泄露信息，不应视为匿名化数据。
7.3 缓存
缓存键应至少包含租户与授权相关的作用域，例如 tenant:{id}:workspace:{id}:asset:{id}:version:{v}。对权限依赖较强的结果还需考虑权限版本、成员变更和撤销后的失效。切勿把不同租户的搜索结果或预签名 URL 放在不区分作用域的共享缓存键下。
7.4 日志与指标
日志记录 tenant_id、run_id、request_id 等用于审计，但不得写入访问令牌、API Key、完整敏感 Prompt 或未经脱敏的工具响应。多租户日志查询本身需要权限过滤；聚合指标的高基数标签与租户可识别信息应有保留与访问策略。
08 · 计算隔离、队列与 Worker
8.1 隔离层级
- 逻辑隔离： 共享 Worker，通过租户上下文和执行策略控制访问；成本低但攻击面较大。
- 进程隔离： 不同执行进程及 OS 账户；可降低部分故障传播。
- 容器隔离： 命名空间、cgroup、网络策略与只读文件系统；并非完整安全边界，需考虑宿主机内核共享。
- 微虚拟机/独立 VM： 隔离较强，启动与运维成本更高。
- 专属集群： 高风险客户可选，成本最高。
不可信代码执行、浏览器自动化、文件解析和第三方插件应采用更强的隔离策略。执行身份应按任务颁发最小权限短期凭证；禁止 Worker 读取全平台通用密钥。
8.2 队列与调度
任务消息应包含不可变 run_id 和服务端验证过的租户引用；Worker 获取消息后重新查询任务归属并检查授权上下文。需要支持租户级并发上限、加权公平调度、任务预算、超时和背压。DLQ（死信队列）及人工重放工具同样必须保留租户边界。
flowchart LR
API[API + AuthZ] --> Q[Durable Queue]
Q --> S[Tenant-aware Scheduler]
S --> WA[Worker Pool A]
S --> WB[Worker Pool B]
WA --> G[Resource Gateway]
WB --> G
G --> Z[Authorization / Policy]
Z --> EXT[External Tools and Models]8.3 长任务与权限撤销
长时间运行的 Workflow 在启动时固定版本与启动身份，用于审计和可追溯；但外部连接器、私有知识库和资产读取需要在每次敏感调用前检查当前授权。成员被移除、租户被暂停或连接被撤销后，平台应能拒绝后续操作并按策略暂停或取消 Run。对于已执行的外部副作用，撤销无法自动回滚，需补偿流程。
09 · 模型、工具、知识与凭证的租户隔离
模型供应商连接、知识库连接、工具权限和密钥都应有明确归属。共享模型供应商账户可能有成本优势，但需要按租户独立计量、限流和日志策略；若供应商侧提供数据保留、区域或专有部署选项，应根据客户需求单独配置，不能假设供应商自动完成租户隔离。
凭证保存于 Secrets Manager 或等效受控存储，业务数据库仅保存引用与元数据。不同租户即便连接同一第三方服务，也应分别管理授权关系。资源网关需防止 Agent 通过任意 URL、路径或工具参数绕过租户权限（包括 SSRF、路径遍历和提示注入诱导）。
9.1 工具调用的授权顺序
Run identity + tenant scope
→ Resolve bound resource
→ Verify resource ownership / explicit grant
→ Check current policy and credential status
→ Validate tool arguments and destination
→ Apply rate limit / budget / human approval
→ Execute with scoped credential
→ Record tenant-scoped invocation and side effectsAgent 自行声称“我是管理员”或在 Prompt 中出现其他租户 ID，不得改变权限决策。
10 · 跨租户协作与资产共享
10.1 四种共享语义
| 共享方式 | 行为 | 撤销后效果 | 主要风险 |
|---|---|---|---|
| 只读引用 | 目标租户访问源资产的受控引用 | 后续读取可被阻断 | 查询时授权、依赖可用性 |
| 受控复制 | 在目标租户生成独立副本 | 已复制内容不随源授权自动消失 | 数据复制、来源追踪、删除责任 |
| 导出交付 | 下载或发送到外部系统 | 无法保证追回外部副本 | 数据外流、接收方验证 |
| 公开发布 | 资产面向公共访问 | 可停止平台后续分发 | 搜索缓存、历史副本、索引残留 |
10.2 共享授权对象
{
"grant_id": "grt_01",
"source_tenant_id": "tnt_a",
"resource_type": "asset_version",
"resource_id": "asv_17",
"target_tenant_id": "tnt_b",
"actions": ["read"],
"expires_at": "2026-12-31T00:00:00Z",
"approved_by": "usr_owner",
"status": "active"
}跨租户共享应限制资源类别、允许动作、接收主体、有效期和审批人，并记录来源与审计链。不建议直接将源租户的数据库记录改写为目标租户的 tenant_id；这会破坏归属、审计与删除语义。对共享内容进行再加工产生的衍生资产，应明确新的所有权和许可证条件。
10.3 跨租户工作流
初期建议禁止一个 Workflow 直接执行另一租户的 Agent 或读取另一租户私有连接器。需要协作时通过受控 API、明确的资源共享或“跨租户委托任务”实现，且每个执行边界单独建立授权、预算、审计与结果交付规则。
11 · 租户开通、迁移、停用与删除
11.1 Provisioning
开通流程包括创建租户记录、初始化默认策略、工作空间、密钥引用、配额、存储前缀与计费账户。流程必须可重试且幂等；任一阶段失败应有可观测的恢复状态，避免“租户已显示创建但安全策略尚未生效”。
11.2 迁移
共享数据库迁移至独立数据库时，需要确定切换窗口、数据复制一致性、Run 的排空或迁移、对象存储引用、搜索索引重建、密钥轮换、双写风险和回滚计划。应采用清单校验（记录数、摘要、引用完整性），并在切换后执行跨租户隔离测试。
11.3 停用与删除
停用先阻断新请求与新执行，再处理在途任务和连接；删除需枚举数据库、对象存储、缓存、索引、日志、备份和外部交付物。保留期、法定保全、财务记录及审计要求可能阻止立即删除。应向用户说明哪些数据可删除、何时删除、哪些外部副本不受平台控制。
12 · 平台 API 与数据契约
12.1 示例接口
| 方法 | 路径 | 功能 | 关键约束 |
|---|---|---|---|
| POST | /v1/tenants | 创建租户 | 平台级管理授权；幂等键 |
| GET | /v1/tenants/{tenant_id} | 查看租户 | 成员或管理权限 |
| POST | /v1/tenants/{tenant_id}/workspaces | 创建工作空间 | 验证租户状态与配额 |
| POST | /v1/workspaces/{workspace_id}/members | 添加成员 | 验证成员管理权限 |
| GET | /v1/projects/{project_id}/assets | 列出资产 | 可信租户上下文 + 对象过滤 |
| POST | /v1/assets/{asset_id}/grants | 共享资产 | 分类、审批、目标租户校验 |
| DELETE | /v1/grants/{grant_id} | 撤销共享 | 原授权管理者或治理角色 |
| POST | /v1/tenants/{tenant_id}/suspend | 停用租户 | 高风险操作、审计 |
路径中的租户 ID 是定位信息，不是授权凭据。批量接口、分页游标、WebSocket 订阅与事件查询应遵守相同隔离规则。错误响应不得泄露其他租户的对象存在性、成员名单或内部配置。
12.2 事件契约
{
"event_id": "evt_123",
"event_type": "workspace.member.revoked",
"tenant_id": "tnt_a",
"workspace_id": "wsp_01",
"principal_id": "usr_42",
"occurred_at": "2026-10-31T12:00:00Z",
"policy_revision": "pol_18"
}事件消费者不能因为消息带有 tenant_id 就认为其可信，应验证事件来源、签名或内部身份，并通过数据库事实重新确认关键操作。事件可能重复或乱序，需要幂等处理与版本比较。
13 · Studio：多 Agent 研究平台的完整案例
13.1 场景
Studio 有两个独立客户租户 A、B。租户 A 包含研究工作空间及多个项目；选题 Agent、调研 Agent、审核 Agent 使用共享模型网关，但 A 的私有知识库和搜索凭证不得被 B 访问。研究任务产生的草稿、证据与正式报告都归属于 A 的项目。
flowchart TB
subgraph TA[Tenant A]
WA[Research Workspace]
PA[Project: Agent Report]
RA[Workflow Run A]
AA[Artifacts A]
WA --> PA --> RA --> AA
end
subgraph TB[Tenant B]
WB[Research Workspace B]
PB[Project B]
RB[Workflow Run B]
AB[Artifacts B]
WB --> PB --> RB --> AB
end
RA --> GW[Shared Model / Tool Gateway]
RB --> GW
GW --> AUTH[Per-call Authorization + Metering]
AUTH --> EXT[External Providers]13.2 典型执行流程
- 用户登录后选择租户 A，服务端验证其成员关系与项目权限。
- 创建研究 Workflow Run；Run 保存
tenant_id、workspace_id、project_id、工作流版本、发起主体及授权来源。 - 调度器为 A 分配执行资源，Worker 仅取得该 Run 所需的短期访问权限。
- 调研 Agent 检索 A 的私有知识库；资源网关检查绑定关系与当前授权。
- 审核 Agent 读取该项目的草稿与证据；其权限不自动扩大到 A 的其他项目。
- 产物服务登记 Asset Version，并绑定项目与 Run 的来源信息。
- 用户选择将正式报告只读共享给租户 B；平台生成经审批的 Grant，而非改写资产所有权。
- 共享撤销后，B 无法继续通过平台读取该资产，但已下载的副本不保证被追回。
13.3 初期推荐架构
对于仍在 MVP 阶段的 Studio，建议采用单平台实例 + PostgreSQL 共享表（复合外键与 RLS）+ 对象存储私有桶 + 持久化队列 + 受控 Worker + 统一资源网关。先实现严格的租户和项目归属、成员关系、对象级授权、运行上下文与审计，再扩展组织管理、跨租户共享和专属执行池。
如果产品尚未对外提供多租户服务，也应在核心业务表和运行事件中保留稳定的租户归属字段，避免未来迁移时需要重构全部数据关系。但不要过早构建复杂的跨租户 Marketplace 和组织层级。
14 · 工程实施路线
| 阶段 | 目标 | 最小交付 | 验收门槛 |
|---|---|---|---|
| M0 单租户基础 | 确立归属模型 | Tenant/Workspace/Project ID、复合外键 | 无孤儿或跨域引用 |
| M1 多租户最小版 | 保障 API 与数据隔离 | Membership、AuthZ、RLS、私有对象存储 | 关键越权测试全部拒绝 |
| M2 异步运行隔离 | 覆盖 Worker、队列、工具 | 运行身份、租户限流、凭证隔离 | 故障与撤销测试通过 |
| M3 共享与协作 | 受控跨空间/租户共享 | Grant、审批、撤销、审计 | 共享边界可追溯 |
| M4 企业级隔离 | 专属数据库/执行池、合规 | 混合拓扑、迁移与灾备 | 隔离与恢复演练通过 |
“通过”是未来验收条件，不是当前已完成的测试结果。
15 · 故障模式与应对
| 故障或攻击 | 根因 | 防护与恢复 |
|---|---|---|
| API 越权读取 | 仅按对象 ID 查询 | 对象归属解析 + AuthZ + RLS |
| 数据库串租写入 | 外键不包含 tenant_id | 复合外键与写入策略 |
| 连接池上下文污染 | 会话变量未重置 | 事务级上下文、连接池测试 |
| 向量搜索泄露 | 未使用可信过滤器 | 查询前隔离 + 返回前授权 |
| 缓存串租 | 缓存键缺少作用域 | 租户级命名空间、权限失效 |
| 对象存储误公开 | 公共桶/长效 URL | 私有桶、短期凭证、下载代理 |
| Worker 串用密钥 | 全局环境变量含所有租户密钥 | 按任务短期凭证、Secrets Manager |
| 提示注入跨租户访问 | Agent 将文本当权限 | 工具网关独立授权 |
| 噪声邻居 | 无租户并发与预算 | 公平调度、限流与隔离池 |
| 撤销后继续访问 | 只在 Run 启动时检查 | 敏感调用逐次授权与撤销事件 |
| 管理脚本误删 | 绕过租户作用域 | 审批、dry-run、审计、备份 |
| 跨租户共享无法追回 | 已产生外部副本 | 事前告知、分类与导出控制 |
16 · 验证方法与测试矩阵
下表是待执行测试设计，未在真实系统中执行。
| ID | 测试项目 | 预期结果 |
|---|---|---|
| T01 | A 用户读取 B 的资产 ID | 拒绝且不泄露敏感元数据 |
| T02 | A 用户修改请求头 tenant_id 为 B | 服务端拒绝伪造作用域 |
| T03 | A 用户访问 B 的 SSE Run 事件 | 无跨租户事件 |
| T04 | A 用户访问 B 的 WebSocket 频道 | 握手或订阅被拒绝 |
| T05 | A 用户通过分页游标读取 B 数据 | 游标作用域校验失败 |
| T06 | A 用户利用批量接口混入 B 资产 ID | 逐对象拒绝越权项 |
| T07 | 插入 A 资产引用 B 项目 | 复合外键拒绝 |
| T08 | 更新 A 记录的 tenant_id 为 B | RLS/业务策略拒绝 |
| T09 | 数据库连接池复用 A/B 请求 | 不残留上一个租户上下文 |
| T10 | 高权限数据库角色意外绕过 RLS | 检测并阻止在业务路径使用 |
| T11 | A 向量查询包含 B 文档 | 无 B 内容返回 |
| T12 | A/B 相同缓存业务键 | 结果严格分离 |
| T13 | B 猜测 A 的对象存储键 | 无法读取 |
| T14 | A 下载 URL 过期后复用 | 拒绝 |
| T15 | A Worker 请求 B 的连接凭证 | 凭证服务拒绝 |
| T16 | Agent Prompt 注入要求访问 B | 工具网关拒绝 |
| T17 | 运行期间撤销 A 用户成员身份 | 后续敏感操作被拒绝 |
| T18 | 运行期间停用租户 A | 新 Run 被拒绝；旧 Run 按策略处理 |
| T19 | 队列消息错误绑定租户 | Worker 验证失败且审计 |
| T20 | DLQ 重放其他租户消息 | 重放权限被拒绝 |
| T21 | A 高并发耗尽 Worker | B 的服务等级仍在目标范围 |
| T22 | A 对 B 资产创建共享授权 | 未经所有者授权时拒绝 |
| T23 | 正常跨租户只读 Grant | 仅指定动作和版本可访问 |
| T24 | Grant 到期或撤销 | 后续平台访问失败 |
| T25 | 共享后创建衍生资产 | 来源与归属可追踪 |
| T26 | 搜索日志含敏感凭证 | 脱敏与访问控制生效 |
| T27 | 租户迁移前后数据校验 | 记录数、摘要、引用一致 |
| T28 | 租户删除涉及缓存/索引/备份 | 处理状态与保留例外可审计 |
| T29 | 组织管理员跨项目查看受限资产 | 按分类策略拒绝 |
| T30 | 恶意插件尝试访问宿主机文件 | 沙箱与文件权限阻断 |
| T31 | 跨租户定时任务误触发 | 调度作用域校验失败 |
| T32 | Webhook 携带伪造租户字段 | 验证签名与真实资源归属 |
建议结合单元测试、属性测试、API 对抗测试、数据库权限测试、Worker 故障注入和多租户负载测试；在 CI 中至少保留关键越权回归集。性能测试需要明确硬件、租户规模、工作负载、SLO 与数据分布，否则无法给出可泛化的吞吐结论。
17 · 局限、取舍与开放问题
- 租户与组织的映射因商业模式而异。 个人 SaaS、企业私有化部署和平台市场可能需要不同层级；本文不将某一模型当作行业标准。
- RLS 不是完整隔离。 数据库角色、函数、安全定义者、连接池与维护脚本仍可能构成绕过路径。
- 容器隔离不等于强安全沙箱。 对不可信代码应进行专门威胁建模与安全评估。
- 跨租户共享与数据驻留可能冲突。 数据副本、索引、备份和模型供应商区域必须纳入约束。
- 模型供应商的数据使用规则随服务与配置变化。 需要针对实际合同、区域、模型与保留设置逐项核验。
- 撤销无法消除已经发生的副作用。 外部邮件、公开页面、下载文件和第三方数据库修改需单独处理。
- 复杂授权引擎会增加维护成本。 初期应优先采用明确、可测试的权限矩阵与资源归属，再引入复杂策略语言。
18 · 总结
Agent Platform 的多租户能力是一个横贯控制面、执行面、数据面与集成面的系统工程。可靠的设计应以可信租户上下文和明确资源归属为基础，以对象级授权、数据库约束、存储与执行隔离形成纵深防御，再通过受控共享、审计和对抗测试验证边界。对于 Studio，最有价值的近期目标不是尽早构建复杂组织系统，而是让每个 Agent、Run、Artifact、Connection 和 Tool Invocation 都具备可验证的归属与权限约束。
下一篇：P12 · 如何管理平台权限、资源配额与治理策略？ - Platform Governance。 P12 将在本篇隔离边界之上研究策略定义、执行点、配额预算、审批与审计治理。
附录 A：参考文献与原始资料
以下优先列出规范与官方文档；它们支持本文所用的安全、数据库与系统设计原则，并不意味着这些来源直接定义了 Agent Platform 的多租户标准。
- PostgreSQL Global Development Group. Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html - 行级安全、角色绕过与策略行为。
- PostgreSQL Global Development Group. SET. www.postgresql.org/docs/current/sql-set.html - 会话与事务配置作用域。
- OWASP. API Security Top 10 - API1:2023 Broken Object Level Authorization. owasp.org/API-Security/editions/2023/en/0xa1-broken-object-level-authorization - 对象级授权风险。
- OWASP. Authorization Cheat Sheet. cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html - 最小权限、默认拒绝与逐请求检查。
- NIST. SP 800-53 Rev. 5: Security and Privacy Controls for Information Systems and Organizations. csrc.nist.gov/pubs/sp/800/53/r5/upd1/final - 访问控制、审计与系统安全控制框架。
- NIST. SP 800-207: Zero Trust Architecture. csrc.nist.gov/pubs/sp/800/207/final - 以身份和策略为中心的访问控制思路。
- Kubernetes. Multi-tenancy. kubernetes.io/docs/concepts/security/multi-tenancy - 命名空间与多租户计算隔离的官方讨论。
- Kubernetes. Network Policies. kubernetes.io/docs/concepts/services-networking/network-policies - 网络流量隔离机制与条件。
- Kubernetes. Resource Quotas. kubernetes.io/docs/concepts/policy/resource-quotas - 资源配额机制。
- Open Policy Agent. Documentation. www.openpolicyagent.org/docs - 策略即代码与授权决策引擎。
- OpenFGA. Documentation. openfga.dev/docs - 关系型授权模型的工程参考。
- AWS. SaaS Tenant Isolation Strategies. docs.aws.amazon.com/whitepapers/latest/saas-tenant-isolation-strategies/saas-tenant-isolation-strategies.html - SaaS 租户隔离的不同模式与取舍。
- AWS. Amazon S3 Presigned URLs. docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html - 预签名 URL 的授权与时效行为。
- OpenTelemetry. Context. opentelemetry.io/docs/concepts/context-propagation - 分布式上下文传播参考；安全授权上下文仍需独立校验。
- OWASP. LLM Prompt Injection Prevention Cheat Sheet. cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html - Agent 工具调用受到提示注入影响的安全风险。
附录 B：研究证据、验证声明与适用边界
B.1 证据层级
- 规范/官方资料支持： PostgreSQL RLS、Kubernetes 多租户与资源配额、OWASP 对象级授权、NIST 访问控制原则、S3 预签名 URL 等属于可在原始文档核对的机制。
- 工程综合与参考设计： 本文的 Tenant/Workspace/Project 对象模型、Studio 权限矩阵、跨租户 Grant 契约、API 路径、SQL 表结构及阶段路线，是基于上述原则组合的架构建议，并非某一标准规定的唯一实现。
- 待验证假设： 共享表 + RLS 对 Studio 当前规模的成本与性能、专属 Worker 的实际收益、混合拓扑的运维成本，需要在真实工作负载中测量。
B.2 验证声明
本文未部署数据库、执行 SQL、进行渗透测试、负载测试或外部服务集成测试；测试矩阵是建议的验收计划。参考资料链接用于后续核验，本文未对所有链接进行当日在线逐页复核。上线前应检查实际使用的软件版本、云服务配置、适用法规与供应商条款。
B.3 适用范围
适用于面向多个客户、组织或工作空间的 Agent Platform，尤其适用于具有外部工具调用、长时工作流、知识检索和资产交付能力的系统。单用户本地 Agent 可简化组织层级，但仍应保留凭证隔离、最小权限、运行沙箱与审计等基本原则。