OneUptime 仪表盘配置与访问控制完全指南：所有者、标签、RBAC 权限与公开访问管理
【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime
本指南以 OneUptime 官方文档「Configuration & Permissions（配置与权限）」为核心骨架，系统讲解当项目中的仪表盘（Dashboard）需要长期维护时，必须掌握的全部配置项与访问控制机制：所有者（Owners）与标签（Labels）的组织方式、基于角色的权限模型、公开仪表盘的三种访问控制层、数据保留策略，以及复制、删除与备份等生命周期管理操作。读完本文，你将能够为一套生产级监控仪表盘搭建出从「内部私有」到「受控公开」的完整权限体系。
所有者（Owners）：为单个仪表盘授予显式访问权
一个仪表盘的所有者，是你在项目级角色之外，通过显式授权赋予其额外访问权的用户与团队。所有者机制解决的核心问题在于：项目级角色通常是「一刀切」的，而部分仪表盘需要面向更细粒度的受众。
在Dashboard → Owners页面，你可以执行两类操作：
- 添加用户所有者（User Owner）：让某一个具体的人获得该仪表盘的额外访问权；
- 添加团队所有者（Team Owner）：让某个团队的全部成员同时获得同样的访问权。
何时该使用所有者？文档给出的典型场景是：当项目级「读」角色过于宽泛时——例如，一个包含客户级别敏感细节的仪表盘，只应允许客户成功团队（Customer Success Team）查看，此时就不应依赖项目级角色，而应通过所有者做精确授权。
从源码实现看，OneUptime 为所有者机制设计了独立的数据模型，而非在仪表盘上叠加简单字段：
- DashboardOwnerUser.ts：表示「用户所有者」，通过
userId关联具体用户，通过dashboardId关联仪表盘，并建立了(dashboardId, userId, projectId)的唯一索引，确保同一用户不会在同一个仪表盘上重复成为所有者； - DashboardOwnerTeam.ts：表示「团队所有者」，结构对称，唯一索引为
(dashboardId, teamId, projectId)。
这两个模型都拥有独立的 CRUD API 端点（/dashboard-owner-user与/dashboard-owner-team）和独立的一套权限（如CreateDashboardOwnerUser、EditDashboardOwnerTeam等，定义在 Permission.ts）。这意味着在权限体系中，所有者管理是可与仪表盘编辑解耦的独立能力。前端层面，Owners.tsx 通过通用的 OwnersCard.tsx 组件渲染所有者头像圈，支持添加/移除用户与团队两类所有者。
标签（Labels）：仪表盘的分类与检索
标签是用于组织仪表盘的标记，在Dashboard → Overview页面为仪表盘打上。它是大型项目中快速定位仪表盘的最有效手段——Dashboards列表支持按标签过滤。
文档给出了三种高频标签命名模式：
| 模式 | 示例 |
|---|---|
| 按团队 | team:platform、team:checkout、team:growth |
| 按环境 | env:prod、env:staging |
| 按用途 | purpose:oncall、purpose:exec、purpose:investigation |
在数据模型层面，Dashboard.ts 中labels字段通过@ManyToMany关系关联到Label模型，中间表名为DashboardLabel；同时，类级别通过@AccessControlColumn("labels")注解将标签列与访问控制挂钩——这意味着标签不仅用于检索，还与 OneUptime 的标签级权限体系联动，可以参与决定谁能看到哪些资源。
权限（Permissions）：基于角色的访问控制
仪表盘完全遵循项目的基于角色的访问控制（RBAC）模型。文档列出的四类核心权限如下：
| 权限 | 允许的操作 |
|---|---|
| Create Dashboard | 创建新仪表盘 |
| Read Dashboard | 查看仪表盘（私有模式下） |
| Edit Dashboard | 修改组件（Widget）、变量与设置 |
| Delete Dashboard | 删除仪表盘 |
在Products → Teams →你的团队→ Permissions页面可以逐项为团队分配这些权限。
源码层面，Dashboard.ts 的@TableAccessControl装饰器完整刻画了权限矩阵：
- create需要
ProjectOwner、ProjectAdmin或CreateDashboard之一； - read的门槛最低，
ProjectOwner、ProjectAdmin、ProjectMember、Viewer、SettingsAdmin/Member/Viewer以及ReadDashboard均可； - update需要
ProjectOwner、ProjectAdmin或EditDashboard； - delete需要
ProjectOwner、ProjectAdmin或DeleteDashboard。
这里有一个关键设计：仪表盘的每个字段（列）也有独立的访问控制。例如name、description、dashboardViewConfig（仪表盘画布配置，即组件的布局与数据绑定，见 Dashboard.ts）等字段的@ColumnAccessControl各自声明了可读、可写的权限集合，读取往往放行给Viewer，而写入则收紧到EditDashboard。
文档还强调了一个容易忽略的点：所有者与自定义域名（Custom Domain）也各自拥有一套对应的权限（Create/Read/Edit/Delete DashboardOwnerUser、Create/Read/Edit/Delete DashboardOwnerTeam与Create/Read/Edit/Delete DashboardDomain，见 Permission.ts）。因此你可以授予某团队「管理所有者」的能力，而不授予「编辑仪表盘本身」的能力——两类权限互不捆绑，可按需组合。
公共仪表盘的访问控制：三层防护可叠加
当你把仪表盘设为公开（详见 共享与公共仪表盘）后，有三个设置共同决定谁能看到它：
- Public Dashboard 开关——若关闭，公开地址直接返回 404；
- Master Password（主密码）——若设置，访客在仪表盘显示前必须先输入密码；
- IP 白名单（IP Whitelist，Scale 套餐）——若设置，来自其他 IP 的请求一律被拒绝。
三个开关可以任意组合。文档特别指出，最严格的组合是「公开开启 + 设置密码 + 启用 IP 白名单」，适用于要求三层防护同时生效的合作伙伴门户（Partner Portal）场景。
从源码可以更深入地理解这三层机制在数据模型与 UI 中的落地（Dashboard.ts）：
isPublicDashboard（第 726-764 行）：布尔字段，默认false。它带有@ColumnBillingAccessControl注解，其中update权限绑定到PlanType.Growth——即开启公共开关有套餐门槛；masterPassword（第 802-866 行）：以HashedString类型存储，并配有独立的masterPasswordSalt（每个仪表盘随机生成的盐值，写库时混入哈希、永不通过 API 暴露），确保密码以安全哈希形式保存，任何人也无法还原明文；同时enableMasterPassword布尔开关决定是否启用密码门禁；ipWhitelist（第 868-907 行）：VeryLongText类型，每行一个 IP，支持 IPv4 与 IPv6，也支持 CIDR 网段；同样带@ColumnBillingAccessControl，update绑定到PlanType.Scale，与文档所述「Scale 套餐」完全一致。
前端实现位于 AuthenticationSettings.tsx：当isPublicDashboard为真时，页面会动态展开主密码设置卡片与 IP 白名单编辑卡片；IP 白名单输入框的占位提示明确写着「请每行输入一个要放行的 IP 地址或 CIDR 网段，支持 IPv4 或 IPv6」，未配置白名单时则提示「当前放行所有 IP 访问该仪表盘」。UI 文案也再次强调主密码「以安全哈希存储，无法找回」。
数据保留（Data Retention）：仪表盘不会过期，数据取决于套餐
仪表盘本身永不过期——它只是一个视图容器。它展示的数据遵循项目的数据保留设置：指标（Metrics）、日志（Logs）与追踪（Traces）只要在套餐保留期内就始终可查询。文档用一个很形象的例子说明：一个指向「过去 90 天」的组件，如果当前套餐只保留 30 天，那么它只会展示仍被存储的数据。
这意味着：仪表盘配置的存续时间与底层遥测数据的存续时间是两个相互独立的维度，理解这一点有助于在规划长期趋势视图时合理预期数据可用范围。
复制（Duplicate）：从模板派生服务专属副本
要复制一个现有仪表盘，打开仪表盘列表并选择Duplicate。副本会包含全部组件、变量与设置，但有一项例外——公共共享（Public Sharing）始终默认关闭，由你决定是否重新开启。
这在需要把一份模板（比如「我们的 On-Call 仪表盘」）派生为某个服务专属副本时非常合适。
源码中，Settings.tsx 使用通用DuplicateModel组件实现复制，其fieldsToDuplicate明确列出被复制的字段：
description（描述）labels（标签）dashboardViewConfig（画布配置，即全部组件与布局）
而isPublicDashboard等公开共享字段不在复制清单中——这与文档「公开共享始终从关闭开始」的描述在实现上完全吻合。复制时还会要求为副本输入新的仪表盘名称（最少 2 个字符）。此外，同一个设置页面还提供了ExportModelCard（导出模型卡片），可将仪表盘配置以 JSON 形式导出，作为轻量备份手段。
删除（Delete）：不可逆操作及其影响范围
在Dashboard → Delete页面可以删除仪表盘。该操作不可撤销，会移除仪表盘的布局（画布配置）以及所有挂接在它上面的自定义域名；但不会影响你的遥测数据（指标、日志、追踪的原始数据独立于仪表盘存储）。
一个值得注意的连锁反应：如果该仪表盘通过自定义域名对外公开，那么删除后该地址立即停止解析。若你希望保留这个 URL 继续工作，必须先把这个自定义域名转移到另一个仪表盘上，再执行删除。
备份（Backup）：自托管与云端的差异
- 自托管 OneUptime：定期备份数据库即可——仪表盘配置与项目其他数据存放在一起（
Dashboard是项目租户下的普通数据库表，通过@TenantColumn("projectId")按项目隔离，见 Dashboard.ts）； - OneUptime Cloud：备份由平台代为处理。若你想要一份自己的副本，可以通过 OneUptime API 读取仪表盘数据（仪表盘模型注册了
@CrudApiEndpoint(new Route("/dashboard"))与@EnableDocumentation()，可自动生成 API 文档与访问端点）。
延伸阅读
- 共享与公共仪表盘：公开模式的完整控制（主密码、IP 白名单、自定义域名、品牌化与 iframe 嵌入）；
- 变量与过滤器：通过变量做模板化，让一个仪表盘适配多个服务或客户；
- 组件（Widgets）：组件完整目录与各自的数据展示能力；
- 仪表盘概览：仪表盘在 OneUptime 中的整体定位与核心概念；
- 构建仪表盘：画布使用与组件编辑。
说明：本文对应文档的波斯语原版位于 packages/App/FeatureSet/Docs/Content/fa/dashboards/configuration.md，内容与英文版一致。
【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
