Grafana 服务器的行为由一个 INI 文件以及覆盖它的环境变量控制。了解这些规则,就可以把整个配置保存在仓库中,而无需手动改动任何东西。本指南涵盖文件的位置、优先级如何运作、如何注入值和密钥,以及你最常接触的设置。

配置位于何处

• defaults.ini 随 Grafana 发布,包含所有默认值(tarball 安装时位于 conf/)。切勿编辑它。它是了解有哪些选项的最佳参考。
• grafana.ini 是你的配置文件。在 Linux 软件包中是 /etc/grafana/grafana.ini,官方 Docker 镜像读取同一路径。对于 tarball 安装,使用 conf/custom.ini。传入 --config 可指向其他文件。
• 以 GF_ 开头的环境变量会同时覆盖这两者。

优先级由低到高:defaults.ini,然后是你的 grafana.ini,再是 GF_* 环境变量(以及命令行参数)。只把你想更改的选项放进你的文件,这样 diff 会保持很小。

在 INI 文件中,以 ; 开头的行是注释,所以要启用某个选项,请去掉开头的 ;:

;http_port = 3000   # ignored
http_port = 3000    # active

更改文件或环境之后,需要重启 Grafana。

环境变量覆盖

模式是 GF_<SECTION>_<KEY>,其中 section 和 key 为大写,任何 . 或 - 都替换为 _:

GF_SECURITY_ADMIN_USER=owner          # [security] admin_user
GF_SERVER_ROOT_URL=https://grafana.example.com   # [server] root_url
GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey        # [auth.google] client_secret
GF_FEATURE_TOGGLES_newNavigation=true            # [feature_toggles] newNavigation
GF_DEFAULT_INSTANCE_NAME=my-instance             # top-level instance_name, no section

环境变量天然适合容器和 Kubernetes,因为同一份文件可以被每个环境共享,而特定于环境的值(URL、密码)则来自平台。

文件内的变量展开

选项值可以使用 $__env{} 和 $__file{} 提供器,或 ${NAME} 简写,来引用环境变量或文件:

[paths]
logs = $__env{LOGDIR}/grafana

[security]
admin_password = ${GF_ADMIN_PASSWORD}
secret_key = $__file{/run/secrets/grafana_secret_key}

[database]
password = $__file{/etc/secrets/gf_sql_password}

$__file{} 读取文件并去除首尾空白,这使它很适合以文件形式挂载的 Docker 和 Kubernetes secret。Grafana Enterprise 还有一个 $__vault{} 提供器。官方 Docker 镜像还接受在变量名后加 __FILE 后缀(例如 GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password),这在密钥指南中有介绍。

一个实用的基线

适用于小型类生产环境的简短 grafana.ini:

[paths]
provisioning = /etc/grafana/provisioning

[server]
protocol = http
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
; add the sub path to root_url and enable this when served from /grafana
; serve_from_sub_path = true

[database]
type = postgres
host = postgres:5432
name = grafana
user = grafana
password = $__file{/run/secrets/grafana_db_password}

[security]
admin_user = admin
admin_password = $__file{/run/secrets/grafana_admin_password}
secret_key = $__file{/run/secrets/grafana_secret_key}
cookie_secure = true

[users]
allow_sign_up = false

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

值得了解的几点:

• 数据库。 默认是 SQLite,适合单实例和测试。生产环境请使用 PostgreSQL 或 MySQL,并且超过一个 Grafana 副本时必须使用。
• root_url 必须与公开地址一致,否则告警通知中的链接和 OAuth 重定向会出错。如果反向代理将 Grafana 放在子路径下,请把该子路径加到 root_url,并设置 serve_from_sub_path = true。
• admin_password 只在 Grafana 首次创建数据库时应用。之后更改该设置不会改变现有管理员用户的密码。
• secret_key 用于加密为数据源存储的密钥。如果你更改它,之前存储的密钥就无法读取,数据源必须重新 provision。请显式设置它,并且不要随意轮换。
• [paths] provisioning 是 Grafana 查找 provisioning 文件夹的位置。软件包上的默认值是 /etc/grafana/provisioning。

用于邮件告警的 SMTP

[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = $__file{/run/secrets/smtp_password}
from_address = grafana@example.com
from_name = Grafana
startTLS_policy = OpportunisticStartTLS

或者使用同样效果的 GF_SMTP_ENABLED=true、GF_SMTP_HOST=... 等。请对照你所用版本的 defaults.ini 验证选项名称。

功能开关

实验性的或需要主动选择的功能,在一个专门的配置段中开启:

[feature_toggles]
; list the toggles you want, as documented for your version
newNavigation = true

优先使用文件或环境变量,而不是 UI,这样设置能在重建后保留下来。开关会随版本更替而增减,所以每次升级时都要复查。

验证并检查实际生效的配置

启动 Grafana 之后,你可以将你设置的内容与实际生效的内容比较:

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/admin/settings | jq '.server'

这个管理端点返回合并后的设置,敏感键的值会被屏蔽。它是确认某个环境变量是否真正生效的最快方式。如果没有生效,请检查变量的拼写(大写、下划线),以及该选项是否存在于 defaults.ini 中。

保存在 Git 中

• 提交 grafana.ini 和一个带占位值的 .env.example。
• 真正的 secret 不要放进仓库:以文件形式挂载、以环境变量形式注入,或加密后提交(参见密钥指南)。
• 升级 Grafana 时,复查 defaults.ini 的变化。新版本会增加选项,有时也会弃用旧选项。