grafana

Grafana 运维

将 Grafana 视为一组带版本、分别授权且所有者明确的资源。在提出变更前，先确认目标、资源来源和实际生效的路由。服务器运行正常或仪表板外观出色，都不能证明配置预配、查询、告警评估或通知投递正常。

操作约定

1. 选择 API 或工作流前，确认 Grafana 版本、版本类型、部署模式、组织、文件夹或命名空间、身份验证模型以及当前权限范围。
2. 盘点现有的文件配置预配、Terraform/provider 状态、Git Sync、Grafana Operator 资源以及由 API/UI 管理的对象。更改资源前，为每个资源 UID 指定唯一的权威所有者。
3. 操作前确认目标、范围和回滚路径。只读发现可在未确认的情况下进行。
4. 将仪表板、文件夹、数据源、告警、用户/RBAC、插件和服务器配置的变更视为不同的授权范围。
5. 切勿打印、提交或保留服务账号令牌、密码、secureJsonData、已解密的接收器设置、OAuth 密钥、签名密钥、SMTP 凭据或 Webhook 中的机密值。通过获授权的机密管理机制保留受支持的安全配置字段，并且只记录已脱敏的元数据。
6. 有权限时，使用真实数据源验证仪表板和告警查询；否则说明离线限制，不要声称语义正确。
7. 验证请求的边界。服务器健康不代表仪表板已完成配置预配；规则触发不代表路由正常；通知送达不代表恢复行为正常。

不适用场景

使用 site-reliability-engineering 定义 SLI、SLO、错误预算、是否值得触发页面告警、严重性策略、升级流程和事件处理实践。使用针对具体数据源的指南处理 PromQL、LogQL、TraceQL、Flux、SQL、存储和后端运维。使用 docker-compose、kubernetes、traefik 或 platform-engineering 管理其基础设施控制平面。使用 secure-software-engineering 进行预防性安全设计，使用 security-audit-methodology 开展获授权的评估。本技能负责 Grafana 产品行为及 Grafana 侧集成。

只读发现

仅收集当前访问权限允许获取的信息：

grafana server -v
curl --fail --silent --show-error "$GRAFANA_URL/api/health"

对于容器、软件包、Helm 或 Cloud，使用所属平台的只读清单来确认镜像/标签、配置路径、部署模式和公开边界。不要转储进程环境变量或包含机密的解析后配置。使用获授权的服务账号令牌时，优先针对确切的资源类别发送范围受限的 GET 请求；通过受保护的环境或凭据存储传递令牌，不要将其写入命令历史或报告。

记录：

• 版本和版本类型：OSS、Enterprise 或 Cloud；
• 部署所有者和持久化方式：软件包、容器、Compose、Kubernetes、Helm、Operator 或托管堆栈；
• 组织、文件夹、命名空间和目标环境；
• 身份验证方法和实际生效的权限；
• 数据源 UID 和类型，不包含安全字段；
• 仪表板/文件夹 UID、告警资源及其来源；
• 配置预配提供方、监视路径、轮询间隔、删除/编辑设置及重复所有权；
• 回滚来源，以及可安全测试的边界。

选择端点前，请阅读API 和版本发现。Grafana 12 引入了新的 /apis 模型，而旧版 /api 路由从 Grafana 13 开始弃用，目前尚无完全一一对应的替代项。

任务路由

需求	首先阅读
了解版本、版本类型、身份验证、组织、资源 API 和权限范围	API 和版本发现
设计或审核仪表板、面板、变量、单位、转换、链接、注释、库面板、JSON 或无障碍功能	仪表板工程
构建或诊断规则评估、标签、联系人、策略、分组、静默、静默时段、模板和通知发送	告警与路由
选择或协调文件配置、Terraform、Git Sync、API、Foundation SDK 或 Operator 的所有权	配置管理与 GitOps
诊断空白面板、查询/身份验证失败、配置漂移、评估失败、通知缺失或代理/身份验证问题	故障排除
处理凭据、用户、服务账户、RBAC、插件、删除、共享或影响生产环境的变更	安全与变更控制
检查证据、版本时效性、实时发现或刷新规则	来源索引

安全工作流

1. 明确运维目标

说明受众、决策、资源 UID、权威所有者、目标环境、预期中断、验证方法和回滚方案。对于仪表板，声明可观测性方法或问题。对于告警，声明负责人、严重性依据、运行手册/仪表板链接、预期路由和噪声风险。

2. 在处理内容前协调所有权

将运行中的对象与所有潜在写入方进行比较。不要仅仅因为某个界面允许操作，就通过该界面编辑已配置的资源。更改文件或对象前，先检测重叠的提供方路径、重复的 UID 或标题、Terraform/API 漂移、会被覆盖的 UI 编辑，以及删除或清理行为。

3. 在处理呈现之前验证语义

在已知时间范围内运行有代表性的查询。确认指标/日志/追踪类型、单位、标签、聚合、基数、空值/无数据行为、时区、刷新间隔和查询成本。根据目标证据、已批准的策略或明确的测量目标，确定默认值、阈值、刷新频率、前 N 项限制和最低流量阈值；否则应留空，而不是自行选择看似合理的值。对于重复面板或多维度告警，应限制维度集合，并证明其仍然具有可操作性。

4. 通过所有者预览并应用

使用权威来源和受支持的最小范围操作。审核差异和导出的备份，并对机密信息进行脱敏。替换策略树、使用 prune、移除提供方来源、重用 UID、更改 RBAC、安装插件或删除数据源/仪表板，都必须在变更前立即获得明确确认。

5. 验证每个受影响的层面

层面	最低证据要求
服务端	有版本信息的进程能够响应，且已报告数据库健康状况；有界日志中没有新的故障循环
配置管理	每个 UID/路径只有一个所有者；协调已完成；多次扫描中均无重复/漂移警告
数据源	已授权的健康检查/查询测试成功，且时间范围和代表性数据符合预期
仪表板	查询在语义上有效；单位/标签/空状态呈现正确；链接和变量保留上下文
告警评估	已观察到预期的正常、待处理、触发、无数据/错误和恢复行为，或明确标记为未测试
通知路由	实际标签会选择预期的策略/联系人；已检查分组和静默行为
通知发送	受控测试已到达预期接收方；在许可的情况下，已观察到告警恢复通知
访问权限	预期角色能够执行操作；权限较低的角色无法执行；机密信息仍保持脱敏

审批边界

在重置密码；更改用户、组织、团队、服务账号或 RBAC；安装或移除插件；删除数据源、仪表板、文件夹、告警规则、联系人或策略；替换通知策略；进行实时通知测试；重新加载配置或重启服务；轮换密钥；更改匿名/公开共享设置；或直接恢复数据库之前，必须获得明确批准。除非用户在备份后、且所有可行的替代方案均已穷尽时，明确授权执行有文档记录的恢复流程，否则绝不直接编辑 Grafana 的数据库。

完成标准

当请求的资源或诊断结果已关联到已知的 Grafana 版本和所有者、相关查询或路由已在获授权的最高边界上通过验证、没有泄露任何密钥，且仍可回滚时，任务即告完成。列出所有未触及的更高边界，包括经过身份验证的 API 清点、实时数据源查询、告警触发、接收方投递、已解决通知、无障碍测试、重新加载/重启后的持久性或生产环境行为。