基础设施即代码 / 系统课时
排查 UNREACHABLE 与 SSH 故障
排查 UNREACHABLE 与 SSH 故障
遇到 UNREACHABLE 时,不要先改 Playbook 任务本身。应把连接链拆成 Inventory、名称解析、TCP 端口、SSH 身份、跳板机和 Ansible 连接参数六层,逐层证明“这一层已通”,直到找到第一个失败点。
学习目标
- 从
UNREACHABLE信息判断故障属于哪一层连接链 - 用原生网络与 SSH 命令隔离 DNS、端口、密钥、用户和跳板机问题
- 把验证通过的连接参数固化回 Inventory,并用 Ansible
ping复验
先确认故障发生在传输层
UNREACHABLE 通常表示控制节点还没有成功建立到目标主机的可用连接,因此远端任务往往尚未真正执行。排查顺序应从最外层的“Ansible 到底准备连谁”开始,而不是直接重装 SSH 服务或更换密钥。

第一条原则是:不要跨层猜测。如果名称解析都失败,继续调整私钥没有意义;如果原生 SSH 已经成功,才值得回到 Ansible 的变量优先级和 Inventory 配置。
用 Inventory 还原实际连接参数
先让 Ansible 自己告诉你某台主机最终解析到了哪些变量。下面假设 Inventory 中存在主机别名 app01。
ansible-inventory -i inventory.yml --host app01预期输出示例
{
"ansible_host": "<IP>",
"ansible_port": 22,
"ansible_user": "<REMOTE_USER>"
}实际字段和值取决于你的 Inventory。重点核对 ansible_host、ansible_port、ansible_user,以及是否存在 ansible_ssh_private_key_file 和 ansible_ssh_common_args。如果这里已经指向错误主机、错误端口或错误用户,应先修 Inventory,而不是继续排查网络。
按 DNS 与端口层排除网络问题
当 ansible_host 使用主机名时先验证解析,再验证 SSH TCP 端口。下面的 <HOSTNAME>、<IP> 与 <PORT> 替换为 Inventory 实际值。
getent hosts <HOSTNAME> >/dev/null && echo "dns_ok"
nc -z -w 3 <IP> <PORT> && echo "tcp_ok"预期输出
dns_ok
tcp_ok只有 dns_ok 缺失时,优先检查 DNS、/etc/hosts 或主机名拼写;只有 tcp_ok 缺失时,再检查安全组、防火墙、路由、sshd 监听地址和端口。Connection refused 常表示网络已到主机但端口未监听,Connection timed out 更像路径或防火墙丢包。
脱离 Ansible 验证密钥、用户与跳板机
网络层通过后,用原生 ssh 重现 Ansible 应完成的连接。BatchMode=yes 会禁止交互式密码提示,适合验证自动化连接条件;如果目标主机不经过跳板机,删除 -J 参数即可。
ssh -o BatchMode=yes \
-o ConnectTimeout=5 \
-J <BASTION_USER>@<BASTION_HOST> \
-i <PRIVATE_KEY_PATH> \
-p <PORT> \
<REMOTE_USER>@<IP> 'printf "ssh_ok\n"'预期输出
ssh_ok如果失败,错误文本通常已经能直接指向层级:
| 典型信息 | 优先检查 |
|---|---|
Could not resolve hostname |
主机名、DNS、跳板机上的解析能力 |
Connection refused / Connection timed out |
端口、路由、防火墙、sshd |
Permission denied (publickey) |
远程用户、私钥、公钥授权、密钥文件权限 |
Host key verification failed |
known_hosts 中的主机指纹是否已变化 |
channel 0: open failed: connect failed |
跳板机虽可登录,但它无法访问目标地址或端口 |
回到 Ansible 固化并复验
原生 SSH 成功后,再把已确认的参数写回 Inventory。下面是结构完整的示例;没有跳板机时删除 ansible_ssh_common_args。
all:
hosts:
app01:
ansible_host: <IP>
ansible_port: <PORT>
ansible_user: <REMOTE_USER>
ansible_ssh_private_key_file: <PRIVATE_KEY_PATH>
ansible_ssh_common_args: "-o ProxyJump=<BASTION_USER>@<BASTION_HOST>"这是 Inventory 配置,不会单独产生控制台输出;保存后用下一条 Ansible 命令验证是否真正生效。
ansible -i inventory.yml app01 -m ansible.builtin.ping预期输出
app01 | SUCCESS => {
"changed": false,
"ping": "pong"
}如果原生 SSH 已成功但这里仍失败,在同一命令后追加 -vvv,重点查看 Ansible 实际选择的主机、端口、用户、私钥和 ProxyJump 参数是否与刚才的成功命令一致。此时若错误已经进入 Python 解释器或模块执行阶段,就说明 SSH 传输链基本排除,应转向远端运行环境,而不是继续更换密钥。