基础设施即代码 / 系统课时

排查 UNREACHABLE 与 SSH 故障

排查 UNREACHABLE 与 SSH 故障

遇到 UNREACHABLE 时,不要先改 Playbook 任务本身。应把连接链拆成 Inventory、名称解析、TCP 端口、SSH 身份、跳板机和 Ansible 连接参数六层,逐层证明“这一层已通”,直到找到第一个失败点。

学习目标

  • 从 UNREACHABLE 信息判断故障属于哪一层连接链
  • 用原生网络与 SSH 命令隔离 DNS、端口、密钥、用户和跳板机问题
  • 把验证通过的连接参数固化回 Inventory,并用 Ansible ping 复验

先确认故障发生在传输层

UNREACHABLE 通常表示控制节点还没有成功建立到目标主机的可用连接,因此远端任务往往尚未真正执行。排查顺序应从最外层的“Ansible 到底准备连谁”开始,而不是直接重装 SSH 服务或更换密钥。

UNREACHABLE 与 SSH 分层排查流程

第一条原则是:不要跨层猜测。如果名称解析都失败,继续调整私钥没有意义;如果原生 SSH 已经成功,才值得回到 Ansible 的变量优先级和 Inventory 配置。

用 Inventory 还原实际连接参数

先让 Ansible 自己告诉你某台主机最终解析到了哪些变量。下面假设 Inventory 中存在主机别名 app01。

bash
ansible-inventory -i inventory.yml --host app01

预期输出示例

json
{
  "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 实际值。

bash
getent hosts <HOSTNAME> >/dev/null && echo "dns_ok"
nc -z -w 3 <IP> <PORT> && echo "tcp_ok"

预期输出

text
dns_ok
tcp_ok

只有 dns_ok 缺失时,优先检查 DNS、/etc/hosts 或主机名拼写;只有 tcp_ok 缺失时,再检查安全组、防火墙、路由、sshd 监听地址和端口。Connection refused 常表示网络已到主机但端口未监听,Connection timed out 更像路径或防火墙丢包。

脱离 Ansible 验证密钥、用户与跳板机

网络层通过后,用原生 ssh 重现 Ansible 应完成的连接。BatchMode=yes 会禁止交互式密码提示,适合验证自动化连接条件;如果目标主机不经过跳板机,删除 -J 参数即可。

bash
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"'

预期输出

text
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。

yaml
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 命令验证是否真正生效。

bash
ansible -i inventory.yml app01 -m ansible.builtin.ping

预期输出

text
app01 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

如果原生 SSH 已成功但这里仍失败,在同一命令后追加 -vvv,重点查看 Ansible 实际选择的主机、端口、用户、私钥和 ProxyJump 参数是否与刚才的成功命令一致。此时若错误已经进入 Python 解释器或模块执行阶段,就说明 SSH 传输链基本排除,应转向远端运行环境,而不是继续更换密钥。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 UNREACHABLE 与 SSH 故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通