用 Docker Compose 30 分钟搭起本地 Prometheus + Grafana 监控（附 5 个踩坑）

为什么要在本地搭一套

做开发或者小团队自建服务时，想看一眼 QPS、内存、接口耗时，第一反应往往是“上云监控”。其实 Prometheus + Grafana 这条链路完全可以在笔记本上用 docker compose 跑起来：零费用、十分钟能拆、随手改配置。下面是我实际跑通的一套最小配置，以及踩到的 5 个坑。

一、目录结构

monitoring/
├── docker-compose.yml
├── prometheus/
│   └── prometheus.yml
└── grafana/        # 为空即可，数据会落在命名卷里

二、docker-compose.yml

services:
  prometheus:
    image: prom/prometheus:v2.54.1
    container_name: prom
    restart: unless-stopped
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=7d
      - --web.enable-lifecycle
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:11.2.0
    container_name: grafana
    restart: unless-stopped
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=change-me
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - "3000:3000"
    depends_on:
      - prometheus

volumes:
  prom-data:
  grafana-data:

三、prometheus.yml：先把自己采集起来

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

四、启动与验证

docker compose up -d
curl -s localhost:9090/-/healthy   # 期望输出 Prometheus is Healthy.

打开 http://localhost:3000 ，用 admin / change-me 登录，添加数据源时类型选 Prometheus，地址填 http://prometheus:9090，保存后点 Save & test 应当显示数据源可用。

五、5 个真实踩到的坑

1. 数据源填 localhost:9090 必然连不上。Grafana 在容器里访问的是自己的 localhost，不是宿主机。必须用 compose 的服务名 prometheus 走容器内网。
2. 宿主机时间不准，曲线会出现断点。Prometheus 按时间戳对齐样本，NTP 漂移会让 15s 的间隔变成几十秒。先 chronyc sources 或 sntp 校时。
3. 改了 retention 但磁盘没变小。retention 只影响新写入的清理，历史块需要等压缩；如果之前把卷建错过位置，先 docker compose down 再重建卷。
4. 3000 端口被前端脚手架占了。很多项目默认也用 3000，改成 "3001:3000"，容器内不变，只改宿主机映射。
5. 改 prometheus.yml 不生效。ro 挂载只是防止容器写坏文件，配置重载要 curl -X POST http://localhost:9090/-/reload ，前提是启动时加了 --web.enable-lifecycle。

六、再加一个 node_exporter 看主机

  node-exporter:
    image: prom/node-exporter:v1.8.1
    pid: host
    volumes:
      - /:/host:ro
    command: ["--path.rootfs=/host"]
    ports:
      - "9100:9100"

在 scrape_configs 里追加一个抓 "node-exporter:9100" 的 job，再到 Grafana 导入模板 ID 1860，主机 CPU、内存、磁盘、网络就都有大盘了。

结语

这套环境很适合本地验证告警规则、调 Dashboard、演练 PromQL，用完 docker compose down -v 一行清干净。真要上生产，记得把默认密码换掉、给 Grafana 加 SSO 或反向代理鉴权、数据卷放持久盘，并在 Prometheus 上规划好远程写或联邦，避免单点。