DevOps知识中心
DevOps知识中心

解决 Ansible Playbook 中的 SSH 连接失败问题

本专家指南提供了一种系统化的方法，用于解决运行 Ansible Playbook 时常见的 SSH 连接失败问题。了解如何利用最大详细级别 (`-vvv`) 进行诊断，解决与私钥和权限相关的身份验证错误，修复“主机密钥验证失败”（`Host key verification failed`）问题，以及诊断网络阻塞。实际操作步骤和命令行示例可确保您快速隔离和解决连接超时和权限拒绝消息的根本原因，从而恢复可靠的自动化。

56 浏览量

解决 Ansible Playbook 中 SSH 连接失败的问题

Ansible 完全依赖安全外壳 (SSH) 协议与托管节点进行通信。当 Ansible playbook 因连接错误而失败时，这几乎总是指向控制机器和目标主机之间标准 SSH 设置中存在的根本问题。了解如何系统地诊断这些故障对于维护可靠的自动化至关重要。

本指南提供了一个分步方法，用于诊断和解决运行 Ansible playbook 时遇到的最常见的 SSH 连接故障，确保您的配置管理顺利运行。

阶段 1：启用详细信息输出和初始检查

Ansible 故障排除中最重要的工具是增加输出的详细程度。SSH 错误通常会被掩盖，但最大详细程度会揭示 Ansible 正在使用的确切参数以及底层 OpenSSH 客户端返回的具体错误消息。

使用详细信息标志

使用三个或四个详细信息标志（-v、-vv、-vvv、-vvvv）运行您的测试命令或 playbook。大多数连接问题都可以通过查看来自 -vvv 的输出来解决。

# 测试与库存中名为 'webserver' 的主机的连接性
ansible webserver -m ansible.builtin.ping -vvv

# 使用最大调试级别运行 playbook
ansible-playbook site.yml -i inventory.ini -vvvv

验证库存和主机状态

确保您要定位的主机已正确定义且可达。

  1. 主机名是否正确？仔细检查您的库存文件（/etc/ansible/hosts 或自定义库存）中的拼写。
  2. 目标主机是否已启动？确保托管节点已开机并在网络上可访问。
  3. 库存变量是否正确？确认如 ansible_host（IP 地址或主机名）和 ansible_user（远程用户名）等基本变量是否已为目标组或主机正确设置。
# 示例库存片段
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

阶段 2：验证基本手动连接性

如果 Ansible 无法连接，第一步必须是确认使用与 Ansible 配置的完全相同的用户、密钥和端口，手动 SSH 连接是否正常工作。

手动 SSH 测试

如果您使用的是特定用户（ansible_user）和特定私钥（ansible_ssh_private_key_file），请手动复制该连接。

# 标准 SSH 测试（如果使用默认端口和密钥）
ssh <ansible_user>@<ansible_host>

# 使用非默认私钥和端口进行测试
ssh -i /path/to/private/key -p 2222 [email protected]

如果手动 SSH 测试失败，问题在于环境，而不是 Ansible。在继续处理 Ansible 之前，请先修复核心的 SSH 问题。

阶段 3：诊断身份验证失败

身份验证失败是导致 Ansible 连接问题最常见的原因。这些通常表现为 Authentication failed（身份验证失败）或 Permission denied（拒绝访问）错误。

3.1 密钥权限和位置

如果 Ansible 使用 SSH 密钥，请确保私钥文件在控制机器上具有正确、受限的权限。SSH 通常会拒绝权限过于宽松的密钥。

# 在私钥文件上设置正确的权限
chmod 600 /path/to/private/key

此外，如果您使用 SSH 代理，请确保已添加您的密钥：

# 如有必要，启动代理
eval "$(ssh-agent -s)"
# 将您的密钥添加到代理
ssh-add /path/to/private/key

3.2 密码提示失败（超时/缺少密码）

如果您的设置需要密码（不推荐用于生产环境，但在实验室中很常见），则需要向 Ansible 提供该密码。如果连接挂起或超时，Ansible 很可能正在等待一个从未提供的密码。

使用 --ask-pass 或 -k 标志来提示输入 SSH 连接密码：

ansible webserver -m ansible.builtin.ping -k

3.3 远程授权密钥

验证您的私钥对应的公钥是否已正确安装在托管节点上的 ~/.ssh/authorized_keys 文件中，并且远程侧的文件和目录权限是否正确（.ssh 为 700，authorized_keys 为 600）。

阶段 4：解决主机密钥错误

Ansible 会遵循 known_hosts 文件，该文件存储远程服务器的数字指纹。如果托管节点的密钥发生更改（例如，由于重建或 IP 重新分配），SSH 连接尝试将失败，并出现类似于中间人攻击的警告。

Host key verification failed 错误

当出现此错误时，您必须更新或删除冲突的密钥条目。

  1. 识别错误输出中提到的 ~/.ssh/known_hosts 中的行号。
  2. 使用 ssh-keygen 删除条目。
# 将 <hostname_or_ip> 替换为实际失败的主机
ssh-keygen -R <hostname_or_ip>

⚠️ 安全警告：禁用主机检查

对于临时测试或在预期主机不稳定的高度受控的实验室环境中，您可以配置 Ansible 以忽略主机密钥检查。强烈不建议在生产环境中使用此方法，因为它会使您面临 MITM 攻击的风险。

在您的 ansible.cfg（或临时环境变量）中：
ini [defaults] host_key_checking = False

阶段 5：网络、防火墙和远程环境问题

有时 SSH 可以连接，但连接会因网络配置或目标机器上的限制而停顿或失败。

5.1 防火墙阻止

如果连接在没有提示的情况下超时，则可能是防火墙阻止了连接尝试。请检查三个点的防火墙：

  1. 本地（控制机器）：确保允许通过端口 22（或自定义端口）的出站流量。
  2. 网络路径：确保没有中间网络 ACL 或公司防火墙阻止流量。
  3. 远程（托管节点）：验证远程主机的防火墙（firewalld、ufw 等）是否已打开 SSH（通常是端口 22）并针对正确的网络接口进行了配置。

5.2 Python 解释器错误

Ansible 要求托管节点上存在 Python 解释器以执行模块。虽然这不严格来说是SSH 故障，但 Ansible 的初始连接阶段涉及事实收集，这是一个 Python 脚本执行过程。如果目标机器是缺少 Python 3 的最小安装，连接可能会在设置阶段失败。

如果您的目标使用 Python 3 但解释器路径不标准（例如，python3.8 而不是 python3），请在库存中指定正确的路径：

[target_host]
ansible_python_interpreter=/usr/bin/python3.8

5.3 SELinux 或 AppArmor 上下文

在极少数情况下，过于严格的安全模块（如 RHEL/CentOS/Fedora 上的 SELinux 或 Ubuntu/Debian 上的 AppArmor）可能会阻止在 SSH 会话期间正确访问远程用户的 shell 配置文件或目录权限。检查远程主机上的审计日志（/var/log/audit/audit.log 或等效文件），查找与 SSH 或用户主目录访问相关的 AVC 拒绝信息。

常见连接错误和解决方案摘要

错误消息 可能原因 可操作的修复方法
Permission denied (publickey). 未识别密钥或密钥权限错误。 对私钥执行 chmod 600；验证远程主机上的公钥。
Host key verification failed. 主机密钥已更改或 known_hosts 文件已损坏。 使用 ssh-keygen -R hostname 删除旧条目。
Connection timed out. 防火墙阻塞或主机已关闭/无法访问。 检查手动连接性（ping、ssh）；验证目标主机上的防火墙规则。
连接挂起/停滞。 等待未提供的密码输入。 使用 -k 运行或配置基于密钥的身份验证。

结论

排查 Ansible 中的 SSH 连接问题主要是一个系统化的过程，用于调试底层的 SSH 客户端配置。通过从基本手动连接检查开始，增加详细程度（-vvv），并系统地验证身份验证、主机密钥和网络路径，您可以快速隔离和解决大多数连接故障，使您的自动化工作流程得以不间断地继续进行。