OpenSSH ControlMaster 复用连接的失效原因

OpenSSH 的 ControlMaster 不是“打开后所有 ssh 都自动共用一条连接”。它要求后续命令算出同一个 ControlPath，并且主连接仍在监听控制套接字；如果 ControlPersist 没有让主连接驻留，首个会话退出后复用自然结束。

官方地址：https://www.openssh.org/

排查时先不要反复删除 socket。先用 ssh -G 看最终配置，再用 ssh -O check 判断主连接是否存活，最后结合 -vvv 区分“没有命中复用”和“命中了但主连接已失效”。

先把“没有复用”分成四种现场

如果后续命令只是重新完成了一次认证，通常是 ControlPath 没有命中：目标主机别名、端口或登录用户不同，都会让最终路径不同。若日志出现控制 socket 无法连接，则更像是路径存在但主连接已经退出，或者 socket 文件属于另一个用户。

还有一种容易忽略的情况：ControlMaster yes 只让当前进程成为主连接，ControlPersist no（默认行为）并不会在初始会话关闭后把它留在后台。想让后续命令继续复用，应明确配置一个驻留时间。

ControlPath 为什么最容易造成误判

ControlPath 是本地 Unix 控制套接字的位置，不是远端目录。OpenSSH 手册建议路径至少包含主机、端口和用户，或者使用 %C，让不同连接身份得到不同的 socket。将它放进其他用户可写的目录也不安全。

# 建立一个只属于当前用户的控制套接字目录
mkdir -p ~/.ssh/cm
chmod 700 ~/.ssh/cm

# %C 根据本地端、目标主机、端口和远端用户生成稳定标识
cat >> ~/.ssh/config 

这里的关键不是记住某一个 socket 文件名，而是保证主连接与后续命令读取到完全相同的有效配置。若一个命令使用 app-prod，另一个命令直接使用 IP，别名展开、用户名或跳板配置可能不同，复用就会落到另一条连接上。

用 -O 和 -vvv 找到断点

先查看最终配置，不要只看配置文件中“写了什么”。ssh -G 会输出经过 Host 匹配后的结果，适合确认 controlmaster、controlpath、controlpersist 和连接身份。

# 只查看 app-prod 最终生效的复用配置
ssh -G app-prod | grep -E '^(controlmaster|controlpath|controlpersist|hostname|user|port) '

# 通过同一套参数检查主连接是否仍由 socket 提供服务
ssh -O check -S "$HOME/.ssh/cm/实际路径" app-prod

# 查看主连接信息，确认复用的目标与通道状态
ssh -O conninfo -S "$HOME/.ssh/cm/实际路径" app-prod

如果不知道实际路径，可以临时让配置中的 ControlPath 使用已知目录，并用 ssh -vvv app-prod true 观察日志。看到尝试连接控制 socket，说明已经进入复用判断；完全没有相关日志，优先回到 Host 匹配和配置来源排查。

主连接已失效时，优先让 OpenSSH 自己退出它，而不是直接删除文件：

# 请求主连接优雅退出，参数必须与它使用的 ControlPath 对应
ssh -O exit -S "$HOME/.ssh/cm/实际路径" app-prod

# 需要立即停止接收新的复用请求时，使用 stop
ssh -O stop -S "$HOME/.ssh/cm/实际路径" app-prod

修复后保留可控的驻留时间

日常运维通常使用 ControlMaster auto 配合 ControlPersist 5m 或 10m。auto 找不到可用主连接时会正常建立新连接，避免把一次 socket 故障扩大成完全无法登录；有限的驻留时间则能防止长期闲置连接积累。

如果使用 ProxyJump、不同端口、不同用户或多个跳板别名，最好让这些连接身份都进入独立的 Host 配置，并保持 ControlPath 唯一。远端服务重启、网络切换、密钥或配置改变后，旧主连接也可能不再代表当前期望的连接，此时重新建立主连接比强行复用更可靠。

两个容易漏掉的边界问题

• 路径太长：深层目录加上完整主机名可能触及 Unix socket 路径限制，使用短目录和 %C 通常更稳。
• 转发状态属于主连接：X11 和 ssh-agent 转发沿用主连接的状态，后续会话不能在同一复用连接上获得另一套转发上下文。
• 权限不一致：用不同本地用户、sudo 环境或不同 HOME 启动 ssh 时，看到的 ~/.ssh/cm 并不是同一个目录。

常见追问

为什么 socket 文件还在，复用仍然失败？文件存在不等于主进程还在监听。用 ssh -O check 看主连接状态，再按同一 ControlPath 执行 ssh -O exit 清理。

ControlMaster auto 会不会导致错误被隐藏？它可能在控制 socket 不存在或不可监听时回退到普通连接，所以“命令能成功”不代表复用生效。需要结合 -vvv 或连接耗时确认是否真正命中主连接。

总结

OpenSSH ControlMaster 的复用条件可以归纳为：有效配置一致、ControlPath 唯一且可访问、主连接仍在监听、ControlPersist 覆盖后续使用时间。按“最终配置—socket 状态—详细日志”的顺序排查，比盲目删除文件或反复重试更快找到失效原因。

参考资料：https://www.openssh.org/manual.html、https://man.openbsd.org/OpenBSD-7.7/ssh_config.5、https://man.openbsd.org/ssh