Grafana Grafana

使用 Docker Compose 和 Provisioning 文件夹运行 Grafana

从 compose 文件启动 Grafana,所有配置都以文件形式挂载。

10 min 初级

本指南使用 Docker Compose 在本地运行 Grafana 和一个 Prometheus 数据源,所有设置都通过文件和环境变量提供。你永远不需要打开 UI 来配置任何东西。你需要安装了 Compose 插件的 Docker。

规划项目布局

grafana-as-code/
├── compose.yaml
├── .env                          # secrets and versions, not committed
├── grafana/
│   ├── grafana.ini
│   └── provisioning/
│       ├── datasources/
│       │   └── prometheus.yaml
│       ├── dashboards/
│       │   └── providers.yaml
│       ├── alerting/             # added in the alerting guide
│       └── plugins/
├── dashboards/
│   └── overview.json
└── prometheus/
    └── prometheus.yml

把它保存在 Git 中。将 .env 加入 .gitignore,并改为提交一个 .env.example。

compose 文件

compose.yaml:

services:
  grafana:
    image: grafana/grafana:13.1.0   # pin a version you have tested
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD}
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - ./grafana/grafana.ini:/etc/grafana/grafana.ini:ro
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
      - ./dashboards:/var/lib/grafana/dashboards:ro
      - grafana-data:/var/lib/grafana
    depends_on:
      - prometheus

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro

volumes:
  grafana-data:

重要的挂载:

  • /etc/grafana/grafana.ini 是官方镜像内的服务器配置文件。
  • /etc/grafana/provisioning 是 Grafana 查找 datasources、dashboards、alerting 和 plugins 文件夹的地方。
  • /var/lib/grafana/dashboards 是用于放置仪表板 JSON 的任意文件夹。该路径必须与你在下面的仪表板 provider 中设置的一致。
  • grafana-data 是一个具名卷,用于存放 Grafana 的 SQLite 数据库和插件。没有它,容器被重新创建时状态会丢失。

这些配置挂载被有意设为只读:Grafana 不需要写入它们。

.env:

GRAFANA_ADMIN_PASSWORD=change-me-before-sharing

请注意,GF_SECURITY_ADMIN_PASSWORD 只在 Grafana 首次创建其数据库时应用。之后在 compose 文件中更改它,对已有的卷没有影响。删除该卷以重新开始,或使用 CLI 重置密码。

一个最小的 grafana.ini

[server]
http_port = 3000

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

[auth]
disable_login_form = false

任何你省略的内容都会回退到 Grafana 的默认值。下一篇指南涵盖 grafana.ini 和 GF_* 覆盖的完整规则。

Provision 数据源

grafana/provisioning/datasources/prometheus.yaml:

apiVersion: 1

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

uid 是仪表板和告警规则应当引用的标识,所以请选择一个稳定的。后面的指南会解释每个字段。

Provision 仪表板 provider 和一个仪表板

grafana/provisioning/dashboards/providers.yaml:

apiVersion: 1

providers:
  - name: default
    type: file
    updateIntervalSeconds: 30
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards

dashboards/overview.json(一个最小的仪表板;详情参见仪表板指南):

{
  "uid": "overview",
  "title": "Overview",
  "schemaVersion": 39,
  "panels": [
    {
      "id": 1,
      "type": "timeseries",
      "title": "Targets up",
      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
      "datasource": { "type": "prometheus", "uid": "prometheus" },
      "targets": [
        { "refId": "A", "expr": "up", "datasource": { "type": "prometheus", "uid": "prometheus" } }
      ]
    }
  ]
}

再加上一个小小的 prometheus/prometheus.yml,这样就有数据可展示:

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

启动并在不使用 UI 的情况下检查

docker compose up -d
docker compose logs grafana | grep -i provisioning
curl -s http://localhost:3000/api/health
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/datasources | jq '.[].name'
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD "http://localhost:3000/api/search?type=dash-db" | jq '.[].title'

健康端点应当报告 ok,数据源列表应当包含 Prometheus,搜索应当返回 Overview。如果你想看看结果,可以打开 http://localhost:3000,但要走到这一步,并没有点击任何东西。

修改某些内容并观察它的应用

  • 编辑 dashboards/overview.json。在 updateIntervalSeconds 之内,Grafana 无需重启即可拾取变更。
  • 编辑数据源文件并重启:docker compose restart grafana。数据源在启动时读取。
  • 删除一个仪表板文件。除非 provider 设置了 disableDeletion: true,否则该仪表板会被移除。

通过配置安装插件

插件可以在容器启动时通过环境变量安装,这样它们就保留在 compose 文件中:

    environment:
      GF_PLUGINS_PREINSTALL: grafana-clock-panel

较旧的版本改用 GF_INSTALL_PLUGINS。请查阅你所用版本的文档,并注意 provisioning 只会配置已安装的插件。

清理

docker compose down        # keep the data volume
docker compose down -v     # also delete Grafana's database

热门指南