treg 超级管理员（Super-admin）跨租户治理解析：鉴权模型、/admin 端点族与运维 CLI

后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载本指南围绕 treg 架构文档 docs/context/architecture/super-admin.md 展开结合 access.py、routers/admin.py、config.py 与 cli.py 源码完整讲解 treg 唯一的跨租户cross-tenant能力超级管理员平台视角。读完你可以掌握超级管理员的双重鉴权路径、专属数据库连接池隔离、全部/admin/*端点读、失败证据、对账、变更、授信、数据模型迁移方式以及通过 CLI 完成平台级治理的完整操作手法。在 treg 的多租户体系中几乎所有能力都严格限制在单个 org组织的作用域内成员只能看到本 org 的工具、密钥与调用记录org 管理员也仅能管理本组织。超级管理员super-admin是唯一的例外——它是站在所有 org 之上的平台视角被刻意与 org 内的角色体系剥离开来。本文将这一能力从是什么拆解到怎么用。混合鉴权模型require_superadmin的两条身份路径超级管理员门禁是 domain/identity/access.py 中的require_superadmin依赖。它采用混合hybrid鉴权满足以下任一条件即视为超级管理员环境变量令牌env-admin请求头X-Treg-Token的值等于环境变量admin_token即TREG_ADMIN_TOKEN且使用hmac.compare_digest做常量时间比较返回的 principal 固定为字符串env-admin被授予标记的用户令牌解析出的Membership所对应的User.is_superadmin为真且User.suspended为假返回的 principal 是该用户的 email。两种路径都不满足时返回 403未携带任何凭证时返回 401 not authenticated。代码层面的实现非常直观async def require_superadmin( x_treg_token: str Header(default), treg_session: str Cookie(default), db: AsyncSession Depends(get_admin_session), ) - str: admin get_settings().admin_token if x_treg_token and admin and hmac.compare_digest(x_treg_token, admin): await db.commit() return env-admin ... if user is not None and user.is_superadmin and not user.suspended: await db.commit() return user.email ... raise HTTPException(status_code403, detailsuper-admin required)几个值得注意的设计点principal 用于审计依赖返回的不是布尔值而是字符串env-admin或用户 email便于在变更类操作中记录谁做的。env key 只负责引导文档明确说明环境变量密钥只负责引导bootstraps平台上线初期用它完成首轮授权随后通过POST /admin/users/{id}/superadmin给具名用户授予is_superadmin标记Web 门户即可用任一方式登录。依赖从domain.identity.access统一导出所有消费方都从该模块导入require_superadmin历史上api.py的过渡性 re-export 已随 stage-3 兼容层退役避免出现两个门禁实现的分叉。admin_token对应的配置项在 config.py 中声明如下Pydantic Settings 通过TREG_前缀读取环境变量# Cross-tenant super-admin bearer (env TREG_ADMIN_TOKEN). Presenting it authorizes every # /admin/* endpoint regardless of org. Empty the env key is disabled (only is_superadmin # users can reach /admin). Keep it long secret; it sees ALL orgs. admin_token: str 注意默认值为空串——不配置TREG_ADMIN_TOKEN时环境变量通道被禁用只有被标记的is_superadmin用户能访问/admin/*。文档与源码都强调该密钥必须长且保密因为它能看到所有 org 的数据。专属管理连接池为什么门禁必须使用get_admin_sessionrequire_superadmin的参数中数据库依赖是Depends(get_admin_session)而不是常规的get_session。这与/admin/*下每一个被它守护的 handler保持一致构成了一个独立的数据库池边界管理池admin pool固定为 3 个连接不参与溢出no overflow与 API 主池完全分离关于池规格的默认值与覆盖配置可参考部署文档 ops/deploy.md 的 Database pools 一节TREG_DB_POOL_OVERRIDES支持按池名如admin.pool_size4在生产环境动态调整。源码注释揭示了这一设计的根本原因FastAPI 会按请求按依赖身份缓存依赖同一个可调用对象在同一请求内只实例化一次。如果门禁用的是get_session而 handler 用的是get_admin_session则门禁会把管理员流量从后门带回 API 池。因此门禁与 handler 必须引用同一个依赖可调用对象管理页面被结构性约束在管理池上——一个把自己轮询到饱和的管理面板代价是管理员自己收到 503而不会拖垮产品的主流量。悬浮Suspension强制org 作用域入口的双闸门超级管理员的变更端点会设置两类悬浮标记而悬浮的执行点不在管理端点上而在普通成员门禁require_member中User.suspended为真 → 所有 org 作用域入口返回 403detail 为account suspended账号被悬浮Org.suspended为真 → 同样返回 403detail 为org suspended组织被悬浮。参见 domain/identity/access.py 中的两行检查if user.suspended: raise HTTPException(status_code403, detailaccount suspended) if org.suspended: raise HTTPException(status_code403, detailorg suspended)而超级管理员的端点不受影响——它们走的是require_superadmin与require_member完全正交。这一设计保证悬浮是平台级的即时熔断被悬浮的用户/组织对所有常规入口立即失效而平台治理能力依然可用。/admin/*端点全景所有管理端点都挂在/admin/*路径下统一由require_superadmin守护实现在 routers/admin.py。按职责可分成四组只读统计跨租户的总览面板GET /admin/statsadmin_stats平台总量users/orgs/tools/secrets/bundles/calls/superadmins/suspended_orgstools_by_injector与tools_by_host分布、credential_health汇总、7/30 天调用量与成功率、新用户/新组织增长数。全部在进程内对小结果集做计算统计时剔除 demo 组织的足迹保证指标不被沙箱引导数据污染对最大的callrecord表只读三列而非整行避免把宽列失败证据物化出来。GET /admin/orgs每个 org 及其成员数、角色分布、工具/密钥/bundle 数。实现上用一次分组的 COUNT 查询group_by替代逐个 org 计数将复杂度从 O(orgs) 查询降到常数级别。GET /admin/orgs/{org_id}单组织详情含成员批量预取用户、工具、密钥、最近 20 条调用。GET /admin/users全部用户及各自成员关系成员与组织均一次性批量查询。GET /admin/tools跨租户全部工具。GET /admin/calls跨租户调用审计日志limit默认 50上限 1000。GET /admin/health所有health_status ! ok的密钥admin_health。GET /admin/feedback私有反馈报告可按分类过滤支持limit与按降序 ID 的before分页与超级管理员门禁共用get_admin_session见 feedback.md。失败证据admin_errors与 14 天保留GET /admin/errorsadmin_errors是排障的核心视图参数形态为GET /admin/errors?days7limit100providerproviderstatuscodetiertierdays回溯窗口服务端钳制在 1–90 天limit行数上限钳制在 1–500provider/status按供应商、HTTP 状态过滤tier按市场分层精确过滤空值选中纯自有工具credential_tier IS NULL。返回每条失败调用的CallRecord.error_request/error_response——即调用方实际发送了什么、供应商实际回答了什么的脱敏捕获字段语义见>if not body.value and principal ! env-admin and await _is_last_active_superadmin(db, user): raise HTTPException(status_code409, detailcannot demote the last active super-admin)组织授信admin_credit_orgPOST /admin/orgs/{org_id}/creditadmin_credit_org是 scripts/manual_grant.py 的HTTP 等价物。请求体需要三个字段{ amount_usd: 100, ref: hs-1234, reason: goodwill comp }amount_usd支持字符串/数字内部用Decimal转为整数微美元micro-USD拒绝无法精确表示的值细于 6 位小数、非正数与非数字ref幂等键——同一 org 重复使用相同ref返回 409并附上先前授信详情。这是对既有账本条目的顺序复用检查文档注明它并非并发安全但每次一个运维人员调用的场景下可以接受若不再成立应改为唯一列reason记录在账本上的人类可读解释。底层走money.grant()在同一事务中写入 block balance ledger保持不变量balance sum(blocks) - sum(holds)。始终使用kindpromotional支出按_KIND_ORDER顺序燃烧促销额度在购买额度之前烧市场费用不可退款。该路由的存在消除了运维打开 Render Postgres IP 白名单的需要而脚本仍适用于气隙/直连数据库场景。数据模型与迁移超级管理员能力只依赖三个布尔列见 models.pyUser.is_superadminL159默认False——跨租户平台管理员标记User.suspendedL160默认False——被悬浮用户无法认证Org.suspendedL48默认False——被悬浮组织的成员被锁定403。这些列属于Alembic baseline schema线上数据库的 schema 变更通过显式的发布阶段python -m treg upgrade完成绝不在重启时隐式发生。升级方式与版本管理可参考 ops/deploy.md 与仓库根目录的alembic.ini。CLI平台治理的实操手册所有超级管理员操作都有 CLI 等价物注册代码见 cli.py命令用途示例treg admin login --token token保存环境变量管理员令牌供后续命令使用treg admin login --token $TREG_ADMIN_TOKENtreg admin stats平台总量与健康treg admin statstreg admin orgs/treg admin org id列出所有组织 / 查看单个组织treg admin org 2treg admin users/tools/calls/health用户 / 工具 / 审计 / 健康汇总treg admin calls --limit 100treg admin grant user_id/revoke user_id授予 / 撤销超级管理员treg admin grant 5treg admin suspend-user id [--undo]平台级悬浮 / 解封用户treg admin suspend-user 5 --undotreg admin rm-user id平台级删除用户treg admin rm-user 5treg admin suspend-org id [--undo]平台级悬浮 / 解封组织treg admin suspend-org 2treg admin rm-org id平台级删除组织treg admin rm-org 2treg admin credit org_id --amount-usd n --ref ticket --reason text组织促销授信HTTP 等价物treg admin credit 2867 --amount-usd 100 --ref hs-1234 --reason goodwill comp凭证选择的细节见 _admin_clientCLI 发送已保存的admin_token若存在否则退回当前活跃 org 的令牌——这意味着一个被授予is_superadmin的用户直接用普通treg令牌也能执行全部admin子命令。更完整的 CLI 语法说明在 interface/cli.md。测试验证tests/test_admin.py仓库用 tests/test_admin.py 对整套机制做了系统验证文件头注释即点明主题Super-admin (cross-tenant) — auth via the env token OR an is_superadmin user; read dashboards; Phase-2 mutationsfixture 通过monkeypatch.setenv(TREG_ADMIN_TOKEN, ADMIN)注入环境令牌并清空设置缓存随后以X-Treg-Token: ENV-ADMIN-SECRET直接访问/admin/*首个用例test_env_token_authorizes_and_sees_across_orgs验证环境令牌授权并跨组织可见统计中的 org 数包含两个个人 两个团队 org其余用例覆盖授予/悬浮/删除、最后超级管理员底线409、org 级联删除等行为。读者可将该文件作为如何为/admin/*编写测试的参考模板。小结treg 的超级管理员能力是一个精心收口的横切面鉴权是环境令牌引导 具名用户标记的混合体资源边界是独立的 3 连接管理池数据可见性是跨租户全读 严格最小化失败证据不镜像、demo 足迹剔除、宽列不物化治理动作全部经由最后超级管理员底线保护。理解这四层你就能安全地运营一个多租户工具注册表而不会把平台治理与 org 治理混为一谈。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐Apache Pulsar 租户Tenant管理实战指南pulsar-admin CLI、REST API 与 Java Admin API 全解析Apache Pulsar 租户Tenant管理实战指南pulsar admin CLI、REST API 与 Java Admin API 全解析 Ap消息队列后端流处理Apache Pulsar 租户Tenant管理实战指南pulsar-admin CLI、REST API 与 Java Admin API 全解Apache Pulsar 租户Tenant管理实战指南pulsar admin CLI、REST API 与 Java Admin API 全解 本篇技消息队列后端流处理Ente CLI 管理员运维指南使用 ente admin list-users 查看实例用户列表Ente CLI 管理员运维指南使用 ente admin list users 查看实例用户列表 ente admin list users 是 Ente后端前端移动开发桌面应用密码学认证鉴权存储创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考