Grafana 安装与部署：容器化与配置即代码

安装与部署：容器化与配置即代码

Grafana 本体是一个无状态服务，唯一的持久化需求是它的 SQLite 数据库与插件目录。生产部署的关键不是把它跑起来，而是把它变成「配置即代码」——大盘和数据源都从文件加载，手工在界面上改的东西不作为事实来源。

1. 确认依赖：一个可用的容器运行时、一块持久化卷、一个可从 Grafana 访问到的数据源地址。Grafana 只发查询不存数据，所以网络连通性是前提。
2. 设置管理员口令：用环境变量 GF_SECURITY_ADMIN_PASSWORD 指定初始密码，不要用默认的 admin/admin。
3. 挂载持久化卷到 /var/lib/grafana，否则容器重建后所有大盘、用户、密钥都会丢。
4. 准备 provisioning 目录：provisioning/datasources/*.yaml 声明数据源，provisioning/dashboards/*.yaml 声明大盘从哪个目录加载。
5. 写 grafana.ini，至少配好 [server] 的 root_url、[database]、[auth.anonymous] 与 [smtp]。
6. 启动后用 docker compose logs -f grafana 确认无报错，再打开 Web 界面验证数据源「Save & Test」通过。

services:
  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD}
      # 反向代理下必须与实际访问地址一致，否则登录跳转会出错
      - GF_SERVER_ROOT_URL=https://grafana.example.com/
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_INSTALL_PLUGINS=grafana-clock-panel
    volumes:
      - ./grafana-data:/var/lib/grafana
      - ./provisioning:/etc/grafana/provisioning
      - ./grafana.ini:/etc/grafana/grafana.ini
    ports:
      - "3000:3000"

# grafana.ini 常用段落
[server]
domain = grafana.example.com
root_url = https://grafana.example.com/
# 反向代理在 Grafana 前面时，务必让代理透传这些头
# proxy_set_header Host $host;
# proxy_set_header X-Forwarded-Proto $scheme;

[database]
type = sqlite3
path = grafana.db
# 并发写入较多时建议换成 PostgreSQL，避免 SQLite 锁竞争
# type = postgres
# host = postgres.internal:5432
# name = grafana
# user = grafana
# password = ${DB_PASSWORD}

[auth.anonymous]
enabled = false
# 若要做大屏免登录展示，可设为 true 并配合 org_role = Viewer

[smtp]
enabled = true
host = smtp.example.com:587
user = alert@example.com
password = ${SMTP_PASSWORD}
from_address = alert@example.com
from_name = Grafana Alert

[alerting]
# 关闭旧的 dashboard 告警面板入口，统一走 Alert Rule
enabled = true

配置即代码：数据源与大盘

# provisioning/datasources/prometheus.yaml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus.internal:9090
    isDefault: true
    jsonData:
      # 与 Prometheus 的 scrape_interval 保持一致，避免查询步长过密
      timeInterval: 15s
      httpMethod: POST

# provisioning/dashboards/default.yaml
apiVersion: 1
providers:
  - name: 'business-dashboards'
    orgId: 1
    folder: '业务大盘'
    type: file
    disableDeletion: false
    # 每 30 秒扫描一次目录，文件改动后自动生效
    updateIntervalSeconds: 30
    allowUiUpdates: true
    options:
      path: /etc/grafana/provisioning/dashboards/json

常见报错与处理