3. Grafana配置

本章节将介绍如何连接到不同的数据源（如 Prometheus、Graphite、InfluxDB 等），以及如何管理用户、团队和组织。在此之前，理解和掌握 Grafana 的配置文件是至关重要的一步。

3.1 Grafana 的配置文件

Grafana 的所有核心配置都通过一个 .ini 格式的文件进行管理。

• defaults.ini: 这是 Grafana 的默认配置文件，包含了所有的默认设置。不应该直接修改这个文件，因为它会在 Grafana 升级时被覆盖。
• grafana.ini: 这是您的自定义配置文件。您可以在此文件中覆盖 defaults.ini 中的任何设置。所有的自定义配置都应该在这里进行。

配置文件位置

• Linux: /etc/grafana/grafana.ini
• Windows: C:\Program Files\GrafanaLabs\grafana\conf\grafana.ini
• Docker: 当使用 Docker 部署时，通常会将配置文件挂载到容器的 /etc/grafana/ 目录。

---

3.2 grafana.ini 的关键部分

重要提示： 在 grafana.ini 文件中，大部分配置项默认都是被分号 (;) 注释掉的。要使某项配置生效，您必须删除行首的分号。

以下是 grafana.ini 文件中一些最重要和常用的配置块。

[server]

控制与 Grafana 服务器相关的设置。

# Grafana 监听的 HTTP 端口
http_port = 3000

# Grafana 实例的域名
domain = grafana.example.com

# 对外访问的完整根 URL，用于生成链接
root_url = %(protocol)s://%(domain)s:%(http_port)s/

[database]

定义 Grafana 用于存储仪表板、用户和配置的数据库。

# 数据库类型: sqlite3, mysql, postgres
type = mysql

# 数据库主机和端口
host = 127.0.0.1:3306

# 数据库名称
name = grafana

# 数据库用户
user = grafana

# 数据库密码
password = mysecurepassword

[security]

控制 Grafana 的核心安全策略。这是最重要的配置块之一。

核心安全设置 (必须配置)

# 默认管理员用户名。
# 强烈建议在首次启动后，通过UI或API创建一个新的管理员账户，并禁用或删除默认admin。
admin_user = admin

# 默认管理员密码。
# 必须在首次启动前修改，或在首次登录后立即修改为一个强密码。
# 环境变量: GF_SECURITY_ADMIN_PASSWORD
admin_password = YourStrongPassword

# 用于会话签名和加密数据源密码等的密钥。
# 极其重要！必须修改为一个长而随机的字符串。否则Grafana会警告并存在安全风险。
# 环境变量: GF_SECURITY_SECRET_KEY
secret_key = a_very_long_and_random_string_generated_by_you

浏览器与网络安全

# 如果您通过 HTTPS 代理访问 Grafana，必须设置为 true。
# 这会为登录 Cookie 设置 Secure 属性，确保其仅通过加密连接传输。
# 环境变量: GF_SERVER_COOKIE_SECURE
cookie_secure = false

# 设置 Cookie 的 SameSite 属性。默认为 'lax'，有助于防止 CSRF 攻击。
# 可选值为 "lax", "strict", "none"。
cookie_samesite = lax

# 是否允许在 <iframe> 中嵌入 Grafana。
# 如果您需要将 Grafana 面板嵌入到其他网站，必须设置为 true。
# 环境变量: GF_SECURITY_ALLOW_EMBEDDING
allow_embedding = false

登录与用户安全

# 是否禁用防止暴力破解登录的保护。
# 强烈建议保持为 false (即启用保护)。
disable_brute_force_login_protection = false

# 在用户账户被锁定前，允许的最大失败登录尝试次数。
brute_force_login_protection_max_attempts = 5

# 禁用 Gravatar 头像服务，以增强隐私，避免向外部服务发送请求。
disable_gravatar = false

[users]

管理用户相关的设置，如注册、默认权限和UI体验。

用户注册与权限 (核心)

# 是否允许用户自行注册。
# 在生产环境中，强烈建议设置为 false，由管理员统一创建账户。
# 环境变量: GF_USERS_ALLOW_SIGN_UP
allow_sign_up = false

# 如果允许注册，是否需要通过邮件验证才能完成注册。
verify_email_enabled = false

# 是否在用户注册后自动将其分配给主组织 (ID 1)。
auto_assign_org = true

# 新用户的默认角色。'Viewer' (观察者) 是最安全的默认设置。
# 可选值: 'Viewer', 'Editor', 'Admin'
# 环境变量: GF_USERS_AUTO_ASSIGN_ORG_ROLE
auto_assign_org_role = Viewer

用户默认体验

# 新用户或未登录用户的默认UI主题。
# 可选值: "dark", "light", "system"
# 环境变量: GF_USERS_DEFAULT_THEME
default_theme = dark

# 默认UI语言。使用标准的IETF语言标签，如 en-US, zh-Hans。
default_language = zh-Hans

# 自定义用户的默认主页路径。
# 用户登录后将被重定向到此路径，例如 '/dashboards'。
home_page =

其他设置

# 是否允许非管理员用户创建新的组织。
# 在多租户场景下可能有用，通常保持为 false。
allow_org_create = false

# 用户邀请链接的有效时长。
# 示例: 6h (小时), 2d (天), 1w (周)。默认为 24h。
user_invite_max_lifetime_duration = 24h

[auth]

这个配置块控制着用户的登录会话、生命周期以及与不同认证方式的集成。

# 登录cookie的名称。
login_cookie_name = grafana_session

# 一个用户在不活动状态下可以保持登录的最长时长。
# 超过这个时间后，下次访问需要重新登录。默认为 7 天。
# 示例: 5m, 6h, 10d, 2w, 1M。
login_maximum_inactive_lifetime_duration = 7d

# 一个用户从首次登录开始可以保持登录的总最长时长。
# 默认为 30 天。到达这个期限后，即使用户一直活跃也需要重新登录。
login_maximum_lifetime_duration = 30d

# 当用户活跃时，其认证 token 的轮换周期（分钟）。
# 默认为 10 分钟。
token_rotation_interval_minutes = 10

# 是否禁用 Grafana 自己的登录表单。
# 当您只希望通过第三方 OAuth (如 Google, GitHub) 登录时，可以设置为 true。
disable_login_form = false

# 是否在左侧菜单中隐藏"Sign out"链接。
# 当使用反向代理进行身份验证时很有用。
disable_signout_menu = false

# 用户登出后重定向到的 URL。
signout_redirect_url =

# API Key 的最长有效期（秒）。
# 默认为 -1，表示永不过期。
api_key_max_seconds_to_live = -1

[auth.generic_oauth]

配置通用的 OAuth2 身份验证。

enabled = true
name = MyOAuth
allow_sign_up = true
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET
scopes = openid email profile
auth_url = https://my-oauth-provider.com/authorize
token_url = https://my-oauth-provider.com/token
api_url = https://my-oauth-provider.com/userinfo

[smtp]

配置邮件服务器，用于发送告警通知和邀请。

enabled = true
host = smtp.example.com:587
user = [email protected]
password = "your-email-password"

[alerting]

配置内置的告警引擎。

# 是否启用告警功能
enabled = true

# 是否允许 Grafana 执行告警规则查询
execute_alerts = true

[log]

配置 Grafana 的日志记录行为。

# 日志级别: debug, info, warn, error, critical
level = info

# 日志模式: console, file
mode = console

[auth.anonymous]

这是实现**免登录访问（匿名访问）**的关键配置，非常适合用于创建公共展示仪表板。

# 启用或禁用匿名访问
enabled = true

# 为匿名用户指定一个组织。你需要先在 Grafana UI 中创建这个组织
# 并且把需要公开的仪表板放在这个组织下。
org_name = Public

# 为匿名用户分配角色。'Viewer' (观察者) 是最安全、最常用的选择。
org_role = Viewer

3.3 其他常用配置块

以下是一些在特定场景下也非常有用的配置块。

[plugins]

控制插件的管理。

# 是否允许加载未签名的插件
# 警告：这可能带来安全风险，请确保您信任插件的来源
allow_loading_unsigned_plugins = false

[analytics]

控制 Grafana 的使用情况报告。

# 向 stats.grafana.org 报告匿名使用数据
# 在生产环境中或出于隐私考虑，通常会禁用此项
reporting_enabled = false

[dataproxy]

配置数据源代理的超时设置。

# 数据源请求的超时时间
timeout = 30

[feature_toggles]

用于启用或禁用实验性或即将推出的功能。

# 启用一个名为 newFeature 的特性
enable = newFeature1 newFeature2

---

3.4 使用环境变量进行配置

在容器化部署（如 Docker 或 Kubernetes）中，通过环境变量来管理配置是最佳实践。Grafana 支持使用以 GF_ 开头的环境变量来覆盖 grafana.ini 中的任何设置。

转换规则: 将配置块名称和键名组合起来，全部大写，并用下划线连接。 [section_name] -> key 变为 GF_SECTION_NAME_KEY

示例:

• 设置管理员密码:
  • ini 中是 [security] 下的 admin_password
  • 环境变量是 GF_SECURITY_ADMIN_PASSWORD=your_strong_password
• 启用匿名访问:
  • ini 中是 [auth.anonymous] 下的 enabled
  • 环境变量是 GF_AUTH_ANONYMOUS_ENABLED=true
• 设置匿名访问的角色:
  • ini 中是 [auth.anonymous] 下的 org_role
  • 环境变量是 GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer

这种方式无需修改配置文件，使得部署和自动化更加灵活。

3.5 应用配置更改

修改 grafana.ini 或更改环境变量后，您需要重启 Grafana 服务才能使新的配置生效。

# 配置文件生效路径
[root@grafana grafana]# docker exec grafana env | grep GF_
GF_PATHS_CONFIG=/etc/grafana/grafana.ini
GF_PATHS_DATA=/var/lib/grafana
GF_PATHS_HOME=/usr/share/grafana
GF_PATHS_LOGS=/var/log/grafana
GF_PATHS_PLUGINS=/var/lib/grafana/plugins
GF_PATHS_PROVISIONING=/etc/grafana/provisioning


# 使用 systemd 重启 Grafana 服务
sudo systemctl restart grafana-server

# 检查服务状态
sudo systemctl status grafana-server

如果使用 Docker，您需要重启容器：

docker restart grafana