Grafana —— 多数据源统一可视化与告警平台

分类：02 可视化与告警呈现 适用：Linux / Windows / 容器 / K8s；从单机实验到上千人共用的企业监控中台 一句话：把 Prometheus、Loki、Elasticsearch、SQL 等任意数据源汇聚成 Dashboard，并用统一告警引擎发通知 官方：https://grafana.com　GitHub：https://github.com/grafana/grafana 授权：OSS 版 AGPLv3；Enterprise 版采用 Grafana Labs License（基础功能免费，高级功能需商业授权）

1. 它解决什么问题

• 数据源割裂：指标在 Prometheus、日志在 Loki/ES、链路在 Tempo、业务数据在 MySQL，故障时要开 N 个控制台；Grafana 用数据源插件统一查询与展示。
• 图表重复造轮子：提供 Time series、Stat、Gauge、Table、Heatmap、Geomap 等 Panel，拖拽即成大盘。
• 告警散落：Unified Alerting 把「规则求值 → 分组 → 抑制 → 路由 → 通知」集中管理。
• 配置不可版本化：Provisioning 用 YAML/JSON 声明数据源、大盘、告警，纳入 Git（GitOps）。
• 多租户隔离：Org / Team / Folder / RBAC 分业务线控制可见性。
• 边界：它不采集、不长期存储指标，是查询与呈现层；查询性能由后端数据源决定。

2. 核心概念与架构

 后端数据源          Grafana Server                          接收端
 ┌────────────┐      ┌───────────────────────────────────────────────┐
 │ Prometheus │ 查询 │ datasource ─► Panel(targets) ─► Dashboard     │
 │ Loki / ES  │◄────►│                 ▲ 变量 Variable 注入标签过滤   │
 │ MySQL /... │ 序列 │ datasource ─► Alert rule(query+expr+for+labels)│
 └────────────┘      │                      │ 独立求值，不依赖大盘    │
                     │                      ▼                        │
                     │  Notification policy（按标签路由/分组/抑制）    │
                     │                      ▼                        │
                     │  Contact point（Email/Slack/Webhook/企微/钉钉） │
                     └──────────────────────┼────────────────────────┘
                                            ▼ 邮件 / IM / HTTP 回调

核心链路：datasource（连后端）→ panel（变量改写查询并渲染）→ alert rule（后端定时独立求值）→ notification policy（按标签匹配路由、分组、去重）→ contact point（投递）。告警规则不依赖大盘是否打开，删掉大盘规则仍在。

新旧告警引擎差异（重要）：Legacy Dashboard Alerting 把告警绑在 Panel 上、只能单条查询、用 /api/alert-notifications、无分组路由；Unified Alerting 自 8 提供、9 起默认，新版本已移除/停用旧引擎，迁移走 UI「Alerting → Upgrade」向导，旧端点 /api/alerts 属 legacy。生产一律用 Unified，具体迁移行为以官方升级说明为准。

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

# A. APT 仓库（Debian/Ubuntu，官方推荐）
sudo apt-get install -y apt-transport-https software-properties-common wget gnupg
sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install -y grafana        # 企业版包名 grafana-enterprise
sudo systemctl daemon-reload && sudo systemctl enable --now grafana-server
# B. YUM/DNF：repo 中 baseurl=https://rpm.grafana.com、gpgkey=https://rpm.grafana.com/gpg.key、gpgcheck=1
# C. Docker / compose
docker run -d --name=grafana -p 3000:3000 -v grafana-storage:/var/lib/grafana \
  -e GF_SECURITY_ADMIN_PASSWORD='<强密码>' grafana/grafana
# compose.yaml：image: grafana/grafana；ports: ["3000:3000"]；
#   volumes: [grafana-storage:/var/lib/grafana, ./provisioning:/etc/grafana/provisioning:ro]
# D. 二进制 tar.gz + systemd
wget https://dl.grafana.com/oss/release/grafana-<版本>.linux-amd64.tar.gz
tar -zxvf grafana-<版本>.linux-amd64.tar.gz -C /opt/ && sudo ln -s /opt/grafana-<版本> /opt/grafana
# grafana.service：[Service] ExecStart=/opt/grafana/bin/grafana-server -homepath /opt/grafana -config /opt/grafana/conf/custom.ini；Restart=on-failure
sudo systemctl daemon-reload && sudo systemctl enable --now grafana
# E. K8s Helm
helm repo add grafana https://grafana.github.io/helm-charts && helm repo update
helm install grafana grafana/grafana -n monitoring --create-namespace \
  --set adminPassword='<强密码>' --set persistence.enabled=true --set persistence.size=10Gi

精确版本号、镜像 tag 以官方最新稳定版为准（当前大版本线 13.x，见官方下载页）。

3.3 首次启动与验证

curl -s http://localhost:3000/api/health | jq .          # database: ok
sudo systemctl status grafana-server                      # active (running)
sudo journalctl -u grafana-server -n 50 --no-pager        # 无 ERROR
sudo ss -lntp | grep 3000
# 浏览器打开 http://<主机>:3000，默认 admin/admin，首次登录强制改密

4. 配置文件详解

主配置：/etc/grafana/grafana.ini（包安装）；二进制为 conf/custom.ini。所有项可用 GF_<段名>_<键名> 环境变量覆盖（如 GF_SERVER_HTTP_PORT=3001），容器部署优先用环境变量。

最小可运行示例 /etc/grafana/grafana.ini：

[server]
http_port = 3000
root_url = https://grafana.example.com/
[security]
admin_password = <强密码>
secret_key = <32位以上随机串，HA各节点相同>
[database]
type = postgres
host = 127.0.0.1:5432
name = grafana
user = grafana
password = <DB密码>
[smtp]
enabled = true
host = smtp.example.com:587
user = alert@example.com
password = <SMTP密码>
from_address = alert@example.com
[unified_alerting]
enabled = true

Provisioning：/etc/grafana/provisioning/，启动幂等加载；该目录声明的资源会在重启时覆盖 UI 手工改动。

# provisioning/datasources/datasource.yaml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    uid: prom-main            # 面板与规则按 uid 引用，勿随意改
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false
    jsonData: { timeInterval: 15s, httpMethod: POST }

# provisioning/dashboards/dashboards.yaml
apiVersion: 1
providers:
  - name: default
    orgId: 1
    folder: 运维大盘
    type: file
    disableDeletion: true
    updateIntervalSeconds: 30
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

# provisioning/alerting/alerting.yaml
apiVersion: 1
contactPoints:
  - orgId: 1
    name: ops-webhook
    receivers:
      - uid: cp-webhook
        type: webhook
        settings:
          url: https://oapi.dingtalk.com/robot/send?access_token=<TOKEN>
          httpMethod: POST
          title: '{{ template "default.title" . }}'
          message: '{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}'
policies:
  - orgId: 1
    receiver: ops-webhook
    group_by: [alertname, severity]
    group_wait: 30s
    group_interval: 5m
    repeat_interval: 4h
    routes:
      - receiver: ops-webhook
        matchers: [severity = critical]
        repeat_interval: 1h
groups:
  - orgId: 1
    name: node-rules
    folder: 运维大盘
    interval: 1m
    rules:
      - uid: rule-node-down
        title: 主机失联
        condition: C
        for: 2m
        labels: { severity: critical, team: ops }
        annotations: { summary: '{{ $labels.instance }} 已失联' }
        data:
          - { refId: A, relativeTimeRange: { from: 600, to: 0 }, datasourceUid: prom-main, model: { expr: 'up{job="node"}', refId: A } }
          - { refId: B, datasourceUid: __expr__, model: { type: reduce, reducer: last, expression: A, refId: B } }
          - { refId: C, datasourceUid: __expr__, model: { type: threshold, expression: B, conditions: [{ evaluator: { type: lt, params: [1] } }], refId: C } }

Provisioning 字段随版本演进，导入前用 POST /api/v1/provisioning/alert-rules 或 UI Export 校验，以官方文档为准。Mute timings / Silences 见第 6 章。

5. 核心使用方法

CLI：

grafana-cli plugins list-remote | grep -i <关键字>       # 搜索插件
grafana-cli plugins install <plugin-id>                  # 安装
grafana-cli plugins ls                                   # 已安装
grafana-cli plugins update-all                           # 升级全部，需重启
grafana-cli plugins remove <plugin-id>
grafana-cli admin reset-admin-password '<新密码>'        # 忘记密码
grafana-server -config /etc/grafana/grafana.ini          # 指定配置启动

HTTP API（Service Account Token，头 Authorization: Bearer <TOKEN>；GRAFANA_URL=http://localhost:3000，H="Authorization: Bearer <TOKEN>"，CT="Content-Type: application/json"）：

curl -s $GRAFANA_URL/api/health                                              # 1 健康检查
curl -s -H "$H" $GRAFANA_URL/api/datasources | jq .                           # 2 数据源列表
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/datasources -d '{"name":"Prom2","type":"prometheus","url":"http://prom:9090","access":"proxy"}'  # 3 新建数据源
curl -s -H "$H" $GRAFANA_URL/api/datasources/uid/prom-main/health | jq .       # 4 连通性
curl -s -X PUT -H "$H" -H "$CT" $GRAFANA_URL/api/datasources/uid/prom-main -d '{"name":"Prometheus","type":"prometheus","url":"http://prom:9090","access":"proxy"}'  # 5 更新
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/dashboards/db -d @dashboard.json            # 6 创建/更新大盘
curl -s -H "$H" "$GRAFANA_URL/api/dashboards/uid/<uid>" | jq .                 # 7 读取大盘 JSON
curl -s -H "$H" "$GRAFANA_URL/api/search?type=dash-db&query=主机"              # 8 搜索大盘
curl -s -X DELETE -H "$H" "$GRAFANA_URL/api/dashboards/uid/<uid>"              # 9 删除大盘 ⚠️
curl -s -H "$H" $GRAFANA_URL/api/folders | jq .                                # 10 文件夹列表
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/folders -d '{"title":"业务监控"}'         # 11 建文件夹
curl -s -H "$H" "$GRAFANA_URL/api/v1/provisioning/alert-rules" | jq .          # 12 告警规则（Unified）
curl -s -H "$H" "$GRAFANA_URL/api/v1/provisioning/contact-points" | jq .       # 13 通知点
curl -s -H "$H" "$GRAFANA_URL/api/v1/provisioning/policies" | jq .             # 14 通知策略树
curl -s -H "$H" "$GRAFANA_URL/api/v1/provisioning/mute-timings" | jq .         # 15 静默时段
curl -s -H "$H" "$GRAFANA_URL/api/ruler/grafana/api/v1/rules" | jq .           # 16 Ruler 规则（Prom 兼容）
curl -s -H "$H" "$GRAFANA_URL/api/alertmanager/grafana/api/v2/alerts" | jq .    # 17 活动告警
curl -s -H "$H" "$GRAFANA_URL/api/annotations?from=<epoch_ms>&to=<epoch_ms>"   # 18 注解
curl -s -H "$H" "$GRAFANA_URL/api/admin/settings" | jq .                       # 19 生效配置
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/serviceaccounts -d '{"name":"ci-bot","role":"Editor"}'  # 20 建服务账号，再 POST /api/serviceaccounts/<id>/tokens 取 token
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/ds/query -d '{"from":"now-1h","to":"now","queries":[{"refId":"A","datasource":{"uid":"prom-main"},"expr":"up"}]}'  # 21 直接查询
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/dashboards/import -d @import.json        # 22 导入社区大盘
# /api/alerts、/api/alert-notifications 为 legacy 端点，Unified 下请用 12~17

变量 + PromQL 面板配置（Dashboard JSON 片段）：

{
  "templating": { "list": [
    { "name": "job", "type": "query", "label": "任务", "datasource": {"type":"prometheus","uid":"prom-main"}, "query": "label_values(up, job)", "refresh": 1, "includeAll": true, "multi": true },
    { "name": "instance", "type": "query", "query": "label_values(up{job=~\"$job\"}, instance)" }
  ]},
  "panels": [
    { "id": 1, "type": "timeseries", "title": "CPU 使用率", "gridPos": {"h":8,"w":12,"x":0,"y":0},
      "datasource": { "type": "prometheus", "uid": "prom-main" },
      "targets": [ { "refId": "A", "expr": "100 - avg by(instance) (rate(node_cpu_seconds_total{mode=\"idle\",job=~\"$job\"}[5m])) * 100", "legendFormat": "{{instance}}" } ],
      "fieldConfig": { "defaults": { "unit": "percent", "min": 0, "max": 100, "thresholds": { "mode": "absolute", "steps": [ {"color":"green"}, {"color":"red","value":80} ] } } } }
  ],
  "time": { "from": "now-6h", "to": "now" }, "refresh": "30s"
}

Web UI 路径：Connections → Data sources → Add data source；Dashboards → New → Add visualization；Dashboard 齿轮 → Variables；Alerting → Alert rules / Contact points / Notification policies / Silences；Administration → Plugins / Service accounts；Explore 做免建盘临时查询。

6. 告警与通知

规则构成：查询 A（PromQL）→ Reduce（last/mean）→ Threshold（< 1、> 80）→ for: 2m 去抖 → labels（路由）→ annotations（模板）。UI：Alerting → Alert rules → New alert rule。

# 企微 markdown body：{"msgtype":"markdown","markdown":{"content":"**告警**\n{{ range .Alerts }}> {{ .Annotations.summary }}{{ end }}"}}
# 钉钉 text body：{"msgtype":"text","text":{"content":"[{{ .Status }}] {{ range .Alerts }}{{ .Annotations.summary }}{{ end }}"}}
# 模板变量与机器人加签/关键字安全设置以官方 Contact points 文档为准

静默 / 升级 / 去重：Silences 按标签 + 起止时间屏蔽通知（规则仍求值）；Mute timings 定义非工作时段并挂到策略 mute_time_intervals；升级用嵌套路由树，先发普通群、repeat_interval 后未恢复再由子路由匹配 severity=critical 发值班渠道；分组 group_by 合并同类，group_wait 等齐、group_interval 合并新增、repeat_interval 控制重复频率，内置 Alertmanager 的 inhibit_rules 可让「集群宕机」压制单机告警。

7. 实战场景

场景一：15 分钟搭出主机资源大盘并接告警

# 目标：node_exporter + Prometheus 呈现 CPU，失联 2 分钟告警到钉钉
# 步骤1：用第 5 章 JSON 片段准备 dashboard.json（变量 job + CPU panel）
curl -s -X POST -H "$H" -H "$CT" $GRAFANA_URL/api/dashboards/db \
  -d '{"dashboard":{...},"folderUid":"<folderUid>","overwrite":true}' > /tmp/import.json
# 步骤2：把第 4 章 alerting.yaml 放入 provisioning/alerting/ 并重启
sudo systemctl restart grafana-server
# 验证
curl -s -H "$H" "$GRAFANA_URL/api/v1/provisioning/alert-rules" | jq '.[].title'
curl -s -H "$H" "$GRAFANA_URL/api/alertmanager/grafana/api/v2/alerts" | jq 'length'
# 回滚：移除该 YAML 与 dashboard.json 后重启，或 DELETE 规则
curl -s -X DELETE -H "$H" "$GRAFANA_URL/api/v1/provisioning/alert-rules/rule-node-down"

场景二：prod/staging 用变量复用一套大盘

# 目标：一套大盘靠下拉切环境，不复制 JSON
# 步骤：templating.list 加 {"name":"env","type":"custom","query":"prod,staging"} 与
#   {"name":"ds","type":"datasource","query":"prometheus"}；panel.expr 写 up{env="$env"}，datasource 用 {"type":"prometheus","uid":"${ds}"}
# 验证：切换下拉，浏览器 Network 看 /api/ds/query 请求体 expr 已带 env=prod
# 回滚：从 Git 恢复上一版 dashboard.json，POST /api/dashboards/db 覆盖

场景三：Grafana 迁移 / 灾备恢复

# 目标：新机房用 Git provisioning + 数据库备份恢复整套视图
pg_dump -Fc -h <旧库> -U grafana grafana > grafana_$(date +%F).dump
tar czf conf_$(date +%F).tgz /etc/grafana/ /var/lib/grafana/plugins/
psql -h <新库> -U grafana -d grafana -f grafana_<日期>.dump && docker compose up -d grafana
# 验证：/api/health、大盘数量、随机抽查 3 张盘有数据
# 回滚：停新节点，DNS 切回旧 VIP；⚠️ 严禁新旧节点共写同一库

8. 日常运维与故障排查

sudo systemctl {start|stop|restart|status} grafana-server   # 服务管理
sudo journalctl -u grafana-server -f                         # 包安装日志
tail -f /var/log/grafana/grafana.log                         # 默认日志
docker logs -f grafana                                       # 容器日志
curl -s localhost:3000/api/health                            # 健康检查
du -sh /var/lib/grafana/                                     # 数据目录容量

9. 性能、容量与高可用

• 大盘：单盘 Panel 控在 20~30 个；用 maxDataPoints、$__rate_interval、采集间隔整数倍的 min interval；避免超大时间范围叠加高基数 label；开数据源 Query caching、降低刷新频率。
• 查询：PromQL 先聚合再展示；Loki 用 label match + line filter 收窄；SQL 数据源强制时间索引与 LIMIT。
• 数据库：SQLite 仅单实例/测试且有锁竞争；生产 PostgreSQL/MySQL，按并发调 database.max_open_conn / max_idle_conn；定期清理 annotation 与旧 dashboard_version。
• HA：多副本无状态 + 共享外置库 + 统一 secret_key；前置 LB 保持会话或用无状态认证；Unified Alerting 依赖库协调，务必同版本同配置。
• 自监控：[metrics] enabled = true 后用 Prometheus 抓 /metrics，导入官方 Grafana 内部大盘，关注 grafana_http_request_duration_seconds、grafana_alerting_*、DB 连接数。

10. 安全加固、备份与升级

• 认证鉴权：关 allow_sign_up；匿名仅给 Viewer；自动化用 Service Account Token 按 Folder 授权并定期轮换。
• LDAP/OAuth/OIDC：[auth.ldap] + config.toml 做组映射；[auth.generic_oauth] / [auth.azuread] / [auth.github] 接企业 SSO，root_url 与回调一致；[auth.proxy] 用于反代统一认证。
• TLS 与最小权限：反代终结 TLS，或 server.protocol=https + cert_file/cert_key；DB 账号仅授本库 DML；数据源用只读账号；cookie_secure=true、关闭未签名插件加载、disable_gravatar=true。
• 备份与恢复：

pg_dump -Fc -U grafana grafana > grafana_$(date +%F).dump
tar czf conf_$(date +%F).tgz /etc/grafana/ /var/lib/grafana/plugins/
curl -s -H "$H" "$GRAFANA_URL/api/dashboards/uid/<uid>" | jq .dashboard > backup/<名称>.json  # 单盘
# 恢复：停服 → pg_restore → 解压 conf → 启动 → /api/health + 大盘抽检
# ⚠️ 恢复覆盖目标库全部数据，先给目标库做快照

• 升级与回滚：先读官方 breaking changes，小版本内逐步升；备份库与 provisioning；apt upgrade grafana 或换镜像 tag → 重启 → 验证；回滚 =「恢复数据库快照 + 装回旧包」，⚠️ 已升级的库不能直接被旧版本打开。Legacy → Unified 告警迁移单向，回滚需升级前导出规则。

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选：已有 Prometheus/Loki/ES 等多套后端，需统一大盘、统一告警入口、GitOps 管配置，或要跨团队分租户展示。 何时不选：只需纯 Prometheus 告警且视图极简（Alertmanager 足够）；核心是日志全文检索/安全分析（Kibana 更贴合）；要零依赖开箱即用的采集+存储+告警全套（考虑 Zabbix 或一体化平台）。

14. 参考链接

• 官网下载：https://grafana.com/grafana/download
• 官方文档：https://grafana.com/docs/grafana/latest/
• GitHub：https://github.com/grafana/grafana
• Debian/Ubuntu 安装：https://grafana.com/docs/grafana/latest/setup-grafana/installation/debian/
• 配置参考：https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/
• Provisioning：https://grafana.com/docs/grafana/latest/administration/provisioning/
• HTTP API：https://grafana.com/docs/grafana/latest/developers/http_api/
• Alerting：https://grafana.com/docs/grafana/latest/alerting/
• Helm Charts：https://github.com/grafana/helm-charts
• 社区大盘库：https://grafana.com/grafana/dashboards/