2. Grafana 安装与部署：多平台实战指南

Grafana 的部署方式灵活多样，支持从轻量级 Docker 容器到企业级源码编译的多种方案。本章将系统讲解在 Linux、Windows、macOS 上的安装步骤、Docker 部署、源码编译及核心配置文件解析，帮助你根据生产环境需求选择最合适的部署路径。

2.1 各平台安装方式对比

下表汇总了主流操作系统的安装方式与适用场景，方便你快速决策：

2.2 Linux 系统安装（以 Ubuntu 为例）

Linux 是 Grafana 最主流的部署平台，以下步骤基于 Ubuntu 22.04 LTS。

步骤 1：添加 Grafana APT 仓库

# 安装必要的依赖
sudo apt-get install -y software-properties-common wget

# 添加 Grafana GPG 密钥
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -

# 添加稳定版仓库
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"

步骤 2：安装 Grafana

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

步骤 3：启动并设置开机自启

# 启动 Grafana 服务
sudo systemctl start grafana-server

# 设置开机自启
sudo systemctl enable grafana-server

# 检查服务状态
sudo systemctl status grafana-server

2.3 Windows 系统安装

Windows 环境通常用于开发测试，采用 ZIP 包解压即用方式。

步骤 1：下载并解压

# 从官网下载最新 ZIP 包（示例版本 10.4.2）
# 下载地址：https://grafana.com/grafana/download?platform=windows

# 解压到目标目录，例如 C:\grafana
# 解压后目录结构如下：
C:\grafana\
├── bin\
├── conf\
├── data\
├── logs\
├── public\
└── scripts\

步骤 2：启动 Grafana

# 进入 bin 目录
cd C:\grafana\bin

# 以控制台方式启动（调试用）
grafana-server.exe

# 或注册为 Windows 服务（生产推荐）
# 以管理员身份运行 PowerShell
C:\grafana\bin\grafana-server.exe --service install
net start grafana

2.4 macOS 系统安装

macOS 开发者推荐使用 Homebrew 安装，简洁高效。

# 更新 Homebrew
brew update

# 安装 Grafana
brew install grafana

# 启动服务（前台运行）
grafana-server --config=/usr/local/etc/grafana/grafana.ini

# 或使用 Homebrew 服务管理（后台运行）
brew services start grafana

2.5 Docker 部署（推荐生产方案）

Docker 部署是当前最流行的方式，具有环境隔离、快速迁移、版本控制等优势。

2.5.1 基础 Docker 部署

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

# 运行容器（挂载数据卷持久化）
docker run -d \
  --name=grafana \
  -p 3000:3000 \
  -v /data/grafana:/var/lib/grafana \
  -v /data/grafana-config:/etc/grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=StrongPass123" \
  grafana/grafana:latest

2.5.2 Docker Compose 部署（含数据源预配置）

# docker-compose.yml
version: '3.8'
services:
  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - ./grafana-data:/var/lib/grafana
      - ./grafana-config:/etc/grafana
      - ./provisioning:/etc/grafana/provisioning
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin123
      - GF_INSTALL_PLUGINS=grafana-piechart-panel
    restart: unless-stopped

2.6 源码编译安装

当需要定制 Grafana 核心功能或使用最新开发特性时，可选择源码编译。

前置条件

• Go 1.20+（后端编译）
• Node.js 18+（前端编译）
• Git
• Python 3.x（构建脚本依赖）

编译步骤

# 1. 克隆源码
git clone https://github.com/grafana/grafana.git
cd grafana

# 2. 安装前端依赖并构建
yarn install --frozen-lockfile
yarn build

# 3. 编译后端二进制
go run build.go build

# 4. 启动开发模式
go run build.go dev

# 5. 生产编译（生成可执行文件）
go run build.go build-server

2.7 核心配置文件详解

Grafana 的配置文件采用 INI 格式，主配置文件为 grafana.ini（Linux 路径：/etc/grafana/grafana.ini）。以下为关键配置段解析：

配置示例：生产环境优化

# /etc/grafana/grafana.ini 关键配置
[server]
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com
enable_gzip = true

[security]
admin_user = admin
secret_key = YourStrongSecretKeyHere

[database]
type = postgres
host = 192.168.1.100:5432
name = grafana
user = grafana_user
password = DB_Password_123

[auth.anonymous]
enabled = false

[log]
mode = console file
level = warn

2.8 Grafana 部署架构图

下图展示了 Grafana 在典型生产环境中的部署架构，涵盖反向代理、数据库、数据源和监控组件的关系：

2.9 部署验证与常见问题

部署后快速验证清单

• 端口监听检查： ss -tlnp | grep 3000 确认 Grafana 已监听
• Web 界面访问： 浏览器打开 http://<IP>:3000 显示登录页
• API 健康检查： curl http://localhost:3000/api/health 返回 {"msg":"OK"}
• 日志无报错： 检查 /var/log/grafana/grafana.log 无 ERROR 级别日志
• 数据源连通性： 在 Grafana UI 中添加测试数据源，点击“Save & Test”

常见问题排查