问题现象描述
在使用Fabric库的Connection().sftp()方法时，开发者经常遇到"Authentication failed"错误。这个错误通常表现为：
paramiko.ssh_exception.AuthenticationException: Authentication failed.
该错误可能发生在各种场景下，包括但不限于：首次连接服务器、密钥更换后、服务器配置变更后等情况。错误信息往往缺乏详细说明，导致排查困难。
根本原因分析
经过对大量案例的研究，我们发现认证失败主要源于以下几个核心问题：
- 密钥文件权限不当：SSH协议严格要求密钥文件的权限模式为600(-rw-------)，过宽的权限会导致自动拒绝
- 密钥格式不兼容：现代OpenSSH默认使用OpenSSH格式密钥，而某些Fabric/Paramiko版本可能更兼容PEM格式
- 用户名不匹配：当使用密钥认证时，服务器上的
authorized_keys文件中可能绑定了特定用户名 - 服务器配置限制：sshd_config中可能设置了
PermitRootLogin no或PasswordAuthentication no - 代理转发问题：通过跳板机连接时，SSH代理可能没有正确转发认证信息
解决方案实践
方案1：检查和修复密钥权限
执行以下命令修复密钥权限：
chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub chmod 700 ~/.ssh
在Python代码中可以通过os.chmod()实现相同效果：
import os
os.chmod('/path/to/key', 0o600)
方案2：转换密钥格式
使用ssh-keygen转换密钥格式：
ssh-keygen -p -m PEM -f ~/.ssh/id_rsa
或者在代码中指定密钥类型：
from fabric import Connection
conn = Connection('host', connect_kwargs={
"key_filename": "/path/to/key",
"look_for_keys": False
})
方案3：启用详细日志
配置Paramiko的日志记录可以获取更详细的错误信息：
import logging
logging.basicConfig()
logging.getLogger("paramiko").setLevel(logging.DEBUG)
这将输出包括密钥交换、认证尝试等详细过程的日志，帮助精确定位问题。
方案4：检查服务器配置
在目标服务器上检查以下关键配置：
cat /etc/ssh/sshd_config | grep -E 'PasswordAuthentication|PubkeyAuthentication|PermitRootLogin'
确保至少有以下配置：
PubkeyAuthentication yes PasswordAuthentication no # 如果仅使用密钥认证
高级调试技巧
对于复杂环境，建议采用以下进阶调试方法：
- 使用
ssh -vvv命令模拟连接，对比成功和失败的连接过程差异 - 在Fabric连接配置中显式指定所有参数，避免依赖默认值
- 测试使用密码认证作为临时解决方案，确认网络和基础配置正常
- 检查系统密钥环(ssh-agent)是否干扰了认证过程
预防措施
为避免未来出现类似问题，建议建立以下最佳实践：
- 在CI/CD流水线中加入SSH连接测试阶段
- 使用Ansible等工具管理服务器SSH配置
- 为自动化任务创建专用SSH账户和密钥对
- 定期轮换密钥并更新所有相关配置