network-interface-health

Network Interface Health

當網路異常症狀可能是由實體連結、交換器埠（switch port）、網路線、光纖收發器（transceiver）、雙工設定或介面壅塞所引起時，請使用此 Skill。

使用時機

• 主機或 VLAN 出現封包遺失（packet loss）、延遲突然飆高（latency spikes）或斷斷續續無法連線。
• 交換器或路由器介面顯示 CRC 錯誤、runt 封包、giant 封包、掉封包、重置（reset）或連線震盪（flap）。
• 在更換硬體設備前，需要比對連結兩端的介面狀態。
• 在變更維護時段（change window）中，需要留存變更前後的介面計數器佐證資料。
• 監控系統回報 ifInErrors、ifOutErrors 或 ifOutDiscards 持續上升。

運作方式

介面計數器是重要的佐證，但比起絕對數值，觀察「增長趨勢」更為關鍵。請先擷取基準值（baseline），等待一段測量區間後再次擷取，並比對變化的增量。

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>

計數器參考指南

Counter	Meaning	Common cause
CRC	接收到的訊框檢查碼（Checksum）驗證失敗	網路線品質不良、光纖接頭髒污、光學模組損壞、雙工模式不一致
input errors	接收端錯誤累計總數	在下結論前請先檢查子項計數器
runts	小於標準乙太網路最小尺寸的訊框	雙工模式不一致、碰撞網域（Collision Domain）問題、網路卡故障
giants	大於預期 MTU 尺寸的訊框	MTU 設定不符或巨型訊框（Jumbo Frame）邊界問題
input drops	設備無法處理傳入的封包	突發流量（Burst）、過度超賣（Oversubscription）、CPU 處理管道過載、佇列壓力過大
output drops	傳出佇列丟棄的封包	網路壅塞、QoS 策略限制、上行鏈路（Uplink）頻寬不足
resets	介面硬體重置次數	連線震盪、Keepalive 超時、驅動程式問題、光學模組故障、供電問題
collisions	乙太網路碰撞計數	半雙工模式或速度/雙工協商不符

診斷流程

CRC 或輸入錯誤

1. 確認計數器持續在增加，而不只是過去留下的歷史紀錄。
2. 比對連結兩端的狀態。接收端出現錯誤通常代表該端接收到的訊號品質有問題，未必是回報錯誤的埠本身有硬體故障。
3. 更換跳線（Patch Cable），或清潔/更換光纖與光學模組。
4. 確認兩端的速率（Speed）與雙工（Duplex）設定完全一致。
5. 檢查日誌中相同時間點附近是否有連線震盪（Flap）事件。

封包遺失（Drops）

1. 區分輸入丟包（Input Drops）與輸出丟包（Output Drops）。
2. 比對介面的即時傳輸速率與最大容量。
3. 檢查 QoS 策略、佇列計數器，以及該連結是否為過度超賣的上行鏈路（Oversubscribed Uplink）。
4. 將佇列調校視為次要步驟；首要任務是先釐清鏈路是否真的處於壅塞狀態。

雙工與速率

在現代乙太網路連結中，只要兩端設備皆支援，應優先使用自動協商（Auto-negotiation）。若其中一端必須指定固定值，請務必手動將兩端皆設定為固定值並記錄原因。切勿在同一連結上出現一端使用固定速率/雙工、另一端使用自動協商的情況。

show interfaces <interface> | include duplex|speed

安全的解析器範例

請依據標頭（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. 完成基準值紀錄後，方可清除計數器。
5. 經過固定時間間隔後再次檢查。

外網速度慢但區域網路（LAN）正常

1. 檢查 WAN 介面的掉封包與錯誤數值。
2. 檢查 LAN 上行鏈路的利用率與 Output Drops。
3. 若 WAN 鏈路運作正常但吞吐量（Throughput）依然低下，請檢查閘道器（Gateway）的 CPU 負載。
4. 在歸咎於上游 ISP 服務之前，先比對有線與無線網路的測試結果。

反模式（應避免的做法）

• 在保存基準值前就清除計數器。
• 只觀察單一端的介面狀態。
• 未設定時間區間觀察，就將過去累積的 CRC 紀錄直接視為當前發生的問題。
• 一端設定自動協商，另一端卻使用固定速率/雙工。
• 在排除網路壅塞前，就將 Output Drops 歸咎於網路線故障。

延伸參考

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