OneUptime 权限参考Permission Reference完全指南从 Permission Key 到角色与细粒度权限【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime权限是 OneUptime 多租户项目中最核心的访问控制机制。本文以仓库内 App/FeatureSet/Docs/Content/en/permissions/reference.md 为主体逐层拆解这份权限参考页面它由什么生成、角色Roles与细粒度权限Granular permissions如何组织、Permission Key在 API / CLI / Terraform provider 中如何使用以及背后的源码实现与完整性保障。读完本文你将掌握按产品领域速查权限、为团队与 API Key 精确授权、以及理解页面永不与产品漂移这一机制的全部原理。这份参考页从哪来请求时从源码动态生成reference.md本身并不是一份手写的权限清单。它的开头明确说明This page is generated from the OneUptime source at request time — the same list the dashboard, the API and the Terraform provider use. It cannot drift from the product, and it reflects the version you are running.这意味着你看到的每一张权限表格都是在页面被请求的那一刻从正在运行的版本源码中实时渲染出来的。因此它天然具备两个特性单一事实源Single Source of TruthDashboard 的权限选择器、API 的鉴权逻辑、Terraform provider 的权限校验全部读取同一份列表任何一处新增权限都会同步出现在所有入口永不漂移不存在文档写了一套、产品跑另一套的陈旧问题。占位符机制页面模板如何被填充reference.md正文中嵌入了若干形如{{PERMISSION_XXX}}的占位符例如{{PERMISSION_ROLE_COUNT}}—— 角色总数{{PERMISSION_ROLE_TABLES}}—— 角色表格{{PERMISSION_TOTAL_COUNT}}—— 细粒度权限总数{{PERMISSION_GROUP_COUNT}}—— 细粒度权限组总数{{PERMISSION_GRANULAR_TABLES}}—— 细粒度权限表格这些占位符由 App/FeatureSet/Docs/Utils/Placeholders.ts 中的DocsPlaceholders.render()在服务端渲染时统一替换。注意替换是白名单式的allow-listed并非对{{...}}的全局扫描——因为文档中合法地存在{{timestamp}}、{{variable}}这类作为内容本身的双花括号语法例如网站监控与工作流文档它们必须原样保留。每个占位符的替换同样只针对包含该 token 的页面执行。在 Placeholders.ts 中可以看到替换时还会根据当前请求的语言lang选择表格外壳的翻译文本列头、Yes/No而权限标题与描述本身始终为英文与 Dashboard 界面显示的字符串完全一致——这正是为了读者对照屏幕时看到同一串文字。为什么不在构建期生成按语言生成的角色表格与细粒度表格后者约 1200 行会被 PermissionsTable.ts 以Mapstring, string缓存到内存中每个语言只构建一次避免每次请求都重新遍历整个权限目录。从源码注释可以看到细粒度表格约 1200 行说明该页面实际承载的信息量远超模板本身的几行文字。角色RolesAdmin / Member / Viewer 三级打包reference.md的 Roles 一节说明角色将一个完整的产品领域打包为Admin、Member、Viewer三个层级这正是 Dashboard 中给团队添加权限时Role选择器提供的选项。结合 permissions/index.md 的模型定义三级的语义是级别含义Admin该领域的完全控制权包括配置项严重级别、状态、模板等Member日常操作可创建、编辑、删除资源但不能重新配置该领域Viewer只读典型角色如MonitorAdmin、IncidentMember、StatusPageViewer。index.md还给出一个重要建议绝大多数场景优先使用角色而非细粒度权限——因为 OneUptime 新增功能时新表会挂到既有角色上而不是要求你逐个补发权限。Scope 列All, Owned or Labels vs Project-wide only角色表格中有Scope作用域列它回答这个授权能管到多宽All, Owned or Labels授予时可被收窄。可选的三种作用域来自index.mdAll resources in the project默认作用于项目内所有匹配资源Owned by this team or its members仅作用于该团队或其成员被列为所有者的资源Restrict by labels (advanced)仅作用于携带至少一个所选标签的资源。Project-wide only角色始终作用于整个项目无法收窄。作用域豁免角色为什么有些角色不能收窄在 Common/Types/Permission.ts 的PermissionHelper.isScopeApplicable()中可以看到哪些角色被判定为不适用作用域public static isScopeApplicable(permission: Permission): boolean { return ( permission ! Permission.ProjectOwner permission ! Permission.ProjectAdmin permission ! Permission.SettingsAdmin permission ! Permission.SettingsMember permission ! Permission.SettingsViewer permission ! Permission.BillingAdmin permission ! Permission.BillingMember permission ! Permission.BillingViewer ); }这些角色ProjectOwner、ProjectAdmin、Settings*、Billing*是无条件项目级授权收窄会产生无法理解的语义——Settings Admin但只对我拥有的设置生效没有意义因为设置不是可拥有的资源。index.md中同样以Billing Admin, but only for the billing I own为例说明了这一点。对应的豁免角色清单由 PermissionsTable.ts 中的getScopeExemptRolesMarkdown()生成供index.md中的{{PERMISSION_SCOPE_EXEMPT_ROLES}}占位符使用。实现细节上UI 会为这些角色隐藏作用域选择器运行时过滤器也会将误加的 Owned 作用域行按更宽的授权处理避免意外收窄访问见 Permission.ts 中getNonAccessControlPermissions()的注释说明。细粒度权限Granular permissions按组组织的单个能力reference.md的 Granular permissions 一节说明细粒度权限是可单独授予的单个能力如CreateProjectMonitor、ReadProjectIncident按组group组织来自Granular选择器也是分配给API Key的权限类型。权限组一览在 Common/Types/Permission.ts 中定义了PermissionGroup枚举即所有权限归属的 21 个组Project、Incident、Alert、Monitor、SLO、Status Page、Scheduled Maintenance、On-Call Duty Policy、Telemetry、Workflow、Runbook、Auto Remediation、Team、Billing、Service Catalog、Settings、AI Agent、Probe、Notification Log、Audit Log、Securityreference.md中的每个###小节对应一个组组下再列出该组所有权限的表格——这也是页面右侧 On This Page 侧边栏的锚点读者可以直接跳转到关心的组而不必滚动上千行的总表见 PermissionsTable.ts 的buildGroupedTables()。Restrict by labels 列细粒度表格中的Restrict by labels列表示该权限的授予是否可以被限制到携带特定标签的资源上。在源码中对应PermissionProps.isAccessControlPermission布尔字段——为true的权限渲染为 Yes否则为 No见 PermissionsTable.ts。需要说明的是这一列是每个权限的固有属性legacy 标记而实际的标签限制机制比它更灵活index.md与PermissionHelper.getAccessControlPermissions()Permission.ts都指出角色权限如IncidentViewer同样可以通过作用域选择 Labels 勾选标签来实现标签限制运行时过滤器依据的是scopelabelIds的组合而不仅是该列标记。Permission KeyAPI、CLI 与 Terraform provider 的通行值reference.md专门强调ThePermission Keycolumn is the value to use with the API, the CLI and the Terraform provider. The titles are what you see in the dashboard.即表格中反引号包裹的键值如CreateProjectMonitor、MonitorAdmin才是程序化接口要使用的值而标题Title仅用于界面展示。三种消费场景API在创建 API Key 或调用接口时按键值授权。API Key 的授权与团队独立——键直接挂在 Key 上不受团队成员身份影响见 permissions/index.mdCLI命令行工具按键值管理权限Terraform provider基础设施即代码中以键值声明权限。index.md补充了与键值相关的两条重要规则API Key 不支持 Owned 作用域——所有者解析的对象是用户而 Key 不是用户因此需要显式授予 Key 所需的全部访问index.mdBlock 永远优先——Block 权限列表始终压过 Allow 列表带标签的 Block 只移除携带该标签资源的权限如可以编辑监控但 Production 标签的除外。底层实现权限目录的生成与完整性保障权限目录的构成PermissionProps接口Permission.ts是每条权限的数据结构export interface PermissionProps { permission: Permission; // 枚举键即 Permission Key description: string; // 描述 isAssignableToTenant: boolean; // 是否可授予项目 title: string; // 界面显示标题 isAccessControlPermission: boolean; // 是否可按标签限制 isRolePermission: boolean; // 是否为内置角色 group: PermissionGroup; // 所属权限组 }PermissionHelper.getAllPermissionProps()Permission.ts返回完整目录再由派生方法过滤出不同子集getTenantPermissionProps()—— 过滤isAssignableToTenant即所有可授予项目的权限getRolePermissionProps()—— 在上一基础上过滤isRolePermission得到内置角色列表细粒度列表则是可授予权限中排除角色后的集合见 PermissionsTable.ts 的getGranularPermissionProps()。PermissionsTable.ts的文件头注释特别强调了绝不手写副本的原则如果文档里维护一份手写的 markdown 权限清单任何人新增一个权限后文档立刻失真——一份关于权限却撒谎的文档比没有更糟。表格渲染细节防破坏的单元格转义Markdown 表格以|分隔、单元格须单行。若某条权限描述里恰好含有换行或竖线会把整行拆成多余列或提前终结表格。为此 PermissionsTable.ts 中的toTableCell()做了三件事text .replace(/\r?\n/g, ) // 换行折叠为空格 .replace(/\s/g, ) // 连续空白归一 .replace(/\|/g, \\|) // 竖线转义 .trim();同时groupPermissions()按首次出现顺序分组而非PermissionGroup声明顺序以匹配 Dashboard 选择器的分组顺序保证文档与 UI 的序列一致PermissionsTable.ts。完整性测试防重复的绊线权限目录长期存在两类静默缺陷两个枚举成员共用同一字符串值导致授予其一即授予其二、所有者作用域被意外放大以及同一权限的PermissionProps被列出两次导致 Granular 选择器出现重复项。这两类问题 TypeScript 编译不会报错因此 Common/Tests/Types/Permission.test.ts 提供了四组目录完整性测试作为绊线枚举成员之间无重复字符串值getAllPermissionProps()无重复条目每条 props 都能通过getTitle/getDescription无损往返防止字典后写覆盖导致文档与界面文本不一致标题含 Template 的条目其键名也必须含 Template防止当年模板所有者权限错挂到非模板成员的 bug 复发。配套阅读权限模型的完整上下文reference.md是权限体系的速查手册其行为语义由 permissions/index.md 定义二者应配合阅读核心规则用户从不直接持有权限其访问权限等于所属所有团队权限的并集ProjectOwner覆盖计费与删除项目ProjectAdmin覆盖除计费外的一切默认团队每个新项目自带不可删除、不可改名的OwnersProjectOwner与AdminProjectAdmin团队以及可自由修改的MembersProjectMember团队——这是防止项目把自己锁在门外的设计请求判定流程依次为收集团队权限行 → 先查 Block → 查 Allow → 应用 Owned/Labels 作用域收窄 → 应用标签 Block解析结果按用户项目缓存权限变更后需刷新index.md。index.md还给出了可直接落地的四种配置配方只读观察团队加Viewer或按领域的*Viewer、自管服务的值班团队MonitorAdmin/IncidentMember/OnCallMember配 Owned 作用域 设为资源所有者、隔离生产环境的承包商All 作用域 对敏感能力加Production标签的 Block、仅上报部署的 CI 流水线API Key 只授必需细粒度权限。这些配方与reference.md中的角色、细粒度权限一一对应是验证该授予哪个 Key最直接的实战参考。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OneUptime 权限参考（Permission Reference）完全指南：从 Permission Key 到角色与细粒度权限
OneUptime 权限参考Permission Reference完全指南从 Permission Key 到角色与细粒度权限【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime权限是 OneUptime 多租户项目中最核心的访问控制机制。本文以仓库内 App/FeatureSet/Docs/Content/en/permissions/reference.md 为主体逐层拆解这份权限参考页面它由什么生成、角色Roles与细粒度权限Granular permissions如何组织、Permission Key在 API / CLI / Terraform provider 中如何使用以及背后的源码实现与完整性保障。读完本文你将掌握按产品领域速查权限、为团队与 API Key 精确授权、以及理解页面永不与产品漂移这一机制的全部原理。这份参考页从哪来请求时从源码动态生成reference.md本身并不是一份手写的权限清单。它的开头明确说明This page is generated from the OneUptime source at request time — the same list the dashboard, the API and the Terraform provider use. It cannot drift from the product, and it reflects the version you are running.这意味着你看到的每一张权限表格都是在页面被请求的那一刻从正在运行的版本源码中实时渲染出来的。因此它天然具备两个特性单一事实源Single Source of TruthDashboard 的权限选择器、API 的鉴权逻辑、Terraform provider 的权限校验全部读取同一份列表任何一处新增权限都会同步出现在所有入口永不漂移不存在文档写了一套、产品跑另一套的陈旧问题。占位符机制页面模板如何被填充reference.md正文中嵌入了若干形如{{PERMISSION_XXX}}的占位符例如{{PERMISSION_ROLE_COUNT}}—— 角色总数{{PERMISSION_ROLE_TABLES}}—— 角色表格{{PERMISSION_TOTAL_COUNT}}—— 细粒度权限总数{{PERMISSION_GROUP_COUNT}}—— 细粒度权限组总数{{PERMISSION_GRANULAR_TABLES}}—— 细粒度权限表格这些占位符由 App/FeatureSet/Docs/Utils/Placeholders.ts 中的DocsPlaceholders.render()在服务端渲染时统一替换。注意替换是白名单式的allow-listed并非对{{...}}的全局扫描——因为文档中合法地存在{{timestamp}}、{{variable}}这类作为内容本身的双花括号语法例如网站监控与工作流文档它们必须原样保留。每个占位符的替换同样只针对包含该 token 的页面执行。在 Placeholders.ts 中可以看到替换时还会根据当前请求的语言lang选择表格外壳的翻译文本列头、Yes/No而权限标题与描述本身始终为英文与 Dashboard 界面显示的字符串完全一致——这正是为了读者对照屏幕时看到同一串文字。为什么不在构建期生成按语言生成的角色表格与细粒度表格后者约 1200 行会被 PermissionsTable.ts 以Mapstring, string缓存到内存中每个语言只构建一次避免每次请求都重新遍历整个权限目录。从源码注释可以看到细粒度表格约 1200 行说明该页面实际承载的信息量远超模板本身的几行文字。角色RolesAdmin / Member / Viewer 三级打包reference.md的 Roles 一节说明角色将一个完整的产品领域打包为Admin、Member、Viewer三个层级这正是 Dashboard 中给团队添加权限时Role选择器提供的选项。结合 permissions/index.md 的模型定义三级的语义是级别含义Admin该领域的完全控制权包括配置项严重级别、状态、模板等Member日常操作可创建、编辑、删除资源但不能重新配置该领域Viewer只读典型角色如MonitorAdmin、IncidentMember、StatusPageViewer。index.md还给出一个重要建议绝大多数场景优先使用角色而非细粒度权限——因为 OneUptime 新增功能时新表会挂到既有角色上而不是要求你逐个补发权限。Scope 列All, Owned or Labels vs Project-wide only角色表格中有Scope作用域列它回答这个授权能管到多宽All, Owned or Labels授予时可被收窄。可选的三种作用域来自index.mdAll resources in the project默认作用于项目内所有匹配资源Owned by this team or its members仅作用于该团队或其成员被列为所有者的资源Restrict by labels (advanced)仅作用于携带至少一个所选标签的资源。Project-wide only角色始终作用于整个项目无法收窄。作用域豁免角色为什么有些角色不能收窄在 Common/Types/Permission.ts 的PermissionHelper.isScopeApplicable()中可以看到哪些角色被判定为不适用作用域public static isScopeApplicable(permission: Permission): boolean { return ( permission ! Permission.ProjectOwner permission ! Permission.ProjectAdmin permission ! Permission.SettingsAdmin permission ! Permission.SettingsMember permission ! Permission.SettingsViewer permission ! Permission.BillingAdmin permission ! Permission.BillingMember permission ! Permission.BillingViewer ); }这些角色ProjectOwner、ProjectAdmin、Settings*、Billing*是无条件项目级授权收窄会产生无法理解的语义——Settings Admin但只对我拥有的设置生效没有意义因为设置不是可拥有的资源。index.md中同样以Billing Admin, but only for the billing I own为例说明了这一点。对应的豁免角色清单由 PermissionsTable.ts 中的getScopeExemptRolesMarkdown()生成供index.md中的{{PERMISSION_SCOPE_EXEMPT_ROLES}}占位符使用。实现细节上UI 会为这些角色隐藏作用域选择器运行时过滤器也会将误加的 Owned 作用域行按更宽的授权处理避免意外收窄访问见 Permission.ts 中getNonAccessControlPermissions()的注释说明。细粒度权限Granular permissions按组组织的单个能力reference.md的 Granular permissions 一节说明细粒度权限是可单独授予的单个能力如CreateProjectMonitor、ReadProjectIncident按组group组织来自Granular选择器也是分配给API Key的权限类型。权限组一览在 Common/Types/Permission.ts 中定义了PermissionGroup枚举即所有权限归属的 21 个组Project、Incident、Alert、Monitor、SLO、Status Page、Scheduled Maintenance、On-Call Duty Policy、Telemetry、Workflow、Runbook、Auto Remediation、Team、Billing、Service Catalog、Settings、AI Agent、Probe、Notification Log、Audit Log、Securityreference.md中的每个###小节对应一个组组下再列出该组所有权限的表格——这也是页面右侧 On This Page 侧边栏的锚点读者可以直接跳转到关心的组而不必滚动上千行的总表见 PermissionsTable.ts 的buildGroupedTables()。Restrict by labels 列细粒度表格中的Restrict by labels列表示该权限的授予是否可以被限制到携带特定标签的资源上。在源码中对应PermissionProps.isAccessControlPermission布尔字段——为true的权限渲染为 Yes否则为 No见 PermissionsTable.ts。需要说明的是这一列是每个权限的固有属性legacy 标记而实际的标签限制机制比它更灵活index.md与PermissionHelper.getAccessControlPermissions()Permission.ts都指出角色权限如IncidentViewer同样可以通过作用域选择 Labels 勾选标签来实现标签限制运行时过滤器依据的是scopelabelIds的组合而不仅是该列标记。Permission KeyAPI、CLI 与 Terraform provider 的通行值reference.md专门强调ThePermission Keycolumn is the value to use with the API, the CLI and the Terraform provider. The titles are what you see in the dashboard.即表格中反引号包裹的键值如CreateProjectMonitor、MonitorAdmin才是程序化接口要使用的值而标题Title仅用于界面展示。三种消费场景API在创建 API Key 或调用接口时按键值授权。API Key 的授权与团队独立——键直接挂在 Key 上不受团队成员身份影响见 permissions/index.mdCLI命令行工具按键值管理权限Terraform provider基础设施即代码中以键值声明权限。index.md补充了与键值相关的两条重要规则API Key 不支持 Owned 作用域——所有者解析的对象是用户而 Key 不是用户因此需要显式授予 Key 所需的全部访问index.mdBlock 永远优先——Block 权限列表始终压过 Allow 列表带标签的 Block 只移除携带该标签资源的权限如可以编辑监控但 Production 标签的除外。底层实现权限目录的生成与完整性保障权限目录的构成PermissionProps接口Permission.ts是每条权限的数据结构export interface PermissionProps { permission: Permission; // 枚举键即 Permission Key description: string; // 描述 isAssignableToTenant: boolean; // 是否可授予项目 title: string; // 界面显示标题 isAccessControlPermission: boolean; // 是否可按标签限制 isRolePermission: boolean; // 是否为内置角色 group: PermissionGroup; // 所属权限组 }PermissionHelper.getAllPermissionProps()Permission.ts返回完整目录再由派生方法过滤出不同子集getTenantPermissionProps()—— 过滤isAssignableToTenant即所有可授予项目的权限getRolePermissionProps()—— 在上一基础上过滤isRolePermission得到内置角色列表细粒度列表则是可授予权限中排除角色后的集合见 PermissionsTable.ts 的getGranularPermissionProps()。PermissionsTable.ts的文件头注释特别强调了绝不手写副本的原则如果文档里维护一份手写的 markdown 权限清单任何人新增一个权限后文档立刻失真——一份关于权限却撒谎的文档比没有更糟。表格渲染细节防破坏的单元格转义Markdown 表格以|分隔、单元格须单行。若某条权限描述里恰好含有换行或竖线会把整行拆成多余列或提前终结表格。为此 PermissionsTable.ts 中的toTableCell()做了三件事text .replace(/\r?\n/g, ) // 换行折叠为空格 .replace(/\s/g, ) // 连续空白归一 .replace(/\|/g, \\|) // 竖线转义 .trim();同时groupPermissions()按首次出现顺序分组而非PermissionGroup声明顺序以匹配 Dashboard 选择器的分组顺序保证文档与 UI 的序列一致PermissionsTable.ts。完整性测试防重复的绊线权限目录长期存在两类静默缺陷两个枚举成员共用同一字符串值导致授予其一即授予其二、所有者作用域被意外放大以及同一权限的PermissionProps被列出两次导致 Granular 选择器出现重复项。这两类问题 TypeScript 编译不会报错因此 Common/Tests/Types/Permission.test.ts 提供了四组目录完整性测试作为绊线枚举成员之间无重复字符串值getAllPermissionProps()无重复条目每条 props 都能通过getTitle/getDescription无损往返防止字典后写覆盖导致文档与界面文本不一致标题含 Template 的条目其键名也必须含 Template防止当年模板所有者权限错挂到非模板成员的 bug 复发。配套阅读权限模型的完整上下文reference.md是权限体系的速查手册其行为语义由 permissions/index.md 定义二者应配合阅读核心规则用户从不直接持有权限其访问权限等于所属所有团队权限的并集ProjectOwner覆盖计费与删除项目ProjectAdmin覆盖除计费外的一切默认团队每个新项目自带不可删除、不可改名的OwnersProjectOwner与AdminProjectAdmin团队以及可自由修改的MembersProjectMember团队——这是防止项目把自己锁在门外的设计请求判定流程依次为收集团队权限行 → 先查 Block → 查 Allow → 应用 Owned/Labels 作用域收窄 → 应用标签 Block解析结果按用户项目缓存权限变更后需刷新index.md。index.md还给出了可直接落地的四种配置配方只读观察团队加Viewer或按领域的*Viewer、自管服务的值班团队MonitorAdmin/IncidentMember/OnCallMember配 Owned 作用域 设为资源所有者、隔离生产环境的承包商All 作用域 对敏感能力加Production标签的 Block、仅上报部署的 CI 流水线API Key 只授必需细粒度权限。这些配方与reference.md中的角色、细粒度权限一一对应是验证该授予哪个 Key最直接的实战参考。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
