Grafana 如何通过环境变量自动配置数据源

作者：袖梨 2026-08-24

环境变量不能直接创建数据源，仅能预填充provisioning YAML模板中的占位符；需结合provisioning配置、环境变量注入和初始化脚本实现自动配置。

Grafana 支持通过环境变量覆盖配置文件中的设置，数据源配置也不例外——但需注意：环境变量不能直接定义完整数据源（如 Prometheus 实例），而是用于预填充或辅助已有配置。真正实现“自动配置数据源”，需结合 Grafana 的 API 或初始化脚本。不过，环境变量在自动化流程中扮演关键角色，尤其在容器化部署（如 Docker、Kubernetes）中非常实用。

哪些数据源配置能用环境变量控制？

环境变量主要用于设置 Grafana 启动时的全局参数，影响数据源的连接行为，而非创建新数据源。常见可覆盖项包括：

  1. 数据源 URL：比如 Prometheus 地址，可通过 GF_DATASOURCES_PROMETHEUS_URL 设置（需配合插件或自定义配置模板）
  2. 认证信息：如 Basic Auth 用户名/密码，用 GF_DATASOURCES_PROMETHEUS_USER 和 GF_DATASOURCES_PROMETHEUS_PASSWORD
  3. 通用连接参数：例如超时时间、TLS 设置等，对应 GF_DATASOURCES_PROMETHEUS_HTTP_TIMEOUT、GF_DATASOURCES_PROMETHEUS_TLS_SKIP_VERIFY
  4. 数据源名称与类型标识：部分插件支持按命名约定注入，如 GF_DATASOURCES_MYDB_NAME=MyDB + GF_DATASOURCES_MYDB_TYPE=mysql（需 Grafana v9.5+ 及插件支持）

为什么不能只靠环境变量“创建”数据源？

Grafana 的数据源是运行时对象，存储在数据库（如 SQLite、PostgreSQL）中，环境变量本身不触发写入操作。最新明确说明：环境变量仅用于覆盖 grafana.ini 中的静态配置项，不用于动态注册数据源。也就是说：

  1. 你无法仅靠 export GF_DATASOURCES_PROMETHEUS_URL=http://prom:9090 就让 Grafana 自动添加一个 Prometheus 数据源
  2. 该变量只在 Grafana 启动时读取，且必须有配套的配置模板（如自定义 provisioning/datasources/ YAML 文件）才能生效
  3. 若未启用 provisioning，环境变量对数据源无实际作用

真正可行的自动配置方案（推荐组合）

要实现“启动即可用”的数据源自动配置，应采用 provisioning + 环境变量 + 初始化脚本 三者协同：

  1. 步骤一：启用 provisioning —— 在 custom.ini 或环境变量中开启：

    GF_PROVISIONING_PATH=/etc/grafana/provisioning

  2. 步骤二：编写 YAML 模板 —— 如 /etc/grafana/provisioning/datasources/prometheus.yaml，其中使用 ${ENV_VAR_NAME} 占位符：

    url: ${PROMETHEUS_URL:-http://localhost:9090}

  3. 步骤三：启动时注入环境变量 —— Docker 示例：

    docker run -e PROMETHEUS_URL=http://prom-prod:9090 grafana/grafana

  4. 步骤四（可选）：API 补充注册 —— 若需动态增删，用 Grafana API 调用 POST /api/datasources，配合脚本验证响应状态

常见避坑提醒

实际部署中容易踩的几个坑：

  1. 变量名大小写敏感，且必须带 GF_ 前缀；provisioning 中的占位符用 ${VAR}，不是 $VAR
  2. provisioning 文件加载顺序影响覆盖逻辑，建议把通用模板放 datasources/，环境专属放 datasources/env/
  3. 使用 GF_SECURITY_ADMIN_PASSWORD 等敏感变量时，避免日志泄露，建议配合 secret mount 或 vault 注入
  4. Kubernetes 中推荐用 envFrom: secretRef 加载凭证，而非明文 env: 定义

相关文章

精彩推荐