Docker 与 Docker Compose

为什么 Docker 常是第一站

官方镜像把运行时、依赖与默认配置打包成一个可复现的单元，起停、升级、回滚都只是换一个 tag。对学习与验证场景，Docker 是成本最低的路径。

一条命令跑起来

docker run -d \
  --name grafana \
  -p 3000:3000 \
  -v grafana-data:/var/lib/grafana \
  grafana/grafana-oss:12.1.0

浏览器打开 http://localhost:3000，用 admin / admin 登录后立即改密。示例版本号仅为占位，实际以官方镜像仓库中的可用 tag 为准。

镜像与关键参数速查

注意： 不给 -v 挂卷，容器一删，仪表盘与数据源配置就没了。生产与长期使用的实例务必持久化 /var/lib/grafana。

数据持久化两种方式

• 命名卷（推荐，省心）：上面命令中的 grafana-data:/var/lib/grafana。
• 绑定挂载（便于直接看文件）：先把宿主机目录交给 UID 472，再挂载：

sudo mkdir -p /srv/grafana
sudo chown 472:472 /srv/grafana
docker run -d --name grafana -p 3000:3000 \
  -v /srv/grafana:/var/lib/grafana grafana/grafana-oss:12.1.0

用环境变量完成初始化

容器首次启动时，Grafana 会读取 GF_ 前缀的环境变量做初始化，最常用的几个：

docker run -d --name grafana -p 3000:3000 \
  -e "GF_SECURITY_ADMIN_USER=admin" \
  -e "GF_SECURITY_ADMIN_PASSWORD=ChangeMe-Str0ng" \
  -e "GF_USERS_ALLOW_SIGN_UP=false" \
  grafana/grafana-oss:12.1.0

完整的命名规则与更多变量，见环境变量覆盖配置。

Docker Compose 示例

services:
  grafana:
    image: grafana/grafana-oss:12.1.0
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    environment:
      GF_USERS_ALLOW_SIGN_UP: "false"

volumes:
  grafana-data:

docker compose up -d 启动，docker compose down 停止；数据在卷里，随起随停都不丢。

升级容器

先备份卷，再换镜像 tag 重建容器：

docker run --rm -v grafana-data:/data -v "$PWD:/backup" \
  alpine tar czf /backup/grafana-data.tgz -C /data .
sed -i 's/12.1.0/12.2.0/' docker-compose.yaml
docker compose pull && docker compose up -d

数据库迁移会在容器启动时自动完成，细节见升级与回滚。

常见坑

• 权限报错：bind mount 后日志出现 permission denied，九成是宿主机目录不属 UID 472。
• 用 latest 图省事：标签漂移会让两次重建的实例版本不一致，生产请钉住具体版本号。
• 容器里访问宿主机服务：数据源 URL 写 localhost 会指向容器自己，宿主机服务用 http://host.docker.internal:9090 这类地址。
• 改了环境变量不生效：GF_SECURITY_ADMIN_PASSWORD 这类初始化变量只在首次建库时生效，之后改密码请走界面或 CLI。

下一步

• 配置项怎么调，看配置文件 grafana.ini与环境变量覆盖配置。
• 想把数据源也代码化，读Provisioning：配置即代码。
• 平台化部署，看Kubernetes 与 Helm 部署。