访问控制参考
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
Capgo 使用 基于角色的访问控制 (RBAC) 来管理每位团队成员能做什么。角色按 范围 进行划分——从整个组织到单个 bundle。
如需查看在 dashboard 中管理成员的可视化演示,请参阅 组织.
角色权限范围
标题为“角色权限范围”的部分每个角色都属于特定的权限范围,决定了其可以访问哪些资源。
| 范围 | 适用范围 | 使用场景示例 |
|---|---|---|
| 组织 | 整个组织及其所有 App | 联合创始人获得 Super Admin;会计获得 Billing Manager |
| 应用 | 单个 App 及其 channels | 负责单个 App 的外包人员获得 App Developer 权限 |
| 渠道 | App 内的单个 channel | QA 工程师仅管理特定的 staging channel |
| Bundle | 单个 bundle 版本 | 审核人员需要对特定 release 的读取权限 |
成员可以拥有 每个作用域目标下的一个角色 — 例如:一个 org role,App A 的一个角色,以及 App B 的另一个角色。
组织角色
“组织角色”章节这些角色在邀请成员时分配,授予整个组织的访问权限。
| 角色 | 内部名称 | 描述 |
|---|---|---|
| 超级管理员 | org_super_admin | 等同于所有者。拥有完整控制权,包括删除组织、管理账单和转移 App。组织创建者将自动获得此角色。 |
| 管理员 | org_admin | 全权管理 — 管理成员、App 和 Channel。无法删除组织、更新账单、转移 App 或将用户提升为 Super Admin。 |
| 账单管理员 | org_billing_admin | 仅限账单访问:查看并更新账单信息、发票和账单审计日志。无法访问 App 或成员。 |
| 成员 | org_member | 对组织及其所有 App 拥有只读权限。 |
组织权限矩阵
标题为“组织权限矩阵”的章节| 权限 | 描述 | 超级管理员 | 管理员 | 账单管理员 | 成员 |
|---|---|---|---|---|---|
org.read | 查看组织 | ✅ | ✅ | ✅ | ✅ |
org.update_settings | 编辑组织名称、Logo 及管理邮箱 | ✅ | ✅ | ❌ | ❌ |
org.delete | 永久删除组织 | ✅ | ❌ | ❌ | ❌ |
org.read_members | 查看成员列表 | ✅ | ✅ | ❌ | ✅ |
org.invite_user | 邀请新成员 | ✅ | ✅ | ❌ | ❌ |
org.update_user_roles | 更改成员角色(Admin 无法提升为 Super Admin——受角色层级限制) | ✅ | ✅ | ❌ | ❌ |
org.read_billing | 查看账单信息和当前套餐 | ✅ | ✅ | ✅ | ❌ |
org.update_billing | 更新支付方式和套餐 | ✅ | ❌ | ✅ | ❌ |
org.read_invoices | 查看发票 | ✅ | ✅ | ✅ | ❌ |
org.read_audit | 查看组织活动日志 | ✅ | ✅ | ❌ | ❌ |
org.read_billing_audit | 查看账单审计日志 | ✅ | ✅ | ✅ | ❌ |
App 角色
“应用角色”章节权限范围仅限单个应用。当团队成员仅需负责某个特定应用而非整个组织时,请使用此类角色。
| 角色 | 内部名称 | 描述 |
|---|---|---|
| 应用管理员 | app_admin | 拥有单个 App 的完全控制权 —— 包括该 App 的 channels、devices 及用户角色。无法删除或转移 App(这些属于组织级操作)。 |
| 应用开发者 | app_developer | 上传 bundles、管理 devices、触发 native builds 以及更新 channel 设置。无法进行删除、修改 App 设置或创建 channel。 |
| App 上传器 | app_uploader | 具备读取权限 + 上传新的 bundle 版本。 |
| App 阅读器 | app_reader | 只读权限 —— 查看 stats、bundles、channels、logs 及 devices。 |
| 应用预览 | app_preview | 绑定组织与 App 的预览版 CI 生命周期:上传 bundle 并创建 preview channel。创建该 channel 后,将自动获得仅针对该 channel 的 lifecycle 权限。 |
App 权限矩阵
“App 权限矩阵”章节| 权限 | 描述 | 应用管理员 | 应用开发者 | App 上传者 | App 阅读器 |
|---|---|---|---|---|---|
app.read | 查看 App 详情、统计数据及元数据 | ✅ | ✅ | ✅ | ✅ |
app.update_settings | 编辑 App 设置 | ✅ | ❌ | ❌ | ❌ |
app.read_bundles | 查看已上传的 bundle 列表 | ✅ | ✅ | ✅ | ✅ |
app.upload_bundle | 上传新的 bundle 版本 | ✅ | ✅ | ✅ | ❌ |
app.create_channel | 创建新 channel | ✅ | ❌ | ❌ | ❌ |
app.read_channels | 查看 channels | ✅ | ✅ | ✅ | ✅ |
app.read_logs | 查看更新分发日志 | ✅ | ✅ | ✅ | ✅ |
app.manage_devices | 分配、覆盖或解绑设备 | ✅ | ✅ | ❌ | ❌ |
app.read_devices | 查看设备列表 | ✅ | ✅ | ✅ | ✅ |
app.build_native | 触发原生云构建 | ✅ | ✅ | ❌ | ❌ |
app.read_audit | 查看应用级活动日志 | ✅ | ✅ | ✅ | ✅ |
app.update_user_roles | 管理应用级角色分配 | ✅ | ❌ | ❌ | ❌ |
bundle.delete | 删除 bundle | ✅ | ❌ | ❌ | ❌ |
App Preview 权限集
标题为 “App Preview permission set” 的章节使用 应用预览 (app_preview) 用于绑定组织和应用级别的 CI key,可在无需广泛应用或组织权限的情况下管理 PR preview 生命周期。
本指南中介绍的 app_preview 绑定仅授予以下应用级权限:
| 权限 | 允许 |
|---|---|
app.read | 读取所选应用 |
app.read_bundles | 读取已上传的 bundle |
app.upload_bundle | 上传 bundle |
app.create_channel | 创建 channel |
当 App Preview key 创建 channel 时,Capgo 会自动为该 key 分配一个子 channel_preview 绑定,仅限新 channel:
| 权限 | 允许 |
|---|---|
channel.read | 读取该 key 创建的 channel |
channel.promote_bundle | 在该 channel 上设置该 key 自己上传的 bundle |
channel.delete | 删除该 channel |
因为 app_preview 保留 app.read,该 key 可以枚举所选 App 中的 channel 元数据。自动子绑定是一种 管理 边界:它不会授予对该 key 未创建的 channel 执行生命周期变更的权限。
Capgo 会记录创建每个 channel 并上传每个 bundle 的 preview key。因此,App Preview key 可以创建所需的每个非公开 preview channel,提升(promote)自己的 bundle,并使用 Capgo 原子化地删除该 channel 和 bundle channel delete --delete-bundle;它无法对现有的 default/main channel、其他 preview key 的 channel 或其他 key 的 bundle 执行这些操作。
它不包含 app.update_settings、设备或角色管理、 channel.update_settings, channel.rollback_bundle、强制设备管理,或通用 bundle.delete.
Channel 角色
“Channel roles” 章节作用范围仅限单个 Channel。适用于为特定的发布 Channel 提供定向访问权限。
| 角色 | 内部名称 | 描述 |
|---|---|---|
| 频道管理员 | channel_admin | 完全控制单个 Channel:设置、发布/回滚 Bundle、管理强制更新设备。 |
| Channel 查看者 | channel_reader | 只读 — 当前 Bundle、历史记录、强制更新设备、审计日志。 |
| Channel 预览者 | channel_preview | 系统分配给创建该 Channel 的 App Preview key:可读取、发布自己的 Bundle,并删除该 Channel。 |
Channel 权限矩阵
“Channel 权限矩阵”章节| 权限 | 描述 | 频道管理员 | Channel 查看者 | Channel 预览者 |
|---|---|---|---|---|
channel.read | 查看频道及其当前 bundle | ✅ | ✅ | ✅ |
channel.update_settings | 编辑频道设置(平台开关、更新策略等) | ✅ | ❌ | ❌ |
channel.delete | 删除该频道 | ✅ | ❌ | ✅ |
channel.read_history | 查看 bundle 分配历史 | ✅ | ✅ | ❌ |
channel.promote_bundle | 设置频道当前生效的 bundle | ✅ | ❌ | ✅ |
channel.rollback_bundle | 回滚至上一个 bundle | ✅ | ❌ | ❌ |
channel.manage_forced_devices | 强制特定设备使用该频道 | ✅ | ❌ | ❌ |
channel.read_forced_devices | 查看强制设备列表 | ✅ | ✅ | ❌ |
channel.read_audit | 查看频道活动日志 | ✅ | ✅ | ❌ |
Bundle 角色
“Bundle 角色”章节作用域仅限单个 bundle 版本。很少需要——大多数团队会改用应用级角色。
| 角色 | 内部名称 | 描述 |
|---|---|---|
| Bundle 管理员 | bundle_admin | 读取、更新元数据并删除特定 bundle。 |
| Bundle 查看器 | bundle_reader | 仅限对特定 bundle 的只读访问权限。 |
Channel 权限覆盖(Dashboard)
标题为“Channel 权限覆盖 (Dashboard)”的章节在 dashboard 中,默认情况下,channel 访问权限由用户的 app role 决定。如需更精细的控制,您可以 覆盖特定的 channel 权限 针对单个用户或用户组,而无需更改其 app role。
覆盖配置需通过应用的 访问权 选项卡进行,点击用户旁边的 channel permissions 按钮(盾牌图标)即可。请参阅 组织 — 覆盖频道权限 以获取可视化操作指南。
可覆盖权限
“可覆盖权限”章节| 权限 | 描述 | 默认行为 |
|---|---|---|
| 读取 | 查看 Channel 及其当前 Bundle | 继承自 App 角色 |
| 历史记录 | 查看 Bundle 分配历史 | 继承自 App 角色 |
| 关联 Bundle | 设置或更改 channel 上的活动 bundle | 继承自 app role |
每个权限都可以设置为:
- 默认 — 继承自 app role(默认)
- 允许 — 显式授权,无视 app role
- 拒绝 — 显式禁用,无视 app role
这可以让你,例如,赋予 App Reader 在 staging channel 上关联 bundle 的能力,而无需将其提升为 App Developer。
角色层级
“角色层级”章节角色构成层级关系。父角色 会继承其所有子角色 的权限。这意味着 org_admin 拥有与 app_admin 可以执行所有操作,而其子角色 channel_admin 也能执行其父角色的所有操作,以此类推。
Super Admin (org_super_admin) └── Admin (org_admin) └── App Admin (app_admin) ├── App Developer (app_developer) │ └── App Uploader (app_uploader) │ └── App Reader (app_reader) ├── Bundle Admin (bundle_admin) │ └── Bundle Viewer (bundle_reader) └── Channel Admin (channel_admin) └── Channel Viewer (channel_reader)实际运作方式:
- 一次 管理员 在组织层级可以执行所有 应用管理员 可以在该组织下的所有 App 中执行。
- 一次 应用管理员 在特定 App 上,可以执行某个角色能做的所有操作 频道管理员 可以在该 App 的每个 Channel 中执行。
- 一次 应用开发者 拥有与 App 上传者 还可以做更多。
权限层级只向下 传递 —— channel_admin 用户永远不会获得组织级权限,即使他们同时拥有应用级角色。
无需为每个用户单独分配角色,您可以创建 用户组 并为用户组分配角色。组内每位成员都会自动继承这些角色。
分组机制
“用户组如何工作”章节- 用户组属于 一个组织 — 无法跨越多个组织。
- 可以在以下任何范围为组设置角色绑定: 任何范围:组织、App、channel 或 bundle。例如,可以为某个组分配 应用开发者 在 App A 上的角色,以及 频道管理员 在
stagingApp B 的 channel 上的角色。 - 在评估用户权限时,系统会自动解析其所属的所有组。如果其中任何一个组授予了所需权限,则允许访问。
- 用户可以属于 多个分组,且所有分组的权限会叠加。
- 基于分组的权限仅适用于 用户主体 —— API 密钥不会继承分组角色。
何时使用分组
标题为“何时使用分组”的章节| 场景 | 不使用分组 | 使用分组 |
|---|---|---|
| 5 名 QA 工程师需要 3 个 App 的 Developer 访问权限 | 15 个独立角色绑定 | 1 个群组 + 3 个角色绑定 |
| 有人加入 QA 团队 | 手动添加 3 个角色绑定 | 将他们添加到群组 |
| 有人离开 QA 团队 | 手动移除 3 个角色绑定 | 将他们从群组中移除 |
通过 API 管理分组
标题为“通过 API 管理群组”的章节所有群组端点都需要身份验证,并运行在 /private/groups.
列出群组
标题为“列出群组”的章节curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \ -H "authorization: <API_KEY>"需要 org.read_members 权限。
创建分组
标题为“创建分组”的区块curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "name": "QA Team", "description": "Quality assurance engineers" }'需要 org.update_user_roles 权限 (超级管理员 或 管理员).
更新分组
标题为“更新分组”的章节curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "name": "QA Team", "description": "Updated description" }'删除分组
标题为“删除分组”的章节curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \ -H "authorization: <API_KEY>"删除分组会同时移除其所有的角色绑定。组织内的成员不会被删除。
列出分组成员
标题为“列出分组成员”的章节curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \ -H "authorization: <API_KEY>"向组内添加成员
标题为“向组内添加成员”的章节curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "user_id": "<USER_UUID>" }'用户必须已经是该组织的成员。添加已有成员是空操作。
从组内移除成员
标题为“从组内移除成员”的章节curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \ -H "authorization: <API_KEY>"通过 API 分配角色
章节标题:“通过 API 分配角色”列出成员
章节标题:“列出成员”curl -X GET "https://api.capgo.app/organization/members" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "orgId": "<ORG_ID>" }'响应:
[ { "uid": "user-uuid", "email": "alice@example.com", "image_url": "https://...", "role": "org_admin", "is_tmp": false }]邀请成员
“邀请成员”章节curl -X POST "https://api.capgo.app/organization/members" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "orgId": "<ORG_ID>", "email": "bob@example.com", "invite_type": "org_admin" }'可选值: invite_type:
| 值 | 分配的角色 |
|---|---|
org_super_admin | 超级管理员 |
org_admin | 管理员 |
org_billing_admin | 账单管理员 |
org_member | 成员 |
移除成员
“移除成员”章节curl -X DELETE "https://api.capgo.app/organization/members" \ -H "authorization: <API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "orgId": "<ORG_ID>", "email": "bob@example.com" }'通过 CLI 分配角色
“通过 CLI 分配角色”章节列出组织
“组织列表”章节npx @capgo/cli organization list --apikey <API_KEY>列出成员
章节标题:“列出成员”npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>自定义角色
标题为“自定义角色”的部分内置角色已涵盖大多数团队结构。自定义角色创建功能已在我们的路线图中 —— 如果您的团队有此需求, 请联系我们。您的使用场景将直接帮助我们优先开发此功能。
继续阅读访问控制参考
标题为“继续阅读访问控制参考”的部分如果你正在使用 访问控制参考 要规划 dashboard 和 API 操作,请将其连接到 API 概览 关于 API Overview 中的实现细节, 简介 关于 Introduction 中的实现细节, API 密钥 有关 API Keys 的实现细节, 设备 有关 Devices 的实现细节,以及 Bundle 有关 Bundles 中的实现细节。