using-backstage-permissions

Backstage 权限模式

何时使用此技能

• 插件需要向没有相应权限的用户隐藏按钮、菜单或页面（前端）
• 插件的路由处理程序需要在执行操作前授权调用者（后端）
• 为插件定义新权限
• 按资源检查权限（“能否更新_此_组件”，而不是“能否更新组件”）

选择合适的模式

声明权限

正在构建……	模式	参考
为插件创建新权限	createPermission({ name, attributes })，位于 *-common 库中	references/declaring.md

前端（在插件组件中）

情况	模式	参考
根据权限有条件地渲染 UI	usePermission({ permission }) 钩子	references/frontend.md
使用权限门控包裹整个子树	<RequirePermission permission={...}>...</RequirePermission>	references/frontend.md

后端（在路由处理程序或定时任务中）

情况	模式	参考
授权基本操作权限	coreServices.permissions.authorize([{ permission }], { credentials })	references/backend.md
按资源授权（包含条件式决策）	permissions.authorizeConditional([{ permission, resourceRef }], { credentials }) + permissionsRegistry.addResourceType(...)	references/resource-permissions.md

两种调用模式

• 独立模式（开发过程中）：用户正在编辑现有插件。根据要添加的内容选择合适的参考——定义权限、门控 UI 或在后端授权。
• 脚手架完成后（由 creating-backstage-plugin 调用）：当意图描述“只有管理员可以……”“当前用户必须有权限才能……”或其他访问控制语言时，将相关模式添加到刚生成脚手架的插件中。

常见注意事项

• 权限只声明一次，使用两次。 权限对象位于 *-common（或 *-permissions-common）库中，这样前端（usePermission）和后端（permissions.authorize）都能导入同一份定义。不要在两个地方重复声明同一项权限。
• 宿主应用必须启用权限框架。 采用者需要在 app-config.yaml 中设置 permission.enabled: true，并安装 PermissionPolicy。如果未启用权限，authorize 始终会返回 AuthorizeResult.ALLOW——你的插件代码没有问题，只是权限检查未生效。请在插件 README 中说明此先决条件。
• permissions.authorize 返回一个数组，其顺序与请求顺序一致。对于单项权限，使用解构赋值 const [decision] = await permissions.authorize(...)——而判断依据是 decision.result === AuthorizeResult.ALLOW，不是布尔值。
• 对于资源权限，如果判断结果可能取决于资源（例如“所有者可以更新”），优先使用 authorizeConditional 而不是 authorize。 它会返回条件判断结果，你可以将其转换为数据库级筛选条件，从而无需将所有候选资源加载到内存中。
• usePermission 是异步的。 它会返回 { allowed, loading, error }——加载期间请渲染 <Skeleton />，否则在确定访问权限时，用户会看到界面闪烁。
• 对于后端插件，coreServices.permissions 和 coreServices.permissionsRegistry 来自 @backstage/backend-plugin-api。它们的作用域限定于插件——你的插件会获得一个 PermissionsService，该服务已知晓自身的 pluginId。