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

2、环境搭建：在Windows、Linux、macOS上安装Grafana，以及通过Docker快速部署的完整步骤

Grafana 作为业界领先的可观测性数据可视化平台，其部署方式灵活多样，既支持传统操作系统上的原生安装，也支持容器化环境中的快速编排。本章将系统讲解在三大主流桌面/服务器操作系统（Windows、Linux、macOS）上的安装细节，并重点演示通过 Docker 进行标准化部署的完整流程。无论你是个人开发者搭建本地监控面板，还是运维工程师在生产环境构建高可用可视化集群，掌握这些环境搭建方法都是后续所有仪表盘设计与告警配置的基础。我们将从安装原理、操作步骤、实战案例到常见误区，进行全方位拆解。

上图清晰地展示了本章的核心知识框架：左侧为传统操作系统原生安装路径，中间为容器化部署路径，右侧为安装完成后的统一验证与初始化流程。三条路径最终都指向同一个目标——成功运行 Grafana 服务并完成基础配置。下面我们将逐一深入每个环节。

2.1 核心原理：Grafana 的安装本质与运行机制

Grafana 本质上是一个基于 Go 语言编写的独立 Web 服务，它不依赖外部应用服务器（如 Tomcat、Nginx），而是内置了 HTTP 服务器。安装 Grafana 的核心任务，就是获取其可执行文件、默认配置、静态资源（前端面板）以及数据存储目录，并确保其能够监听指定端口（默认 3000）并提供服务。

从运行机制来看，Grafana 启动后主要完成以下几件事：

加载配置：读取默认配置文件（grafana.ini）以及环境变量中的覆盖项，确定 HTTP 端口、数据库类型（默认 SQLite）、日志级别等参数。
初始化数据库：Grafana 使用 SQLite（默认）或 MySQL/PostgreSQL 存储用户、仪表盘、数据源等元数据。首次启动时会自动创建数据库文件（grafana.db）。
启动 HTTP 服务：监听配置的端口，提供 Web UI 和 REST API。所有仪表盘渲染、数据查询代理均通过该服务完成。
插件加载：从插件目录加载已安装的数据源插件和应用插件，扩展其功能边界。

理解这一机制对排障至关重要。例如，如果端口被占用，服务会启动失败；如果数据库目录无写入权限，服务会异常退出。因此，安装时不仅要关注二进制文件是否就位，更要关注运行用户对配置目录、数据目录的读写权限。

经验提醒：Grafana 官方将安装包分为两类：一类是包含所有依赖的独立二进制包（适用于 Linux/macOS），另一类是平台特定的安装包（如 Windows 的 .msi、Linux 的 .deb/.rpm）。生产环境建议使用系统包管理器安装，便于后续版本升级和依赖管理。

2.2 操作流程：三大操作系统原生安装详解

不同操作系统的安装方式差异较大，但核心步骤一致：下载 → 安装 → 配置 → 启动 → 验证。以下分别展开。

2.2.1 Windows 平台安装（MSI 安装包）

Windows 下推荐使用官方 MSI 安装包，它自动处理了服务注册、防火墙规则和默认目录创建。

访问 Grafana 官网下载页，选择 Windows 版本（通常为 .msi 文件）。
双击运行 MSI 安装包，选择安装目录（默认 C:\Program Files\GrafanaLabs\Grafana）。
安装完成后，打开“服务”管理器（Win+R 输入 services.msc），找到 Grafana 服务，右键启动。
验证：浏览器访问 http://localhost:3000，出现登录页面即成功。

Windows 下默认配置文件位于 C:\Program Files\GrafanaLabs\Grafana\conf\defaults.ini，自定义配置应复制为 custom.ini 并修改。注意，Windows 服务默认以 LocalSystem 账户运行，如需访问网络共享或特定权限，需在服务属性中调整账户。

2.2.2 Linux 平台安装（APT/YUM 与二进制包）

Linux 是 Grafana 最常用的部署环境。以 Ubuntu/Debian 系为例，使用 APT 安装最为便捷：

# 添加 Grafana 官方 GPG 密钥和 APT 仓库
sudo apt-get install -y gnupg2 software-properties-common
sudo wget -q -O /usr/share/keyrings/grafana.key https://apt.grafana.com/gpg.key
echo "deb [signed-by=/usr/share/keyrings/grafana.key] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

# 更新并安装
sudo apt-get update
sudo apt-get install -y grafana

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

对于 CentOS/RHEL/Fedora 系，使用 YUM/DNF 安装：

# 添加仓库
sudo cat <<EOF | sudo tee /etc/yum.repos.d/grafana.repo
[grafana]
name=grafana
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://rpm.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF

# 安装并启动
sudo yum install -y grafana
sudo systemctl start grafana-server
sudo systemctl enable grafana-server

Linux 下配置文件位于 /etc/grafana/grafana.ini，数据目录为 /var/lib/grafana，日志目录为 /var/log/grafana。务必确保 grafana-server 用户对这些目录有读写权限。

2.2.3 macOS 平台安装（Homebrew）

macOS 用户推荐使用 Homebrew 安装，简单且易于管理：

# 更新 brew 并安装 grafana
brew update
brew install grafana

# 启动服务（前台运行）
grafana server

# 或者作为后台服务运行
brew services start grafana

Homebrew 安装的 Grafana 配置目录在 /usr/local/etc/grafana/（Intel）或 /opt/homebrew/etc/grafana/（Apple Silicon），数据目录在 /usr/local/var/lib/grafana。使用 brew services 可以方便地管理开机自启。

操作系统	安装方式	配置文件路径	数据目录	服务管理命令
Windows	MSI 安装包	C:\Program Files\GrafanaLabs\Grafana\conf\custom.ini	C:\ProgramData\GrafanaLabs\Grafana\data	services.msc 或 net start grafana
Ubuntu/Debian	APT	/etc/grafana/grafana.ini	/var/lib/grafana	systemctl start grafana-server
CentOS/RHEL	YUM	/etc/grafana/grafana.ini	/var/lib/grafana	systemctl start grafana-server
macOS	Homebrew	/opt/homebrew/etc/grafana/grafana.ini	/opt/homebrew/var/lib/grafana	brew services start grafana

2.3 案例拆解：Docker 快速部署与数据持久化实战

容器化部署已成为现代应用交付的主流方式。Grafana 官方提供了高质量的 Docker 镜像，支持快速启动和弹性伸缩。以下通过一个完整案例演示如何从零开始用 Docker 部署 Grafana，并解决数据持久化这一关键问题。

场景背景：某互联网公司运维团队需要在 3 台测试服务器上快速部署 Grafana 用于监控指标展示。要求：① 部署过程可重复、可版本控制；② 容器重启后仪表盘配置不丢失；③ 需要同时接入 Prometheus 和 MySQL 两个数据源。

初始目标：使用 Docker Compose 编排 Grafana 服务，实现一键启动，并验证数据持久化效果。

实施步骤：

mkdir -p /opt/grafana-deploy
cd /opt/grafana-deploy
touch docker-compose.yml

编写 docker-compose.yml：

version: '3.8'
services:
  grafana:
    image: grafana/grafana:10.4.2
    container_name: grafana-prod
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=StrongPass#2024
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_SERVER_ROOT_URL=http://grafana.example.com
    volumes:
      - grafana-storage:/var/lib/grafana
      - ./provisioning:/etc/grafana/provisioning
    networks:
      - monitoring-net

volumes:
  grafana-storage:
    driver: local

networks:
  monitoring-net:
    driver: bridge

启动服务：

docker compose up -d
docker ps | grep grafana

验证数据持久化：

# 创建测试仪表盘后重启容器
docker restart grafana-prod
# 再次访问 UI，确认仪表盘仍然存在

结果对比：使用命名卷 grafana-storage 后，即使删除并重新创建容器，数据依然保留。而未使用卷的容器在删除后所有配置将丢失。

风险与代价：Docker 部署虽然便捷，但需注意镜像版本与宿主机内核的兼容性；同时，如果使用 host 网络模式，端口冲突风险增加。此外，provisioning 目录用于自动配置数据源和仪表盘，需确保 YAML 格式正确，否则容器启动时会报错。

  复盘经验：生产环境建议固定镜像版本（如 grafana/grafana:10.4.2），避免使用 latest 标签导致不可控升级。同时，将敏感配置（如数据库密码）通过环境变量注入，而非硬编码在 Compose 文件中。

2.4 常见误区与总结复盘

在环境搭建过程中，初学者常遇到以下几类问题，这里逐一剖析并给出解决方案。

误区/问题	现象	根因分析	解决方案
端口被占用	启动失败，日志显示 `bind: address already in use`	3000 端口被其他进程占用	修改 `http_port` 配置，或使用 `netstat -tlnp` 排查占用进程
数据目录权限不足	启动后立即退出，日志提示 `mkdir /var/lib/grafana: permission denied`	运行用户对数据目录无写权限	执行 `chown -R grafana:grafana /var/lib/grafana` 或使用 Docker 卷
忘记默认密码	无法登录 Web UI	默认账号 admin/admin 首次登录后未修改	通过 CLI 重置：`grafana-cli admin reset-admin-password newpass`
Docker 容器数据丢失	容器删除后仪表盘消失	未挂载数据卷	使用 `volumes` 声明持久化存储
配置文件不生效	修改 grafana.ini 后重启无变化	未区分 defaults.ini 与 custom.ini，或环境变量优先级更高	将自定义配置写入 custom.ini，并确认环境变量未覆盖

总结复盘：环境搭建的核心在于理解 Grafana 的目录结构和配置优先级。无论使用哪种安装方式，最终都要确保三个关键目录可用：配置目录（读取配置）、数据目录（存储 SQLite 数据库和插件）、日志目录（输出运行日志）。Docker 方式通过卷映射天然解决了数据持久化问题，但需要额外关注环境变量与配置文件的优先级关系——环境变量（GF_ 前缀）会覆盖配置文件中的同名设置。

风险提示：切勿在生产环境使用默认密码 admin/admin。Grafana 官方文档明确警告，暴露在公网的默认凭据会在数小时内被扫描工具攻击。建议首次登录后立即修改密码，并启用两步验证（2FA）。

最后，建议读者在完成安装后，执行一次健康检查：访问 http://localhost:3000/api/health，返回 {"database":"ok"} 即表示服务正常。至此，Grafana 环境搭建已全部完成，下一阶段即可开始连接数据源并创建第一个仪表盘。