cAdvisor —— 容器资源与性能采集器（cgroup → /metrics → Prometheus）

分类：06 容器与云原生监控 适用：Docker / containerd / CRI-O 单机容器监控、K8s 每节点容器资源指标；每节点一个实例 一句话：读取 cgroup 与 /proc 暴露 container_* Prometheus 指标，是 K8s 容器资源指标的事实来源 官方：https://github.com/google/cadvisor 授权：Apache License 2.0（开源）

版本说明：官方镜像自 v0.53.0 起为 ghcr.io/google/cadvisor，更早为 gcr.io/cadvisor/cadvisor；版本/tag 一律写「以官方最新稳定版为准」。K8s 现状：kubelet 自 2015 年起内嵌 cAdvisor，v1.7 起把容器指标拆到独立 /metrics/cadvisor 端点，v1.12 移除了独立 cAdvisor Web UI 与 --cadvisor-port 参数，但内嵌 cAdvisor 仍在、指标仍由 /metrics/cadvisor 暴露；当前官方系统指标文档仍明确列出该端点。

1. 它解决什么问题

不适合：业务应用自定义指标（用 Prometheus client library）；K8s 对象状态如副本数/Pod Phase（用 kube-state-metrics）；kubectl top/HPA 所需的 Metrics API（用 metrics-server）；主机硬件/OS 全局指标（用 node_exporter）。cAdvisor 自身不存储、不告警、不画图，这三者分别交给 Prometheus、Alertmanager、Grafana。

2. 核心概念与架构

 Linux 内核（每台宿主机）            cAdvisor / kubelet :8080/:10250        Prometheus / 消费
┌──────────────────────┐  读取   ┌────────────────────────────┐  pull  ┌──────────────┐
│ /sys/fs/cgroup        │────────►│ 容器发现（cgroup 层级）      │ /metrics│  scrape      │
│  cpu.stat / memory.*  │         │  Housekeeping: 1s/容器      │────────►│ manager      │
│  blkio / net_cls      │         │  聚合: container_*/machine_* │        └──────┬───────┘
│ /proc/*/stat, /proc/net│────────►│  Web UI /  /api/v1.3/...    │               ▼
│ /dev/disk, docker.sock│         │  可选 storage_driver 推送   │     TSDB → Grafana /
└──────────────────────┘         └────────────────────────────┘     Alertmanager 告警

数据链路：cgroup 数据来源 → /metrics → Prometheus 抓取。cAdvisor 是无状态旁路进程，每次抓取现读内核数据；只在内存里保留很短历史（--storage_duration 默认 2m）用于 UI 曲线；持久化、阈值告警、可视化全部由外部承担。

K8s 中 kubelet 内置 cAdvisor 的现状（重点）

结论：K8s 集群通常不需要单独部署 cAdvisor，Prometheus 抓 kubelet 即可；独立 cAdvisor 主要用于裸 Docker / containerd 主机、需要 Web UI 或 kubelet 指标被裁剪的场景。

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

# 版本一律以官方最新稳定版为准
export CADVISOR_VER=<以官方最新稳定版为准>
# A. 官方 Docker 镜像（README 快速上手，裸 Docker 主机每机一个）
sudo docker run --volume=/:/rootfs:ro --volume=/var/run:/var/run:ro --volume=/sys:/sys:ro \
  --volume=/var/lib/docker/:/var/lib/docker:ro --volume=/dev/disk/:/dev/disk:ro \
  --publish=8080:8080 --detach=true --name=cadvisor --privileged --device=/dev/kmsg \
  ghcr.io/google/cadvisor:${CADVISOR_VER}
# 注：v0.53.0 之前用 gcr.io/cadvisor/cadvisor:${CADVISOR_VER}
# B. 二进制 + systemd（物理机 / VM）
curl -fsSL -o /usr/local/bin/cadvisor <官方 Releases 资产 URL> && chmod +x /usr/local/bin/cadvisor
cat >/etc/systemd/system/cadvisor.service <<'EOF'
[Service]
Type=simple
ExecStart=/usr/local/bin/cadvisor --port=8080 --housekeeping_interval=5s --logtostderr
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now cadvisor
# C. Docker Compose（单机调试）

# docker-compose.yaml —— tag 以官方最新稳定版为准
services:
  cadvisor:
    image: ghcr.io/google/cadvisor:${CADVISOR_VER}
    container_name: cadvisor
    privileged: true
    devices: ["/dev/kmsg"]
    volumes: ["/:/rootfs:ro", "/var/run:/var/run:ro", "/sys:/sys:ro", "/var/lib/docker/:/var/lib/docker:ro", "/dev/disk/:/dev/disk:ro"]
    ports: ["8080:8080"]
    restart: unless-stopped

docker compose up -d && docker compose ps
# D. K8s：优先抓 kubelet /metrics/cadvisor（见 4.4），无需部署；确需独立 DaemonSet 时用官方清单
kubectl apply -k github.com/google/cadvisor/deploy/kubernetes/<以官方目录为准>
kubectl -n cadvisor get ds,pod -o wide

⚠️ K8s 里独立部署 cAdvisor 时，旧版 kubelet 可能占用 hostPort 4194，需按官方 deploy/kubernetes 说明调整端口映射；且 DaemonSet 与 kubelet 内置指标会双份采集，注意去重与额外开销。

3.3 首次启动与验证

curl -sS -o /dev/null -w 'Web UI HTTP %{http_code}\n' http://localhost:8080/          # 预期 200
curl -sS http://localhost:8080/healthz                                                # 预期 ok
curl -sS http://localhost:8080/metrics | grep -m1 '^container_cpu_usage_seconds_total'  # 预期带标签样本行
curl -sS http://localhost:8080/api/v1.3/containers/ | head -c 300                     # 预期 JSON 容器树
curl -sS http://localhost:8080/metrics | grep -c '^container_'                        # 预期 > 0；浏览器 :8080 看 CPU/Memory/Network/Filesystem 子页

4. 配置文件详解

cAdvisor 没有主配置文件，全部通过命令行参数 / 环境变量（容器用 command:）配置；本节给出启动参数表与「独立部署 + Prometheus 抓取」的完整可运行最小示例。

4.1 启动参数关键项（来自官方 docs/runtime_options.md）

4.2 完整可运行最小示例：独立部署命令

# 带常用调优参数的最小启动（对应 3.2 A，替换镜像 tag 即可运行）
docker run -d --name cadvisor -p 8080:8080 --privileged --device=/dev/kmsg \
  -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 \
  ghcr.io/google/cadvisor:${CADVISOR_VER} \
  --port=8080 --housekeeping_interval=5s --storage_duration=2m0s \
  --disable_metrics=percpu,tcp,udp,advtcp --logtostderr

4.3 完整可运行最小示例：Prometheus 抓取（裸 Docker 主机）

# prometheus.yml —— 抓独立 cAdvisor
scrape_configs:
  - job_name: cadvisor
    static_configs:
      - targets: ['<HOST1>:8080', '<HOST2>:8080']
    metrics_path: /metrics
    scrape_interval: 15s

4.4 完整可运行最小示例：K8s 抓 kubelet 内置 cAdvisor

# prometheus.yml —— K8s 场景，抓 kubelet :10250 的 /metrics/cadvisor（无需独立部署 cAdvisor）
scrape_configs:
  - job_name: kubernetes-cadvisor
    scheme: https
    metrics_path: /metrics/cadvisor
    tls_config:
      ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      insecure_skip_verify: true          # 无节点证书时用；生产建议改为证书校验
    bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
    kubernetes_sd_configs:
      - role: node
    relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)

# 所需 RBAC（官方系统指标文档最小形态，以集群版本官方文档为准）
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata: { name: prometheus-cadvisor }
rules: [{ nonResourceURLs: ["/metrics", "/metrics/cadvisor"], verbs: ["get"] }]

也可经 apiserver 代理抓取：/api/v1/nodes/<node>/proxy/metrics/cadvisor（需相应 RBAC）。⚠️ 不要再依赖已废弃的 :10255 只读端口或 --cadvisor-port。

5. 核心使用方法

5.1 命令与查询集（编号 1~22 + 5.2 指标表）

# --- 部署与参数 ---
# 1) 官方镜像启动（完整挂载，见 4.2）
docker run -d --name cadvisor -p 8080:8080 --privileged --device=/dev/kmsg \
  -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 \
  ghcr.io/google/cadvisor:${CADVISOR_VER}
# 2) 版本 / 3) 改端口与采集间隔
/usr/local/bin/cadvisor --version
/usr/local/bin/cadvisor --port=9091 --housekeeping_interval=10s
# 4) 关闭高基数指标类别 / 5) 只保留容器 cgroup
/usr/local/bin/cadvisor --disable_metrics=percpu,tcp,udp,advtcp,resctrl
/usr/local/bin/cadvisor --docker_only --raw_cgroup_prefix_whitelist=/kubepods
# 6) 标签基数 / 7) 环境变量白名单
/usr/local/bin/cadvisor --store_container_labels=false --whitelisted_container_labels=app,env
/usr/local/bin/cadvisor --env_metadata_whitelist=APP_ENV,JAVA_OPTS
# 8) Podman socket / 9) Basic 认证 / 10) 反代前缀与 pprof
/usr/local/bin/cadvisor --podman=unix:///var/run/podman/podman.sock
/usr/local/bin/cadvisor --http_auth_file=/etc/cadvisor/htpasswd --http_auth_realm=cadvisor
/usr/local/bin/cadvisor --url_base_prefix=/cadvisor --profiling
# --- 端点验证 ---
# 11) Web UI / 健康检查 / 版本化 REST API
curl -sS -o /dev/null -w '%{http_code}\n' http://<HOST>:8080/
curl -sS http://<HOST>:8080/healthz
curl -sS http://<HOST>:8080/api/v1.3/containers/ | jq '.subcontainers[0].name'
# 12) 抓全量指标 / 只看 CPU / 只看内存
curl -sS http://<HOST>:8080/metrics > /tmp/cadvisor.metrics
grep '^container_cpu_usage_seconds_total' /tmp/cadvisor.metrics | head
grep '^container_memory_working_set_bytes' /tmp/cadvisor.metrics | head
# 13) 看机器级指标 / 指标类别数
grep '^machine_cpu_cores' /tmp/cadvisor.metrics
grep '^container_' /tmp/cadvisor.metrics | wc -l
# --- K8s 端点 ---
# 14) 直接查 kubelet（需 token，示例用 kubectl proxy 转发）
kubectl get --raw "/api/v1/nodes/<node>/proxy/metrics/cadvisor" | grep '^container_memory_working_set_bytes' | head
# 15) 另两个 kubelet 端点
kubectl get --raw "/api/v1/nodes/<node>/proxy/metrics/resource" | head
kubectl get --raw "/api/v1/nodes/<node>/proxy/metrics/probes" | head
# 16) 服务管理
systemctl status cadvisor && journalctl -u cadvisor -f
docker logs -f cadvisor 2>&1 | grep -iE 'error|failed'
# --- 常用 PromQL（在 Prometheus/Grafana 执行）---
# 17) 容器 CPU 使用率（核数）
sum by (name) (rate(container_cpu_usage_seconds_total{name!=""}[5m]))
# 18) CPU 节流占比（quota 撞限）
sum by (name) (rate(container_cpu_cfs_throttled_periods_total[5m])) / sum by (name) (rate(container_cpu_cfs_periods_total[5m]))
# 19) 内存工作集 / limit 使用率（排除无 limit 容器）
container_memory_working_set_bytes{name!=""} / (container_spec_memory_limit_bytes{name!=""} > 0)
# 20) 容器网络收发速率
sum by (name) (rate(container_network_receive_bytes_total[5m]))
sum by (name) (rate(container_network_transmit_bytes_total[5m]))
# 21) OOM 事件与最近存活
increase(container_oom_events_total[10m]) > 0
time() - container_last_seen > 120
# 22) 文件系统用量 / 丢包
container_fs_usage_bytes / container_fs_limit_bytes
sum by (name) (rate(container_network_receive_packets_dropped_total[5m]))

5.2 关键指标清单（官方 docs/storage/prometheus.md）

container_* 标签常见 id（cgroup 路径）、name、image、container、pod、namespace、device、interface；K8s 场景以 pod/namespace/container 聚合，空 name 常是根/暂停容器，查询时注意过滤。

6. 告警与通知

cAdvisor 无内置告警，用 Prometheus container_* 规则 + Alertmanager 通知。注意 container_spec_memory_limit_bytes 可能为 0（无 limit），除法必须加 > 0 保护。

# prometheus/rules.yml —— 容器资源告警（limit 可能为 0，除法加 >0 保护）
groups:
  - name: container-resources
    rules:
      - { alert: ContainerMemoryNearLimit, expr: '(container_memory_working_set_bytes{name!=""} / (container_spec_memory_limit_bytes{name!=""} > 0)) > 0.85', for: 5m, labels: {severity: warning} }
      - { alert: ContainerCpuThrottled, expr: '(sum by (name) (rate(container_cpu_cfs_throttled_periods_total[5m])) / sum by (name) (rate(container_cpu_cfs_periods_total[5m]))) > 0.25', for: 10m, labels: {severity: warning} }
      - { alert: ContainerOOM, expr: 'increase(container_oom_events_total[10m]) > 0', for: 0m, labels: {severity: critical} }
      - { alert: ContainerFsNearFull, expr: '(container_fs_usage_bytes{name!=""} / (container_fs_limit_bytes{name!=""} > 0)) > 0.9', for: 10m, labels: {severity: warning} }

# alertmanager.yml —— 多通道通知 + 噪声抑制
route:
  group_by: [alertname, namespace, pod]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  receiver: webhook-default
  routes:
    - { matchers: ['severity="critical"'], receiver: wechat-p0 }
receivers:
  - name: webhook-default
    webhook_configs:
      - url: http://<告警网关_HOST>:<PORT>/cadvisor/alarm   # 网关转发钉钉/飞书/邮件
  - name: wechat-p0
    webhook_configs:
      - url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<企业微信机器人key>
  - name: email-p2
    email_configs:
      - { to: <值班邮箱>, from: <发件邮箱>, smarthost: '<SMTP_HOST>:587', auth_username: <账号>, auth_password: <密码> }
inhibit_rules:
  - { source_matchers: ['severity="critical"'], target_matchers: ['severity="warning"'], equal: [namespace, pod] }

# 钉钉由告警网关按 Alertmanager JSON 渲染后转发
curl -sS -X POST 'https://<钉钉机器人Webhook URL>' -H 'Content-Type: application/json' -d '{"msgtype":"text","text":{"content":"容器告警：<alerts>"}}'

降噪：for 持续时长、group_by 按 namespace/pod 聚合、repeat_interval 重发间隔、inhibit_rules 抑制、按 severity 分级路由；滚动更新的瞬时抖动用 for 与 absent() 配合削掉。

7. 实战场景

7.1 接入一个 Java 服务并采集其容器指标

• 目标：Java 服务容器化后，在 Prometheus 看到其 CPU/内存/网络指标。步骤：起 cAdvisor → 跑 Java 容器 → 配抓取 job → 造流量。

docker run -d --name cadvisor -p 8080:8080 --privileged --device=/dev/kmsg \
  -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 \
  ghcr.io/google/cadvisor:${CADVISOR_VER}
docker run -d --name order-java --memory=1g --cpus=1 -p 8081:8080 <Java业务镜像:tag>
# prometheus.yml 加 4.3 的 cadvisor job，reload 后查：
# sum by (name) (rate(container_cpu_usage_seconds_total{name=~".*order-java.*"}[5m]))

• 验证：curl -sS http://<HOST>:8080/metrics | grep 'name="order-java"' 有样本；Prometheus /targets 中 cadvisor job 为 UP。
• 回滚：停掉 Java 容器与 Prometheus 中该 job；cAdvisor 继续留着无副作用。⚠️ 设了 --memory/--cpus 才有 container_spec_*_limit_bytes，否则限额类 PromQL 分母为 0。

7.2 定位一次慢调用（CPU 节流 / 内存压力）

• 目标：接口偶发变慢，判断是 CPU quota 撞限还是内存回收。步骤：看 CPU 节流率 → 看 working_set/limit → 看 OOM 与 PSI → 调整 limit。

# 1) 节流率（>0.25 说明 CPU 配额不足）
sum by (name) (rate(container_cpu_cfs_throttled_periods_total{name="<容器名>"}[5m]))
  / sum by (name) (rate(container_cpu_cfs_periods_total{name="<容器名>"}[5m]))
# 2) 内存工作集占限额比例
container_memory_working_set_bytes{name="<容器名>"} / (container_spec_memory_limit_bytes{name="<容器名>"} > 0)
# 3) OOM / failcnt / PSI 压力（cgroup v2）
increase(container_oom_events_total{name="<容器名>"}[30m])
container_memory_failcnt{name="<容器名>"}
container_pressure_cpu_stalled_seconds_total{container="<容器名>"}
# 4) 对照业务 P99 曲线，确认时段吻合；再调 --cpus / resources.limits

• 验证：节流率或 working_set 尖峰与慢调用时段重合；提高 limit 后节流率下降、P99 回落。
• 回滚：把 --cpus / resources.limits 调回原值并重启容器；⚠️ 调整 limits 会触发容器重建，先在非高峰执行。

7.3 单机 Docker 主机接入 Prometheus

• 目标：一台裸 Docker 主机纳入监控。步骤：装 cAdvisor（4.2）→ 写 4.3 的 prometheus.yml → 热重载 → Grafana 导入容器仪表盘。

curl -X POST http://<PROM_HOST>:9090/-/reload      # 需 Prometheus 启用 --web.enable-lifecycle
curl -sS 'http://<PROM_HOST>:9090/api/v1/query?query=up{job="cadvisor"}'   # 预期 up=1

• 验证：Prometheus /targets UP；container_cpu_usage_seconds_total 有该主机样本。
• 回滚：从 scrape_configs 删除 cadvisor job 并 reload；⚠️ 不要直接删历史数据。

7.4 K8s 集群通过 kubelet 内置 cAdvisor 抓取

• 目标：不部署额外组件，采集全集群 Pod 容器指标。步骤：配 4.4 的 RBAC 与 kubernetes_sd_configs（role: node）→ reload。

kubectl apply -f prometheus-rbac.yaml
kubectl get --raw "/api/v1/nodes/<node>/proxy/metrics/cadvisor" | grep -c '^container_'
curl -sS 'http://<PROM_HOST>:9090/api/v1/query?query=count(container_memory_working_set_bytes{pod!=""})'

• 验证：/targets 中 kubernetes-cadvisor job 每个节点 UP，指标带 pod/namespace/container 标签。
• 回滚：删除该 scrape job 与 ClusterRoleBinding 并 reload；⚠️ 不要误删 kubelet 自身 :10250 的健康探针路径。

8. 日常运维与故障排查

systemctl status cadvisor && journalctl -u cadvisor -f       # 服务管理 / 二进制日志
docker logs -f cadvisor 2>&1 | grep -iE 'error|failed'       # 容器日志
curl -sS http://<HOST>:8080/healthz                          # 健康检查
curl -sS http://<HOST>:8080/metrics | grep -c '^container_'  # 指标产出计数
curl -sS http://<HOST>:8080/api/v1.3/machine                  # 机器信息
kubectl -n <ns> get pod -l app=cadvisor -o wide               # K8s DaemonSet 状态

9. 性能、容量与高可用

10. 安全加固、备份与升级

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选 cAdvisor：需要容器/Pod 级真实资源用量、CPU 节流与 OOM 诊断、容器网络/磁盘 IO；裸 Docker/containerd 主机监控；K8s 里通过抓 kubelet /metrics/cadvisor 拿 Pod 用量。 何时不选：只要 kubectl top/HPA（用 metrics-server）；只要对象状态与副本健康（用 kube-state-metrics）；只要宿主机硬件/OS（用 node_exporter）；要业务黄金指标或链路（用 APM / OTel）；要开箱即用的存储与告警（cAdvisor 必须配 Prometheus 全家桶）。 组合建议：K8s 标准管线 = kubelet /metrics/cadvisor（用量）+ node_exporter（宿主机）+ kube-state-metrics（对象状态）+ kube-state-metrics/metrics-server 各司其职，统一进 Prometheus → Grafana → Alertmanager；四者指标前缀不同，不重叠也不互相替代。

14. 参考链接

• 主仓库：https://github.com/google/cadvisor
• 运行参数：https://github.com/google/cadvisor/blob/master/docs/runtime_options.md
• Prometheus 指标清单：https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md
• Web UI / REST API / 独立运行说明：https://github.com/google/cadvisor/blob/master/docs/web.md ｜ https://github.com/google/cadvisor/blob/master/docs/api.md ｜ https://github.com/google/cadvisor/blob/master/docs/running.md
• K8s DaemonSet 清单：https://github.com/google/cadvisor/tree/master/deploy/kubernetes
• K8s 系统组件指标（/metrics/cadvisor 现状与 RBAC）：https://kubernetes.io/docs/concepts/cluster-administration/system-metrics/
• K8s 可观测性（指标管线）：https://kubernetes.io/docs/concepts/cluster-administration/observability/
• Kubelet PSI 指标（/metrics/cadvisor 新增 container_pressure_*）：https://kubernetes.io/blog/2025/09/04/kubernetes-v1-34-introducing-psi-metrics-beta
• Prometheus 配置 / Exporter 生态：https://prometheus.io/docs/operating/configuration/ ｜ https://prometheus.io/docs/instrumenting/exporters/