跳转到正文

访问控制参考

Capgo 使用 基于角色的访问控制 (RBAC) 来管理每位团队成员能做什么。角色按 范围 进行划分——从整个组织到单个 bundle。

如需查看在 dashboard 中管理成员的可视化演示,请参阅 组织.


每个角色都属于特定的权限范围,决定了其可以访问哪些资源。

范围适用范围使用场景示例
组织整个组织及其所有 App联合创始人获得 Super Admin;会计获得 Billing Manager
应用单个 App 及其 channels负责单个 App 的外包人员获得 App Developer 权限
渠道App 内的单个 channelQA 工程师仅管理特定的 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_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.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) 用于绑定组织和应用级别的 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 提供定向访问权限。

角色内部名称描述
频道管理员channel_admin完全控制单个 Channel:设置、发布/回滚 Bundle、管理强制更新设备。
Channel 查看者channel_reader只读 — 当前 Bundle、历史记录、强制更新设备、审计日志。
Channel 预览者channel_preview系统分配给创建该 Channel 的 App Preview key:可读取、发布自己的 Bundle,并删除该 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_admin读取、更新元数据并删除特定 bundle。
Bundle 查看器bundle_reader仅限对特定 bundle 的只读访问权限。

在 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 上的角色,以及 频道管理员 在 staging App B 的 channel 上的角色。
  • 在评估用户权限时,系统会自动解析其所属的所有组。如果其中任何一个组授予了所需权限,则允许访问。
  • 用户可以属于 多个分组,且所有分组的权限会叠加。
  • 基于分组的权限仅适用于 用户主体 —— API 密钥不会继承分组角色。
场景不使用分组使用分组
5 名 QA 工程师需要 3 个 App 的 Developer 访问权限15 个独立角色绑定1 个群组 + 3 个角色绑定
有人加入 QA 团队手动添加 3 个角色绑定将他们添加到群组
有人离开 QA 团队手动移除 3 个角色绑定将他们从群组中移除

所有群组端点都需要身份验证,并运行在 /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>"

终端窗口
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"
}'

终端窗口
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 中的实现细节。