network-interface-health

网络接口健康度诊断 (Network Interface Health)

当怀疑网络异常是由物理链路、交换机端口、线缆、光模块、双工设置或接口拥塞引起时，可以使用本 Skill。

适用场景

• 主机或 VLAN 出现丢包、延迟飙升或偶发性不可达。
• 交换机或路由器接口出现 CRC 校验错误、超短帧（runts）、超长帧（giants）、丢包（drops）、复位（resets）或端口抖动（flapping）。
• 准备更换硬件前，需要对比链路两端的接口状态。
• 变更窗口期内，需要留存变更前后的接口计数器对比证据。
• 监控告警提示 ifInErrors、ifOutErrors 或 ifOutDiscards 增长。

工作原理

接口计数器是排查故障的依据，但相比绝对数值，增量趋势更为关键。标准流程为：记录基线 -> 等待固定观察间隔 -> 再次抓取计数器 -> 对比增量。

show interfaces <interface>
show interfaces <interface> status
show logging | include <interface>|changed state|line protocol

在 Linux 主机上：

ip -s link show <interface>
ethtool <interface>
ethtool -S <interface>

常见计数器对照表

计数器	含义	常见原因
CRC	接收到的数据帧校验失败	网线损坏、光纤脏污、光模块故障、双工模式不匹配
input errors	接收端错误统计汇总	下结论前需先排查具体子项计数器
runts	小于以太网最小长度的残缺帧	双工不匹配、存在冲突域、网卡故障
giants	超出预期 MTU 的超长帧	MTU 设置不一致或超大帧（jumbo-frame）边界问题
input drops	设备无法接收/处理入站数据包	突发流量、超分过载、CPU 处理路径瓶颈、队列压强过大
output drops	出站队列丢弃的数据包	网络拥塞、QoS 策略拦截、上行链路带宽不足
resets	接口硬件复位	端口抖动、Keepalive 失败、驱动异常、光模块或电源故障
collisions	以太网冲突计数	半双工模式或协商不匹配

诊断流程

CRC 校验错误或入站错误 (Input Errors)

1. 确认计数器是否在持续增长，而不仅是历史遗留数值。
2. 检查链路两端的接口。接收端的错误通常反映的是传入该侧的信号质量问题，不一定是报错端口本身有问题。
3. 更换网线，或清洁/更换光纤和光模块。
4. 确认链路两端的速率与双工模式配置一致。
5. 检查相同时间戳附近的日志是否有端口抖动（flap）记录。

丢包 (Drops)

1. 区分入站丢包（input drops）与出站丢包（output drops）。
2. 将接口实时速率与物理带宽容量进行对比。
3. 检查 QoS 策略、队列计数器，以及该链路是否为高超分比的上行链路。
4. 队列调优应放在次要位置。优先证明链路是否存在真实拥塞。

双工与速率 (Duplex And Speed)

在现代以太网链路中，若双边均支持，优先使用自动协商（auto-negotiation）。如果必须固定参数，务必在两端同时显式配置并记录原因。切勿在链路一端配置固定速率/双工，而另一端保持自协商。

show interfaces <interface> | include duplex|speed

安全解析器示例 (Safe Parser Example)

按 Header 切分每一个接口数据块（从一个 Header 切到下一个 Header）。不要使用固定字符窗口截取，因为大型接口数据块可能导致计数器被遗漏或错配到其他端口。

import re
from typing import Any

HEADER_RE = re.compile(
    r"^(?P<name>\S+) is (?P<status>(?:administratively )?down|up), "
    r"line protocol is (?P<protocol>up|down)",
    re.I | re.M,
)
ERROR_RE = re.compile(r"(?P<input>\d+) input errors, (?P<crc>\d+) CRC", re.I)
DROP_RE = re.compile(r"(?P<output>\d+) output errors", re.I)
DUPLEX_RE = re.compile(r"(?P<duplex>Full|Half|Auto)-duplex,\s+(?P<speed>[^,]+)", re.I)

def parse_show_interfaces(raw: str) -> list[dict[str, Any]]:
    headers = list(HEADER_RE.finditer(raw))
    interfaces = []
    for index, header in enumerate(headers):
        end = headers[index + 1].start() if index + 1 < len(headers) else len(raw)
        block = raw[header.start():end]
        errors = ERROR_RE.search(block)
        drops = DROP_RE.search(block)
        duplex = DUPLEX_RE.search(block)
        interfaces.append({
            "name": header.group("name"),
            "status": header.group("status"),
            "protocol": header.group("protocol"),
            "duplex": duplex.group("duplex") if duplex else "unknown",
            "speed": duplex.group("speed").strip() if duplex else "unknown",
            "input_errors": int(errors.group("input")) if errors else 0,
            "crc_errors": int(errors.group("crc")) if errors else 0,
            "output_errors": int(drops.group("output")) if drops else 0,
        })
    return interfaces

实战案例

单交换机端口持续出现 CRC 错误

1. 记录本端端口的计数器基线。
2. 记录对端连接端口的计数器基线。
3. 在调整路由规则或防火墙策略前，优先更换网线或光模块。
4. 必须在保存完基线数据后才能清空计数器（Clear counters）。
5. 间隔固定时间后重新检查。

外网网速慢但局域网正常

1. 检查 WAN 接口的丢包及错误计数。
2. 检查 LAN 上行链路利用率与出站丢包（output drops）。
3. 若 WAN 链路无报错但吞吐量依然低下，检查网关设备的 CPU 占用率。
4. 在推卸给上游运营商之前，先对比有线网与无线网的测试结果。

避坑指南 (Anti-Patterns)

• 还没保存基线数据就直接清空计数器。
• 只看链路的单侧接口，忽略对端状态。
• 没有结合时间窗口，把历史遗留的 CRC 计数误判为当前依然存在的故障。
• 一端配置自动协商，另一端配置固定速率/双工模式。
• 还没排查链路拥塞情况，就直接把出站丢包归咎于网线硬件问题。

参见 (See Also)

• Agent: network-troubleshooter
• Skill: network-config-validation
• Skill: homelab-network-setup