📚 课程目录第2章 Grafana架构与部署

2. Grafana 架构与部署：整体架构、单机部署、Docker 部署与环境变量配置

本章聚焦 Grafana 的系统架构与主流部署方式。理解 Grafana 的前后端分离设计、数据持久化策略以及环境变量注入机制，是后续进行面板设计、数据源集成与告警阈值调优的基础。我们将从整体架构图开始，逐步深入到单机、Docker 及生产级配置实践。

2.1 Grafana 整体架构

Grafana 采用经典的三层 Web 架构：前端（React）、后端（Go） 与 数据库（SQLite/PostgreSQL/MySQL）。前端负责面板渲染与用户交互，后端提供 API 与告警引擎，数据库存储仪表盘、用户、数据源与告警规则等元数据。

  架构要点： Grafana 本身不存储监控指标数据，仅通过数据源插件（如 Prometheus、InfluxDB、Elasticsearch）查询并可视化。告警规则评估由后端定时执行，结果写入数据库。

2.2 单机部署（二进制 / RPM / DEB）

单机部署适用于测试环境或小规模团队。Grafana 官方提供 Linux、macOS、Windows 二进制包及主流发行版包管理器安装方式。

安装方式	命令 / 步骤	默认数据库	适用场景
二进制（Linux）	`wget ... && tar -zxvf grafana-*.tar.gz && ./bin/grafana server`	SQLite	快速验证、开发
APT（Ubuntu/Debian）	`sudo apt-get install -y grafana`	SQLite	生产单机
YUM（CentOS/RHEL）	`sudo yum install grafana`	SQLite	生产单机
Windows 二进制	解压后运行 `grafana-server.exe`	SQLite	Windows 环境

生产建议： 单机部署时，建议将默认的 SQLite 替换为 PostgreSQL 或 MySQL，以获得更好的并发性能与数据可靠性。配置文件位于 /etc/grafana/grafana.ini（Linux）或 conf/defaults.ini（二进制）。

2.3 Docker 部署

Docker 是当前最流行的 Grafana 部署方式，尤其适合容器化环境与 CI/CD 流程。官方镜像 grafana/grafana 支持通过环境变量、挂载配置文件或 Docker Compose 进行定制。

2.3.1 快速启动

# 启动 Grafana 容器，映射 3000 端口，使用默认 SQLite
docker run -d --name=grafana \
  -p 3000:3000 \
  grafana/grafana:latest

2.3.2 持久化数据与配置

# 创建本地数据与配置目录
mkdir -p /data/grafana/data /data/grafana/config

# 复制默认配置文件后修改
docker run --rm grafana/grafana:latest cat /etc/grafana/grafana.ini > /data/grafana/config/grafana.ini

# 启动并挂载
docker run -d --name=grafana \
  -p 3000:3000 \
  -v /data/grafana/data:/var/lib/grafana \
  -v /data/grafana/config/grafana.ini:/etc/grafana/grafana.ini \
  grafana/grafana:latest

2.3.3 Docker Compose（推荐生产）

version: '3.8'
services:
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana.ini:/etc/grafana/grafana.ini
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=strong_password
      - GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource
    restart: unless-stopped

volumes:
  grafana-data:

注意： 生产环境务必修改默认管理员密码，并通过 GF_SECURITY_ADMIN_PASSWORD 环境变量或配置文件设置。避免将密码明文写入 docker-compose.yml 文件，建议使用 Docker Secrets 或外部密钥管理。

2.4 环境变量配置

Grafana 支持通过环境变量覆盖配置文件中的任意参数，命名规则为：GF_<SECTION>_<KEY>。环境变量在 Docker 部署中尤为常用，可实现配置与镜像分离。

环境变量	对应配置项	说明	示例值
`GF_SERVER_HTTP_PORT`	`[server].http_port`	HTTP 监听端口	`3000`
`GF_SECURITY_ADMIN_PASSWORD`	`[security].admin_password`	管理员密码	`MyStr0ng!Pass`
`GF_DATABASE_TYPE`	`[database].type`	数据库类型	`postgres`
`GF_DATABASE_HOST`	`[database].host`	数据库地址	`192.168.1.100:5432`
`GF_DATABASE_NAME`	`[database].name`	数据库名称	`grafana`
`GF_INSTALL_PLUGINS`	`[plugins].install`	启动时自动安装插件（逗号分隔）	`grafana-clock-panel,grafana-piechart-panel`
`GF_SERVER_ROOT_URL`	`[server].root_url`	外部访问 URL（反向代理时必设）	`https://grafana.example.com`

  最佳实践： 在 Docker 部署中，优先使用环境变量注入敏感信息（密码、）和运行时差异配置（端口、数据库地址）；将通用配置（日志级别、插件列表）放在挂载的 grafana.ini 中，便于版本管理。

2.5 部署验证与基础检查

部署完成后，通过以下步骤验证 Grafana 是否正常运行：

访问 Web UI： 浏览器打开 http://<服务器IP>:3000，默认用户名/密码为 admin/admin。
检查 API 健康状态： curl http://localhost:3000/api/health，返回 {"database":"ok"} 表示数据库连接正常。
查看日志： Docker 部署使用 docker logs grafana；二进制部署日志默认输出到 /var/log/grafana/grafana.log。
验证数据源： 添加一个测试数据源（如 Prometheus 或 TestData DB），确认查询能正常返回数据。

快速排障： 如果页面加载缓慢或告警无法触发，优先检查数据库连接池配置（[database].max_open_conn）与后端日志中的错误堆栈。环境变量 GF_LOG_LEVEL=debug 可临时开启详细日志。