日志、诊断与服务器管理

配置 [log] 段

日志行为由配置文件里的 [log] 及其子段控制：

[log]
mode = file
level = info

[log.file]
file_name = grafana.log
max_days = 30
log_rotate = true

[log.console]
level = warn

• mode 可取 console、file、null，也可组合（逗号分隔多个）；容器形态一般保持 console，让 docker logs 接管。
• level 从 debug、info、warn、error 中选；排查询问题临时调 debug，查完调回。
• 子段可以对不同输出通道设置不同级别，例如文件记 debug、控制台只留 warn。
• 一切都可以用环境变量覆盖，如 GF_LOG_LEVEL=debug，见环境变量覆盖配置。

各形态的日志位置

日志里最有价值的关键词：error、failed、migration（升级迁移）、permission denied（权限）。

健康检查：/api/health

curl -s http://localhost:3000/api/health

典型返回：

{
  "database": true,
  "version": "12.1.0",
  "commit": "a1b2c3d4"
}

database 为 true 表示元数据库连通。这个端点无需认证即可探测基本存活状态，但会暴露版本号，对外部访问的处理建议见生产环境安全加固。Kubernetes 的存活/就绪探针与负载均衡的健康检查，都可以直接指向它，见Kubernetes 与 Helm 部署。

提示： 健康检查失败时先分清两类问题：进程在但 database 为 false，查数据库连接与凭据；整个端点无响应，查进程是否存活、端口是否被占。

前端资源诊断

界面白屏、图表画不出来，多半是静态资源没加载上：

1. 浏览器开发者工具 Network 面板过滤 JS/CSS，看 404 或跨域报错。
2. 404 的 URL 前缀不对——十有八九是 root_url 与反代路径不一致；部署在子路径下还要设 serve_from_sub_path = true。
3. 刚升级完出现的怪现象，先强制刷新（忽略缓存）再下结论。
4. 数据源查询失败与前端无关，直接看 Grafana 日志里的请求错误。

维护窗口怎么做

Grafana 没有内置「维护模式」开关，通行的做法是：停服务，在反向代理上挂一个静态维护页返回 503；多实例则逐个滚动重启，对外域名不受影响。维护前后的备份与验证流程，见升级与回滚。

图像渲染服务简述

仪表盘快照、告警通知里的图片、分享时的 PDF 导出，都依赖独立的渲染服务（一个无头浏览器）：

docker run -d --name grafana-image-renderer \
  -p 8081:8000 grafana/grafana-image-renderer

然后在配置里指过去：

[rendering]
server_url = http://localhost:8081/render

没有渲染服务时告警图片与 PDF 功能会降级，现象是提示渲染器不可用。

常见坑

• debug 忘关：高流量实例的 debug 日志能很快写满磁盘，记得配 max_days 轮转或接日志采集。
• 容器里「没有日志文件」：默认 mode = console 本就不落盘，这是设计而非故障。
• 只看界面报错不看日志：绝大多数数据源与权限问题的完整原因都写在服务端日志里。

下一步

• 更深层的排障手册：故障排查手册。
• 配置体系入口：配置文件 grafana.ini。
• 例行升级与备份：升级与回滚。