Grafana 配置参数详解

目标：详解 Grafana 13.2.3 的配置体系，从默认配置文件入手剖析 server、database、security、auth、log、metrics 等核心段落，并给出生产实践配置模板，已在 Ubuntu 22.04 部署实例上实测对照默认值与生效方式。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Grafana 版本：13.2.3
主配置文件：/etc/grafana/grafana.ini（deb 包安装）
默认配置：/usr/share/grafana/conf/defaults.ini（2669 行，安装自带，勿改）
数据目录：/var/lib/grafana

二、前置条件

已安装 Grafana（见《Ubuntu 22.04 安装 Grafana 指南》）
了解 Grafana 配置分层：defaults.ini（出厂默认）→ grafana.ini（用户覆盖）→ 环境变量 GF_*

三、参数查看与修改方式

3.1 查看生效配置（已加载值）

grafana server --help                       # 查看 server 子命令与配置选项
grep -nE "^\[" /etc/grafana/grafana.ini     # 列出所有配置段

▶️ 实测回显（部分段）：
13:[paths]
40:[server]
136:[database]
369:[security]
1184:[log]

3.2 标准修改流程

# 编辑用户配置文件（不存在则从 sample 复制）
cp /usr/share/grafana/conf/sample.ini /etc/grafana/grafana.ini
vim /etc/grafana/grafana.ini

# 修改后重启
systemctl restart grafana-server
# 无 systemd 时
pkill -f grafana-server
nohup /usr/sbin/grafana-server server --config=/etc/grafana/grafana.ini --homepath=/usr/share/grafana --packaging=deb >/var/log/grafana/server.log 2>&1 &

3.3 环境变量覆盖（优先级更高，Docker 友好）

规则：GF_ + 大写的配置段 + _ + 大写的键。例：[server].http_port → GF_SERVER_HTTP_PORT=3000。

💡 配置最终生效值优先级：GF_* 环境变量 > grafana.ini 用户配置文件 > defaults.ini 出厂默认。

四、参数总览

配置段	作用	常见键
`[paths]`	数据/日志/插件路径	data、logs、plugins
`[server]`	HTTP/HTTPS 监听与对外地址	http_addr、http_port、domain、root_url
`[database]`	元数据库（sqlite/mysql/postgres）	type、host、name、user、password、path
`[security]`	管理员账号、密钥、登录防护	admin_user、admin_password、secret_key、cookie_secure
`[auth.anonymous]`	匿名访问	enabled、org_role
`[auth.github]` 等	外部认证（GitHub/OAuth/LDAP）	enabled、client_id、client_secret
`[log]`	日志级别与输出	mode、level、filters
`[metrics]`	内部指标暴露	enabled、interval_seconds、basic_auth_username
`[smtp]`	邮件告警	host、user、password、from
`[dashboards]`	看板行为	default_home_dashboard_path、versions_to_keep

五、[server] 服务器段

参数	默认值	说明
`protocol`	`http`	http / https / h2 / socket
`http_addr`	空	绑定地址，空 = 所有网卡
`http_port`	`3000`	HTTP 监听端口
`domain`	`localhost`	对外域名
`enforce_domain`	`false`	host 头校验，防 DNS rebinding
`root_url`	`%(protocol)s://%(domain)s:%(http_port)s/`	对外完整 URL
`enable_gzip`	`true`	开启 gzip
`read_timeout`	`0`	读请求超时（分钟），0 = 不超时
`cert_file`/`cert_key`	空	HTTPS 证书/私钥路径

💡 反向代理（Nginx/Traefik）环境下务必同步设置 root_url 与实际代理协议（https），避免重定向与回调 URL 出错。

六、[database] 元数据库段

Grafana 元数据默认存内嵌 sqlite。

参数	默认值	说明
`type`	`sqlite3`	mysql / postgres / sqlite3
`host`	`127.0.0.1:3306`	外部库地址
`name`	`grafana`	库名
`user` / `password`	`root` / 空	账号密码
`url`	空	连接串（优先级高于分散配置）
`path`	`grafana.db`	sqlite 文件路径（相对 data 目录）
`ssl_mode`	`disable`	postgres 用 require；mysql 用 true/false
`wal`	`false`	sqlite WAL 模式（建议开启减压锁冲突）

▶️ 实测：高可用（多实例）必须切换为 MySQL/PostgreSQL 共享元库，并保持 high_availability = true（默认 true）。详见《Grafana 高可用/多实例部署专项篇》。

七、[security] 安全段

参数	默认值	说明
`admin_user`	`admin`	初始管理员用户名
`admin_password`	`admin`	初始管理员密码（首次启动创建）
`admin_email`	`admin@localhost`	管理员邮箱
`disable_initial_admin_creation`	`false`	禁用首次自动创建管理员
`secret_key`	`SW2YcwT...`（出厂）	签名密钥，生产必须改
`cookie_secure`	`false`	HTTPS 环境下应置 true
`cookie_samesite`	`lax`	lax / strict / none
`allow_embedding`	`false`	是否允许 iframe 嵌入
`brute_force_login_protection_max_attempts`	`5`	登录失败锁定阈值

⚠️ 生产环境必须修改 secret_key、admin_password，否则存在会话伪造与弱口令风险。

八、[auth.anonymous] 匿名访问

参数	默认值	说明
`enabled`	`false`	是否允许匿名访问
`org_name`	`Main Org.`	匿名所属组织
`org_role`	`Viewer`	匿名角色（Viewer 只读）
`hide_version`	`false`	对匿名隐藏版本号

九、[log] 日志段

参数	默认值	说明
`mode`	`console file`	输出方式（console/file/syslog，空格分隔）
`level`	`info`	debug/info/warn/error
`filters`	空	指定 logger 级别，如 `sqlstore:debug`
`[log.file].format`	`text`	文件日志格式
`[log.file].log_rotate`	`true`	是否轮转
`[log.console].format`	`console`	控制台格式

▶️ 实测启动日志即采用该体系，格式示例：logger=settings t=...Z level=info msg="Starting Grafana" version=13.2.3。

十、[metrics] 指标段

Grafana 把自身内部 metrics 暴露到 /metrics，可被 Prometheus 抓取。

参数	默认值	说明
`enabled`	`true`	是否暴露指标
`interval_seconds`	`10`	内部采集间隔
`disable_total_stats`	`false`	是否禁用总量统计
`classic_http_histogram_enabled`	`true`	HTTP 直方图格式
`basic_auth_username`/`basic_auth_password`	空	`/metrics` 访问认证

十一、生产配置模板

适用场景：16GB 内存、SSD、单/双实例、承载 200+ 看板、日志级别控制在 info、Nginx 反代：

[server]
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
enable_gzip = true
read_timeout = 60

[database]
type = postgres
host = 10.0.0.20:5432
name = grafana
user = grafana
password = ${GF_DB_PASSWORD}
ssl_mode = require

[security]
admin_user = admin
admin_password = q1w2e3r4
secret_key = ${GF_SECURITY_SECRET_KEY}
cookie_secure = true

[log]
mode = console file
level = info
[log.file]
log_rotate = true

[metrics]
enabled = true
interval_seconds = 10

[auth.anonymous]
enabled = false

⚠️ 敏感密钥（password/secret_key）在生产用 ${VAR} 占位并通过环境变量注入，命令演示账号除外。

十二、常见问题

Q1：为什么改了 grafana.ini 没生效？ 检查是否同时存在 GF_* 环境变量（优先级更高）；确认重启了服务。

Q2：sqlite 在高并发下锁冲突？

开启 wal = true；
或将元库迁移到 MySQL/PostgreSQL。

Q3：外网 HTTPS 访问看板跳转成 http？ [server] 段 root_url 需设置为 https://域名/，若走 Nginx 反代还需同步 protocol。

十三、参考链接

Grafana 配置参考：https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/
Grafana 默认配置文档：https://grafana.com/docs/grafana/latest/setup-grafana/configuration/