Grafana | 开源可观测性平台，把指标、日志和链路汇成 Dashboard

如果指标、日志和链路数据分别落在 Prometheus、Loki、Tempo、Elasticsearch 或数据库里，Grafana 的核心价值不是替换这些后端，而是提供统一的查询、可视化、分享和告警入口。它更像可观测性系统的工作台：先接入数据源，再用 Explore 验证查询，把有效查询组织成可复用 Dashboard，最后为真正需要响应的问题配置告警。本文介绍的是 grafana/grafana 开源仓库，重点解释它能做什么、Docker 自托管怎样避免丢配置、Provisioning 如何接入版本控制，以及 AGPL-3.0-only 对二次分发和网络服务意味着什么。

截至 2026 年 9 月 2 日核对，GitHub 最新 Release 为 v13.2.1，发布时间为 2026 年 9 月 2 日；仓库页面约有 7.66 万 stars、1.47 万 forks，默认分支为 main，GitHub 当前标记的主要语言为 TypeScript。v13.2.1 的 Release 说明包含两项安全修复和多项 Dashboard、打包与面板编辑器修复；版本号、统计数量和变更内容会继续变化，实际部署前应以官方 Release 为准。

Grafana 的定位：统一查询与可视化，不是数据仓库

Grafana README 将项目概括为开放源码的监控与可观测性、数据可视化平台，核心动作是 query、visualize、alert 和 understand。Grafana 可以向外部数据源发起查询，再把返回结果交给面板渲染；指标、日志和链路的采集、存储、保留周期与容量规划，仍然由 Prometheus、Loki、Tempo、InfluxDB、Elasticsearch 或数据库等系统负责。只部署 Grafana 而没有可查询的数据源，得到的只是空的管理界面。

组件	在工作流中的角色	需要自行负责的边界
数据源插件	连接某类指标、日志、链路或数据库后端	端点、认证、权限、查询成本与后端可用性
Grafana 服务	保存用户、数据源、Dashboard 和权限等平台配置	配置数据库、密钥、备份、升级和访问控制
Dashboard / Panel	将查询组织成团队可复用的图表和表格	面板查询、刷新频率、变量和浏览权限
Alerting	评估规则并把通知路由到联系点	阈值、标签、静默、维护窗口和通知责任人

数据源先于漂亮面板

Grafana 内置 Prometheus、Loki、MySQL 等核心数据源，也可以通过插件扩展。添加数据源时需要准备服务地址、认证方式、访问模式和最小权限；连接测试成功只说明 Grafana 能发起查询，不代表查询低成本，也不代表数据源已经具备高可用。混合数据源允许同一个面板中的不同查询指向不同后端，适合把同一时间窗口的指标、日志统计或业务数据库结果放进一个观察上下文，但跨源组合会同时放大字段语义、延迟和排障复杂度。

Dashboard 与 Explore 是两种工作场景

Explore 适合临时查询、拆分时间范围、比较不同数据源并从指标钻取到日志；Dashboard 适合把已经验证过的查询沉淀为团队共识。模板变量可以把环境、主机、服务或租户变成 Dashboard 顶部的选择项，让一份布局复用于多个对象。真正上线前，还要核对每个面板的单位、刷新频率和查询成本，而不是只看图表是否好看。

Grafana 官方 Dashboard 多面板可观测性界面 — Grafana 官方产品页展示的多面板 Dashboard 界面，包含折线图、面积图、指标卡和柱状图。来源：Grafana 官方产品页：https://grafana.com/products/cloud/grafana/

从数据源走到可复用 Dashboard

一个可维护的 Grafana 工作流可以按下面的顺序展开：

先配置数据源：填写端点、认证和访问模式，确认 Grafana 能读取目标后端，并为服务账号设置最小权限。
在 Explore 写最小查询：先验证时间范围、标签、单位和返回数据，再考虑变量、转换和多查询组合。
创建 Panel 和变量：把已经验证的查询放进单个面板，选择合适的可视化，再抽取环境、服务或主机变量。
组织 Dashboard：让一组面板回答同一个运营问题，明确刷新间隔、访问角色和分享范围；不要把所有指标堆到一张图里。
再接入告警：只有当阈值、持续时间、标签和通知责任人都清楚时，才把查询升级成规则。

这套顺序的实际意义在于隔离问题：查询无数据时先查数据源和时间范围，图表异常时再看单位与转换，通知过多时再调整规则分组和静默。Grafana 可以把不同后端组合在一起，但不会替你定义业务指标含义；指标命名、标签基数和数据保留策略仍属于上游系统的治理工作。

告警是独立工作流，不是把面板变红

Grafana Alerting 以规则评估为中心：规则可以对一个或多个数据源运行查询与表达式，按时间序列或维度产生 alert instance，再交给 contact point 和 notification policy 路由。这样做比“某个面板变红就发消息”更可控，但也要求同时设计评估间隔、标签、通知分组、维护窗口和静默策略。多数据源告警尤其要记录数据延迟与缺失值语义，否则规则可能把后端暂时无数据误判为业务故障。

告警数量、规则评估频率、Dashboard 刷新频率和并发用户都会影响 Grafana 服务进程负载。生产环境应把通知升级、值班责任人和故障演练纳入流程，而不是仅凭“已经配置了 Alerting”就认为监控闭环完成。

Docker 自托管：先把数据持久化

官方 Docker 文档提供 Grafana Enterprise 与 Grafana Open Source 两种镜像；本文对应 GitHub 开源仓库，使用 grafana/grafana 镜像。官方文档还提醒，从 Grafana 12.4.0 开始，grafana/grafana-oss Docker Hub 仓库不再更新，新的 OSS 镜像入口应使用 grafana/grafana。一个带 Docker volume 的评估命令如下：

docker volume create grafana-storage
docker run -d --name=grafana -p 3000:3000 \
  --volume grafana-storage:/var/lib/grafana \
  grafana/grafana

容器内默认使用嵌入式 SQLite 保存配置、用户和 Dashboard；如果没有 volume 或 bind mount，删除容器时这些数据也会随容器文件系统一起丢失。进入 http://localhost:3000 后，应先完成管理员密码、访问入口和数据源配置，再把 /var/lib/grafana、Provisioning 文件和数据库纳入自己的备份方案。本文没有在本机执行 Docker，不把上述命令写成实测结果。

评估环境和生产环境的差异

单容器和 SQLite 适合先确认界面、插件与数据源连接；多实例、高并发或需要独立数据库时，应根据官方部署文档评估 MySQL 或 PostgreSQL、反向代理、HTTPS、会话、插件策略和恢复流程。Grafana 的配置数据库与 Prometheus、Loki、Tempo 等观测后端是两套不同的状态，备份其中一套不能替代另一套。

插件要固定来源和版本

Grafana 支持 panel、data source 和 app 三类插件。Docker 可以通过 GF_PLUGINS_PREINSTALL 预安装插件，也可以在变量中写明版本；不指定版本时会使用插件当前可用版本。生产镜像和插件都应记录明确版本，避免容器重建时无意获得不同代码。

Provisioning：把配置纳入版本控制

Grafana 的 Provisioning 系统用配置文件定义数据源和 Dashboard，让自托管环境更容易接入 GitOps。数据源配置通常放在 provisioning/datasources，Dashboard 可以由对应的 Provisioning 文件加载；环境变量适合注入 URL、用户名和密码等配置值，但不应替代配置键或整段文件结构。

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

上面的示例只表达结构，不包含真实凭据，也没有假设你的服务名称。需要删除已不在文件中的数据源时，可以使用 prune: true，但启用前要确认“从配置文件移除”确实等于“希望删除托管对象”。多实例部署还应为数据源配置维护版本号，避免不同实例重启时用旧文件覆盖新状态。

AGPL-3.0-only 与 Apache 例外：先分清你分发的是什么

grafana/grafana 仓库的默认许可证是 AGPL-3.0-only，LICENSING.md 同时列出部分目录和文件的 Apache-2.0 或上游许可证例外，例如部分 packages、packaging、pkg 和图标目录。例外清单只适用于列明的路径，不能把整仓库概括成 Apache 或 MIT。

v13.2.1 的维护信号与使用取舍

最新 Release v13.2.1 在 2026 年 9 月 2 日发布，变更记录包含 CVE-2026-12704 与 CVE-2026-14199 两项安全修复，以及 Dashboard 变量导入、打包插件移动、面板编辑器尺寸和多项桌面体验修复。对生产部署而言，安全修复比追逐浮动的 latest 标签更值得优先处理；升级前应阅读完整变更记录，在预发布环境验证登录、数据源、关键 Dashboard 和通知路由。

Grafana 适合已经拥有一个或多个指标、日志或链路后端，希望统一查询和分享入口的开发团队、平台团队与运维团队；也适合把 Dashboard、数据源和告警配置纳入版本控制的组织。如果你只需要一个无需维护采集与存储后端的托管监控面板，应把 Grafana Cloud 或其他托管方案一起比较。Grafana OSS 本身不会自动提供数据采集、长期存储、容量规划或高可用。