📚 课程目录第2章 Grafana环境搭建

2. Grafana 环境搭建：安装方式、初始配置与数据源添加

搭建 Grafana 是水位看板实战的第一步。本章覆盖三种主流安装方式、初始化配置流程以及 Prometheus / InfluxDB 数据源的添加方法。无论你使用 Docker、二进制包还是包管理器，都能在 15 分钟内完成可用环境。

2.1 安装方式对比

安装方式	适用场景	优势	劣势
Docker	开发 / 测试 / 快速部署	环境隔离、启动秒级、版本切换方便	需 Docker 环境、持久化需额外配置
二进制包	生产环境 / 离线部署	无依赖、性能最优、可 systemd 管理	升级需手动替换文件
APT/YUM 包管理器	Linux 服务器标准运维	自动处理依赖、方便版本锁定	官方源可能滞后

推荐选择： 个人学习或快速原型使用 Docker；生产环境建议二进制包 + systemd 管理，便于版本控制和回滚。

2.2 Docker 安装 Grafana

Docker 方式是最简洁的入门路径。以下命令拉取最新稳定版并启动容器：

# 拉取镜像
docker pull grafana/grafana:latest

# 启动容器（挂载数据目录用于持久化）
docker run -d \
  --name=grafana \
  -p 3000:3000 \
  -v /data/grafana:/var/lib/grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=admin123" \
  grafana/grafana:latest

启动后访问 http://<服务器IP>:3000，默认用户名 admin，密码为环境变量中设置的 admin123。

注意： 生产环境务必修改默认密码，并配置 HTTPS 和反向代理。Docker 方式下插件安装需在容器内执行 grafana-cli plugins install 或使用自定义镜像。

2.3 二进制包安装（Linux 通用）

二进制安装适合对系统依赖有严格要求的场景。以下以 Ubuntu 20.04 为例：

# 下载最新稳定版（以 10.4.2 为例）
wget https://dl.grafana.com/oss/release/grafana-10.4.2.linux-amd64.tar.gz

# 解压到指定目录
tar -zxvf grafana-10.4.2.linux-amd64.tar.gz -C /opt/
mv /opt/grafana-10.4.2 /opt/grafana

# 创建数据目录
mkdir -p /data/grafana

# 启动（前台运行，测试用）
/opt/grafana/bin/grafana server \
  --homepath=/opt/grafana \
  --config=/opt/grafana/conf/defaults.ini

生产环境建议注册为 systemd 服务：

# 创建 systemd 单元文件 /etc/systemd/system/grafana-server.service
[Unit]
Description=Grafana
After=network.target

[Service]
ExecStart=/opt/grafana/bin/grafana server --homepath=/opt/grafana
Restart=always
User=grafana

[Install]
WantedBy=multi-user.target

# 启动并设置开机自启
systemctl daemon-reload
systemctl enable grafana-server
systemctl start grafana-server

2.4 初始配置要点

Grafana 的主配置文件为 conf/defaults.ini（二进制）或 /etc/grafana/grafana.ini（包管理器）。以下为水位看板场景的关键配置项：

配置项	默认值	推荐值	说明
`server.http_port`	3000	3000	Web 访问端口
`security.admin_user`	admin	admin	超级管理员用户名
`security.admin_password`	admin	（自定义强密码）	首次登录后建议修改
`paths.data`	/var/lib/grafana	/data/grafana	数据库、插件、会话存储路径
`auth.anonymous.enabled`	false	false	水位看板建议关闭匿名访问
`dashboards.default_home_dashboard_path`	（空）	/opt/grafana/dashboards	可指定默认首页看板路径

实践建议： 水位看板通常需要长时间运行，建议将 paths.data 指向独立数据盘，并配置日志轮转。修改配置后需重启 Grafana 服务。

2.5 数据源添加：Prometheus

Prometheus 是水位看板最常用的时序数据库。添加步骤如下：

登录 Grafana Web 界面，点击左侧齿轮图标 → Data Sources。
点击 Add data source，选择 Prometheus。
在 HTTP 区域填写 Prometheus 服务地址，例如 http://192.168.1.100:9090。
点击 Save & Test，页面显示 Data source is working 即表示成功。

也可以通过 Grafana API 添加：

curl -X POST http://admin:admin123@localhost:3000/api/datasources \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Prometheus",
    "type":"prometheus",
    "url":"http://192.168.1.100:9090",
    "access":"proxy",
    "isDefault":true
  }'

2.6 数据源添加：InfluxDB

InfluxDB 适用于 IoT 和事件型水位数据。添加时需注意版本差异：

参数	InfluxDB v1.x	InfluxDB v2.x
Type	InfluxDB	InfluxDB
URL	`http://host:8086`	`http://host:8086`
Database	填写数据库名（如 `water_level`）	不填，使用 Flux 查询
User / Password	可选	认证
HTTP Method	GET	POST
Query Language	InfluxQL	Flux

InfluxDB v2.x 添加时需在 Custom HTTP Headers 中添加 Authorization: your-influxdb-。

版本选择： 水位看板场景推荐使用 InfluxDB v1.x + InfluxQL，查询语法更直观，与 Grafana 的兼容性更成熟。若使用 v2.x，请确保 Grafana 版本 ≥ 8.0 以支持 Flux。

2.7 数据源架构示意

下图展示了 Grafana 与两种数据源的典型连接架构：

2.8 验证与排障

添加数据源后，建议执行以下验证步骤：

Save & Test：Grafana 会返回具体错误信息，如网络不通、认证失败、版本不兼容等。
Explore 面板：进入左侧 Explore 图标，选择对应数据源，输入简单查询（如 up{job="node"}）验证数据返回。
查看日志：Docker 方式使用 docker logs grafana；二进制方式查看 /var/log/grafana/grafana.log。

常见错误：

401 Unauthorized：InfluxDB v2.x 缺少或无效。
404 Not Found：Prometheus 地址或端口错误，或 InfluxDB 数据库名不存在。
Timeout：网络不通或防火墙未放行，检查数据源所在主机与 Grafana 之间的连通性。

2.9 多数据源管理建议

水位看板通常需要同时接入多个数据源。建议遵循以下命名规范：

数据源名称	用途	示例
`Prometheus-Prod`	生产环境指标	CPU、内存、水位阈值
`InfluxDB-WaterLevel`	水位历史数据	液位传感器时序
`Prometheus-Dev`	开发测试环境	实验性看板

在 Dashboard 的 Query 编辑器中，可通过数据源选择器快速切换，便于同一看板展示不同来源的数据。

最佳实践： 将生产数据源设为默认（isDefault: true），新建看板时自动关联。非生产数据源在名称中加入环境标识，避免误操作。