怎么用这份手册
每个问题三段落：症状帮你确认「是不是它」，定位给出最短排查路径，解法按命中率排序。日志是第一现场：
# 安装包部署：日志在数据目录
tail -f /var/log/grafana/grafana.log
# Docker / Kubernetes
docker logs -f grafana
kubectl logs deploy/grafana -n monitoring一、启动失败
- 症状：服务起不来，或起来后端口无响应、systemd 反复重启。
- 定位：看日志开头几行——
address already in use是端口冲突；permission denied是数据目录属主不对；can't parse config file是 ini 写坏了。 - 解法：
ss -lntp | grep 3000找到占用进程并处理；数据目录chown -R grafana:grafana /var/lib/grafana；用grafana server -config ... -configOverrides homepath=/usr/share/grafana手工前台启动，报错一目了然。改配置前先跑grep -v '^#'目测语法，配置文件详解见grafana.ini。
二、白屏 / 静态资源 404
- 症状：浏览器只有空白页或裸文字，开发者工具 Network 里大量
public/build/...404。 - 定位：404 的资源 URL 前缀是否与你访问的地址一致？典型诱因是
[server] root_url与实际访问路径不匹配（如挂在/grafana/子路径反代后），或[paths] static_root_path指错。 - 解法：
root_url改成含协议、域名与子路径的完整前缀（如https://obs.example.com/grafana/）并同步反代配置；确认static_root_path指向安装自带的public目录。改完重启验证。
三、数据源连不通
- 症状：Save & test 报
context deadline exceeded、connection refused或 4xx/5xx。 - 定位：记住一句话——测试请求从 Grafana 服务器发出，不是你的浏览器。在 Grafana 所在机器上
curl <data-source-url>复现：通了再看返回码，refused是网络/端口，401/403 是凭据，超时是防火墙。容器部署最常见错填localhost。 - 解法：URL 改用容器可达地址（宿主机服务用
host.docker.internal或 Docker 网络内的服务名）；带鉴权的补 Token/Basic；Kubernetes 里检查 NetworkPolicy 与 Service 名。
四、面板 No data
- 症状：面板显示 No data，但数据源本身在 Explore 里查得到数。
- 定位：四连查——时间范围是否覆盖数据；查询里的标签/条件是否把结果过滤空了；变量替换后的真实查询（Query inspector 里能看）是否与你手敲的一致；指标名/表名拼写。
- 解法：把 Explore 里验证过的查询原样搬回面板；变量问题去仪表盘设置核对候选值；Prometheus 长时间范围下 step 过大也可能「抽稀到空」，可手动指定更小 Step。数据源侧细节见连接 Prometheus。
五、告警不触发
- 症状：指标明显越线，通知却没来。
- 定位：按链路顺序看：规则状态（Normal/Pending/Firing）→ 实例是否存在 → 是否有静默/静音时段 → 路由落点 → 联系点 Test。规则详情页的实例状态历史是最好的证人。
- 解法：对号入座——一直 Normal：查询或阈值写错；Pending 卡住：
for设太长；Firing 无通知：被静默或路由到了别处；通知发出你没收到：查联系点凭据。完整清单在指标与日志告警实战的排错一节。
六、登录循环重定向
- 症状：登录后闪回登录页，或浏览器报
too many redirects。 - 定位：三大概率源：
root_url协议/域名与浏览器地址不一致；HTTPS 反代 +[security] cookie_secure配置矛盾；OAuth 的回调地址没在 IdP 侧登记。 - 解法：让
root_url与用户地址栏完全一致；反代终结 TLS 时 Grafana 侧配[server] protocol = http并确认代理传对了X-Forwarded-Proto；SSO 场景核对回调 URL。认证集成见认证与登录集成。
提示： 六类之外的问题，先开 Administration → Server stats 与日志里的
ERROR级别行，多数配置错误会在那里留下第一句证词。
下一步
- 日志与诊断工具全解，读日志、诊断与服务器管理。
- 告警链路专项排错，见Grafana 告警体系总览。
- 看不懂术语时，查术语表。