Grafana Docker Compose 部署指南

目标：使用 Docker Compose 部署 Grafana 13.2.3，一键拉起官方镜像可视化平台，覆盖数据持久化、常用环境变量、等价 docker run 与常用运维命令，已在 Ubuntu 22.04 实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Docker / Docker Compose 均可用（实测 Compose 版本 v5.5.1）
镜像：grafana/grafana:13.2.3
对外端口：宿主 3000 → 容器 3000
数据目录：/opt/data/grafana（宿主持久化）

二、镜像选型说明

Grafana 官方镜像 grafana/grafana，标签策略：

标签	说明	适用
`latest`	最新稳定版	快速体验
`13.2.3`	指定版本（本文锁定）	生产固定版本
`oss`	仅开源	严格合规场景

💡 生产强烈建议锁定具体版本标签（如 13.2.3），避免 latest 升级破坏既有看板。

三、前置条件

已安装 Docker 与 Docker Compose
数据目录已创建且属主为运行用户

四、部署步骤

4.1 创建数据目录

mkdir -p /opt/data/grafana

💡 Grafana 官方镜像默认以 UID 472（grafana 用户）运行，需保证数据目录对该用户可写：
chown 472:472 /opt/data/grafana

4.2 编写 docker-compose.yml

services:
  grafana:
    image: grafana/grafana:13.2.3
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # 机构/监听
      - GF_SERVER_HTTP_PORT=3000
      # 数据源/看板插件目录（保持默认即可，也可显式指定）
      - GF_PATHS_DATA=/var/lib/grafana
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      # 初始管理员账号（可选；不设则在 Web 首次初始化）
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=q1w2e3r4
    volumes:
      - /opt/data/grafana:/var/lib/grafana

⚠️ 说明：图像内默认数据卷即 /var/lib/grafana，通过 bind mount 挂到宿主 /opt/data/grafana 实现持久化。首次启动会自动初始化 sqlite 数据库 grafana.db。

4.3 启动服务

# 在当前目录（含 docker-compose.yml）执行
docker compose up -d

▶️ 实测回显：

Network grafana-compose_default Created
Container grafana Creating
Container grafana Created
Container grafana Started

4.4 查看运行状态

docker compose ps

▶️ 实测回显：

NAME     IMAGE                   COMMAND   SERVICE   STATUS        PORTS
grafana  grafana/grafana:13.2.3  "/run.sh" grafana   Up 6 seconds  0.0.0.0:3000->3000/tcp

4.5 验证健康接口与登录

curl http://localhost:3000/api/health

▶️ 实测回显：

{"database":"ok","version":"13.2.3","commit":"90ffed056f0884267356c12a0eeb72a022af53f1"}

浏览器访问 http://服务器IP:3000/，使用环境变量中设定的 admin/q1w2e3r4 登录；Web 页面 <title> 已确认为 Grafana。

▶️ 实测登录业务接口（获取组织信息）：
curl -u admin:q1w2e3r4 http://localhost:3000/api/org
{"id":1,"name":"Main Org.","address":{"address1":"","address2":""}}

五、数据持久化说明

仪表盘、数据源、组织、用户等全部保存在 /var/lib/grafana/grafana.db（sqlite），已通过卷挂到宿主 /opt/data/grafana，容器重建不丢失。
插件目录 plugins、会话 sessions 同在此卷下。
备份：直接备份宿主目录即可：tar -czf grafana-backup.tar.gz /opt/data/grafana。

六、常用环境变量表

环境变量	默认	说明
`GF_SERVER_HTTP_PORT`	`3000`	HTTP 监听端口
`GF_SERVER_HTTP_ADDR`	空	监听地址，留空绑定所有网卡
`GF_SECURITY_ADMIN_USER`	`admin`	初始管理员用户名
`GF_SECURITY_ADMIN_PASSWORD`	空	初始管理员密码（未设则在 Web 首次初始化）
`GF_PATHS_DATA`	`/var/lib/grafana`	数据目录
`GF_PATHS_LOGS`	`/var/log/grafana`	日志目录
`GF_DATABASE_TYPE`	`sqlite3`	数据库类型，可改 `mysql`/`postgres`
`GF_SERVER_ROOT_URL`	`%(protocol)s://%(domain)s:%(http_port)s/`	对外完整 URL

💡 环境变量命名规则：GF_ + 配置段大写 + _ + 键大写，如 [server].http_port → GF_SERVER_HTTP_PORT。

七、常用配置参数说明（command）

需要临时注入命令行参数时可覆盖镜像默认 entrypoint：

    command:
      - --homepath=/usr/share/grafana
      - server

正常情况下无需自定义 command；环境变量已覆盖绝大多数配置。

八、配置文件持久化（conf 挂载）

将自定义 grafana.ini 挂载到容器 etc/grafana/：

services:
  grafana:
    image: grafana/grafana:13.2.3
    volumes:
      - /opt/data/grafana:/var/lib/grafana
      - ./grafana.ini:/etc/grafana/grafana.ini:ro

⚠️ 挂载后该文件优先级高于环境变量，二者冲突时以配置文件为准。

九、等价 docker run 运行方式

docker run -d --name grafana \
  -p 3000:3000 \
  -e GF_SECURITY_ADMIN_USER=admin \
  -e GF_SECURITY_ADMIN_PASSWORD=q1w2e3r4 \
  -v /opt/data/grafana:/var/lib/grafana \
  --restart unless-stopped \
  grafana/grafana:13.2.3

十、常用运维命令

# 查看实时日志
docker compose logs -f grafana

# 重启
docker compose restart grafana

# 停止
docker compose stop grafana

# 停止并删除容器（数据卷保留）
docker compose down

# 停止并删除容器+网络（数据卷保留）
docker compose down --remove-orphans

十一、常见问题（FAQ）

Q1：容器一直 Restarting？

docker compose logs grafana

常见原因是数据目录权限不足，日志会出现 GF_PATHS_DATA ... is not writable，执行 chown 472:472 /opt/data/grafana 后重启。

Q2：如何升级 Grafana？

# 修改镜像版本 tag 后
docker compose pull grafana
docker compose up -d

Q3：外部访问不了 3000 端口？ 确认宿主防火墙放行：ufw allow 3000/tcp。

十二、参考链接

Grafana 官方 Docker 部署文档：https://grafana.com/docs/grafana/latest/setup-grafana/installation/docker/
官方镜像：https://hub.docker.com/r/grafana/grafana