访问控制参考

Capgo uses 基于角色的访问控制 (RBAC) 管理每个团队成员可以做什么。 范围 ——从整个组织到单个包。

查看管理成员的仪表板视觉教程，请参见 组织.

---

角色范围

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

范围	适用范围	示例用例
组织	整个组织及其所有应用	你的合伙人获得超级管理员;你的会计师获得账单管理员
应用	一个应用及其频道	一个只负责一个应用的承包商获得应用开发者
频道	一个应用中的一个频道	一个仅负责管理的频道 staging 频道
一个版本的捆绑包	捆绑包版本	A reviewer needs to have read access to one specific release

A member can hold one role per scope target 例如，一个组织角色，一个 App A 角色，和一个 App B 角色。

---

组织角色

这些角色在邀请成员时分配。它们授予对整个组织的访问权限。

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

组织权限矩阵

描述	超级管理员	管理员	组织权限矩阵	Billing Manager	成员
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	查看账单相关的审计日志	✅	✅	✅	❌

注意

组织角色继承了应用、频道和包的角色下方的所有权限。一个 超级管理员 可以做一个 应用管理员 或 HTML文本片段来自更长的Capgo UI字符串（父级键`alternatives_cta_questions`）。页面/区域：Capacitor实时更新替代方案比较页面。角色：长期营销或法律段落。见于：页面alternatives.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键`alternatives_cta_questions`（替代方案CTA问题）。 | HTML文本片段来自更长的Capgo UI字符串（父级键`appflow_cta_questions`）。页面/区域：Appflow比较/迁移营销文案。角色：长期营销或法律段落。见于：页面ionic-appflow.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键`appflow_cta_questions`（Appflow CTA问题）。 | HTML文本片段来自更长的Capgo UI字符串（父级键`capwesome_cta_questions`）。页面/区域：Capawesome比较页面。角色：长期营销或法律段落。见于：页面capwesome.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键`capwesome_cta_questions`（Capwesome CTA问题）。 | HTML文本片段来自更长的Capgo UI字符串（父级键`consulting_faq_subtitle`）。页面/区域：咨询服务页面。角色：段落标题或标语。见于：页面consulting.astro。保留Capgo产品/品牌和开发者术语完全不变。消息键`consulting_faq_subtitle`（咨询FAQ字幕）。 | 页面/区域：Appflow比较/迁移营销文案。角色：短UI标签或导航项。见于：页面ionic-appflow.astro，页面ionic-enterprise-plugins.astro，页面解决方案/ionic-enterprise-plugins.astro。消息键`appflow_plugins_or`（Appflow插件或） 频道管理员

---

可以在所有应用和频道中执行所有操作。

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

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

应用权限矩阵

权限	描述	应用管理员	应用开发者	应用上传者	应用读者
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）用于一个组织和应用绑定的CI密钥，该密钥管理PR预览生命周期，而不提供广泛的应用或组织级别访问。

它 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 记录预览键创建每个频道和上传每个包裹。 因此，应用预览键可以创建每个非公共预览频道它需要，推广自己的包裹，并原子性地删除该频道和包裹 channel delete --delete-bundle；它不能做这些事情到一个现有的默认/主要频道，另一个预览键的频道，或者另一个键的包裹。

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

注意

每个App Preview绑定都与所选应用的拥有组织保持关联。该角色省略了组织级别的角色;它不会移除组织关联。撤销或过期应用绑定会移除密钥的有效生命周期访问。

---

频道角色

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

注意

频道角色目前仅可通过__CAPGO_KEEP_0__和__CAPGO_KEEP_1__访问 via API and CLI only __CAPGO_KEEP_0__是例外:它会自动为App Preview密钥创建一个频道。在仪表盘中，请使用 channel_preview is an exception: Capgo creates it automatically for an App Preview key when that key creates a channel. In the dashboard, use 频道权限覆盖 而不是每个用户都细化频道访问权限。

角色	内部名称	描述
频道管理员	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__ 进行配置 via API and CLI only 角色

捆绑角色是应用级别角色的一种特殊类型，仅限于一个捆绑版本。	内部名称	描述
包管理者	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)

实践中如何运作:

• 一个 组织管理员 在组织层级可以对组织内的每个应用程序执行 应用程序管理员 的所有操作。
• 一个 应用程序管理员 在特定应用程序中可以对应用程序内的每个频道执行 频道管理员 的所有操作。
• 一个 应用开发者 可以做所有应用上传者能做的, 甚至更多。 应用上传者 可以做应用开发者能做的, 甚至更多。

只有向下流动的层级结构 — 一旦 从不获得组织级别的权限, 即使他们也持有应用级别的角色。 channel_admin 组

---

标题：组

组 groups 并将角色分配给该组。组内的每个成员都会自动继承这些角色。

如何组工作

• 一个组属于 一个组织 —它不能跨越多个组织。
• 组可以在 任何范围: 组织、应用、频道或包。例如，一个组可以被分配到 应用开发者 角色在应用A上，并且 频道管理员 在 App B 的频道上 staging 频道 App B 上的角色
• 当用户权限被评估时，所有用户组成员身份都会透明地被解析。如果用户的任何组授予所需的权限，访问将被允许。
• 一个用户可以属于 多个用户组, 并且所有用户组的权限都是累积的。
• 基于组的权限仅适用于 用户主体 — 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 权限（超级管理员 或 需要).

权限（

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上面的API端点。

---

自定义角色

内置角色覆盖了大多数团队结构。自定义角色创建是我们的路线图中的一部分—if您的团队需要这个功能，请联系我们 如果您的团队需要这个功能，请联系我们. 你的用例将直接帮助我们优先考虑这个功能。

继续阅读 Access Control Reference

如果你正在使用 Access Control Reference 来规划仪表板和 API 操作，连接它与 API Overview 查看 API Overview 中的实现细节 介绍 查看介绍中实现细节 API Keys 查看 API Keys 中的实现细节 设备 查看设备的详细信息 包 查看包的详细信息