Grafana 离线安装故障排除：解决无法启动问题

2025-01-24 08:33:22

Grafana 独立二进制安装故障排查

使用 Grafana 独立二进制安装包时，在没有互联网连接的环境中，启动服务可能会遇到问题。尽管修改了配置文件，禁用了更新检查，服务器依然无法启动。这篇文章将探讨一些常见问题及其对应的解决方法。

常见错误分析

常见问题之一，与 Grafana 尝试连接互联网获取插件列表和更新有关。虽然通过禁用 check_for_updates, check_for_plugin_updates 和 public_key_retrieval_disabled 配置项，可以屏蔽相关的日志错误，但并非所有依赖都能通过配置项关闭。某些内部启动组件仍可能尝试进行外部通信，导致初始化失败，致使服务无法启动。

解决方案

1. 确认端口可用性

端口冲突是常见的问题。默认情况下， Grafana 使用 3000 端口。如果此端口已被其他程序占用，则 Grafana 将无法启动。

操作步骤:

使用 netstat -tulnp （或 ss -tulnp）命令查看 3000 端口是否被占用。
```
 netstat -tulnp | grep 3000
```
或
```
ss -tulnp | grep 3000
```
如果端口被占用，可以选择关闭占用该端口的程序，或者修改 Grafana 的监听端口。在grafana.ini配置文件中修改 http_port 选项：
```
[server]
http_port = 3001 #  更换为未使用的端口，如 3001
```
修改后重启 Grafana。

2. 仔细检查配置文件

除了上述提到的更新相关配置，还应该注意 paths 配置部分。 paths 配置项定义了 Grafana 读取和存储数据的位置，若配置不正确，可能导致服务无法正确初始化。
确保 paths.data, paths.logs, paths.plugins, 和 paths.provisioning 指向存在且可写的目录。

操作步骤:

定位grafana.ini配置文件。通常，在二进制解压后的 config 目录下。

确认以下 paths 路径存在且用户具有读写权限。

 [paths]
data = /var/lib/grafana/data   # 例如 /data/grafana/data
logs = /var/log/grafana    # 例如 /data/grafana/logs
plugins = /var/lib/grafana/plugins   #例如 /data/grafana/plugins
provisioning = /var/lib/grafana/provisioning #例如 /data/grafana/provisioning

根据实际环境更改以上路径。
创建以上配置的目录。并给予 Grafana 运行的用户读写权限。假设运行 Grafana 的用户是 grafana:

 sudo mkdir -p  /data/grafana/{data,logs,plugins,provisioning}
 sudo chown -R grafana:grafana /data/grafana

3. 运行日志排错

即使没有控制台输出错误，日志中仍然可能存在有价值的信息。详细检查 Grafana 日志是故障排除的关键步骤。

操作步骤:

定位 grafana.ini 配置中定义的日志文件路径（通常是 [paths].logs 配置的值）。
使用 tail -f 命令实时查看日志文件，观察是否有任何错误或警告信息。
```
tail -f /var/log/grafana/grafana.log # 替换为实际的日志文件路径
```
分析日志内容。重点关注 ERROR 或 WARN 级别的日志条目，尝试理解错误发生的原因。例如日志中若出现数据路径权限错误，可以参照上述 2 修改权限。

4. 显式指定运行用户

部分情况下，服务运行用户权限不充分，也可能导致启动失败。通过显式指定运行用户可以解决潜在的权限问题。
使用 systemctl 或类似的工具创建服务管理单元（Service Unit）文件，并指定 User 和 Group。

操作步骤：

创建 systemd 服务单元文件，例如 /etc/systemd/system/grafana.service。

[Unit]
Description=Grafana
After=network.target

[Service]
User=grafana  #  Grafana 运行的用户，需要是实际存在的系统用户
Group=grafana   #  Grafana 运行的用户组，需要是实际存在的系统用户组
Type=simple
Restart=on-failure
ExecStart=/path/to/your/grafana-binary/bin/grafana-server  \
         --config /path/to/your/grafana-binary/conf/defaults.ini  \ # 指向您的配置目录
WorkingDirectory=/path/to/your/grafana-binary

[Install]
WantedBy=multi-user.target

 替换上面 `/path/to/your/grafana-binary` 指向您实际的 Grafana 路径.
 `--config /path/to/your/grafana-binary/conf/defaults.ini` 确认此参数可以成功启动。 或者使用 `--config /path/to/your/grafana.ini`  指向您修改后的配置文件。
 在启动前需要先修改配置 `log_mode = file` 并配置好文件日志路径。`[paths] logs=/var/log/grafana` 并确保这个目录存在并属于`grafana:grafana`. 详细参照上述 **2** .

2. 刷新 systemd 并启用 grafana 服务
 ```bash
  sudo systemctl daemon-reload
 sudo systemctl enable grafana
  ```
3. 启动 grafana 服务并查看状态：
 ```bash
  sudo systemctl start grafana
 sudo systemctl status grafana
 ```

如果状态显示运行异常，请重新参照上述步骤分析日志或配置。

## 安全提示

* 避免使用 root 用户运行 Grafana 服务，这可能带来潜在的安全风险。创建专门的系统用户，并赋予其必要的权限。
* 定期检查 Grafana 版本并进行升级，以确保使用最新版本修复的漏洞。

解决 Grafana 独立二进制安装错误的关键在于细致排查。端口占用、文件权限、配置错误和日志分析，是排除故障的重要方向。逐步排查并分析每个环节，最终将能使 Grafana 顺利启动。