指标口径与数据核对

核对监控数据时，应比较同一台主机、同一组设备和同一段采样时间。CPU、网络和磁盘速率是时间段内的平均值；磁盘容量与可用内存是采集时的快照。两次刷新间隔不同、网卡范围不同，或者把 MiB/s 与 Mbit/s 直接比较，都会产生明显差异。

新版 Agent 修正了整机与每核 CPU 采样窗口不一致、磁盘 I/O 重复累计、bind mount 重复显示容量、虚拟网卡重复累计，以及容器和进程采样口径问题。仍运行 v1.20.21 或更早版本的节点需要升级 Agent；只升级网页不能改变旧 Agent 的采集结果。升级前的历史报告仍保留当时的统计值。

常用指标如何计算

指标	统计口径	适合的对照方式
整机 CPU	同一批每核累计时间的两次差值，按时间加权计算；总值为 0–100%	mpstat 3 3，留意 iowait 单独统计
每核 CPU	与整机 CPU 使用相同的两次快照	mpstat -P ALL 3 3
进程 CPU	两轮之间进程新增 CPU 时间 / 实际经过时间；一个逻辑核满载为 100%	pidstat -u 3 3；多线程进程可能超过 100%
已用内存	总内存减去操作系统报告的可用内存	Linux 查看 MemTotal 与 MemAvailable
内存使用率	已用内存 / 总内存	使用同一 available 口径，勿把可回收缓存全部算作已用
磁盘容量	各文件系统的总量、已用量和普通用户可用量	df -kP，单位为 KiB
磁盘使用率	Linux 使用 used / (used + available)，保留文件系统保留块语义	df 的 Use%；整数百分比可能有取整差异
单盘读写速率	对应块设备两次字节累计值的差 / 实际采样时间	iostat -dxk 3 3，比较同一个分区或逻辑设备
整机网络速率	选中网卡各自的字节增量 / 实际采样时间，再求和	sar -n DEV 3 3，只比较相同网卡
容器 CPU	Docker 统计时间差计算；一个逻辑核满载为 100%	docker stats；容器可超过 100%
容器内存	按 Docker CLI 口径扣除非活跃文件缓存，再除以容器内存上限	docker stats

页面容量和速率使用二进制单位：1 KiB = 1024 B，1 MiB = 1024 KiB。带宽供应商常使用十进制位单位：1 Mbit/s = 1,000,000 bit/s，而 1 MiB/s ≈ 8.39 Mbit/s。

Linux 的 iowait 不计作 CPU 执行忙碌时间；虚拟机的 steal 时间计入非空闲时间。CPU 负载 load1/load5/load15 表示运行或等待中的任务数量，不是 CPU 百分比，不能直接拿 load1 = 2 与 CPU = 2% 对照。

磁盘：容量、挂载点与 I/O

默认收集磁盘时，同一文件系统的目录绑定挂载只显示一次，优先保留原始文件系统挂载点。例如把数据盘上的备份目录绑定到应用目录后，这两个路径仍共享同一块盘的容量。Btrfs 和 ZFS 子卷可能有各自的容量或配额语义，不仅凭同一底层设备就合并。

只读镜像文件系统 squashfs、iso9660 和只读 UDF 默认不参与磁盘列表与最高使用率统计，避免 Snap 或光盘镜像一直显示 100%。普通的只读数据盘仍保留。显式设置 disk_mountpoints 后，按选择的挂载点采集，也可保留绑定挂载与镜像文件系统：

{
  "disk_mountpoints": ["/", "/www"]
}

Linux 磁盘速率根据内核的设备主次编号匹配，分别计算分区、LVM/设备映射器与 NVMe 的 I/O。整盘与其分区不会再一起相加后复制给每个挂载点。设备详情的速率属于对应的块设备，不是某个目录独有的文件读写量。总览读写速率按对应 I/O 设备去重后汇总，磁盘使用率则仍表示已采集挂载盘中的最高使用率。

Windows 按 C:、D: 等卷分别匹配，读取容量时使用卷根目录。无法可靠关联到块设备的文件系统仍可提供容量，但不冒用全机 I/O 作为该文件系统的速度。首次采样、设备重置或计数读取失败后，需要重新建立两次有效采样；报告中的 ioAvailable 用于区分尚不可用与真实的零速率。

Docker Agent 会检查 /host 中的路径是否对应宿主机记录的同一个文件系统。若 Agent 启动后新增挂载，而现有容器的私有挂载未同步，Agent 会尝试核验宿主机进程根目录中的路径；仍不能访问或设备不匹配时跳过该项，避免把系统盘容量标成数据盘。新增磁盘后发现挂载项缺失时，应检查宿主机和容器的挂载可见性。

两块盘、三个挂载路径的示例

假设一台主机有系统盘与数据盘，并把数据盘上的备份目录绑定到应用目录。以下是用于说明关系的示例，不是实际服务器占用数据：

挂载点	设备	主次编号	含义
/	/dev/vda1	252:1	系统盘文件系统
/data	/dev/vdb1	252:17	数据盘文件系统
/opt/guanlan-monitor/backups	数据盘目录的 bind mount	252:17	与 /data 共享容量

后两行是同一文件系统。默认显示 / 与 /data 两个容量条目，并分别使用 vda1、vdb1 的速率。如果 /proc/diskstats 同时出现 vda 与 vda1，两行可能记录同一批写入，不能把整盘和它的分区一起相加。核对时应按主次编号及挂载关系选择对应设备。

网络：先确认采集了哪些网卡

默认网络汇总排除回环、容器虚拟接口、网桥和常见隧道接口，避免同一流量经过 eth0、Docker 网桥、veth 后被重复累计。Bond 使用聚合接口并排除其成员；存在下层接口时，避免再叠加对应的 VLAN/macvlan 层。单独处于当前网络命名空间内的有效 eth0 不会仅因为是虚拟接口就被排除。

如果需要专门监测 VPN、多个出口或者自定义网卡名称，可以在实际 Agent 配置中设置：

{
  "network_interfaces": ["eth0", "eth1"]
}

列表是明确选择，包含其中的 VPN 或回环接口也会被采集。应先确认所选接口不会重复承载同一层流量；同时选择物理口及其 VLAN 子接口可能再次重复累计。报告中的 sampledInterfaces 会列出实际参与汇总的接口。此配置是手工高级配置，修改时保留原有服务器地址、设备 ID 与密钥字段，并重启对应 Agent 服务使配置生效；安装命令暂未提供网卡白名单参数。

发送/接收累计值来自所选接口的操作系统计数器，不是按月计费流量。重启、接口重建和采集范围调整会改变累计值。速率逐接口计算；遇到新接口、重置或读取失败时重新建立采样基线，避免出现瞬时尖峰。

TCP 连接数来自 TCP 连接枚举，包含监听等状态，不能直接与只筛选 ESTABLISHED 的连接数量比较。关闭连接采集时也不应把缺少数据解释为确实没有连接。

内存、进程与容器

Linux 可用内存包括操作系统预计能够回收利用的部分缓存。不同发行版的 free 对 used 一栏存在版本差异，建议直接核对 total - available。磁盘 ext4 的保留块也类似：used + available 小于文件系统总量可以是正常情况。

进程 CPU 采用相邻两轮采样，按 PID 与进程创建时间识别实例，避免 PID 重用后串用旧数据。首轮尚无增量基线；多线程进程超过 100% 是合法值。进程内存百分比使用常驻内存 RSS 占整机总内存的比例，不等同于虚拟地址空间占比。

容器 CPU 使用同一容器实例的两轮 Docker 计数差，容器重启后重新采样。容器 CPU 的 200% 约表示使用两个逻辑核；主机整体 CPU 则始终以整机为 100%。容器内存使用率的分母是容器内存上限，与整机内存使用率可能不同。

Docker/Podman API 不可访问、容器停止或统计读取失败时，报告会区分统计不可用状态。容器重启次数读取自运行时，不再把固定的零作为重启次数。宿主机、各容器网络累计值属于不同统计范围，不应直接相加。

Linux 排查命令

先确认配置的 Agent 上报周期，例如 3 秒，再让对照工具按相近周期采样。部分工具第一组结果是开机以来的平均值，比较后续间隔结果更合适。mpstat、pidstat、iostat、sar 通常由发行版的 sysstat 软件包提供。

# CPU、每核和进程；观察后续间隔结果
mpstat -P ALL 3 3
pidstat -u -r 3 3

# 直接核对内存总量与可用量
awk '/^(MemTotal|MemAvailable|Cached|SwapTotal|SwapFree):/ { print }' /proc/meminfo

# 挂载盘、设备身份及容量；df 的单位是 KiB
findmnt -rn -t ext4,xfs,btrfs,zfs -o TARGET,SOURCE,FSTYPE,MAJ:MIN
df -kP
iostat -dxk 3 3

# 接口清单与相同接口的流量
ip -br link
sar -n DEV 3 3

# 容器统计
docker stats --no-stream

# 时钟同步状态
date -u
timedatectl status

对于 Docker Agent，可对比宿主机与容器内的同一挂载路径。把 <Agent容器名> 和 /www 换成实际值：

stat -c 'device=%d path=%n' /www
df -kP /www
docker exec <Agent容器名> stat -c 'device=%d path=%n' /host/www
docker exec <Agent容器名> df -kP /host/www

不同路径的设备号相同，通常说明它们属于同一文件系统。核对时保留输出时间、Agent 版本、采样周期和所选网卡名即可；不要把整个含密钥的 Agent 配置粘贴到反馈内容。

采样时间与当前限制

上报周期表示计划的开始间隔。采集与网络发送超过一个周期时，Agent 跳过已经错过的时间点，不会连续补采几次来制造更密集的实时数据。各项速率使用各自真实的采样间隔，但一份报告中的 CPU、内存、磁盘、容器并非同一瞬间的原子快照。

离线缓冲恢复后的报告保留原采集时间。总控依据采集时间排列历史，并区分旧报告补传与最新数据；补传到达的时间不等于当时刚刚采集。

系统时钟仍需要由操作系统的时间同步服务维护。Agent 不会自动修正主机时钟，总控会拒绝比服务器时间超前 5 分钟以上的报告；时钟明显落后、回拨或离线缓冲积压可能影响“最新数据”和图表时间位置。跨机器时钟偏移的自动估算与历史时间修复尚不提供，排查这类问题时应同时检查 Agent 主机与总控的 UTC 时间。