访问控制参考

Capgo 使用 基于角色的访问控制 (RBAC) 来管理每个团队成员可以做什么。角色根据 范围 ——从整个组织到一个单独的捆绑包。

要了解如何在仪表板中管理成员，请参阅 组织.

---

角色范围

每个角色都属于一个范围，决定它可以访问的资源。

范围	适用范围	适用范围
示例用例	组织	整个组织及其所有应用
App	应用	一个应用及其频道
Channel	一个应用程序中的单个频道	一个应用程序中的单个频道 staging 一个QA工程师只管理频道
频道	一个软件包	一个软件包版本

一个审阅者需要对一个特定的发布有读取权限 一个成员可以持有 一个角色

---

一个角色

组织角色

角色	内部名称	描述
超级管理员	org_super_admin	拥有者等同。拥有删除组织、管理账单、转移应用的全部控制权。组织创建者自动获得此角色。
管理员	org_admin	拥有完整的管理权限 — 管理成员、应用、频道。无法删除组织、更新账单、转移应用或提升用户为超级管理员。
账单管理员	org_billing_admin	仅有账单访问权限：查看和更新账单信息、发票和账单审计日志。无应用或成员访问权限。
成员	org_member	仅有对组织和所有应用的读取权限。

组织权限矩阵

权限	描述	超级管理员	管理员	账单管理员	成员
org.read	查看组织	✅	✅	✅	✅
org.update_settings	编辑组织名称、Logo、管理邮箱	✅	✅	❌	❌
org.delete	永久删除组织	✅	❌	❌	❌
org.read_members	查看成员列表	✅	✅	❌	✅
org.invite_user	邀请新成员	✅	✅	❌	❌
org.update_user_roles	修改成员角色 (管理员无法提升为超级管理员 — 角色层级阻止)	✅	✅	❌	❌
org.read_billing	查看账单信息和当前计划	✅	✅	✅	❌
org.update_billing	更新付款方式和计划	✅	❌	✅	❌
org.read_invoices	查看发票	✅	✅	✅	❌
org.read_audit	查看组织活动日志	✅	✅	❌	❌
org.read_billing_audit	查看账单相关审计日志	✅	✅	✅	❌

注意

组织角色继承了应用、频道和包角色下方的所有权限。一个 超级管理员 可以做所有 应用管理员 或 频道管理员 可以在所有应用程序和频道中进行

---

应用角色

仅限于一个应用程序。使用这些角色时，团队成员应该只在一个应用程序中工作，而不是整个组织。

角色	内部名称	描述
应用管理员	app_admin	对一个应用程序有完全控制权 — 频道、设备、应用程序用户角色。无法删除或转移应用程序（这些是组织级别的操作）。
应用开发者	app_developer	上传包、管理设备、触发原生构建、更新频道设置。无删除、无应用设置更改、无频道创建。
应用上传者	app_uploader	读取访问 + 上传新包版本。
应用读者	app_reader	只读 — 统计、包、频道、日志、设备。
应用预览	app_preview	组织和应用绑定的预览 CI 生命周期：上传一个包并创建一个预览频道。创建该频道会自动授予该频道的生命周期权限。

应用权限矩阵

描述	应用管理员	App Uploader	App 开发者	App 上传者	App 阅读者
app.read	查看应用详细信息、统计和元数据	✅	✅	✅	✅
app.update_settings	编辑应用设置	✅	❌	❌	❌
app.read_bundles	查看已上传的应用包列表	✅	✅	✅	✅
app.upload_bundle	上传新应用包版本	✅	✅	✅	❌
app.create_channel	创建新频道	✅	❌	❌	❌
app.read_channels	查看频道	✅	✅	✅	✅
app.read_logs	查看更新分发日志	✅	✅	✅	✅
app.manage_devices	分配、覆盖或解除绑定设备	✅	✅	❌	❌
app.read_devices	查看设备列表	✅	✅	✅	✅
app.build_native	触发本地云构建	✅	✅	❌	❌
app.read_audit	查看应用级活动日志	✅	✅	✅	✅
app.update_user_roles	管理应用范围角色分配	✅	❌	❌	❌
bundle.delete	删除一个捆绑包	✅	❌	❌	❌

注意

app.delete 并且 app.transfer 是 组织级操作 — 只有 org_super_admin 才能执行它们，无论应用级角色如何

应用预览权限集

使用 应用预览 (app_preview)用于一个管理PR预览周期的组织和应用绑定的CI密钥，且不具有广泛的应用或组织级访问权限。

The app_preview 绑定仅授予这些应用级权限:

权限	允许
app.read	读取所选应用
app.read_bundles	读取上传的包
app.upload_bundle	上传包
app.create_channel	创建频道

当 App 预览密钥创建一个频道时，Capgo会自动为该密钥创建一个子项 channel_preview 仅限于新频道:

权限	允许
channel.read	读取该密钥创建的频道
channel.promote_bundle	在该频道上设置密钥上传的包
channel.delete	删除该频道

因为 app_preview 保留 app.read, 密钥可以在选定的应用中枚举频道元数据。自动子项绑定是管理界限：它不会为密钥未创建的频道授予生命周期变更 允许 读取该密钥创建的频道

Capgo 记录了每个频道和每个捆绑包的预览密钥。因此，一个 App 预览密钥可以创建它需要的每个非公共预览频道，推广自己的捆绑包，并原子性地删除该频道和捆绑包（它不能对现有的默认/主频道、另一个预览密钥的频道或另一个密钥的捆绑包进行这些操作。） channel delete --delete-bundle;它不能对现有的默认/主频道、另一个预览密钥的频道或另一个密钥的捆绑包进行这些操作。

它不包括 app.update_settings，设备或角色管理 channel.update_settings, channel.rollback_bundle，强制设备管理，或通用 bundle.delete.

注意事项

每个 App 预览绑定都与所选应用的拥有组织相关联。该角色省略了组织范围的角色；它不移除组织关联。撤销或过期应用绑定会移除密钥的有效生命周期访问。

---

频道角色

仅限于一个频道。适用于为特定发布频道提供目标访问。

注意

当前仅支持通过 __CAPGO_KEEP_0__ 和 __CAPGO_KEEP_1__ 来管理频道角色 通过 API 和 CLI __CAPGO_KEEP_0__ 是一个例外：当 App Preview key 创建一个频道时，它会自动创建一个 channel_preview Capgo中，Capgo在App Preview密钥创建一个频道时会自动创建一个。 频道权限覆盖 来细化每个用户对频道的访问权限

角色	内部名称	描述
频道管理员	channel_admin	对一个频道拥有完全控制权：设置、推广/回滚包、管理强制设备
频道浏览器	channel_reader	只读 — 当前捆绑包、历史记录、强制设备、审计日志。
频道预览	channel_preview	系统分配到 App 预览密钥创建的频道：读取、促进其自身捆绑包和删除该频道。

频道权限矩阵

权限	描述	频道管理员	频道浏览器	频道预览
channel.read	查看频道及其当前捆绑包	✅	✅	✅
channel.update_settings	编辑频道设置（平台开关，更新策略…）	✅	❌	❌
channel.delete	删除频道	✅	❌	✅
channel.read_history	查看分配的包版本历史	✅	✅	❌
channel.promote_bundle	为频道设置当前的包	✅	❌	✅
channel.rollback_bundle	回滚到之前的包版本	✅	❌	❌
channel.manage_forced_devices	强制特定设备使用此频道	✅	❌	❌
channel.read_forced_devices	查看强制设备列表	✅	✅	❌
channel.read_audit	查看频道活动日志	✅	✅	❌

---

包角色

仅限于一个包版本。很少使用 — 大多数团队使用应用级别角色代替。

注意

目前仅通过 __CAPGO_KEEP_0__ 和 __CAPGO_KEEP_1__ 可以使用角色包 通过 API 和 CLI 角色

内部名称	描述	包管理者
读取、更新元数据以及删除特定包	bundle_admin	包浏览者
对特定包有只读访问权	bundle_reader	渠道权限覆盖 (控制台)

---

组织角色

在控制台中，频道访问权限由用户的应用角色决定。为了获得更细致的控制，您可以 覆盖特定频道权限 针对每个用户或组而不改变其应用角色

覆盖配置 访问 从应用的 tab中点击频道权限按钮（盾牌图标） 查看

组织—覆盖频道权限

权限	概述	默认行为
读取	查看频道及其当前包	从应用角色继承
历史	查看包分配历史	从应用角色继承
关联包	设置或更改频道的活动包	从应用角色继承

每个权限可以设置为:

• 默认角色 — 从应用角色继承（默认）
• 允许 — 明确授权，忽略应用角色
• 拒绝 — 明确阻止，忽略应用角色

这让您可以，例如，给 App Reader 权限，让他们能够在渠道上关联包裹，而不必将其提升为 App Developer。 staging 角色层级

---

标题：角色层级

继承所有权限 角色层级 它的子项。 这意味着一个 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 管理员 在特定应用中可以执行所有 频道管理员 在该应用中的每个频道都可以执行
• 一个 应用开发者 可以执行所有 应用上传者 可以执行的所有内容，

等级体系只向下流动 — 一个 channel_admin 不论他们是否还持有应用级别角色，成员永远不会获得组织级别权限。

---

组

而不是为每个用户分配角色，你可以创建 组 并将角色赋予组。组中的每个成员都会自动继承这些角色。

组的工作原理

• 一个组织 —它不能跨越多个组织。 组可以在
• 组织中持有角色绑定 任何范围: 组织、应用、频道或包。例如，一个组可以被赋予 App 开发者 角色在 App A 上，并且 频道管理员 角色在 App B 的频道上。 staging 当用户权限被评估时，所有他们的组成员身份都会透明地被解析。如果他们的任何组授予所需的权限，访问将被允许。
• 一个用户可以属于
• 多个组 ,并且来自所有组的权限是累积的。基于组的权限仅适用于
• scope 用户主体 — API 键不继承组角色

何时使用组

场景	没有组	有组
5 名 QA 工程师需要对 3 个应用程序拥有开发者访问权限	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 权限（超级管理员 或 Cloudflare).

Capacitor

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 Assigning 角色

列表成员

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 Assigning roles

列表组织

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

成员列表

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

注意

当前的CLI支持成员列表。要邀请成员或更改角色，使用以下API端点。

---

自定义角色

内置角色覆盖了大多数团队结构。自定义角色创建已在我们的路线图上 — 如果您的团队需要此功能，请联系我们 联系我们.您的用例将直接帮助我们优先考虑此功能

继续从访问控制参考

如果您正在使用 访问控制参考 来规划仪表板和API操作，连接它与 API概览 为 API 的实现细节概述 简介 为简介的实现细节 API 密钥 为 API 密钥的实现细节 设备 对于设备中的实现细节 为设备的实现细节，并且 包