访问控制参考

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

如需在 dashboard 中管理成员的直观演示，请参阅 组织.

---

角色权限范围

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

权限范围	适用范围	使用场景示例
组织	整个组织及其所有 App	您的联合创始人拥有 Super Admin 权限；您的会计拥有 Billing Manager 权限
应用	单个 App 及其所有 Channel	负责单个 App 的外包人员拥有 App Developer 权限
渠道	App 内的单个 Channel	QA 工程师仅管理特定的 staging channel
Bundle	单个 Bundle 版本	审核人员仅需对特定 Release 的读取权限

成员可以拥有 每个作用域目标下的一个角色 — 例如：一个 Org 角色，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、channel 及 bundle 角色的权限。A 超级管理员 拥有与 应用管理员 或 频道管理员 完全相同的权限，且可跨所有应用和频道操作。

---

App 角色

权限范围仅限单个应用。当团队成员仅需负责某个特定应用而非整个组织时，请使用此类角色。

角色	内部名称	描述
应用管理员	app_admin	拥有单个 App 的完全控制权 —— 包括频道、设备及该 App 的用户角色。无法删除或转移 App（这些属于组织级操作）。
应用开发者	app_developer	上传 bundle、管理设备、触发 Native Build、更新频道设置。无法进行删除、修改 App 设置或创建频道。
App 上传者	app_uploader	具备读取权限 + 上传新 bundle 版本。
App 阅读器	app_reader	只读权限 —— 查看统计数据、bundle、频道、logs 及设备。
应用预览	app_preview	绑定组织与 App 的预览版 CI 生命周期：上传 bundle 并创建预览频道。创建该频道后，将自动获得仅针对该频道的生命周期管理权限。

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.delete 以及 app.transfer 是 组织级操作 — 仅 org_super_admin 可以执行这些操作，无论应用层角色如何。

App Preview 权限集

使用 应用预览 (app_preview) 用于绑定组织和应用级别的 CI 密钥，该密钥可在无需广泛应用或组织访问权限的情况下，管理 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 的 channel_preview 子绑定：

权限	允许
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.

注意

每个 App Preview 绑定仍与所选 App 的所属组织关联。该角色不包含组织级角色，但不会移除组织关联。撤销或让 App 绑定过期，会移除该 key 的有效生命周期访问权限。

---

Channel 角色

作用范围仅限单个 channel。适用于为特定的发布 channel 提供定向访问权限。

注意

Channel roles 目前仅可通过 API 和 CLI 使用 — dashboard 暂不支持通过 UI 进行分配。 channel_preview 是一个例外：当 App Preview key 创建 channel 时，Capgo 会为其自动创建。在 dashboard 中，请使用 渠道权限覆盖 来针对每个用户精细化配置 channel 访问权限。

角色	内部名称	描述
频道管理员	channel_admin	拥有单个 Channel 的完全控制权：包括设置、Bundle 的发布/回滚以及强制设备管理。
频道查看者	channel_reader	只读权限 — 可查看当前 Bundle、历史记录、强制设备及审计日志。
频道预览	channel_preview	系统自动分配给创建该 Channel 的 App Preview 密钥：拥有读取、发布其自身 Bundle 以及删除该 Channel 的权限。

Channel 权限矩阵

权限	描述	频道管理员	Channel 查看者	Channel 预览者
channel.read	查看 Channel 及其当前 bundle	✅	✅	✅
channel.update_settings	编辑 Channel 设置（平台开关、更新策略等）	✅	❌	❌
channel.delete	删除 Channel	✅	❌	✅
channel.read_history	查看 bundle 分配历史	✅	✅	❌
channel.promote_bundle	设置 Channel 的当前 active bundle	✅	❌	✅
channel.rollback_bundle	回滚至之前的 bundle	✅	❌	❌
channel.manage_forced_devices	强制特定设备使用此 Channel	✅	❌	❌
channel.read_forced_devices	查看强制设备列表	✅	✅	❌
channel.read_audit	查看 Channel 活动日志	✅	✅	❌

---

Bundle 角色

作用范围仅限单个 bundle 版本。极少需要 —— 大多数团队会使用应用级角色。

注意

Bundle 角色目前仅可通过 API 和 CLI 使用 —— dashboard 中暂无分配界面。

角色	内部名称	描述
Bundle 管理员	bundle_admin	读取、更新元数据并删除特定的 bundle。
Bundle 查看器	bundle_reader	仅限对特定 bundle 的只读访问权限。

---

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 中拥有与 a 相同的权限， 频道管理员 可以在该 App 的所有 Channel 中执行。
• 一次 应用开发者 拥有与 App 上传器 还可以执行更多操作。

权限层级仅 向下传递 —— channel_admin 即使拥有应用级角色，也无法获得组织级权限。

---

分组

与其为每个用户单独分配角色，不如创建 分组 并为分组分配角色。组内的每位成员都会自动继承这些角色。

分组机制

• 分组属于 一个组织 — 无法跨越多个组织。
• Group 可以在以下范围进行角色绑定： 任意范围：org、app、channel 或 bundle。例如，一个 group 可以被分配在 App A 上的 应用开发者 角色，以及在 频道管理员 App B 的 staging channel 上的角色。
• 在评估用户权限时，系统会自动解析其所属的所有 group。如果其中任何一个 group 授予了所需权限，则允许访问。
• 用户可以属于 多个分组，且所有分组的权限会叠加。
• 基于分组的权限仅适用于 用户主体 —— API 密钥不会继承分组角色。

何时使用分组

场景	不使用分组	使用分组
5 名 QA 工程师需要 3 个 App 的 Developer 访问权限	15 个独立角色绑定	1 个分组 + 3 个角色绑定
有人加入 QA 团队	手动添加 3 个角色绑定	将他们添加到分组中
有人离开 QA 团队	手动移除 3 个角色绑定	将他们从分组中移除

通过 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，并将 principal_type: "group" 以及 principal_id 其设置为该组 UUID。

---

通过 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 分配角色

列出组织

npx @capgo/cli organization list --apikey <API_KEY>

列出成员

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

注意

CLI 目前仅支持列出成员。如需通过程序邀请成员或更改角色，请使用上方的 API 接口。

---

自定义角色

内置角色已涵盖大多数团队结构。自定义角色创建功能已在我们的路线图中 —— 如果您的团队有此需求， 请联系我们。您的使用场景将直接帮助我们优先开发此功能。

继续阅读访问控制参考

如果你正在使用 访问控制参考 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。