本篇目录7 节

03配置与安全Configure

环境变量覆盖配置

GF_ 前缀的环境变量可以覆盖 grafana.ini 里的任何配置项。本文讲清命名规则，以及在 Docker、Compose 与 systemd 三种环境中的设置方法，附常用变量速查表。

约 2 分钟/537 字/GRAFANA 12.X

命名规则：一句话讲完

把配置文件里的「段名 + 项名」都转成大写，用下划线连接，再加 GF_ 前缀：

GF_<段名>_<配置项>
配置文件写法 对应环境变量
[server] http_port = 3000 GF_SERVER_HTTP_PORT=3000
[security] admin_password = ... GF_SECURITY_ADMIN_PASSWORD=...
[users] allow_sign_up = false GF_USERS_ALLOW_SIGN_UP=false
[auth.anonymous] enabled = false GF_AUTH_ANONYMOUS_ENABLED=false
[log] level = debug GF_LOG_LEVEL=debug

优先级：环境变量 > 配置文件 > 内置默认值。这让你可以保持镜像或安装包原封不动，只用环境变量交付差异配置。

在 Docker 里设置

docker run -d --name grafana -p 3000:3000 \
  -e "GF_SERVER_ROOT_URL=https://grafana.example.com/" \
  -e "GF_USERS_ALLOW_SIGN_UP=false" \
  -e "GF_LOG_LEVEL=info" \
  grafana/grafana-oss:12.1.0

在 Compose 里设置

services:
  grafana:
    image: grafana/grafana-oss:12.1.0
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    environment:
      GF_SERVER_ROOT_URL: "https://grafana.example.com/"
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD}

最后一个写法把密码留在 .env 文件里而不是 compose 文件里，记得把 .env 加进 .gitignore。

注意： 镜像内置了一组默认环境变量（如 GF_PATHS_DATA、GF_PATHS_CONFIG），它们定义了数据与配置的路径，覆盖前先用 docker exec grafana env | sort 看清现状，别把容器指到空目录上。

在 systemd 里设置

包安装形态推荐用 override 文件注入，不直接改 unit：

sudo systemctl edit grafana-server
# 编辑器里写入:
# [Service]
# Environment="GF_LOG_LEVEL=warn"
sudo systemctl daemon-reload
sudo systemctl restart grafana-server

部分发行版的包还提供了一个默认环境变量文件（Debian 系常见于 /etc/default/grafana-server），是否可用以你的安装为准；override 方式是通用的。

常用变量速查

环境变量 作用 备注
GF_SERVER_HTTP_PORT 监听端口 改容器映射时两边要一致
GF_SERVER_ROOT_URL 站点根地址 反代 / Ingress 场景必设
GF_SECURITY_ADMIN_USER 初始管理员用户名 仅首次初始化生效
GF_SECURITY_ADMIN_PASSWORD 初始管理员密码 仅首次初始化生效
GF_SECURITY_SECRET_KEY 登录签名密钥 部署时设置一次，此后别乱换
GF_USERS_ALLOW_SIGN_UP 自助注册开关 生产一般 false
GF_AUTH_ANONYMOUS_ENABLED 匿名访问开关 生产应为 false
GF_LOG_LEVEL / GF_LOG_MODE 日志级别 / 输出方式 见日志、诊断与服务器管理
GF_DATABASE_TYPE 数据库类型 sqlite3 / mysql / postgres
GF_DATABASE_URL 数据库连接串 敏感信息用 Secret 注入

常见坑

  • 拼错变量名不报错：Grafana 不认识的环境变量会被安静忽略，配置没生效先逐字符核对。
  • 布尔值写成 0 / 1：请老老实实写 true / false。
  • 换 GF_SECURITY_SECRET_KEY 的后果：已加密存储的 OAuth 会话与部分凭据会失效，只在首次部署时设定。
  • 以为环境变量能改老库密码：GF_SECURITY_ADMIN_* 只在初始化建库时起作用，之后用界面或 CLI 重置。

下一步

本页为学习整理的中文改写,依据Grafana 官方文档最新版本编写(以 Grafana 12.x 为基准),操作路径请以实际产品界面为准。

Configure