SSH ControlMaster 复用连接并限制共享范围的方法

如果同一台 Linux 管理机需要连续执行多次 ssh、scp 或 sftp，可以让第一个 SSH 会话作为 master，后续会话通过控制套接字复用已经完成的连接。比较稳妥的做法是把配置放在一个明确的 Host 别名下，使用包含主机、端口和用户信息的 %C 作为 ControlPath，再给 master 设置有限的空闲保留时间。

官方文档：https://man.openbsd.org/ssh_config

本文示例只让 prod-api 这个别名参与连接复用，并把控制套接字放到当前用户的私有目录中。其它 Host 别名不会因为这段配置自动共享连接。

SSH ControlMaster 到底复用了什么

ControlMaster 复用的是已经建立的 SSH 网络连接，不是把多条命令拼成一个远程脚本。启用 master 后，后续客户端会尝试连接同一个 ControlPath；如果控制套接字不存在或 master 没有监听，auto 模式会回退为普通连接。

这个边界很重要：同一个 master 连接上的会话会共享初始连接的部分状态。例如 SSH agent 转发或 X11 转发使用的是 master 建立时的转发上下文，不能把它当作每个后续客户端都拥有独立转发环境。

先建立私有的控制套接字目录

控制套接字本质上是本地文件入口，应放在不允许其它用户写入的目录中。先创建目录，再检查 SSH 配置文件权限：

# 创建只允许当前用户访问的控制套接字目录
install -d -m 700 "$HOME/.ssh/control"

# 确保 SSH 用户配置文件存在，并限制为当前用户可读写
touch "$HOME/.ssh/config"
chmod 600 "$HOME/.ssh/config"

这里的 700 和 600 是本地权限边界，不是连接复用开关。目录已经存在时，install -d 仍会按给定模式设置目录权限；如果系统有额外的 ACL 或安全策略，还应按本机规则处理。

只给一个 Host 别名开启复用

把下面的配置追加到 ~/.ssh/config。示例中的地址使用文档保留网段，实际使用时替换为自己的主机名或地址：

# 只对这个别名开启复用，不影响其它 SSH 目标
Host prod-api
    # 实际环境中替换为目标主机名或地址
    HostName 203.0.113.10
    # 固定远端用户和 SSH 端口，避免身份边界漂移
    User deploy
    Port 22
    # 有 master 就复用，没有就正常新建连接
    ControlMaster auto
    # %C 为目标身份生成稳定且较短的控制套接字名
    ControlPath ~/.ssh/control/%C
    # 初始会话退出后，master 最多空闲保留十分钟
    ControlPersist 10m

ControlMaster auto 适合脚本和人工操作共用：它不会要求所有连接都必须依赖 master。ControlPersist 10m 让初始会话退出后 master 在后台等待十分钟；设置太长会让连接状态存活过久，设置为 no 则不会在初始会话退出后继续等待。

不要为了省配置把这些选项直接放到 Host * 下。全局匹配会扩大共享范围，使临时跳板、不同权限的账号或不希望复用的目标也进入同一套规则。

用 ControlPath 把共享范围锁在正确目标

ControlPath 决定客户端到哪里寻找 master。官方手册建议让路径至少区分主机、端口和远端用户，也可以使用 %C 这个组合标识。这样，即使两个别名最终指向相同地址，只要端口或用户不同，也不会因为套接字名称过于简单而误用同一条连接。

用控制命令检查和关闭 master

配置完成后，第一次连接会按普通方式完成认证，并可能成为 master。之后可以用 SSH 的控制命令查看状态和主动关闭后台连接：

# 第一次连接：按 prod-api 的配置建立连接，并可能成为 master
ssh prod-api

# 查看该别名对应的 master 是否仍在运行
ssh -O check prod-api

# 任务结束后主动关闭 master，避免继续占用连接
ssh -O exit prod-api

-O check 和 -O exit 操作的是活动的 multiplexing master。若没有找到控制套接字，命令会提示无法连接到 master；这表示当前没有可复用的后台连接，不等同于远端 SSH 服务一定不可用。

排查“没有复用”或“复用范围不对”

先让客户端打印实际生效的配置，再检查控制目录和路径是否一致：

# 展开 prod-api 的最终客户端配置，只查看三个复用相关字段
ssh -G prod-api | grep -E '^(controlmaster|controlpath|controlpersist) '

# 查看连接协商日志，重点观察控制套接字是否被使用
ssh -vv prod-api

# 列出当前用户控制目录中的套接字文件
ls -la "$HOME/.ssh/control"

常见原因有三类：配置块没有匹配到实际使用的别名；控制目录不存在或权限不允许创建套接字；不同命令使用了不同的主机名、端口或用户，最终生成了不同的 %C。不要通过把目录改成所有用户可写来“修好”复用，这会破坏共享范围的安全边界。

把配置收敛成可维护的小项目规则

如果只需要在批量部署、连续文件传输或短时间运维窗口中复用连接，可以采用下面四条规则：

1. 只在明确的 Host 别名上开启，不把所有主机默认纳入。
2. 使用 %C 或同时包含 %h、%p、%r 的路径，避免目标身份碰撞。
3. 控制目录保持当前用户私有，并让配置文件只对当前用户可读写。
4. 给 ControlPersist 设置有限时间，任务结束时用 ssh -O exit 清理。

这样得到的是“按需复用、按目标隔离、按时间回收”的连接模型：复用减少重复握手，Host 和 ControlPath 限制误共享，ControlPersist 和显式退出则控制生命周期。

相关问题

ControlMaster auto 和 yes 有什么区别？

auto 会尝试复用已有 master，但找不到时回退为普通连接；yes 会让当前客户端监听控制套接字，适合明确要建立 master 的场景。批处理脚本通常更适合从 auto 开始。

为什么两个 SSH 别名没有复用同一条连接？

复用依赖相同的 ControlPath 和匹配的目标身份。两个别名只要主机、端口、用户或最终生效配置不同，就可能得到不同的 %C；这是隔离行为，不是故障。

ControlPersist 是否应该永久开启？

除非有明确的长时间连接需求，否则不建议永久保留。有限的空闲时间更容易回收过期认证上下文，也能让连接状态与运维窗口保持一致。