cAdvisor v0.60.6 配置参数详解

逐组实测 cAdvisor v0.60.6 启动参数的效果详解:housekeeping 采样节奏降频对照、docker_only 采集范围收敛、disable/enable_metrics 整组替换行为、Prometheus 标签白名单治理、stdout 等 8 类存储驱动、Web UI Basic 认证与 /metrics 盲区、容器资源限额与生产三档配置模板,每组附真实回显。

cAdvisorcAdvisor2026/10/18

cAdvisor v0.60.6 配置参数详解

目标:逐组实测 cAdvisor v0.60.6 的常用启动参数——采集节奏(housekeeping)、采集范围、指标组开关、Prometheus 标签治理、存储驱动、Web UI 认证、资源限制与日志调试,每组给出参数说明与真实效果回显,并汇总生产配置模板。全文在 Ubuntu 22.04.4 LTS 服务器(192.168.146.128,Docker 29.8.1)上实测,命令与回显逐条照抄。

一、环境信息

本章列出实测环境基线与验证实例清单,所有参数效果对比均出自这些实例的真实运行数据。

  • 操作系统:Ubuntu 22.04.4 LTS(x86_64),主机 IP 192.168.146.128(ens33),CPU 12 核,内存 31.3GiB(metrics 实测 machine_cpu_cores=12、machine_memory_bytes=3.3607307264e+10)

  • 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(--version 实测):

    cAdvisor version v0.60.6 (5bf5d43)
    
  • 宿主机容器规模:60+ 个运行中实例(appwrite 全家桶、zitadel 栈、teable 栈等),该规模是本章资源开销对比的背景值,容器越少各项开销越小

  • 主实例:cadvisor-v0-60-6-main(compose 部署,8116->8080,默认参数,全量采集),部署过程见《cAdvisor Docker Compose 部署指南》

  • 参数验证实例(与主实例相同挂载,独立启动,逐组验证参数效果):

    实例名验证参数组端口映射
    cadvisor-v0-60-6-hkhousekeeping 节奏组8117→8080
    cadvisor-v0-60-6-dockeronly采集范围 + 指标组开关8118→8080
    cadvisor-v0-60-6-labelsPrometheus 标签治理8119→8080
    cadvisor-v0-60-6-stdout存储驱动(stdout)8120→8080
    cadvisor-v0-60-6-authWeb UI 认证 + 端口8121→9091
    cadvisor-v0-60-6-limit资源限制 + profiling8122→8080

二、前置条件

  1. 已按《cAdvisor Docker Compose 部署指南》完成主实例部署,可访问 http://localhost:8116/healthz 返回 ok。
  2. 理解 cAdvisor 配置入口:cAdvisor 的全部配置通过命令行 flag 传入,不解析环境变量、无主配置文件。Docker 方式下写法为 docker run ... ghcr.io/google/cadvisor:v0.60.6 --flag=value(镜像参数),compose 方式为 service 的 command: 段。
  3. 对照基线:本章的「默认行为」均指主实例(默认参数)的实测输出;改动参数后用同款命令对比即可评估效果。

三、参数查看与修改方式

本章给出查看全量参数与确认参数生效的实测方法,任何参数调整都应先看后改、改完验证。

3.1 查看全量参数与默认值

docker exec cadvisor-v0-60-6-main /usr/bin/cadvisor --help 2>&1

实测回显(v0.60.6 全量 flag 清单,输出节选,保留核心段;完整输出约 130 行):

Usage of /usr/bin/cadvisor:
  -add_dir_header
        If true, adds the file directory to the header of the log messages
  -allow_dynamic_housekeeping
        Whether to allow the housekeeping interval to be dynamic (default true)
  -application_metrics_count_limit int
        Max number of application metrics to store (per container) (default 100)
  -collector_cert string
        Collector's certificate, exposed to endpoints for certificate based authentication.
  -container_hints string
        location of the container hints file (default "/etc/cadvisor/container_hints.json")
  -containerd string
        containerd endpoint (default "/run/containerd/containerd.sock")
  -crio_client_timeout duration
        CRI-O client timeout. Default is no timeout.
  -disable_metrics metrics
        comma-separated list of metrics to be disabled. Options are advtcp,app,cpu,cpuLoad,cpu_topology,cpuset,disk,diskIO,hugetlb,memory,memory_numa,network,oom_event,percpu,perf_event,pressure,process,referenced_memory,resctrl,sched,tcp,udp. (default advtcp,cpu_topology,cpuset,hugetlb,memory_numa,process,referenced_memory,resctrl,sched,tcp,udp)
  -disable_root_cgroup_stats
        Disable collecting root Cgroup stats
  -docker string
        docker endpoint (default "unix:///var/run/docker.sock")
  -docker_only
        Only report docker containers in addition to root stats
  -enable_load_reader
        Whether to enable cpu load reader
  -enable_metrics metrics
        comma-separated list of metrics to be enabled. If set, overrides 'disable_metrics'. Options are advtcp,app,cpu,cpuLoad,cpu_topology,cpuset,disk,diskIO,hugetlb,memory,memory_numa,network,oom_event,percpu,perf_event,pressure,process,referenced_memory,resctrl,sched,tcp,udp.
  -env_metadata_whitelist string
        a comma-separated list of environment variable keys matched with specified prefix that needs to be collected for containers, only support containerd and docker runtime for now.
  -event_storage_age_limit string
        Max length of time for which to store events (per type). ... (default "default=24h")
  -event_storage_event_limit string
        Max number of events to store (per type). ... (default "default=100000")
  -global_housekeeping_interval duration
        Interval between global housekeepings (default 1m0s)
  -housekeeping_interval duration
        Interval between container housekeepings (default 1s)
  -http_auth_file string
        HTTP auth file for the web UI
  -listen_ip string
        IP to listen on, defaults to all IPs
  -max_housekeeping_interval duration
        Largest interval to allow between container housekeepings (default 1m0s)
  -max_procs int
        max number of CPUs that can be used simultaneously. Less than 1 for default (number of cores).
  -perf_events_config string
        Path to a JSON file containing configuration of perf events to measure. Empty value disabled perf events measuring.
  -podman string
        podman endpoint (default "unix:///var/run/podman/podman.sock")
  -port int
        port to listen (default 8080)
  -profiling
        Enable profiling via web interface host:port/debug/pprof/
  -prometheus_endpoint string
        Endpoint to expose Prometheus metrics on (default "/metrics")
  -raw_cgroup_prefix_whitelist string
        A comma-separated list of cgroup path prefix that needs to be collected even when -docker_only is specified
  -storage_driver driver
        Storage driver to use. Data is always cached shortly in memory, this controls where data is pushed besides the local cache. Empty means none, multiple separated by commas. Options are: <empty>, bigquery, elasticsearch, influxdb, kafka, redis, statsd, stdout
  -storage_duration duration
        How long to keep data stored (Default: 2min). (default 2m0s)
  -store_container_labels
        convert container labels and environment variables into labels on prometheus metrics for each container. If flag set to false, then only metrics exported are container name, first alias, and image name (default true)
  -url_base_prefix string
        prefix path that will be prepended to all paths to support some reverse proxies
  -version
        print cAdvisor version and exit
  -whitelisted_container_labels string
        comma separated list of container labels to be converted to labels on prometheus metrics for each container. store_container_labels must be set to false for this to take effect.

官方 runtime_options.md(https://github.com/google/cadvisor/blob/v0.60.6/docs/runtime_options.md )按场景归档了同款参数说明,可交叉对照。

3.2 修改参数的三种方式

  1. compose 方式(推荐):在 service 下加 command:,docker compose up -d 重建生效:

    services:
      cadvisor:
        image: ghcr.io/google/cadvisor:v0.60.6
        command:
          - --housekeeping_interval=5s
          - --docker_only=true
    
  2. docker run 方式:镜像名后直接跟 flag:

    docker run -d --name cadvisor-v0-60-6-hk --privileged \
      -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 \
      --device=/dev/kmsg -p 8117:8080 \
      ghcr.io/google/cadvisor:v0.60.6 --housekeeping_interval=5s --allow_dynamic_housekeeping=false
    
  3. 验证生效:参数是否生效看两处——启动日志第一行 enabled metrics: 列表(指标组开关类),以及 /metrics、API 的实际输出(行为类)。

3.3 确认版本与运行形态

docker exec cadvisor-v0-60-6-main /usr/bin/cadvisor --version

实测回显:

cAdvisor version v0.60.6 (5bf5d43)
docker exec cadvisor-v0-60-6-main /usr/bin/cadvisor --help 2>&1 | head -1

实测回显:

Usage of /usr/bin/cadvisor:

四、参数总览

cAdvisor 全量 flag 按用途归为八组,总览如下(默认值均来自 3.1 节实测 --help 输出):

分组核心参数默认值一句话作用
采集节奏(housekeeping)--housekeeping_interval1s每容器统计采样间隔
--allow_dynamic_housekeepingtrue允许动态拉长采样间隔
--max_housekeeping_interval1m0s动态调整的上限
--global_housekeeping_interval1m0s全局 cgroup 树扫描间隔
采集范围--docker_onlyfalse只采 Docker 容器与根 cgroup
--raw_cgroup_prefix_whitelist空docker_only 下保留的 cgroup 前缀
--disable_root_cgroup_statsfalse关闭根 cgroup 统计
--docker/--containerd/--podmanunix socket 各默认路径运行时端点
指标组开关--disable_metrics11 组(见 3.1)禁用指定指标组
--enable_metrics空显式启用(覆盖 disable)
Prometheus 标签--store_container_labelstruelabels/环境变量转 Prometheus label
--whitelisted_container_labels空label 白名单(需 store=false)
--env_metadata_whitelist空采集指定环境变量
存储驱动--storage_driver空(仅内存)外发后端:influxdb/kafka/redis/es/statsd/bigquery/stdout
--storage_duration2m0s内存缓存保留时长
--storage_driver_db/host/user/password/...按后端后端连接参数
Web UI 与安全--port/--listen_ip8080 / 全部 IP监听地址
--http_auth_file/--http_digest_file空Web UI Basic/Digest 认证
--url_base_prefix空反代路径前缀
--profilingfalse开启 /debug/pprof/
性能与资源--max_procs0(=核数)可用 CPU 上限
--enable_load_readerfalse启用 CPU load 读取器
日志调试--logtostderrtrue日志输出到 stderr
-v0日志详细级别
--log_file/--log_dir空落盘日志文件/目录
事件存储--event_storage_event_limitdefault=100000每类事件保留条数
--event_storage_age_limitdefault=24h每类事件保留时长

分组解读:资源开销治理优先动「采集节奏 + 采集范围 + 标签治理」三组;数据留存问题动「存储驱动」组;暴露面收敛动「Web UI 与安全」组。以下逐组实测。

五、核心参数分类详解

5.1 housekeeping 采集节奏组

参数说明:housekeeping(管家循环)是 cAdvisor 的心跳,按 --housekeeping_interval 对每个容器周期采样 CPU/内存/IO 统计并写入内存缓存——这是进程 CPU 与内存开销的第一来源。--allow_dynamic_housekeeping=true(默认)时允许在容器空闲时自动拉长间隔(上限 --max_housekeeping_interval);显式关闭动态调整可让节奏完全固定。

实测:启动节奏降频实例(间隔 5s、关闭动态调整):

docker run -d --name cadvisor-v0-60-6-hk --privileged \
  -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 \
  --device=/dev/kmsg -p 8117:8080 \
  ghcr.io/google/cadvisor:v0.60.6 --housekeeping_interval=5s --allow_dynamic_housekeeping=false

实测回显:

aa54d4b4caa95d74faefc973c4b698ac8cdfeedd71daa99debb11ce23e12712e

效果验证一:采样间隔变化。连续取根 cgroup 最新统计时间戳(中间 sleep 5):

for i in 1 2 3; do curl -s http://localhost:8117/api/v1.3/containers/ | python3 -c "import json,sys; d=json.load(sys.stdin); s=d['stats'][-1]; print(s['timestamp'])"; sleep 5; done

实测回显(5s 实例,相邻时间戳间隔约 5~7 秒):

2026-10-18T15:07:40.846979757Z
2026-10-18T15:07:48.179150413Z
2026-10-18T15:07:55.150889028Z

对照默认实例(1s 间隔,同样的取法、sleep 1):

2026-10-18T15:08:02.41856401Z
2026-10-18T15:08:03.55692469Z
2026-10-18T15:08:03.55692469Z

默认实例相邻统计间隔约 1 秒(第三条与第二条相同,因 1 秒内未产生新样本),降频实例拉长到 5 秒以上,参数生效。

效果验证二:资源开销变化(docker stats --no-stream 瞬时采样):

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

采样间隔 1s→5s 后,CPU 从 5.88% 降到 1.42%、内存缓存从 1.9GiB 降到 1.02GiB(60+ 容器背景)。瞬时采样有波动,量级结论稳定:降频直接省一半以上内存与 CPU。

要点提示:

  • 间隔放大到 5s 的代价是「最新样本延迟最多 5s」——对 Prometheus 15s~30s 抓取周期毫无影响,是纯收益。
  • --allow_dynamic_housekeeping 保持默认 true 时,空闲容器会自动被拉长间隔,多数场景无需显式关闭;固定 5s + 关动态的组合适合「开销优先、节奏可预期」的场景。

5.2 采集范围组(docker_only / raw cgroup 白名单)

参数说明:默认情况下 cAdvisor 报告整个 cgroup 树——除 Docker 容器外还包括宿主机全部 systemd service 的 cgroup 统计(raw cgroup metrics)。--docker_only=true 只保留 Docker 容器与根 cgroup;--raw_cgroup_prefix_whitelist 在 docker_only 模式下为特定 cgroup 前缀开白名单;--disable_root_cgroup_stats 进一步关掉根 cgroup 统计。

实测:--docker_only --disable_metrics=percpu,diskIO,network(指标开关效果归 5.3 分析,本节只看范围):

docker run -d --name cadvisor-v0-60-6-dockeronly --privileged \
  -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 \
  --device=/dev/kmsg -p 8118:8080 \
  ghcr.io/google/cadvisor:v0.60.6 --docker_only --disable_metrics=percpu,diskIO,network

效果验证一:raw cgroup 指标消失。默认实例的 /metrics 中包含大量非 Docker 的 systemd service cgroup:

curl -s http://localhost:8116/metrics | grep -oE 'id="/system.slice/[^d"][^"]*"' | sort -u | head -3

实测回显:

id="/system.slice/accounts-daemon.service"
id="/system.slice/acpid.service"
id="/system.slice/avahi-daemon.service"

dockeronly 实例同一命令:

curl -s http://localhost:8118/metrics | grep -oE 'id="/system.slice/[^d"][^"]*"' | sort -u | head -3 || echo "(none)"

实测回显:

(none)

非 Docker cgroup 统计被完整剔除,只留 Docker 容器与根 cgroup——与 --help 中 "Only report docker containers in addition to root stats" 的语义一致。

效果验证二:内存开销:

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

内存从 1.9GiB 降到 149.8MiB,量级收益最大的一组参数(CPU 为瞬时采样值波动较大,以内存对比为准)。

要点提示:容器宿主机上 systemd service 级统计通常已有 node_exporter/systemd 导出器承接,cAdvisor 侧开 --docker_only 是干净的分工;如个别 raw cgroup(如某物理进程)仍需保留,用 --raw_cgroup_prefix_whitelist=/system.slice/目标前缀 精确放行。

5.3 指标组开关(disable_metrics / enable_metrics)

参数说明:cAdvisor 内置 22 个指标组,默认启用 11 组、禁用 11 组(默认禁用:advtcp、cpu_topology、cpuset、hugetlb、memory_numa、process、referenced_memory、resctrl、sched、tcp、udp)。--disable_metrics 增补禁用、--enable_metrics 显式启用(enable 优先级高于 disable,两者都以逗号分隔组名)。

⚠️ 实测发现(重要):--disable_metrics 传值后是整体替换默认禁用集,而非在其基础上追加。传 --disable_metrics=percpu,diskIO,network 后,原先默认禁用的 11 组反而全部变成启用,指标总量不降反升。想在默认基础上额外禁用时,必须把默认禁用列表一并写全。

实测:验证上述替换行为。启动时传 --disable_metrics=percpu,diskIO,network,看启动日志的 enabled metrics 行:

docker logs cadvisor-v0-60-6-dockeronly 2>&1 | grep 'enabled metrics' | head -1

实测回显:

I1018 15:05:17.031951       1 cadvisor.go:126] enabled metrics: advtcp,app,cpu,cpuLoad,cpu_topology,cpuset,disk,hugetlb,memory,memory_numa,oom_event,perf_event,pressure,process,referenced_memory,resctrl,sched,tcp,udp

对照主实例(默认参数):

I1018 15:03:53.428544       1 cadvisor.go:126] enabled metrics: app,cpu,cpuLoad,disk,diskIO,memory,network,oom_event,percpu,perf_event,pressure

确认:目标禁用的 percpu/diskIO/network 确实消失,但默认禁用组(advtcp、process、tcp 等 11 组)全部被激活——metrics 行数从默认的 10556 涨到 11170:

curl -s http://localhost:8118/metrics | wc -l

实测回显:

11170

要点提示:

  • 「额外禁用」的正确写法是把默认禁用集 + 新增项合并传入,例如 --disable_metrics=advtcp,cpu_topology,cpuset,hugetlb,memory_numa,process,referenced_memory,resctrl,sched,tcp,udp,percpu,diskIO,network。
  • 精确控量推荐反向操作:--enable_metrics=cpu,memory,network,disk,diskIO,cpuLoad,oom_event 只留刚需组(enable 覆盖 disable),/metrics 体积可大幅缩减。
  • 组名清单以 --help 输出为准(3.1 节 disable_metrics 行),版本升级后应复核。

5.4 Prometheus 标签治理组(store_container_labels / whitelisted_container_labels / env_metadata_whitelist)

参数说明:--store_container_labels=true(默认)把容器全部 labels 与环境变量转为每条容器指标的 Prometheus label;容器标签多时单条指标拉长到上千字符、抓取体积与基数暴涨。--store_container_labels=false 后只保留容器名、第一个别名与镜像名,同时可用 --whitelisted_container_labels 白名单保留指定标签(须与 store=false 搭配)。--env_metadata_whitelist 控制哪些环境变量前缀被采集。

实测:白名单只保留 compose 的 project/service 两个标签:

docker run -d --name cadvisor-v0-60-6-labels --privileged \
  -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 \
  --device=/dev/kmsg -p 8119:8080 \
  ghcr.io/google/cadvisor:v0.60.6 \
  --store_container_labels=false \
  --whitelisted_container_labels=com.docker.compose.service,com.docker.compose.project

效果验证:取同一容器(kener-4-1-7-app)同一条指标对比。白名单实例:

curl -s http://localhost:8119/metrics | grep '^container_cpu_usage_seconds_total{' | grep 'name="kener-4-1-7-app"' | head -1

实测回显:

container_cpu_usage_seconds_total{container_label_com_docker_compose_project="kener-compose",container_label_com_docker_compose_service="kener",cpu="total",id="/system.slice/docker-e9303e9229ae61b99625d0ec58c760fa819fa41bb05a2fa6e84017979ae60f4e.scope",image="rajnandan1/kener:v4.1.7",name="kener-4-1-7-app"} 3.665447 1792335948565

默认实例同条指标(输出节选,label 串过长截取前 400 字符,实际该行超过 2000 字符):

container_cpu_usage_seconds_total{container_label_base_image="",container_label_build_version="",container_label_com_clickhouse_build_version="",container_label_com_docker_compose_config_hash="8dbae90bc8507d7fa61964d428586fd39330f21a1c0a66d4118e0441de24e2ce",container_label_com_docker_compose_container_number="1",container_label_com_docker_compose_depends_on="redis:service_healthy:false",container...

对比结论:白名单模式下单条指标只带 2 个容器标签(project/service),从 2000+ 字符缩到 300 字符以内;内存占用同步从 1.9GiB 降到 107.8MiB(与 5.2 叠加使用收益更大)。

要点提示:store_container_labels=false 会同时丢弃环境变量转换,需要某个环境变量进标签时改用 --env_metadata_whitelist=前缀1,前缀2。

5.5 存储驱动组(storage_driver / storage_duration)

参数说明:cAdvisor 统计始终先入内存缓存(--storage_duration 默认 2 分钟),--storage_driver 决定缓存之外是否推送到外部后端,可选:<empty>(默认,不推送)、influxdb、kafka、redis、elasticsearch、statsd、bigquery、stdout,可逗号分隔多选。各后端连接参数成组配套(见 5.5.2)。

5.5.1 stdout 驱动实测(观察推送内容最直观的方式)

docker run -d --name cadvisor-v0-60-6-stdout --privileged \
  -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 \
  --device=/dev/kmsg -p 8120:8080 \
  ghcr.io/google/cadvisor:v0.60.6 --storage_driver=stdout --storage_duration=1m

效果验证:观察该实例日志,每个采样周期输出逐容器统计(k=v 流式格式):

docker logs cadvisor-v0-60-6-stdout 2>&1 | grep -v '^I1018.*fs.go' | tail -5 | cut -c1-300

实测回显(输出节选,每行截取前 300 字符):

cName=appwrite-realtime host=localhost:8086 memory_total_active_file=0 memory_failure.hierarchical.pgfault=160368 cpu_usage_total=6104115000 cpu_usage_system=3192336000 tx_bytes=11315 memory_max_usage=59441152 memory_cache=27590656 ...
cName=cadvisor-v0-60-6-main host=localhost:8086 cpu_cumulative_usage=69851773000 memory_cache=569536512 memory_failure.hierarchical.pgfault=247274 cpu_usage_total=69851773000 cpu_usage_system=48994058000 load_average=0 rx_bytes=4805300 ...
cName=appwrite-clickhouse-1 host=localhost:8086 memory_working_set=321396736 memory_total_inactive_file=8462336 memory_failcnt=0 cpu_cumulative_usage=365672407000 tx_bytes=152413 memory_max_usage=428105728 ...

stdout 驱动把逐容器统计以 cName=<容器名> 指标=值 ... 形式写入日志流,实际生产多用于调试与管道接流处理;资源代价不小(本实例 CPU 瞬时采样 49.88%,全量序列化写日志开销显著),常驻部署建议改用 influxdb/kafka 等二进制友好后端。

5.5.2 各后端连接参数速查(v0.60.6 --help 实测默认值)

后端配套参数默认值
influxdb--storage_driver_hostlocalhost:8086
--storage_driver_dbcadvisor
--storage_driver_user / --storage_driver_passwordroot / root
kafka--storage_driver_kafka_broker_listlocalhost:9092
--storage_driver_kafka_topicstats
--storage_driver_kafka_ssl_ca/cert/key空(--storage_driver_kafka_ssl_verify 默认 true)
elasticsearch--storage_driver_es_hosthttp://localhost:9200
--storage_driver_es_index / --storage_driver_es_typecadvisor / stats
redis复用 --storage_driver_host/db/user/password 组同 influxdb 组
bigquery--bq_project_id/--bq_account/--bq_credentials_file 等按账号
statsd复用 --storage_driver_host 组同上

要点提示:--storage_duration 只决定内存缓存深度(我们实测改为 1m 生效,日志中 Caching stats in memory for 2m0s 会随之变为 1m0s),不是历史数据留存时长;长期留存由后端自身承担。

5.6 Web UI 与安全组(port / listen_ip / http_auth_file / url_base_prefix / profiling)

参数说明:--port(默认 8080)与 --listen_ip(默认全部网卡)控制监听;--http_auth_file 为 Web UI 挂 Basic 认证(htpasswd 格式文件);--url_base_prefix 为反代场景加统一路径前缀;--profiling 开启 Go pprof 剖析端点。

实测一:认证 + 改端口。生成口令文件(账号 admin、密码 q1w2e3r4,apr1 哈希):

openssl passwd -apr1 'q1w2e3r4'

实测回显:

$apr1$YKIGA8ps$k528CtwtoHpumNYTWe28F.

写入 /opt/data/quzuo/cadvisor-0-60-6/auth/htpasswd(内容一行):

admin:$apr1$YKIGA8ps$k528CtwtoHpumNYTWe28F.

启动认证实例(--port=9091 改容器内监听端口,注意映射同步改为 8121:9091):

docker run -d --name cadvisor-v0-60-6-auth --privileged \
  -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 \
  --device=/dev/kmsg \
  -v /opt/data/quzuo/cadvisor-0-60-6/auth/htpasswd:/etc/cadvisor/htpasswd:ro \
  -p 8121:9091 \
  ghcr.io/google/cadvisor:v0.60.6 --http_auth_file=/etc/cadvisor/htpasswd --port=9091

认证效果验证:

curl -sI --max-time 10 http://localhost:8121/containers/ | head -4

无凭据实测回显:

HTTP/1.1 401 Unauthorized
Content-Type: text/plain
Www-Authenticate: Basic realm="localhost"
Date: Sun, 18 Oct 2026 15:07:11 GMT
curl -s -u admin:q1w2e3r4 --max-time 10 -o /dev/null -w "HTTP_CODE:%{http_code}\n" http://localhost:8121/containers/
curl -s -u admin:wrongpass --max-time 10 -o /dev/null -w "HTTP_CODE:%{http_code}\n" http://localhost:8121/containers/

实测回显:

HTTP_CODE:200
HTTP_CODE:401

Basic 认证闭环:无凭据 401、正确凭据(admin/q1w2e3r4)200、错误凭据 401。

⚠️ 实测发现(安全边界):--http_auth_file 只保护 Web UI 路径,/metrics 与 /api/v1.3/ 不受其保护:

curl -s --max-time 10 -o /dev/null -w "HTTP_CODE:%{http_code}\n" http://localhost:8121/metrics

实测回显:

HTTP_CODE:200

生产暴露前务必用反向代理对 /metrics 一并加认证,或用 --listen_ip=<内网IP> 限制监听面。

实测二:profiling 端点:

docker run -d --name cadvisor-v0-60-6-limit --privileged \
  -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 \
  --device=/dev/kmsg -p 8122:8080 \
  --memory=256m --cpus=0.5 \
  ghcr.io/google/cadvisor:v0.60.6 --profiling
curl -s --max-time 10 -o /dev/null -w "pprof HTTP_CODE:%{http_code}\n" http://localhost:8122/debug/pprof/

实测回显:

pprof HTTP_CODE:200

--profiling 生效后 /debug/pprof/ 可访问(CPU/内存/协程剖析),排查内存增长时使用;默认关闭,日常保持关闭以收敛暴露面。

5.7 性能与资源限制组(max_procs / 容器资源约束)

参数说明:--max_procs 限制 cAdvisor 自身可同时使用的 CPU 数(默认 0 = 全部核);运行平台侧限制(compose 的 deploy.resources 或 docker run --memory/--cpus)从外部兜底,两者配合使用。

实测:5.6 节启动的 limit 实例带 --memory=256m --cpus=0.5,验证约束被识别:

docker stats --no-stream --format '{{.Name}}: CPU {{.CPUPerc}} MEM {{.MemUsage}} ({{.MemPerc}})' cadvisor-v0-60-6-limit cadvisor-v0-60-6-main

实测回显:

cadvisor-v0-60-6-limit: CPU 8.21% MEM 41.3MiB / 256MiB (16.13%)
cadvisor-v0-60-6-main: CPU 33.25% MEM 1.786GiB / 31.3GiB (5.71%)

内存上限 256MiB 生效(本宿主机容器少一半规模时 256MiB 足够;主实例 1.786GiB 是 60+ 容器全量采集的量级参照)。CPU 限额 0.5 核生效后,采集超时会体现为样本间隔波动,不会击穿限额。

要点提示:--max_procs=2 这类进程级限制与平台级 --cpus 语义不同(线程池上限 vs CFS 配额),容器化部署优先用平台级限额;二者叠加不冲突。

5.8 日志与调试组(logtostderr / v / log_file / version)

参数说明:cAdvisor 默认 -logtostderr=true(日志到 stderr,由容器日志驱动接管)。需要落盘时用 --log_file(单文件,默认上限 1800MB)或 --log_dir(按级别分文件);-v N 提升详细级别排障;--version 打印版本退出。

实测:版本查询与日志级别验证:

docker exec cadvisor-v0-60-6-main /usr/bin/cadvisor --version

实测回显:

cAdvisor version v0.60.6 (5bf5d43)

主实例日志输出形态(stderr 直出,docker logs 可见,启动首屏):

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]

要点提示:-v 5 级别会输出每次 housekeeping 细节,仅排障短时开启;--log_file 模式下注意 1800MB 默认上限(--log_file_max_size 可调),容器化部署保持默认 stderr + Docker 日志轮转更省心。

六、生产配置模板

按宿主机容器规模给三档推荐配置(全部参数均经上文实测验证),直接可粘贴进 compose 的 command: 段。

模板一:小规模(≤20 容器,4GB 内存级宿主机)——默认全量,保真优先

    command:
      - --housekeeping_interval=5s
      - --store_container_labels=false
      - --whitelisted_container_labels=com.docker.compose.service,com.docker.compose.project

适用:开发/测试服务器,指标全保真,只做标签治理。内存预期:百 MiB 以内。

模板二:中规模(20~100 容器,16GB 内存级宿主机)——本文实测环境同款

    command:
      - --housekeeping_interval=5s
      - --allow_dynamic_housekeeping=false
      - --docker_only=true
      - --enable_metrics=cpu,cpuLoad,memory,network,disk,diskIO,oom_event,pressure
      - --store_container_labels=false
      - --whitelisted_container_labels=com.docker.compose.service,com.docker.compose.project
      - --listen_ip=0.0.0.0

适用:生产业务宿主机,容器指标为主、raw cgroup 交由 node_exporter。内存预期:200~500MiB(实测 60+ 容器同款组合 149.8MiB)。配平台限额 --memory=512m --cpus=1。

模板三:大规模(100+ 容器,64GB+ 宿主机)——降频 + 白名单 + 外置存储

    command:
      - --housekeeping_interval=10s
      - --allow_dynamic_housekeeping=true
      - --docker_only=true
      - --enable_metrics=cpu,memory,network,diskIO,oom_event
      - --store_container_labels=false
      - --whitelisted_container_labels=com.docker.compose.service
      - --storage_driver=stdout
      - --max_procs=2

适用:高密度节点,先保证采集自身不抢业务资源;历史数据改由 Prometheus 抓取或后端承接,必要时才启用 storage_driver。内存预期:512MiB 以内,配平台限额 --memory=1g --cpus=2。

💡 说明:三档模板均未启用 --http_auth_file——Web UI 认证建议在反向代理层统一做(可同时覆盖 /metrics,弥补 5.6 节实测发现的认证盲区);如 cAdvisor 直接暴露,按 5.6 节配置认证文件。

七、常见问题

Q1:--disable_metrics=xxx 加了以后指标反而变多了? 见 5.3 节实测:disable 传值会整体替换默认禁用集(默认 11 组:advtcp,cpu_topology,cpuset,hugetlb,memory_numa,process,referenced_memory,resctrl,sched,tcp,udp),需把默认集合并写入;或者改用 --enable_metrics 白名单正向声明。

Q2:配了 --http_auth_file,为什么 /metrics 还是无凭据可读? 认证文件只覆盖 Web UI(/containers/ 等 UI 路径),/metrics 与 /api/v1.3/ 是给采集器/程序用的裸端点(5.6 节实测 200)。防护方案:反向代理统一加认证,或 --listen_ip 限定内网。

Q3:改了 --port 后连不上? --port 改的是容器内监听端口,-p/ports: 映射的右侧必须同步修改(如 --port=9091 配 8121:9091)。本节 5.6 实测即踩过映射未同步导致 curl 无响应的问题,修正映射后恢复。

Q4:宿主机容器很多,cAdvisor 内存涨到 GiB 级正常吗? 正常,统计缓存与容器数量、标签量成正比(实测 60+ 容器全量采集约 1.8~1.9GiB)。按 5.1/5.2/5.4 组合治理后降到 100~150MiB 量级;仍高时查是否有异常大的 label 基数(5.4 白名单收敛)。

Q5:--storage_driver 配了 influxdb 但没数据入库? 按序排查:启动日志是否出现 Caching stats in memory for ...(说明驱动加载);--storage_driver_host 是否从容器内可达(influxdb 容器需与 cAdvisor 同网络或用宿主 IP);账号口令是否含特殊字符需引号包裹。调试期可先换 --storage_driver=stdout 确认统计流正常(5.5.1 实测形态),再切回目标后端。

Q6:/metrics 有 1 万多行,Prometheus 抓取会不会太重? 看基数:118 个指标族本身不大,重的是容器 label 基数(默认全量转换)。按 5.4 白名单治理后单指标 300 字符内、抓取体积降一个量级;再叠加 --enable_metrics 收组,可把 /metrics 控制到千行内。

Q7:能只监控指定容器吗? cAdvisor 没有 per-container 白名单;范围控制到「运行时」粒度(--docker_only 只看 Docker)。按容器过滤在抓取侧做:Prometheus relabel/metric_relabel_configs 按 name/container_label_com_docker_compose_service 过滤。

八、参考链接

  1. 官方运行参数文档(本文参数分组依据):https://github.com/google/cadvisor/blob/v0.60.6/docs/runtime_options.md
  2. 官方存储驱动文档:https://github.com/google/cadvisor/blob/v0.60.6/docs/storage/README.md
  3. 官方 Web UI 文档:https://github.com/google/cadvisor/blob/v0.60.6/docs/web.md
  4. 官方 REST API 文档:https://github.com/google/cadvisor/blob/v0.60.6/docs/api.md
  5. v0.60.6 源码(参数默认值权威出处):https://github.com/google/cadvisor/tree/v0.60.6
  6. 本组件配套文档:《cAdvisor v0.60.6 介绍与选型指南》《cAdvisor Docker Compose 部署指南》