多租户与权限

多租户与权限

多租户（Multi-Tenancy）是 HeteroFlow 平台的企业级核心能力：把一套 GPU 集群安全地划分给多个团队或客户使用。租户（Tenant）是平台最基本的隔离单元——每个租户拥有独立的成员名单、独立的资源配额、独立的数据边界与独立的用量账目，租户之间默认完全隔离，一个租户在任何接口上都无法看到、更无法操作另一个租户的资源。可以把它类比成一栋写字楼：整栋楼是集群，每个租户占一层，每层有自己的工位配额（GPU 配额）、门禁卡（API Key）、水电表（用量核算）和访客登记（操作审计）。

平台采用两级管理域设计：平台管理员管理"有哪些租户"——创建租户、调整配额、划拨节点、配置跨租户共享组，面向平台运营方；租户管理员管理"租户内部的人与资源"——邀请成员、分配角色、设定成员密钥限额、查看本租户用量与审计。两级管理域互不越权：租户管理员不能决定跨租户事务，平台管理员的敏感代管操作则全程留痕。这套体系让"一套集群服务多个客户"在数据、资源、凭据、用量核算四个维度上同时成立。

功能总览

---

一、角色体系

三层权限模型

权限判定由三层组成，逐层收窄：

两个"角色"概念务必分清：平台角色回答"是否平台运维"，租户内角色回答"在租户内部是管理员、普通成员还是只读者"。一个平台角色普通的账号完全可以是自己租户里的租户管理员（团队负责人的常见形态）；平台运维则在任何租户上都被判定为等价管理员，不查 tenant_users 表。

租户内三级角色能力矩阵

两条容易被忽略的红线：

• viewer 的只读先于归属判定生效——viewer 不能发起任何写操作，哪怕对象是自己创建的资源（例如 viewer 无法撤销自己名下的 Key，需租户管理员代为处理）。
• 角色查不出来时按最窄档处理（fail-closed）——查库失败或不在成员表里的调用方，一律按 member/viewer 的最窄口径执行，绝不因"查不到"而放宽。

API Key scope：叠加在角色之上的第二层闸门

每把 Key 签发时声明 scope，每次请求由中间件强制校验：

scope 上限由持有者的租户内角色决定：viewer 的所有 Key 强制为 read。这样"viewer 只读"在资源归属判定与 Key scope 两道闸门上同时成立，单独绕过其中一道都没有用。

四层视角

聚合类读接口（仪表盘、任务统计、告警、分片统计、健康明细）与上面的三档可见范围同源判定——同一个人在任何页面看到的范围一致。

---

二、成员管理

租户成员的四类管理操作：

"创建并加入"与"邀请成员"的区别：前者面向"人还不存在"的场景，建号与挂载在同一数据库事务里，要么都成要么都不成；后者面向"账号已在别处注册"的场景。租户管理员给租户加人优先用"创建并加入"。

移除成员的级联清理：移除时按账号来源分两支——经"创建并加入"产生的账号在最后一个成员关系被移除时连账号带全部 Key 一起删除（释放用户名）；先在别处注册、后被邀请进来的既有账号只解绑：撤销其在本租户的所有 Key、账号归属回落到公共池。

成员变更即时吊销会话：以下操作与业务写入同一事务让当事人已签发的 JWT 立即失效（多实例部署下最多滞后 5 秒）：

---

三、成员级 API Key

Key 类型

签发与存储

• 本租户任意已认证成员（含 viewer）均可自助创建自己的 Key——不需要、也不能由管理员代创建。这是刻意设计：资源归属要精确到人，必须让每个成员持有自己的 Key；管理员冒充成员身份操作会破坏追责链。
• 服务端用加密随机数生成 32 位 hex，拼成 sk-tenant- 前缀；数据库只存 SHA-256 哈希，明文仅在创建响应里返回一次，列表接口只回显前缀。
• 请求体严格解码：expires_in_days 等字段名敲错会被 400 拒绝，不会静默签出永不过期的密钥。

权限继承

Key 天然继承持有者的全部权限判定：持有者的租户归属、租户内角色、资源归属（本人资源可读写、他人资源 404）对 Key 调用与本人登录态完全同口径——下游判定的是同一个身份值，不区分它来自登录还是来自 Key。因此若持有者是租户管理员，其 Key 同样能执行成员管理等管理面操作。

Key 级限流与额度

每把 Key 可单独配置五项限额：qps_limit（每秒请求数）、concurrency_limit（并发在途请求数）、daily_call_limit / monthly_call_limit（日/月调用次数）、monthly_token_quota（月 Token 额度，当前仅占位不强制）。全部为 0（默认）表示不限制。超限返回 429，带 Retry-After 与 X-RateLimit-* 响应头，额度类带重置时间。只作用于推理调用接口，不影响管理面。

成员 Key 限额上限

租户管理员可为整个租户设置一组"成员 Key 限额上限"（GET/PUT /api/v1/tenant/member-key-limit-caps）：设置后，非管理员成员（含 viewer）新建或编辑自己的 Key 时，五项限额每一项都不得超过上限——"填 0 表示不限"也算超过。上限只约束成员之后的建/改操作，不追溯调整存量 Key；租户管理员与平台管理员不受约束。前端建 Key 弹窗会展示当前上限并默认填入。

撤销与编辑

• 撤销（DELETE）立即生效：置撤销标记并即时清空校验缓存，下一个请求即 401。
• 编辑限额（PUT）权限同撤销：本人（viewer 除外）或租户管理员/平台管理员。成员编辑自己的 Key 时限额只能收紧、不能放宽或取消；新建不限额 Key 绕过检查的路子则被上面的租户级上限堵住。
• 智能路由覆盖：开启模型智能路由后，可对单把 Key 覆盖 model=auto 的开关与策略（quality/speed/cost），不影响其他 Key。

---

四、认证集成：JWT 与 API Key 双轨

平台同时接受两种凭据，覆盖"人"与"程序"两类调用方：

两轨在中间件层汇合成同一身份上下文：租户归属、用户身份、scope 三要素注入后，下游所有权限与配额逻辑对两种凭据一视同仁。推理接口（/v1/chat/completions 等）两条认证路径都可用——端点专属 Key（无成员身份，用量不按人拆分）或成员自己的 Key / 登录态（用量带成员归属，可按人拆账）。平台级账号体系（登录、密码、平台管理员账号）的完整说明见《用户管理》篇，本篇聚焦租户内部的凭据与权限。

每次请求经过四层中间件依次处理：租户上下文（解析凭据注入身份）→ 审计（旁路捕获，被拒绝的请求也会被审计）→ scope 校验（read 仅放行 GET/HEAD）→ QPS 限流（滑动窗口）。

---

五、数据隔离机制

三层强制

统一 404 语义：跨租户访问不返回 403 而返回 404——"不存在"与"存在但无权"使用同一响应，调用方无法通过状态码枚举其他租户的资源 ID。这是平台安全基线，适用于任务、任务组、端点、节点、存储卷等全部资源类型。

逐资源类型的隔离行为

调度边界：排队与共存是两回事

排队等空闲资源不看租户——一张卡释放后任何租户的任务都能按先来后到排上；同时共存复用才看租户——同一张物理卡被多个任务同时占用（GPU 分片、推理显存比例共卡、训练借用休眠推理卡）必须"同租户或同共享组"，组关系查询失败一律按不允许处理（fail-closed）。无卡可配时明确失败并提示需要共享组，绝不静默降级为跨租户放置。

---

六、配额体系

配额维度

配额与套餐对应关系：Free（1 GPU / 5 端点 / 100 QPS / 10 GB，个人评估）、Pro（10 / 50 / 1000 / 100，中小团队）、Enterprise（不限，大企业）。实际结算规则由业务方制定，平台提供用量数据。

并发安全：advisory lock fail-closed

GPU 配额检查在"进程内互斥锁 + PostgreSQL advisory lock（跨实例）"的临界区内执行：多实例部署下并发请求也不会突破配额上限（双实例多轮压测恒为上限）。取锁失败时 fail-closed——宁可拒绝请求，绝不放行后超卖。

配额语义细则

• 显式设为 0 就是真的 0：管理员把某项配额降为 0 表示"封零该租户的这一能力"（例如临时冻结推理请求而不删除租户），系统按字面值拒绝新请求，不会误解为"不限"。
• 降级检查：调低配额前先检查当前用量，新值低于已有活跃资源数时返回 409 并说明数量，不允许配额降到资源存量之下。
• 超限行为：GPU 配额超限时创建任务组直接失败（403）；端点配额超限时仅跳过端点创建、任务组本身仍创建成功。
• 自动扩容同样封顶：自动扩容与调度窗口扩容按"剩余配额可容纳的副本数"封顶；滚动更新允许临时超额（否则满额租户永远无法不中断更新），但超额部分有明确上限。
• 豁免面：仅平台管理员与系统级内部调用豁免配额检查；公共默认租户与其它租户同等受配额约束。

---

七、QPS 滑动窗口限流

窗口机制

限流按租户维度执行滑动窗口算法：以当前时刻为终点取最近 1 秒的真实请求时间戳，窗口内请求数达到 max_qps 即拒绝。相比固定窗口，滑动窗口不存在"窗口边界处瞬间双倍流量"的漏洞。

超限响应

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 1

{"error": "rate limit exceeded: 100/100 QPS for tenant-abc123"}

分层与豁免

豁免面只有两类：平台管理员；以及不归属任何租户的系统级内部调用（节点心跳、探针等）。租户被显式设为 max_qps=0 时其全部请求被拒绝——这是管理员的冻结手段，不是"不限"。

---

八、用量统计与核算

双轨计量

Token 提取对流式响应同样生效：转发前自动注入 stream_options.include_usage，从 SSE 数据行中提取用量；失败请求 Token 记 0，状态按真实结果记 success/error，retry 不重复核算。

按成员拆分

用量查询支持 ?user_id=（查单个成员）与 ?group_by=user（按成员汇总，仅租户 admin / 平台管理员）：每行含成员的 Token 两列、推理请求数与 GPU 秒数。成员身份发起的推理调用天然带归属；端点共享 Key 发起的调用无成员归属，计入租户总量但不进按人拆分（各行相加不一定等于总量，属预期）。

用量面板

Web 控制台"用量统计"页提供：推理请求次数、推理 Token 数、GPU 时长（GPU·小时）、任务数、活跃端点数五个维度，按日聚合可回溯。

---

九、跨租户共享租户组

默认完全隔离；共享租户组是唯一能打开跨租户共享的开关，也是唯一的授权来源。 由平台管理员显式配置：把若干租户放进同一个组，组内租户之间允许复用推理服务、共用同一张物理卡；组外租户之间完全隔离。一个租户可以同时属于多个组，判定谓词是"存在至少一个共同的启用中分组"。

共享组内的共卡是同组内的显存与算力复用（软配额语义，防善意超用）；真正的硬件级隔离由 MIG 等硬件切分能力提供（硬件切分当前仅 NVIDIA 系真机可用），两者是不同层次。

---

十、租户生命周期

创建

创建租户时填写名称、套餐与四维配额（严格 JSON 解码，未知字段 400，防止配额字段名敲错后静默建出零配额租户；名称唯一，重名 409）。可选字段 admin_user_id 一步指定首个租户管理员：与建租户同一事务播种管理员角色，要么都成、要么都不成；不传时租户照常建成，但响应带 warning 提示该租户暂无管理员，需后续补种（平台管理员可"创建并加入"一个管理员账号）。这解决了"新租户没人能管"的自举缺口。

修改

可修改显示名、套餐、四维配额、状态与联系信息；租户名称不可改（带上不同名称返回 400）。配额降级有前置检查（见配额体系）。

停用（suspended）

停用后，该租户的资源申请类操作（创建任务、任务组扩容、创建推理端点、自动扩容与失败重建）被拒绝（403）；读接口不受影响——停用租户的成员仍能登录查看自己的任务、用量与审计。这是刻意设计：欠费停用后客户要能看到用量、去付费。成员 Key 认证同样保持通过（仅排除已软删除的租户）。

删除（软删除）

删除是软删除（置删除标记，数据保留可恢复），带两级前置检查：还有活跃任务组 → 409；还有推理端点 → 409；全部通过后单事务级联：租户置删除态、清成员映射行、成员账号归属回落到公共池。补充约束：默认租户禁删（403，后端硬保护）；已软删租户不可复活（对其执行更新一律 409）。注意删除租户与移除单个成员的凭据后果不同：软删除租户后，其成员 Key 因租户已删除而立即无法通过认证；但成员登录态 JWT 不会被吊销（与移除单个成员时"立即失效"不同），靠后续登录自然过渡。

---

十一、操作审计

记录范围与内容

全部修改型请求（POST/PUT/PATCH/DELETE）旁路捕获并异步写入审计表，记录：租户、用户、方法、路径、资源类型与 ID、状态码、错误信息、耗时、客户端 IP、User-Agent 与脱敏后的请求摘要（≤500 字符）。被 scope 或限流拒绝的请求同样留痕（审计中间件位于二者之前）。整租户数据导出这类敏感读操作也纳入审计。节点侧 agent 的例行状态回写不入审计，避免淹没真正的人工操作记录。

敏感字段脱敏

请求摘要落库前对 JSON 请求体递归脱敏：命中敏感键名（口令、密钥、凭据类）的值一律替换为 [REDACTED]，采用子串/边界匹配——新增的 ssh_password、client_secret 等组合字段同样被覆盖，同时避免误伤 keyword 这类无关词。非 JSON 请求体不落原文，只记录字节数。历史明文行已清理。

跨租户可追溯

• 平台管理员用 ?tenant_id= 代其它租户操作时，目标租户写入独立的结构化列（可检索，审计页高亮显示）；仅当"调用方是平台管理员且目标租户不同于自身"时记录，不会为普通调用方随手带的无效参数造出误导行。
• 代管留痕：租户 admin / 平台管理员操作他人资源时，审计行带"代管对象"字段，证明这次操作的真正归属。
• 平台管理员代发基础设施上报的审计行带专属标记，与 agent 自身上报严格区分。

保留期与查询

审计日志默认保留 365 天（可配置，下限 30 天），到期的清理分批异步执行。查询入口 GET /api/v1/tenant/audit-logs（分页 + 日期区间过滤），仅租户 admin / 平台管理员可读；平台管理员可定向查询任意租户。

---

十二、完整业务场景：客户接入全程

以客户 Acme 公司接入为例，串起多租户的全部能力：

全程任何一步，Acme 的成员都无法看到其它租户的资源（404 语义），所有管理动作留审计痕。

---

十三、API 参考

租户管理（平台管理员）

成员与 Key（租户自助）

示例：创建租户（指定首个管理员）

curl -X POST http://your-server:3333/api/v1/admin/tenants \
  -H "Authorization: Bearer <平台管理员JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-corp",
    "display_name": "Acme Corporation",
    "plan": "pro",
    "max_gpus": 10,
    "max_endpoints": 50,
    "max_qps": 1000,
    "admin_user_id": "user-1a2b3c4d"
  }'

# 201 —— admin_user_id 与建租户同事务生效，该用户即刻成为本租户首个租户管理员
# 不传 admin_user_id 时租户照常建成，响应带 warning 提示需补种管理员

示例：成员自助创建 Key

curl -X POST http://your-server:3333/api/v1/tenant/api-keys \
  -H "Authorization: Bearer <成员JWT或已有Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "scopes": ["read", "write"],
    "expires_in_days": 90,
    "qps_limit": 200,
    "concurrency_limit": 50
  }'

# 201 —— api_key 明文仅此一次返回；数据库只存哈希，列表只回显 sk-tenant-ab 前缀
# viewer 传 write 会被 403（角色天花板）；各项限额若超过租户上限同样 403

---

十四、最佳实践与故障排查

API Key 安全建议

1. 环境隔离：生产与测试环境使用不同 Key，避免测试侧泄露波及生产。

2. 定期轮换：建议每 90 天更换一次；签发时直接设置过期时间，到期自动失效。

3. 最小权限：只读场景签 read，业务读写才给 write；每把 Key 配置 QPS / 并发 / 日月额度限额，单把 Key 泄露的爆炸半径可控。

4. 人员变动：成员离职时由租户管理员立即撤销其名下全部 Key 并移除成员——移除操作本身会连带吊销其会话与 Key，两道都做最稳妥。

配额规划参考

常见问题速查

---

十五、已知限制

以下事项如实列出，避免误依赖：