Paramiko的SFTP功能需显式管理Transport连接、严格使用绝对路径并逐级创建目录；SSHClient仅适配命令执行，SFTP必须基于Transport构建，且IOError: Failure多因远程路径不存在或权限不足所致。
Paramiko 的 SFTP 功能能用，但直接套用 paramiko.SSHClient() + sftp.put() 很容易卡在连接失败、权限拒绝或路径不存在上——根本原因不是代码写错了，而是没处理 SSH 认证方式、目标路径语义和异常传播这三类问题。
为什么 paramiko.Transport 比 paramiko.SSHClient 更适合 SFTP 场景
SSHClient 是为交互式命令设计的，它默认调用 connect() 时会尝试多种认证方式（密码、密钥、键盘交互），而 SFTP 协议本身依赖底层 Transport 连接。一旦认证流程不明确，比如服务器禁用了密码登录但你只传了 password=，就会抛出模糊的 AuthenticationException，且无法区分是密钥格式错、权限不对，还是根本没走密钥路径。
实操建议：
- 显式创建
paramiko.Transport，再手动加载密钥或设置密码，避免自动协商干扰 - 用
transport.connect(username=..., pkey=...)替代ssh_client.connect(...)，控制认证源头 - 密钥必须是
paramiko.RSAKey或paramiko.Ed25519Key实例，不能直接传文件路径字符串 - 如果用密码，确保目标用户允许密码登录（
PermitRootLogin和PasswordAuthentication在 sshd_config 中已启用）
sftp.put() 报错 IOError: Failure 的真实原因和修复方式
这个错误几乎总是来自路径问题，而非网络中断。SFTP 协议里路径是相对于用户 home 目录的，且不支持 ~ 展开；sftp.put() 也不会自动创建父目录。
立即学习“Python免费学习笔记（深入）”；
常见现象：
- 本地路径存在，但远程路径
/data/logs/2024/06/不存在 → 报Failure - 传
sftp.put("local.txt", "~/remote.txt")→ 报Failure（~不被识别） - 远程目录权限为
drwxr-xr-x，但用户不属于该组 → 报Permission denied
实操建议：
- 先用
sftp.chdir()测试能否进入目标目录，或用sftp.stat()检查路径是否存在 - 用
sftp.mkdir()逐级创建目录，注意捕获IOError（目录已存在时也会抛这个异常） - 远程路径一律用绝对路径，如
/home/user/upload/，不要用~/upload/ - 确认目标目录属主和权限匹配：上传用户需对父目录有
w权限，且 SELinux 或 AppArmor 未拦截
如何安全地复用 SFTP 连接并避免“Connection reset by peer”
频繁新建 Transport + SFTPClient 会导致连接堆积，服务端可能主动断连；而长期保持连接又面临超时自动关闭问题。Paramiko 默认没有心跳机制，空闲 5–15 分钟后常被中间设备（防火墙、负载均衡）断开。
实操建议：
- 用
transport.set_keepalive(30)开启保活，每 30 秒发一次空包（注意：必须在connect()后、open_sftp()前调用） - 不要全局复用同一个
SFTPClient实例，但可复用Transport，每次传输前检查transport.is_active() - 捕获
EOFError和socket.error，触发重连逻辑，而不是直接抛异常 - 传输大文件时加
callback参数（如lambda x, y: None）防止阻塞，但别在里面做耗时操作
真正麻烦的从来不是写几行 sftp.put()，而是当远程目录结构动态变化、SSH 配置随环境切换、或某台服务器突然启用双因素认证时，脚本是否还能沉默运行——这些边界情况不会报语法错误，只会让日志里反复出现一个笼统的 AuthenticationException 或 IOError。
