chenchenandClaude Opus 4.8
88240dc79e
Synthesizes Claude's admin-setup/authentication/server-managed-settings/settings/ managed-mcp/auto-mode docs into a team-management design for HM, mapped onto the analogy (client≈Claude Code, HM≈Claude.ai admin console, AM≈cloud agent) and grounded in HM's existing primitives (new-api users/groups/sk-token model-limits/ quota, plus our V2 device auth, resource bindings, agent templates, /v1 gateway). Covers org/team/seat model, roles, allocation, managed-settings push over the V2 channel, managed agent/tool catalog, auth/SSO, auto-mode, audit, and a phased plan. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
16 KiB
16 KiB
HM 团队管控设计（参考 Claude Code 企业范式）
起草：2026-06-05 · 状态：设计草案（供讨论，不含实现）
类比锚点：我们的桌面客户端 ≈ Claude Code · HM（Heicode Manager）≈ Claude.ai 企业/管理控制台 · AM（agent_management）≈ 云端 agent 运行时。
本文把 Claude 的企业管控范式（来自官方文档 admin-setup / authentication / server-managed-settings / settings / managed-mcp / auto-mode-config）提炼为「团队如何通过 HM 控制与分配」的设计，并逐条对齐 HM 现状（new-api fork 本身已有的能力 + 我们已加的 V2 设备鉴权 / 资源绑定 / agent 模板 / 模型网关）。
0. 一句话目标
让一个团队/组织的管理员，能在 HM 控制台里：拉人 → 分角色 → 配可用模型与额度 → 授权可用资源/agent/工具 → 把策略强制下发到每个客户端 → 看用量与审计。客户端（我们的桌面端）只能在 HM 划定的边界内工作；真正的硬边界由 HM 网关侧强制，而非依赖客户端自觉。
1. Claude 范式精炼：三层控制
Claude 的企业管控可归纳为三层，HM 应整体借鉴这套分层：
| 层 | Claude 机制 | 作用 |
|---|---|---|
| 身份与准入 | 提供商选择 + 座位(seat) + 邀请/角色 + SSO/SCIM/域名捕获 | 决定「谁能用、用哪个组织身份」 |
| 策略下发（受管设置） | server-managed-settings：管理员在 Web 控制台下发 JSON，客户端登录时拉取、每小时刷新、最高优先级不可本地覆盖、数组规则只增不删 | 决定「客户端能做什么、不能做什么」 |
| 能力供给（受管工具/agent） | managed-mcp + agent/插件下发：组织级统一发一批可用 MCP/工具，可「软允许」或「独占控制」，deny 永远优先 | 决定「客户端有哪些工具/agent 可用」 |
外加两条贯穿性能力：分配与计费（模型白名单、支出/速率上限、用量归属）与审计（compliance API、审计日志、ZDR）。
Claude 自己承认的最大短板，正是 HM 的机会：
- server-managed 是纯客户端控制（client-side control）——有 sudo 的用户能改二进制/绕过；HM 是网关，可把强制放在服务端，更硬。
- server-managed 暂不支持分组（全组织统一）；HM 用 V2 设备鉴权天然能按设备/用户/组织下发。
- 配置第三方 provider（Bedrock/自定义 BASE_URL）会完全绕过 server-managed；HM 须在网关侧封死这条旁路。
2. HM 现状盘点（已有 vs 缺口）
重要：HM 是 new-api fork，很多分配原语已经现成，团队管控不是从零造，而是「加一个组织层 + 一套策略下发通道」。
2.1 已有（可直接复用的原语）
- 用户与角色：new-api 有
role（普通=1 / 管理员=10 / 超级管理员=100）。 - 分组(group)：
User.Group+ 分组级模型倍率/可用性。 - 令牌(sk-)：
model.Token支持 per-token 模型限制model_limits、配额RemainingQuota/UnlimitedQuota、过期ExpiredTime、速率、HideFromUserUI等——这就是「按 key 限模型 + 限额」的现成能力。 - 配额/计费：用户
Quota/UsedQuota、计费表达式系统（pkg/billingexpr）、日志归属。 - 模型网关：
/v1/*统一鉴权 + 计费 + 路由（团队可用模型的强制点天然在这）。 - V2 设备鉴权（我们加的）：Ed25519 验签 + X25519/ChaCha20 加密，
/api/agnet/user/*用户身份唯一来源——这是策略安全下发的现成通道。 - 资源绑定（我们加的）：KV + secret_ref，按用户隔离。
- agent 模板库（我们加的）：admin CRUD + 下发客户端列表 + 部署到 AM——这已经是一个「受管 agent registry」雏形。
2.2 缺口（需新建）
- 组织/团队对象层：当前是「用户」单层，没有 org→team→member 的多租户层与座位概念。
- 角色细化：只有 1/10/100 三档全局角色，缺「组织内 owner/admin/member/auditor」与「能配 AM / 能配模型 / 只能用客户端」的能力维度。
- 受管设置下发通道：没有「服务端下发、客户端强制、不可覆盖」的策略机制（对标 server-managed-settings）。
- 受管工具/agent 的 allow/deny 策略语义：agent 模板目前是「全部可见」，缺组织级白/黑名单与「软下发 vs 独占」两档。
- SSO/SCIM/域名捕获：缺企业身份联邦与自动归属。
- 组织级用量看板与审计日志：缺按组织/成员的用量归属与策略变更审计。
3. HM 团队管控设计
3.1 对象模型：组织 → 团队 → 成员 → 座位
Organization (租户，计费主体)
├─ Team (可选二级，部门/项目组)
│ └─ Membership (User × role × seat)
├─ Plan / Seats (席位订阅：座位是否含「客户端访问」「AM 调用额度」)
├─ Policy (受管设置，§3.4)
├─ ToolCatalog (受管 agent/MCP/资源目录，§3.5)
└─ Quota / SpendLimit (组织级额度池，§3.3)
- 座位(seat)= 客户端访问的硬开关（对标 Claude「座位不含 Claude Code 访问会被拒登」）。HM 落点：V2 设备登录后，先校验该用户在某组织有有效座位，才签发客户端身份；无座位 → 拒绝拿到 agent 列表/资源/模型 key。
- 复用 new-api：
Organization可由现有group升级承载，或新建organizations/memberships表（GORM AutoMigrate 加表，跨 SQLite/MySQL/PG）。
3.2 角色与权限
借鉴 Claude「角色 = 能创建/使用哪类凭证 + 能调哪些能力」的朴素范式，定义组织内角色：
| 角色 | 能力 |
|---|---|
| Owner | 全权：计费、座位、下发受管策略、增删 admin |
| Admin | 管成员、配模型白名单/额度、配 agent 目录、下发策略（不含计费/删 owner） |
| Member | 用客户端 + 已授权的 agent/资源/模型 |
| Auditor（只读） | 看用量、审计日志，不能改 |
并用正交的能力位细分（参考 Claude 把「能创建哪类 key」做成角色）：can_manage_models / can_manage_agents / can_manage_resources / can_push_policy / can_view_audit。落点：成员表加 role + capabilities 位图。
3.3 分配（模型 / 配额 / 资源 / agent）—— 大量复用 new-api 现成能力
这是 HM 相对 Claude 的强项（Claude 这部分靠外部 gateway，HM 自己就是 gateway）：
| 分配维度 | 机制 | 复用 HM 现状 |
|---|---|---|
| 可用模型白名单 | 组织/团队/成员级允许模型集 | 复用 Token.model_limits + 分组模型可用性；网关 /v1/* 已是强制点 |
| 支出上限(spend limit) | 组织额度池 + 成员子额度 | 复用 User.Quota/UnlimitedQuota + 计费表达式 |
| 速率限制(rate limit) | 按组织/成员/key | 复用 new-api 既有 rate limit |
| 凭据有效期 | CI/服务用短期/长期 token（对标 claude setup-token 一年期、仅推理、不可建远控会话） |
复用 Token.ExpiredTime + 范围位 |
| 可用资源 | 授权某成员/团队可绑定哪些资源类型 | 复用资源绑定 + KV secret_ref |
| 可用 agent 模板 | 组织级 agent 目录（§3.5） | 复用 agent 模板库 + 下发列表 |
关键设计：把「分配」做成组织池 → 成员子额度的两级（组织买总量，admin 切给成员），对应 Claude 的座位/支出归属。
3.4 受管设置下发（核心，对标 server-managed-settings）
这是最值得照搬的范式。HM 设计：
a) 下发通道 = 复用 V2 设备鉴权
- 策略以 JSON 形式，挂在设备鉴权返回里下发（
/api/agnet/user/*已是身份唯一来源）。 - Ed25519 验签保证策略不被中间篡改——比 Claude 纯客户端控制更强。
- 天然支持按组织/团队/设备分组下发，补上 Claude「暂不支持分组」的缺口。
b) 优先级与合并（照搬 Claude 语义）
- 受管层 = 最高优先级，客户端 user/project/CLI 本地配置不可覆盖。
- 区分两类：强制项(enforced，不可改) vs 默认值(default，客户端可改)。
- 数组类规则（如允许模型、允许域）只增不删：客户端只能在受管基础上扩展，不能删受管项；但允许「自我收紧」（客户端可为自己再 deny）。
c) 拉取 / 缓存 / 故障策略（照搬）
- 客户端启动拉取 + 周期刷新（Claude 每小时）；本地缓存，断网仍按上次策略执行。
- fail-closed 开关（对标
forceRemoteSettingsRefresh）：高敏组织拉取失败即拒绝启动客户端，杜绝「未强制窗口」。 - 豁免重认证：fail-closed 不能把「登录/续签」也锁死（Claude 的教训——凭证过期时要留重认证口子）。
/status式自检：客户端能显示「当前生效策略来源 + 是否受管」。
d) 优先做的强制项（对标 Claude managed-only 键，挑贴合 HM 的）
| HM 强制项 | 对标 Claude 键 | 为什么 |
|---|---|---|
| 可用模型白名单 | availableModels |
HM 是 /v1/* 网关，计费/合规边界 |
| 网络/域名准入 | sandbox.network.allowedDomains + allowManagedDomainsOnly |
锁客户端只能连 HM 及受信域 |
| 危险操作禁止 | permissions.deny + allowManagedPermissionRulesOnly |
禁读 secrets、禁危险命令，且禁客户端放宽 |
| 登录组织绑定 | forceLoginOrgUUID / forceLoginMethod |
强制客户端只认 HM 签发身份，堵旁路 |
| 高危能力开关 | disableBypassPermissionsMode / disableRemoteControl 等 |
按组织策略关高危能力 |
| 审计 hook | managed hooks + PostToolUse |
客户端编辑后强制跑审计 |
⚠️ MEMORY 已记的隐患：策略状态不要只放单实例内存 map，要持久化 + 多实例一致（HM 单实例内存 map 隐患）。
3.5 受管工具 / agent（对标 managed-mcp）
HM 已有 agent 模板下发，等于自带 registry（Claude 反而没有内置 registry）。把它升级为带策略的「组织级能力供给」：
a) 两档下发语义（必须显式，不要隐式）
- 软下发(additive)：HM 发一批可用 agent/工具，客户端仍可叠加自配 → 对标 Claude「软允许列表」。
- 独占控制(exclusive)：客户端只能用 HM 下发的，本地自建被服务端拒绝 → 对标
managed-mcp.json独占控制。
b) allow/deny 三步评估（照搬）
- 各源 allow/deny 合并；开启「仅受管」开关时本地 allow 失效、只认 HM allow；
- deny 永远优先、不可被任何层覆盖，且 deny 从所有源合并（用户能为自己再禁，不能放宽）；
- allow 命中才放行。
c) 匹配落到不可伪造标识
- Claude 警告「只按 server 名字匹配不安全」。HM 校验客户端可用 agent/工具时，不要只信客户端上报的名字，要绑定模板 ID + 签名 + 设备身份（V2 鉴权链已具备）。
- 直接受益：解决我们 AM 契约 §3.1 那条「按用户隔离」——agent 准入也走同一套不可伪造标识。
d) 凭据 per-user，不入下发物
- Claude 禁止把 key 写进下发的
env。HM 下发「连接定义」但凭据按用户动态注入/OAuth（契合已有 Managed Identity / Key Vault）——下发物里绝不出现共享密钥。
e) 变更可观测
- Claude 痛点是「server 被新策略静默消失、用户不知原因」。HM 作为网关，下发变更时给客户端可见原因，并在服务端记录「客户端实际调了哪些工具/agent」。
3.6 认证与准入（对标 authentication + SSO）
- 多种登录分层：个人订阅式 OAuth、Console 式 key、CI 长期 token（范围限定：仅推理、不可建远控会话）、网关 bearer token（
ANTHROPIC_AUTH_TOKEN路线天然契合 HM 作网关）。 - 确定性凭据优先级：客户端需一套固定选择顺序（网关 token > 设备 OAuth > …），并处理「key 属过期组织→认证失败」的冲突态，给
/status诊断。 - 企业强制：组织可强制 SSO/SAML + SCIM 自动配置 + 域名捕获，把同域用户自动归属到组织身份——决定「客户端用哪个组织身份接入」。
- 封旁路：Claude 承认配第三方 provider 会绕过 server-managed。HM 必须在网关侧强制：客户端的模型请求只能经 HM，绕过即无额度/无身份。
3.7 auto-mode 类客户端行为（软策略 + 网关硬边界）
- auto-mode 的教训：分类器合并是累加、可被用户 allow 覆盖，不是硬边界；真正不可绕过的放
permissions.deny（分类器之前）。 - 映射 HM：
- HM 可下发一套「受信环境/允许/拒绝」语义偏好（组织级），统一风险口径、减少误拦；
- 但**「绝不允许」的能力边界，HM 在网关侧（请求进模型/工具前）硬拦**，等同
permissions.deny角色，不依赖客户端分类器。
- 隔离不可信来源：客户端/项目侧上报的规则只能收紧、不能放宽 HM 下发的策略（对标「分类器不读 check-in 的共享项目设置」）。
3.8 审计与用量
- 用量归属看板：对标 Claude Analytics（每用户指标、贡献、排行榜）——按组织/团队/成员的 token 用量、模型分布、agent 调用，复用 new-api 日志 + 计费。
- 审计日志：对标 compliance API——策略下发、成员变更、agent 部署/删除全程留痕（操作者、设备、新旧值）。HM 作网关是放请求级审计的天然位置。
- 数据留存：可选 ZDR / 零留存档位。
4. 关键设计原则（HM 要比 Claude 更硬的三点）
- 硬强制在服务端，不在客户端。Claude 的 server-managed 是客户端控制、可被 sudo 绕过。HM 把模型/工具/agent 的真正准入放在网关 + V2 鉴权侧——客户端策略只是第一道 UX，越权请求在 HM 被拒。
- 下发通道带验签。复用 V2（Ed25519+ChaCha20）下发策略，防篡改、可按组织/设备分组——一举补上 Claude「分组缺失 + 纯客户端控制」两个短板。
- 不对称权限：受管策略「能自我收紧、不能自我放宽」；deny 永远优先且不可覆盖；凭据 per-user 永不入下发物。
5. 落地优先级（建议分阶段）
P0（地基）
- 组织/团队/成员/座位对象模型（新表，AutoMigrate）；座位作为 V2 登录签发客户端身份的前置门。
- 组织内角色 + 能力位。
P1（分配，复用现成原语，见效快）
- 组织池 → 成员子额度（模型白名单 / 支出上限 / 速率 / 凭据有效期），全部映射到
Token.model_limits+ 配额 +ExpiredTime。 - 组织级 agent 目录：给现有 agent 模板加「组织可见性 + allow/deny + 软/独占」字段。
P2（受管设置下发，核心差异化）
- 受管策略表 + V2 通道下发 + 优先级合并 + 拉取/缓存/fail-closed +
/status自检。 - 先落 6 个强制项中的：可用模型白名单、网络域白名单、
permissions.deny、登录组织绑定。
P3（企业身份与审计）
- SSO/SAML + SCIM + 域名捕获；组织用量看板 + 审计日志。
附：来源与对照
| 本文章节 | Claude 文档来源 |
|---|---|
| §1、§3.1 座位/准入、§3.6 认证 | admin-setup、authentication |
| §3.4 受管设置下发 | server-managed-settings、settings |
| §3.5 受管 agent/工具 | managed-mcp |
| §3.7 auto-mode | auto-mode-config |
待补（Claude 文档外链未展开，设计 SSO/SCIM 细节前再抓）：SAML 字段、SCIM 属性映射、域名捕获流程、Enterprise 完整角色清单（在《Claude Enterprise Administrator Guide》）。