cAdvisor Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上以 Docker Compose 单服务方式部署 cAdvisor v0.60.6，完成宿主机端口与网段预检、镜像获取、服务启动、Web UI 与 /metrics 访问验证，并沉淀核心指标解读与日常运维命令。全文命令均在部署机（Ubuntu 22.04.4 LTS，192.168.146.128）逐条实测，回显照抄。

一、环境信息

本章记录部署机的真实环境基线，所有信息来自实测命令回显，读者可按同款命令核对自身环境。

操作系统：Ubuntu 22.04.4 LTS（x86_64）
主机 IP：192.168.146.128（网卡 ens33）
Docker 版本（docker --version 实测）：
```
Docker version 29.8.1, build 4a63305
```
Docker Compose 版本（docker compose version 实测）：
```
Docker Compose version v5.5.1
```
cAdvisor 版本：v0.60.6（镜像 ghcr.io/google/cadvisor:v0.60.6，镜像体积 107MB）
本次部署端口映射：宿主机 8116 → 容器内 8080（cAdvisor 默认监听端口为 8080）
本次部署网络：自定义 bridge 网络 cadvisor-net，子网 10.89.40.0/24
部署目录：/opt/data/quzuo/cadvisor-0-60-6/

cAdvisor 内部进程形态（docker compose top 实测，输出节选）：

SERVICE   #   UID   PID     PPID    C   STIME  TTY  TIME      CMD
cadvisor  1   root  316591  316567  28  23:03  ?    00:02:37  /usr/bin/cadvisor -logtostderr

💡 说明：cAdvisor 是 Go 编写的单二进制守护进程，容器内主进程即 /usr/bin/cadvisor -logtostderr，无任何外部依赖（不需要数据库/消息队列即可工作），因此本部署为单 service compose。

二、镜像选型说明

cAdvisor 官方发布的容器镜像仓库在 v0.53.0 发生过迁移，选错镜像源会拿到停更的旧版本，本章给出实测核实结论与选型依据。

官方镜像源迁移事实（官方 README 原文注释，查询日期 2026-10-18）：

ghcr.io/google/cadvisor:$VERSION # for versions prior to v0.53.0, use gcr.io/cadvisor/cadvisor instead

即 v0.53.0 起官方镜像统一发布在 ghcr.io/google/cadvisor；旧地址 gcr.io 于查询日实查其 tag 列表，版本 tag 最高止于 v0.55.1，且存在成批的 no-new-use-public-image-* tag，明确示意不要再使用。
ghcr.io 仓库版本核实（查询日期 2026-10-18，通过 Registry v2 API 实查）：仓库共 43 个 tag，v0.60.x 系列齐全：v0.60.1～v0.60.6，本次取最新稳定版 v0.60.6（对应 GitHub Release 发布时间 2026-09-18）。

版本与发布物对照：

形态	获取方式	说明
OCI 镜像	`ghcr.io/google/cadvisor:v0.60.6`	本文采用；另有 `latest` tag 但生产建议锁版本
Linux 二进制	GitHub Release 资产 `cadvisor-v0.60.6-linux-amd64` / `-arm64`	适合非容器化裸机部署（官方 docs/running.md standalone 方式）
Kubernetes	官方 deploy/kubernetes 目录 DaemonSet 清单	K8s 场景优先用 kubelet 内嵌 cAdvisor，无需独立部署

选型结论：Docker Compose 部署统一使用 ghcr.io/google/cadvisor:v0.60.6，固定版本 tag 而非 latest，保证升级可控、回滚可溯。

三、前置条件

部署前需复核两件硬性事项：宿主机端口空闲性、Docker 网段槽位占用。这两步的实测过程同时也是踩坑实录（8110 端口在部署窗口期被并行服务抢占），照做可避免端口冲突与服务启动失败。

3.1 端口复核

cAdvisor 容器内默认监听 8080，需要映射到宿主机空闲端口。先检查目标端口是否被占用：

ss -ltn | grep -E ':(8110|8080|8114|8115|8116)\s' || echo "PORTS_FREE"

实测回显（部署时点）：

LISTEN 0      4096         0.0.0.0:8080       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8114       0.0.0.0:*
LISTEN 0      4096            [::]:8114          [::]:*

结论：8080 与 8114 已被监听，8110/8115/8116 看似空闲。进一步用 ss -ltnp 看占用进程：

LISTEN 0      4096         0.0.0.0:8110       0.0.0.0:*    users:(("docker-proxy",pid=300010,fd=8))
LISTEN 0      4096         0.0.0.0:8114       0.0.0.0:*    users:(("docker-proxy",pid=78509,fd=8))
LISTEN 0      4096            [::]:8110          [::]:*    users:(("docker-proxy",pid=300017,fd=8))
LISTEN 0      4096            [::]:8114          [::]:*    users:(("docker-proxy",pid=78516,fd=8))

⚠️ 注意：8110 在第一次检查时空闲、几分钟内被另一服务抢占（kener-4-1-7-envtest 映射 0.0.0.0:8110->3456/tcp）；8115 也在随后被 kener-4-1-7-pg-app 映射 0.0.0.0:8115->3000/tcp 占用——多服务共用一台服务器时，端口选定与 docker compose up 应连续执行，避免窗口期被抢。本部署最终锁定 8116（ss -ltn 未出现监听，实测可绑）。

3.2 Docker 网段槽位复核

自定义网络必须显式指定 --subnet，且不得使用 192.168.0.0/16（含物理网段 192.168.146.0/24 与宿主机局域网 192.168.1.0/24）与 100.64.0.0/16。先盘点现有网络的子网占用：

for n in $(docker network ls --format '{{.Name}}'); do s=$(docker network inspect $n --format '{{range .IPAM.Config}}{{.Subnet}} {{end}}' 2>/dev/null); echo "$n: $s"; done

实测回显（查询时点）：

appwrite: 10.89.31.0/24
bookstack_default: 10.89.36.0/24
bridge: 10.0.0.0/24
browser: 10.89.34.0/24
docmost-0-96-0-net: 10.89.37.0/24
gateway: 10.89.30.0/24
host:
kener-compose_kener-net: 10.89.39.0/24
none:
runtimes: 10.89.32.0/24
teable-run-net: 10.89.35.0/24
teable-standalone-network: 10.89.33.0/24
zitadel: 10.89.38.0/24

结论：10.89.30～10.89.39 槽位已全部占用（原计划预分配的 39 已被 kener 占用），本部署顺延取 10.89.40.0/24。

创建网络并立即自检子网与宿主机路由：

docker network create -d bridge --subnet 10.89.40.0/24 cadvisor-net

实测回显：

596dc16848f46e3079b1670f1e97f7fa11e341675427b808cac9eb445201734a

docker network inspect cadvisor-net --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' && ip route get 192.168.1.62

实测回显：

10.89.40.0/24
192.168.1.62 via 192.168.146.2 dev ens33 src 192.168.146.128 uid 0
    cache

验证通过：子网落位 10.89.40.0/24（非禁用段），宿主机访问外网流量仍经 ens33 物理网卡（192.168.146.2 网关），未受新网桥影响。

💡 技术拓展：Docker 自定义 bridge 网络的子网来源有两种——不显式指定时由 daemon 从地址池自动分配（default-address-pools），显式 --subnet 则优先固定。生产环境强烈建议显式指定：自动分配可能与物理网段冲突（曾有组件自动分到 192.168.0.0/20 抢占默认路由导致整机断网的先例），固定网段还能按「10.89.槽位」规划全局地址表。

四、部署步骤

本章从编写 compose 文件到验证三项出口（健康检查/Web UI/metrics）给出完整 0→1 流程，全部命令实测通过。

4.1 编写 docker-compose.yml

在部署目录 /opt/data/quzuo/cadvisor-0-60-6/ 创建 docker-compose.yml：

services:
  cadvisor:
    image: ghcr.io/google/cadvisor:v0.60.6
    container_name: cadvisor-v0-60-6-main
    ports:
      - "8116:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    devices:
      - /dev/kmsg
    privileged: true
    restart: unless-stopped
    networks:
      default:
        aliases:
          - cadvisor

networks:
  default:
    name: cadvisor-net
    ipam:
      config:
        - subnet: 10.89.40.0/24

逐项说明（官方 docker run 示例等价转写为 compose 语法）：

image：锁定 v0.60.6 版本 tag（见「二、镜像选型说明」）。
container_name：实例名 cadvisor-v0-60-6-main，便于一眼识别组件与版本用途。
ports：8116:8080——宿主机 8116 映射容器内 cAdvisor 默认端口 8080。
volumes（五个只读挂载）：官方 Quick Start 固定要求——/→/rootfs（根文件系统分区识别）、/var/run（Docker socket 所在目录）、/sys（cgroup/sysfs 内核统计）、/var/lib/docker/（容器层磁盘用量统计）、/dev/disk/（磁盘设备与 UUID 信息），全部 :ro 只读。
devices：放行 /dev/kmsg，用于读取内核消息缓冲（OOM 事件等）。
privileged: true：官方示例要求特权运行（cAdvisor 需要读取内核级 cgroup 统计与部分设备）。
restart: unless-stopped：开机自启与异常退出自动拉起（手动 stop 后不再自动启动）。
networks：显式绑定 3.2 节创建的 cadvisor-net（10.89.40.0/24），并给服务配置网络别名 cadvisor 方便同网段其他组件按名访问。

4.2 拉取镜像

docker pull ghcr.io/google/cadvisor:v0.60.6

实测回显：

dfecceb8fdfa: Pull complete
Digest: sha256:b8e7d1093144fd088f425ff003d75a4aa405de075db78dae3bc563730b1bd07a
Status: Downloaded newer image for ghcr.io/google/cadvisor:v0.60.6

docker images | grep cadvisor

实测回显：

ghcr.io/google/cadvisor:v0.60.6                                     b8e7d1093144        107MB         30.7MB

镜像获取成功（107MB）。服务器 Docker 守护进程已配置代理（192.168.1.62:7897），ghcr.io 直拉无需额外操作；如遇拉取超时，先检查代理可用性再重试。

4.3 启动服务

docker compose up -d

实测回显：

 Container cadvisor-v0-60-6-main Starting
 Container cadvisor-v0-60-6-main Started

docker compose ps

实测回显（启动数秒后，健康状态从 health: starting 翻转为 healthy）：

NAME                    IMAGE                             COMMAND                   SERVICE    CREATED         STATUS                   PORTS
cadvisor-v0-60-6-main   ghcr.io/google/cadvisor:v0.60.6   "/usr/bin/entrypoint…"   cadvisor   9 minutes ago   Up 9 minutes (healthy)   0.0.0.0:8116->8080/tcp, [::]:8116->8080/tcp

查看启动日志确认采集能力加载正常：

docker logs cadvisor-v0-60-6-main 2>&1 | head -3

实测回显：

I1018 15:03:53.428544       1 cadvisor.go:126] enabled metrics: app,cpu,cpuLoad,disk,diskIO,memory,network,oom_event,percpu,perf_event,pressure
I1018 15:03:53.428805       1 storagedriver.go:55] Caching stats in memory for 2m0s
I1018 15:03:53.463052       1 fs.go:119] Filesystem UUIDs: map[43e68207-7df4-4f66-933a-8a595cdde8c8:/dev/sda3 7C90-153C:/dev/sda2]

日志解读：第一行列出默认启用的 11 个指标组（app、cpu、cpuLoad、disk、diskIO、memory、network、oom_event、percpu、perf_event、pressure）；第二行说明内存缓存保留时长 2 分钟；第三行起为磁盘分区与 UUID 识别结果。三者分别对应 metrics 内容、历史数据深度与文件系统指标来源。

4.4 验证一：健康检查端点

curl -s --max-time 10 http://localhost:8116/healthz -w "\nHTTP_CODE:%{http_code}\n"

实测回显：

ok
HTTP_CODE:200

/healthz 返回 ok、HTTP 200，即服务进程健康（内部容器健康检查同样基于该端点，docker compose ps 的 healthy 状态即由此而来）。

4.5 验证二：Web UI

先确认根路径行为与页面可达性：

curl -sI --max-time 10 http://localhost:8116/ | head -6

实测回显：

HTTP/1.1 307 Temporary Redirect
Content-Type: text/html; charset=utf-8
Location: /containers/
Date: Sun, 18 Oct 2026 15:04:11 GMT

curl -s --max-time 10 http://localhost:8116/containers/ | grep -oE '<title>[^<]*</title>' | head -2

实测回显：

<title>cAdvisor - /</title>

浏览器访问 http://192.168.146.128:8116/（自动 307 跳转到 /containers/）即进入 cAdvisor Web UI：首页展示整机概览，页面按 cgroup 层级树列出每个容器的 CPU、内存、网络、文件系统曲线，页面标题 cAdvisor - / 表示当前浏览的是根层级。

4.6 验证三：/metrics（Prometheus 指标）

curl -s --max-time 15 http://localhost:8116/metrics | wc -l

实测回显：

curl -s --max-time 15 http://localhost:8116/metrics | grep -c '^# HELP'

实测回显：

即 /metrics 共 1 万余行、118 个指标族（指标族数随容器数量小幅波动）。抽查整机指标与本组件自身进程指标：

curl -s http://localhost:8116/metrics | grep -E '^machine_(cpu_cores|memory_bytes)'

实测回显（输出节选，保留关键行）：

machine_cpu_cores{boot_id="70ba7d91-2d66-4b9e-86a5-d291c7904c49",machine_id="c01f6b5b1b0b405fba2ef8797d335efc",system_uuid="32074d56-8f30-5439-31f0-14b7ebd3b4d8"} 12 1792335833489
machine_memory_bytes{boot_id="70ba7d91-2d66-4b9e-86a5-d291c7904c49",machine_id="c01f6b5b1b0b405fba2ef8797d335efc",system_uuid="32074d56-8f30-5439-31f0-14b7ebd3b4d8"} 3.3607307264e+10 1792335833489

curl -s http://localhost:8116/metrics | grep '^container_cpu_usage_seconds_total{' | grep 'name="cadvisor-v0-60-6-main"' | head -1 | cut -c1-200

实测回显（输出节选，单条指标 label 过长，此处截取前 200 字符）：

container_cpu_usage_seconds_total{container_label_base_image="",container_label_build_version="",container_label_com_clickhouse_build_version="", ...} 44.060278 1792335863043

指标可正常导出：整机 12 核、内存 33.6GB（3.3607307264e+10 字节 ≈ 31.3GiB），cAdvisor 自身进程累计 CPU 时间 44.06 秒。

⚠️ 注意：默认配置会把容器的全部 labels 与环境变量转成 Prometheus label（上面单条指标因此拉得极长）。容器多、标签杂的宿主机建议按《cAdvisor v0.60.6 配置参数详解》启用 --store_container_labels=false 白名单模式收敛。

4.7 验证四：REST API（可选）

cAdvisor 同时暴露版本化 REST API，取根 cgroup 最新一条统计验证：

curl -s http://localhost:8116/api/v1.3/containers/ | python3 -c "import json,sys; d=json.load(sys.stdin); s=d['stats'][-1]; print(s['timestamp'])"

实测回显：

2026-10-18T15:08:02.41856401Z

API 返回 JSON 且时间戳实时滚动，说明统计采集循环正常工作。

至此部署验证闭环完成：进程 healthy + healthz 200 + Web UI 可浏览 + /metrics 118 个指标族 + REST API 实时。三项出口的地址汇总：

出口	地址（本部署）	用途
Web UI	`http://192.168.146.128:8116/`	人工浏览容器层级与曲线
Prometheus	`http://192.168.146.128:8116/metrics`	Prometheus/Grafana 生态抓取
REST API v1.3	`http://192.168.146.128:8116/api/v1.3/containers/`	程序化查询原始统计
健康检查	`http://192.168.146.128:8116/healthz`	探活（负载均衡/健康检查）

五、数据持久化说明

cAdvisor 与传统有状态服务不同，本章说清「哪些数据在内存、哪些要外发、磁盘上要留什么」，避免按惯性挂载无用卷。

统计数据：设计上只驻留内存。cAdvisor 把逐容器统计以环形缓冲缓存在内存，默认保留 2 分钟（启动日志 Caching stats in memory for 2m0s 即此含义）。无需也无法为统计数据挂载持久卷——超过 2 分钟的历史数据必须由外部系统承接：Prometheus 按抓取周期拉走 /metrics 落入自身时序库，或用 --storage_driver 把统计推送到 influxdb/kafka/redis 等后端（配置方法见《cAdvisor v0.60.6 配置参数详解》）。
本部署无需任何持久卷：compose 文件中的 5 个 volumes 全部是 :ro 只读挂载，目的是「读取宿主机状态」而非「写入数据」，cAdvisor 自身不向磁盘写任何业务数据（日志走 stderr，由 Docker 日志驱动接管，见下条）。
日志持久化：cAdvisor 以 -logtostderr 启动（docker compose top 可见），日志由 Docker 默认 json-file 驱动落盘在 /var/lib/docker/containers/<id>/，可用 docker logs/docker compose logs 查看；如需限制日志体积，可在 compose 的 service 上配置 logging: {driver: json-file, options: {max-size: "50m", max-file: "3"}}。

六、环境变量表

cAdvisor 不依赖环境变量做配置——全部配置通过启动参数（命令行 flag）传入，容器镜像也没有声明任何可用的 ENV 配置项。因此本部署无 environment: 段，等价的配置入口是 compose 的 command: 或容器参数（见「七、配置参数说明」与《cAdvisor v0.60.6 配置参数详解》）。

以下环境变量仅为容器运行时通用项，列出供排查参考（非 cAdvisor 配置通道）：

环境变量	是否必需	说明
PATH	否	镜像内置默认 PATH，无需修改
HTTP_PROXY / HTTPS_PROXY	否	cAdvisor 本身不主动外联；仅当配置 stdout 之外需要外网的 storage driver（如 BigQuery）时才相关

⚠️ 注意：社区常见把 cAdvisor 配置写成 environment: 传入的做法是无效的——cAdvisor 不解析环境变量，必须用命令行 flag。这是本组件与很多「ENV 驱动配置」镜像的差异点。

七、配置参数说明

compose 部署下给 cAdvisor 传参的规范位置是 service 的 command:，本章给出最常用的三组启动参数写法与默认值速查，参数级逐项实测与效果对比见《cAdvisor v0.60.6 配置参数详解》。

7.1 在 compose 中传参

在 service 下追加 command: 即可（镜像 entrypoint 会把参数转交给 /usr/bin/cadvisor）：

services:
  cadvisor:
    image: ghcr.io/google/cadvisor:v0.60.6
    command:
      - --housekeeping_interval=5s
      - --docker_only=true
      - --store_container_labels=false

修改后 docker compose up -d 重建实例生效。

7.2 默认值速查（来自 v0.60.6 `--help` 实测输出）

参数	默认值	作用
`--housekeeping_interval`	1s	每容器统计采样间隔，资源开销主源头
`--allow_dynamic_housekeeping`	true	允许动态拉长采样间隔
`--storage_duration`	2m0s	内存缓存保留时长
`--port`	8080	监听端口
`--docker_only`	false	只报告 Docker 容器与根 cgroup
`--store_container_labels`	true	容器 labels/环境变量是否转 Prometheus label
`--disable_metrics`	advtcp,cpu_topology,cpuset,hugetlb,memory_numa,process,referenced_memory,resctrl,sched,tcp,udp	默认禁用的指标组
`--event_storage_event_limit`	default=100000	每类事件保留条数上限
`--event_storage_age_limit`	default=24h	每类事件保留时长上限
`--max_procs`	0（=CPU 核数）	可同时使用的 CPU 上限

八、配置文件挂载

cAdvisor 支持少量「文件型配置」，本章说明各自用途与挂载写法，均可在第八章的 volumes 中追加。

文件	传入参数	用途	挂载写法（compose volumes 追加）
认证口令文件	`--http_auth_file`	Web UI Basic 认证（htpasswd 格式，bcrypt/apr1）	`- ./auth/htpasswd:/etc/cadvisor/htpasswd:ro`
认证口令文件	`--http_digest_file`	Web UI Digest 认证	`- ./auth/htdigest:/etc/cadvisor/htdigest:ro`
容器提示文件	`--container_hints`	为 raw 驱动容器补充元信息（默认 `/etc/cadvisor/container_hints.json`）	`- ./container_hints.json:/etc/cadvisor/container_hints.json:ro`
perf 事件配置	`--perf_events_config`	自定义 perf 事件采集（JSON）	`- ./perf_events.json:/etc/cadvisor/perf_events.json:ro`
TLS 证书	`--collector_cert`/`--collector_key`	自定义 metrics collector 端点的证书认证	按需只读挂载

以 Basic 认证为例的完整组合（口令文件生成与 401/200 实测过程见《cAdvisor v0.60.6 配置参数详解》）：

    volumes:
      - ./auth/htpasswd:/etc/cadvisor/htpasswd:ro
    command:
      - --http_auth_file=/etc/cadvisor/htpasswd

⚠️ 注意：--http_auth_file 只保护 Web UI（/containers/），/metrics 与 /api/v1.3/ 不受该认证控制（实测：配置认证后 /containers/ 无凭据返回 401，而 /metrics 无凭据仍返回 200）。生产暴露时应在反向代理层对 /metrics 一并加认证或做网络隔离。

九、等价 docker run

与 4.1 节 compose 完全等价的 docker run 命令如下（便于无 compose 环境或在官方示例基础上比对）：

docker run -d \
  --name cadvisor-v0-60-6-main \
  --privileged \
  --device=/dev/kmsg \
  -p 8116:8080 \
  -v /:/rootfs:ro \
  -v /var/run:/var/run:ro \
  -v /sys:/sys:ro \
  -v /var/lib/docker/:/var/lib/docker:ro \
  -v /dev/disk/:/dev/disk:ro \
  --network cadvisor-net \
  --restart unless-stopped \
  ghcr.io/google/cadvisor:v0.60.6

两种方式的对应关系：compose 的 ports: ↔ -p、volumes: ↔ -v、devices: ↔ --device、privileged: true ↔ --privileged、networks.default ↔ --network（compose 里额外声明的 ipam 子网在 docker run 方式下需先按 3.2 节手工 docker network create --subnet 10.89.40.0/24 cadvisor-net）。

十、常用运维命令

以下命令均在部署目录 /opt/data/quzuo/cadvisor-0-60-6/ 下实测。

查看运行状态：

docker compose ps

实测回显：

NAME                    IMAGE                             COMMAND                   SERVICE    CREATED         STATUS                   PORTS
cadvisor-v0-60-6-main   ghcr.io/google/cadvisor:v0.60.6   "/usr/bin/entrypoint…"   cadvisor   9 minutes ago   Up 9 minutes (healthy)   0.0.0.0:8116->8080/tcp, [::]:8116->8080/tcp

查看实时资源占用：

docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}' cadvisor-v0-60-6-main

实测回显（瞬时采样）：

NAME                     CPU %     MEM USAGE / LIMIT
cadvisor-v0-60-6-main    5.88%     1.906GiB / 31.3GiB

💡 说明：cAdvisor 的内存占用与宿主机容器数量正相关（逐容器维护统计缓存），本宿主机容器规模较大（60+）时 1～2GiB 属正常量级；容器少的宿主机通常仅几十 MiB。降配手法（--docker_only、拉长采样间隔等）与实测对比数据见《cAdvisor v0.60.6 配置参数详解》。

查看日志：

docker compose logs --tail 3

实测回显（输出节选）：

cadvisor-v0-60-6-main  | I1018 15:05:10.610567       1 fsHandler.go:135] fs: disk usage and inodes count on following dirs took 2.446210344s: [/var/lib/docker/rootfs/overlayfs/5a9fb63e63182c25e52a233c...
cadvisor-v0-60-6-main  | I1018 15:05:20.515731       1 fsHandler.go:135] fs: disk usage and inodes count on following dirs took 7.240499621s: [/var/lib/docker/rootfs/overlayfs/5edd02023bfdbc0b9a98f308...

fsHandler.go 的耗时日志表示容器层磁盘用量统计（du）在容器多/盘慢的宿主机上耗时较长，属提示性日志，不影响服务；如磁盘统计开销成为负担，可用 --docker_only 或 --disable_metrics 收敛采集范围。

重启服务（改配置后生效）：

docker compose restart

实测回显：

 Container cadvisor-v0-60-6-main Started

curl -s --max-time 10 http://localhost:8116/healthz -w " HTTP_CODE:%{http_code}\n"

实测回显（重启后 6 秒）：

ok HTTP_CODE:200

升级版本：把 compose 中 image tag 改为目标版本（如 v0.60.7），执行 docker compose pull && docker compose up -d，随即用 4.4～4.6 的三条验证命令回归。回滚则把 tag 改回旧版本重跑同一组命令（统计数据在内存，重启即重建，无数据迁移负担）。

停止与启动：

docker compose stop    # 停止（容器保留）
docker compose start   # 再次启动
docker compose down    # 停止并删除容器与网络（compose 配置保留，可随时 up 重建）

十一、常见问题

Q1：docker compose up 报 "Bind for 0.0.0.0:xxxx failed: port is already allocated"？ 宿主机端口已被其他映射占用。本次部署实测记录：预分配 8110 后在部署窗口期被并行服务抢占，up -d 直接失败——

Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint cadvisor-v0-60-6-main (...): Bind for 0.0.0.0:8115 failed: port is already allocated

解决：ss -ltn | grep :<端口> 重新选一个当前空闲端口（本例顺延到 8116），改 compose 的 ports 后重新 docker compose up -d。多服务共用宿主机时建议「选定端口后立即启动」，并避开 8080 这类高频默认端口。

Q2：启动后 docker compose ps 一直 health: starting 或 unhealthy？ 健康检查依赖容器内 /healthz。先看启动日志定位：docker compose logs --tail 50。常见原因：(1) 缺少挂载——漏掉 /sys 或 /var/lib/docker 挂载时统计初始化失败；(2) 端口冲突——容器内 8080 被占（一般不会，除非自行改过 --port 却没同步改 ports）；(3) /dev/kmsg 不可读——宿主机内核过严时删除 devices 段重试（功能上仅影响 OOM 事件类指标）。

Q3：浏览器打开 Web UI 卡顿或 /metrics 抓取超时？ 容器数量大时默认全量指标（含 percpu、全部容器 label）体积大（本环境实测 1 万余行/118 个指标族），抓取与渲染开销随之上升。解决路径：--store_container_labels=false + 白名单、--docker_only=true、必要时拉长 --housekeeping_interval，三者叠加后 /metrics 体积与进程内存都有量级下降（参数逐项实测见《cAdvisor v0.60.6 配置参数详解》）。

Q4：Web UI 能加访问密码吗？/metrics 也会被保护吗？ 可以加 Basic 认证：生成 htpasswd 文件（账号 admin）挂载后加 --http_auth_file=/etc/cadvisor/htpasswd，实测无凭据访问 /containers/ 返回：

HTTP/1.1 401 Unauthorized
Content-Type: text/plain
Www-Authenticate: Basic realm="localhost"

正确凭据（admin/q1w2e3r4）返回 200。但注意 /metrics 与 REST API 不受该文件保护（实测无凭据仍 200），需要一并防护时在反代层处理或仅绑定内网网卡（--listen_ip）。

Q5：历史数据只有 2 分钟，图表回看不了怎么办？ 这是设计行为：--storage_duration 默认 2m0s，cAdvisor 只做短周期缓存。长期历史二选一：(1) Prometheus 抓取 /metrics 落库 + Grafana 看板；(2) --storage_driver 直推 influxdb/kafka 等后端。两条路线的参数配置见《cAdvisor v0.60.6 配置参数详解》。

Q6：gcr.io/cadvisor/cadvisor 拉不到新版本 tag？ 官方镜像仓库自 v0.53.0 起迁移到 ghcr.io（见「二、镜像选型说明」），gcr.io 版本 tag 停在 v0.55.1 且带 no-new-use-public-image-* 标记。改用 ghcr.io/google/cadvisor:v0.60.6 即可。

十二、参考链接

官方仓库 Quick Start（本文挂载与参数依据）：https://github.com/google/cadvisor
v0.60.6 Release 页：https://github.com/google/cadvisor/releases/tag/v0.60.6
官方镜像仓库（ghcr.io）：https://ghcr.io/google/cadvisor
官方运行文档（standalone / 容器化 / K8s）：https://github.com/google/cadvisor/blob/v0.60.6/docs/running.md
官方运行参数文档：https://github.com/google/cadvisor/blob/v0.60.6/docs/runtime_options.md
官方存储驱动文档：https://github.com/google/cadvisor/blob/v0.60.6/docs/storage/README.md
官方 Web UI 文档：https://github.com/google/cadvisor/blob/v0.60.6/docs/web.md
本组件配套文档：《cAdvisor v0.60.6 介绍与选型指南》《cAdvisor v0.60.6 配置参数详解》

cAdvisor Docker Compose 部署指南

cAdvisor Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

3.1 端口复核

3.2 Docker 网段槽位复核

四、部署步骤

4.1 编写 docker-compose.yml

4.2 拉取镜像

4.3 启动服务

4.4 验证一：健康检查端点

4.5 验证二：Web UI

4.6 验证三：/metrics（Prometheus 指标）

4.7 验证四：REST API（可选）

五、数据持久化说明

六、环境变量表

七、配置参数说明

7.1 在 compose 中传参

7.2 默认值速查（来自 v0.60.6 --help 实测输出）

八、配置文件挂载

九、等价 docker run

十、常用运维命令

十一、常见问题

十二、参考链接

7.2 默认值速查（来自 v0.60.6 `--help` 实测输出）