3. Grafana 安装与部署：二进制安装、Docker 部署、Kubernetes 部署、配置文件的详解

在生产环境中，Grafana 的部署方式直接影响后续的运维效率与扩展能力。本章将系统讲解三种主流部署方式（二进制、Docker、Kubernetes），并深入剖析核心配置文件的结构与关键参数。无论你是初次搭建还是迁移升级，都能在此找到对应的操作路径与避坑指南。

📌 选型建议： 单机测试或低负载场景推荐二进制或 Docker 部署；生产集群、需要弹性伸缩与自愈能力时，优先选择 Kubernetes 部署。

3.1 二进制安装（Linux 环境）

二进制安装是最直接的方式，不依赖容器运行时，适合对系统资源有严格管控的场景。以下步骤基于 CentOS 7 / Ubuntu 20.04 验证。

3.1.1 下载与解压

# 获取最新稳定版（以 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

3.1.2 创建系统用户与数据目录

# 创建 grafana 用户（无登录权限）
useradd --no-create-home --shell /bin/false grafana

# 创建数据与日志目录
mkdir -p /var/lib/grafana /var/log/grafana
chown -R grafana:grafana /var/lib/grafana /var/log/grafana /opt/grafana

3.1.3 配置 systemd 服务

cat <<EOF > /etc/systemd/system/grafana-server.service
[Unit]
Description=Grafana Server
After=network.target

[Service]
User=grafana
Group=grafana
ExecStart=/opt/grafana/bin/grafana-server \
  --homepath=/opt/grafana \
  --config=/opt/grafana/conf/defaults.ini \
  --config=/opt/grafana/conf/custom.ini
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

# 启动并设置开机自启
systemctl daemon-reload
systemctl start grafana-server
systemctl enable grafana-server
✅ 验证： 访问 http://<服务器IP>:3000，默认用户名/密码为 admin/admin，首次登录会强制修改密码。
二进制安装流程 下载 tar.gz 解压到 /opt 创建用户&目录 配置 systemd ⚠️ 注意：custom.ini 中的配置会覆盖 defaults.ini 中的同名参数 建议将自定义配置全部写入 custom.ini，便于升级时保留

3.2 Docker 部署

Docker 部署将 Grafana 及其依赖打包在容器中，实现环境一致性。官方镜像 grafana/grafana 已包含默认配置，用户只需挂载数据卷与自定义配置文件即可。

3.2.1 快速启动（单容器）

docker run -d \
  --name=grafana \
  -p 3000:3000 \
  -v /data/grafana:/var/lib/grafana \
  -v /data/grafana/conf:/etc/grafana \
  -e "GF_SERVER_ROOT_URL=http://yourdomain.com" \
  -e "GF_SECURITY_ADMIN_PASSWORD=StrongPass123" \
  --restart=always \
  grafana/grafana:10.4.2

3.2.2 Docker Compose 编排（推荐）

version: '3.8'
services:
  grafana:
    image: grafana/grafana:10.4.2
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - ./data/grafana:/var/lib/grafana
      - ./config/grafana.ini:/etc/grafana/grafana.ini
      - ./config/provisioning:/etc/grafana/provisioning
    environment:
      - GF_SERVER_ROOT_URL=http://localhost:3000
      - GF_SECURITY_ADMIN_PASSWORD=admin
    restart: unless-stopped
⚠️ 权限陷阱： 容器内 Grafana 以 UID 472（grafana 用户）运行。如果宿主机挂载目录权限不足，会导致容器启动失败。请执行 chown -R 472:472 ./data/grafana 修正。

3.2.3 关键环境变量速查表

环境变量对应配置项说明
GF_SERVER_HTTP_PORT[server].http_port容器内监听端口，默认 3000
GF_SERVER_ROOT_URL[server].root_url外部访问 URL，反向代理时必填
GF_SECURITY_ADMIN_PASSWORD[security].admin_password初始管理员密码
GF_DATABASE_TYPE[database].type后端数据库类型（sqlite3/mysql/postgres）
GF_INSTALL_PLUGINS—启动时自动安装插件，多个用逗号分隔
Docker 部署架构 宿主机 Grafana 容器 grafana/grafana:10.4.2 端口 3000 UID 472 数据卷 /var/lib/grafana 配置卷 /etc/grafana 外部访问 http://host:3000

3.3 Kubernetes 部署

在 K8s 集群中部署 Grafana，可以充分利用声明式配置、自动扩缩容与自愈能力。推荐使用 Helm Chart 或自定义 YAML 清单。

3.3.1 使用 Helm 安装（官方 Chart）

# 添加 Grafana 官方 Helm 仓库
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

# 安装 Grafana（命名空间 monitoring）
helm upgrade --install grafana grafana/grafana \
  --namespace monitoring --create-namespace \
  --set service.type=NodePort \
  --set service.nodePort=30300 \
  --set persistence.enabled=true \
  --set persistence.size=10Gi \
  --set adminPassword="K8sAdmin123"

3.3.2 自定义 YAML 部署（核心资源清单）

apiVersion: apps/v1
kind: Deployment
metadata:
  name: grafana
  namespace: monitoring
spec:
  replicas: 2
  selector:
    matchLabels:
      app: grafana
  template:
    metadata:
      labels:
        app: grafana
    spec:
      containers:
      - name: grafana
        image: grafana/grafana:10.4.2
        ports:
        - containerPort: 3000
        env:
        - name: GF_SERVER_ROOT_URL
          value: "https://grafana.yourdomain.com"
        - name: GF_SECURITY_ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: grafana-admin
              key: password
        volumeMounts:
        - name: data
          mountPath: /var/lib/grafana
        - name: config
          mountPath: /etc/grafana/grafana.ini
          subPath: grafana.ini
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: grafana-pvc
      - name: config
        configMap:
          name: grafana-config

3.3.3 暴露服务（Ingress 示例）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana-ingress
  namespace: monitoring
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: grafana.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: grafana
            port:
              number: 3000
🔐 安全建议： 生产环境务必通过 Secret 管理管理员密码，并启用 Ingress TLS 证书。避免将 adminPassword 明文写在 Values 或 YAML 中。
Kubernetes 部署架构 K8s Cluster Ingress Service (NodePort) Deployment replicas: 2 Pod: grafana-xxx Pod: grafana-yyy PVC (10Gi) ConfigMap

3.4 配置文件详解

Grafana 的配置体系采用“分层覆盖”机制：defaults.ini 提供出厂默认值，custom.ini（或通过 --config 指定的文件）中的值会覆盖前者。理解核心配置段是调优与排障的基础。

3.4.1 配置文件加载顺序

  1. defaults.ini — 内置默认配置，不要直接修改，升级时会被覆盖。
  2. custom.ini — 用户自定义配置，优先级高于 defaults.ini。
  3. 环境变量 — 格式 GF_<SECTION>_<KEY>，优先级最高。

3.4.2 核心配置段速查表

配置段关键参数默认值说明
[server]http_port3000HTTP 监听端口
[server]root_urlhttp://localhost:3000外部访问 URL，反向代理时必填
[security]admin_useradmin初始管理员用户名
[security]admin_passwordadmin初始管理员密码（首次登录强制修改）
[database]typesqlite3后端数据库类型：sqlite3 / mysql / postgres
[database]pathgrafana.dbSQLite 数据库文件路径
[auth.anonymous]enabledfalse是否允许匿名访问
[smtp]enabledfalse是否启用邮件通知
[smtp]hostlocalhost:25SMTP 服务器地址
[alerting]enabledtrue是否启用报警功能
[unified_alerting]enabledtrue是否启用统一报警系统（Grafana 8+ 推荐）

3.4.3 典型配置示例（custom.ini）

# ==================== 服务器配置 ====================
[server]
http_port = 3000
root_url = https://grafana.example.com
enable_gzip = true

# ==================== 数据库配置 ====================
[database]
type = postgres
host = postgres-service:5432
name = grafana
user = grafana
password = DB_Password_123
ssl_mode = disable

# ==================== 安全配置 ====================
[security]
admin_user = admin
admin_password = Admin_Strong_456
secret_key = SW2YkxI1Q2Z8F3T5p7b9d0e1r4t6y8u0

# ==================== 邮件通知 ====================
[smtp]
enabled = true
host = smtp.example.com:587
user = alert@example.com
password = Mail_Pass_789
from_address = alert@example.com
from_name = Grafana Alert

# ==================== 统一报警 ====================
[unified_alerting]
enabled = true
evaluation_timeout = 30s
notification_timeout = 30s
max_attempts = 3
⚠️ 生产环境必改项：
  • secret_key — 用于加密数据源密码、告警通知等敏感信息，务必使用强随机字符串。
  • admin_password — 首次登录后应立即修改，或通过环境变量注入。
  • database — 生产环境建议使用 PostgreSQL 或 MySQL，避免 SQLite 在高并发下出现锁冲突。

3.4.4 配置验证与重载

# 检查配置文件语法（Grafana 10+）
grafana-cli admin check-config

# 热重载配置（无需重启服务）
# 方法一：通过 API
curl -X POST http://localhost:3000/api/admin/provisioning/dashboards/reload \
  -H "Authorization: Bearer <>"

# 方法二：发送 SIGHUP 信号
kill -HUP $(pgrep grafana-server)

# 方法三：重启服务（最彻底）
systemctl restart grafana-server
💡 最佳实践： 将配置文件纳入 Git 版本管理，配合 CI/CD 实现配置变更的审计与回滚。对于 Kubernetes 部署，使用 ConfigMap 管理配置，修改后自动触发 Pod 滚动更新。
配置分层覆盖机制 defaults.ini（出厂默认值） custom.ini（用户自定义） 环境变量 GF_*（最高优先级）

3.5 部署方式对比总结

维度二进制安装Docker 部署Kubernetes 部署
部署复杂度中等（需手动配置 systemd）低（一条命令启动）较高（需掌握 Helm / YAML）
资源隔离无（直接使用宿主机资源）容器级隔离Pod 级隔离 + 资源限制
扩展性手动复制部署需编排工具（Compose/Swarm）原生支持水平扩缩
配置管理本地文件挂载卷 / 环境变量ConfigMap / Secret
升级回滚手动替换二进制更换镜像标签Helm rollback / 镜像版本控制
适用场景单机测试、离线环境开发环境、中小规模生产大规模生产、微服务架构
📘 学习路径建议： 初学者先从 Docker 部署入手，快速体验 Grafana 功能；熟悉后再尝试二进制安装以理解底层文件结构；最后在生产环境中落地 Kubernetes 部署，结合本章的配置详解进行调优。
← 上一章 📖 返回目录 下一章 →