2. Netmiko核心连接机制
Netmiko 的入口几乎总是 ConnectHandler()。它看起来只是一个构造函数，实际上承担了三件事：把设备类型映射到具体驱动类、把认证与传输参数组装成 Paramiko 连接、把会话级超时与重试策略固化到对象属性中。理解这三件事，才能解释“为什么同样的代码连 Cisco IOS 成功、连华为却报 Pattern not detected”，也才能把偶发的连接失败从“玄学”变成可定位的问题。
一、ConnectHandler 参数的分层
ConnectHandler 的参数可以按作用域分成四层，混淆层次是配置错误的主要来源。
- 设备标识层：
device_type决定驱动类，host、port决定 TCP 目标，username、password、secret决定认证与提权。 - 传输层：
protocol（默认 ssh，可设 telnet）、ssh_config_file、allow_agent、use_keys、key_file、disabled_algorithms。 - 会话行为层：
timeout（TCP/认证阶段）、session_timeout（read 循环）、read_timeout_override、global_delay_factor、fast_cli、conn_timeout。 - 交互层：
expect_string、auto_connect、verbose、global_cmd_verify。
其中 device_type 是唯一必填且不可猜的参数。Netmiko 内部维护一张 CLASS_MAPPER 字典，把 cisco_ios 映射到 HuaweiSSH 之外的 CiscoIosSSH，把 huawei 映射到 HuaweiSSH，把 juniper_junos 映射到 JuniperSSH。驱动类里定义了该厂商的提示符正则、分页命令、退出命令、配置模式进入方式。选错 device_type，即使 SSH 登录成功，后续 send_command 也会因为提示符匹配不上而超时。
python -c "from netmiko import platforms; print(platforms)" 查看当前版本支持的平台名，再对照设备实际操作系统选择，不要凭厂商名硬猜。二、设备类型驱动与提示符匹配
驱动类的核心是 base_prompt 与 _prompt 正则。以 Cisco IOS 为例，提示符形如 Router# 或 Router(config)#，驱动用 r"[>#]" 类模式识别；华为 VRP 的提示符形如 <Huawei> 或 [Huawei]，驱动用 r"[<\[]" 类模式识别。当设备提示符被自定义（例如加了 hostname 前缀或 banner），正则仍能匹配，但若提示符被改成不含这些符号的形式，就必须用 expect_string 显式指定。
另一个常被忽略的是 fast_cli。默认 fast_cli=True 时，Netmiko 会缩短命令回显等待，依赖提示符精确匹配；某些老设备或高延迟链路下会误判，此时设 fast_cli=False 并配合 global_delay_factor=2 更稳。这不是“越新越好”的参数，而是与设备响应速度匹配的取舍。
三、SSH 密钥与密码认证
Netmiko 底层用 Paramiko，因此认证方式与 Paramiko 一致。密码认证直接传 password；密钥认证需要 use_keys=True 并指定 key_file，同时把 allow_agent 设为 False 以避免本机 ssh-agent 干扰。若私钥有口令，还要传 passphrase。典型写法：
from netmiko import ConnectHandler
device = {
"device_type": "cisco_ios",
"host": "10.0.0.1",
"username": "netops",
"use_keys": True,
"key_file": "/home/netops/.ssh/id_ed25519",
"allow_agent": False,
"passphrase": "key-pass",
"timeout": 20,
"session_timeout": 60,
"fast_cli": False,
"global_delay_factor": 2,
}
conn = ConnectHandler(**device)
print(conn.find_prompt())
conn.disconnect()
密钥认证失败时，Paramiko 抛出的异常往往只写 Authentication failed，不区分“密钥格式不对”还是“服务端未授权”。排查顺序是：先用 ssh -i key_file user@host 在命令行验证密钥本身可用，再检查 Netmiko 是否因 allow_agent=True 优先用了 agent 里的错误密钥。把 allow_agent 显式设为 False 能排除这一类干扰。
四、超时与重试策略
Netmiko 的超时不是单一值，而是分阶段生效：timeout 管 TCP 建连与认证，session_timeout 管每次 read 循环等待提示符，read_timeout_override 可对单条命令覆盖。重试则分两层：连接层可用 conn_timeout 与外部循环重试，命令层可用 send_command(..., read_timeout=...) 单独放宽。
工程上更稳的做法是“连接重试 + 命令级超时”组合，而不是把 timeout 一味调大。下面是一个可复用的重试封装示例，参数均为示例值，实际需按网络质量调整：
import time
from netmiko import ConnectHandler, NetmikoTimeoutException
def connect_with_retry(device, retries=3, backoff=5):
last_err = None
for i in range(retries):
try:
return ConnectHandler(**device)
except NetmikoTimeoutException as e:
last_err = e
time.sleep(backoff * (i + 1))
raise last_err
判断连接是否真正可用，不能只看 ConnectHandler 是否返回。建议在拿到对象后立即执行 conn.find_prompt()，确认提示符符合预期；再执行一条只读命令如 show version，观察返回中是否包含设备型号或版本关键字。若 find_prompt() 返回空串或异常，说明会话已建立但驱动不匹配，应优先检查 device_type 与 expect_string。
把这张图对应到实际排障：如果 ConnectHandler 直接抛 NetmikoTimeoutException，问题在 TCP 或认证阶段，先查 host、port、timeout 与网络可达性；如果对象返回但 find_prompt() 异常，问题在驱动匹配，先查 device_type 与提示符；如果 find_prompt() 正常但 send_command 超时，问题在 session_timeout 或 fast_cli，可先设 fast_cli=False 并适当放大 global_delay_factor。按这个顺序排查，绝大多数连接类故障都能在几分钟内定位到具体参数，而不是反复重启脚本。