Linux 与服务器运维 / 知识点
SSH 配置与排障手册
手册条目
确认当前使用的客户端、服务端版本及实际加载的可执行文件。
检查 SSH 版本与路径
当主机上存在多个 OpenSSH 包、别名、软链接或自定义安装目录时,先确认当前终端实际调用的 ssh,再核对服务端 sshd。这一步可避免把“版本不一致”误判为配置无效,也能明确后续排障应检查哪个二进制文件和配置目录。
命令定位
在发起连接的同一用户、同一 Shell 中执行以下命令。command -v 给出当前命令解析结果,type -a 会继续列出别名、函数和 PATH 中的其他同名文件,readlink -f 用于解析 Linux 上的最终软链接目标。
command -v ssh
type -a ssh
readlink -f "$(command -v ssh)"
ssh -V 2>&1预期输出
/usr/bin/ssh
ssh is /usr/bin/ssh
ssh is /bin/ssh
/usr/bin/ssh
OpenSSH_<VERSION>, OpenSSL <VERSION> <DATE>第一行是当前实际调用路径;type -a 若列出多个路径,排在最前面的通常会被使用。版本信息中的 <VERSION> 和 <DATE> 随系统不同而变化。ssh -V 通常写入标准错误,因此示例使用 2>&1 统一输出。
检查服务端程序
服务端程序通常位于 /usr/sbin/sshd。普通用户的 PATH 可能不包含 /usr/sbin,因此同时检查常见路径;命令只读取版本,不会启动或重启服务。
SSHD_PATH="$(command -v sshd 2>/dev/null || true)"
if [ -z "$SSHD_PATH" ] && [ -x /usr/sbin/sshd ]; then
SSHD_PATH=/usr/sbin/sshd
fi
if [ -n "$SSHD_PATH" ]; then
printf 'sshd path: %s\n' "$SSHD_PATH"
"$SSHD_PATH" -V 2>&1
else
printf 'sshd not found\n'
fi预期输出
sshd path: /usr/sbin/sshd
OpenSSH_<VERSION>, OpenSSL <VERSION> <DATE>出现 sshd not found 表示当前主机可能只安装了客户端,或服务端安装在非标准目录。此时先查询软件包,不要直接复制其他机器的 sshd 文件。
确认软件包来源
路径正确但版本与预期不符时,查询该文件由哪个软件包提供。下面命令自动选择 Debian、Ubuntu 的 dpkg 或 RHEL、Fedora 系列的 rpm。
SSH_PATH="$(command -v ssh)"
if command -v dpkg >/dev/null 2>&1; then
dpkg -S "$SSH_PATH"
dpkg-query -W -f='${Package} ${Version}\n' openssh-client openssh-server 2>/dev/null || true
elif command -v rpm >/dev/null 2>&1; then
rpm -qf "$SSH_PATH"
rpm -q openssh-clients openssh-server 2>/dev/null || true
else
printf 'package manager not detected\n'
fi预期输出
openssh-client: /usr/bin/ssh
openssh-client <VERSION>
openssh-server <VERSION>RPM 系统会显示包名和版本,格式与示例不同。重点确认客户端与服务端是否来自系统包、是否同时存在旧版本,以及实际路径是否指向自定义安装目录。
风险与边界
仅看到 /usr/bin/ssh 不代表没有覆盖行为;Shell 函数、别名、容器环境、sudo 的 secure_path 都可能改变命令解析。若刚修改 PATH 或替换文件,先执行 hash -r 清除 Shell 命令缓存,再重复定位。
不要为了“统一版本”直接覆盖 /usr/bin/ssh 或 /usr/sbin/sshd。覆盖系统文件可能导致包校验失败、升级冲突或远程登录中断。安全做法是通过系统包管理器升级,并保留一个已验证的现有会话用于回滚。
排障清单
依次确认当前用户的 type -a ssh、软链接最终目标、ssh -V、服务端路径及软件包来源。若交互终端与自动化任务结果不同,再比较两者的 PATH、执行用户、容器或 chroot 环境,并检查脚本是否写死了绝对路径。
兼容性
readlink -f 主要适用于 Linux,部分 macOS 或 BSD 环境不支持该选项;此时可先使用 command -v ssh 和 type -a ssh 完成定位,再使用系统已有的 realpath 工具解析软链接。
使用主机名、用户名和默认端口登录远程服务器。
建立基础 SSH 连接
使用 ssh 用户名@主机名 可通过默认 TCP 22 端口登录远程服务器。连接成功后会进入远程 Shell;首次连接还需要核对主机密钥指纹,避免把凭据发送给错误主机或中间人。
基本语法
基础形式为 ssh [选项] [用户名@]主机名。省略用户名时,SSH 会默认使用当前本地用户名;省略端口时使用 22。生产环境建议显式写出用户名,避免因本地账号名不同而登录失败。
ssh ops@example.com预期输出
The authenticity of host 'example.com (<IP>)' can't be established.
ED25519 key fingerprint is SHA256:<FINGERPRINT>.
Are you sure you want to continue connecting (yes/no/[fingerprint])?首次连接先通过运维平台、云控制台或管理员提供的可信渠道核对 <FINGERPRINT>。确认一致后输入 yes,随后使用私钥、SSH Agent 或密码完成认证。成功时通常会显示远程系统欢迎信息并出现远程提示符,具体文本因服务器配置而异。
常用参数
-l <USER> 指定远程用户,效果等同于 用户@主机;-p <PORT> 指定非默认端口;-i <KEY_FILE> 指定私钥;-v 输出连接过程,适合判断失败发生在 DNS、TCP、密钥交换还是认证阶段。参数名区分大小写,端口参数是小写 -p。
高频用法
远端使用非默认端口或指定私钥时,可在一次命令中明确全部连接条件。私钥文件应仅允许当前用户读取。
chmod 600 ~/.ssh/id_ed25519
ssh -p 2222 -i ~/.ssh/id_ed25519 ops@example.com预期输出
Welcome to <REMOTE_SYSTEM>
ops@<REMOTE_HOST>:~$<REMOTE_SYSTEM> 和 <REMOTE_HOST> 是动态值。若不希望进入交互 Shell,可在主机名后附加远程命令;远程命令执行完毕后连接自动关闭。
ssh ops@example.com 'hostname && id -un'预期输出
<REMOTE_HOST>
ops该结果同时验证了网络连通、主机密钥、用户认证和远程命令执行。若远端禁用了交互 Shell,但允许指定命令,第二种方式仍可能成功。
风险与边界
出现 REMOTE HOST IDENTIFICATION HAS CHANGED 时,不要直接删除全部 known_hosts 文件。该提示可能由服务器重装、IP 复用、负载均衡切换或中间人攻击触发。先通过可信渠道确认新指纹;确认确为合法变更后,再定点清理对应主机记录。
ssh-keygen -R example.com预期输出
# Host example.com found: line <LINE>
<PATH> updated.
Original contents retained as <PATH>.old<LINE> 和 <PATH> 是动态值。若连接时使用 IP、别名或非默认端口,还需清理实际报错中显示的主机标识,例如 [example.com]:2222,不要删除无关服务器的记录。
不要把密码写进命令、脚本参数或 URL,也不要在未核对指纹时使用 StrictHostKeyChecking=no。这些做法可能泄露凭据或静默接受伪造主机。自动化场景应预先分发受信任的主机公钥,并使用权限受控的专用密钥。
排障清单
连接超时时先确认主机名解析、路由、防火墙和目标端口;立即返回 Connection refused 通常表示端口可达但没有服务监听。认证失败时使用 ssh -v ops@example.com 查看客户端尝试了哪些密钥和认证方式,但日志可能包含用户名、路径和主机信息,提交工单前应先脱敏。
速查:先核对主机指纹,再判断失败阶段;网络问题、主机密钥问题和用户认证问题应分别处理。
在非默认端口或多私钥环境中明确连接参数。
指定端口与私钥
当 SSH 服务不监听默认的 22 端口,或本机存在多把私钥时,在命令中显式指定端口和密钥,可避免连接到错误端口、SSH Agent 尝试过多密钥,或服务端因认证次数过多而拒绝连接。
基本语法
ssh -p <PORT> -i <PRIVATE_KEY> -o IdentitiesOnly=yes <USER>@<HOST>-p 指定 SSH 端口,-i 指定私钥文件,IdentitiesOnly=yes 限制客户端只使用命令行和配置文件声明的身份。将 <PORT>、<PRIVATE_KEY>、<USER>、<HOST> 替换为实际值。
高频用法
先设置连接参数,再执行无副作用的远程命令验证身份和目标主机:
PORT=2222
HOST='server.example.net'
USER='deploy'
KEY="$HOME/.ssh/id_ed25519_prod"
ssh -p "$PORT" -i "$KEY" -o IdentitiesOnly=yes "$USER@$HOST" 'hostname; id -un'预期输出:
<REMOTE_HOSTNAME>
deploy<REMOTE_HOSTNAME> 由远端主机决定,第二行应与指定用户一致。首次连接还可能先显示主机指纹确认提示。
使用相同参数复制文件时,scp 的端口选项是大写 -P:
scp -P 2222 -i "$HOME/.ssh/id_ed25519_prod" ./app.tar.gz deploy@server.example.net:/tmp/预期输出:
app.tar.gz 100% <SIZE> <RATE> <TIME>大小、速率和耗时会随文件与网络变化;退出码为 0 才表示复制成功。
关键参数
-p <PORT>:ssh使用小写-p;scp、sftp在命令行指定端口时通常使用大写-P。-i <FILE>:可重复指定多把候选私钥,但排障时宜先只保留目标密钥。-o IdentitiesOnly=yes:多密钥或启用 Agent 时优先使用,可避免Too many authentication failures。-o ConnectTimeout=10:连接阶段最多等待 10 秒,适合自动化脚本快速失败。
风险与边界
私钥权限过宽时,OpenSSH 会拒绝加载并提示 UNPROTECTED PRIVATE KEY FILE。触发条件通常是文件可被组内或其他用户读取;后果是公钥认证失败并可能退回密码认证。安全做法是执行 chmod 600 <PRIVATE_KEY>,并确认文件所有者正确。
不要为绕过主机指纹告警长期设置 StrictHostKeyChecking=no。主机重装、DNS 污染或中间人攻击都可能触发告警;直接忽略会失去服务器身份校验。应通过可信渠道核对新指纹,再用 ssh-keygen -R <HOST> 删除确认失效的旧记录。
排障清单
使用详细日志确认实际连接端口、尝试的密钥和认证结果:
ssh -vvv -p 2222 -i "$HOME/.ssh/id_ed25519_prod" -o IdentitiesOnly=yes deploy@server.example.net预期关键输出:
debug1: Connecting to server.example.net [<IP>] port 2222.
debug1: Offering public key: <KEY_PATH>
debug1: Server accepts key: <KEY_PATH>
Authenticated to server.example.net ([<IP>]:2222) using "publickey".若停在 Connecting,检查端口监听、防火墙和路由;若只有 Offering public key 而没有 Server accepts key,检查远端 authorized_keys、登录用户名和目录权限;若出现 Too many authentication failures,确认已启用 IdentitiesOnly=yes。
通过客户端配置文件保存主机、用户、端口和密钥参数。
配置主机别名
当同一服务器需要反复指定主机、用户、端口和私钥时,把参数写入 ~/.ssh/config 并定义别名。之后可直接执行 ssh prod-api,也能让 scp、sftp、Git 和多数基于 OpenSSH 的工具复用同一配置。
配置文件
用户级配置文件通常是 ~/.ssh/config。文件不存在时可创建,并限制为仅当前用户可读写:
mkdir -p "$HOME/.ssh"
touch "$HOME/.ssh/config"
chmod 700 "$HOME/.ssh"
chmod 600 "$HOME/.ssh/config"预期结果:
命令成功时通常无输出,退出码为 0。权限过宽不一定在所有版本中立即报错,但会增加配置、主机地址和跳板信息泄露的风险。
别名配置
在 ~/.ssh/config 中加入以下配置,并将示例主机名和密钥路径替换为实际值:
Host prod-api
HostName server.example.net
User deploy
Port 2222
IdentityFile ~/.ssh/id_ed25519_prod
IdentitiesOnly yes
ConnectTimeout 10Host 是本地别名或匹配模式,HostName 才是实际域名或 IP。配置保存后无需重启 SSH 客户端。
验证与连接
先用 ssh -G 查看合并后的最终配置,避免直接连接时才发现匹配错误:
ssh -G prod-api | grep -E '^(hostname|user|port|identityfile|identitiesonly|connecttimeout) '预期输出:
user deploy
hostname server.example.net
port 2222
identityfile <EXPANDED_KEY_PATH>
identitiesonly yes
connecttimeout 10字段顺序可能因 OpenSSH 版本不同而变化,identityfile 也可能显示展开后的绝对路径。确认无误后连接:
ssh prod-api 'hostname; id -un'预期输出:
<REMOTE_HOSTNAME>
deploy复制文件时同样使用别名,无需再次写端口和私钥:
scp ./app.tar.gz prod-api:/tmp/预期输出:
app.tar.gz 100% <SIZE> <RATE> <TIME>匹配顺序
OpenSSH 对每个参数通常采用首次获得的值,因此更具体的 Host 块应放在前面,通用默认值放在文件末尾。例如先写 Host prod-api,最后再写 Host *。否则前面的通配配置可能提前占用 User、Port 等值,使后续别名块看似存在却不生效。
同一别名可以在命令行临时覆盖单个参数,例如 ssh -p 2200 prod-api。命令行值优先,适合临时排障;长期变更仍应回写配置,避免脚本和人工操作使用不同参数。
风险与边界
不要在配置文件中保存密码;OpenSSH 客户端配置不提供安全的明文密码字段。需要无人值守时应使用受控私钥、SSH Agent 或硬件密钥,并限制远端账号权限。
Host *、Host prod-* 等模式会匹配多个目标。触发条件是别名满足通配表达式;错误的共享 IdentityFile 或 ProxyJump 可能把请求发送到非预期路径。安全做法是先运行 ssh -G <ALIAS> 检查最终值,再投入脚本。
排障清单
若别名行为异常,先查看匹配后的配置,再用详细日志确认读取了哪个文件:
ssh -vvv prod-api预期关键输出:
debug1: Reading configuration data <HOME>/.ssh/config
debug1: Applying options for prod-api
debug1: Connecting to server.example.net [<IP>] port 2222.若没有 Applying options for prod-api,检查别名拼写、Host 匹配和配置文件权限;若怀疑系统级配置干扰,可使用 ssh -F /dev/null user@host 做对照测试。-F /dev/null 会忽略用户配置,应只用于定位问题,不要作为长期连接方式。
展开并检查命令行、用户配置和系统配置合并后的连接参数。
查看 SSH 最终生效配置
当 ~/.ssh/config、系统配置、Include 文件和命令行参数同时存在时,用 ssh -G 展开目标别名的最终客户端配置。该命令完成配置求值后退出,不建立 SSH 会话,适合确认实际主机名、用户、端口、密钥和跳板机设置。
基本语法
ssh -G [连接选项] <host-alias>
ssh -G -F <config-file> -o <key=value> <host-alias><host-alias> 应与实际执行 ssh 时使用的名称一致。-F 改用指定配置文件,便于隔离测试;-o、-p、-l、-i 等命令行选项会先于配置文件取值,常用于验证临时覆盖是否生效。
主示例
下面创建一份临时配置,再用命令行把端口从 22 覆盖为 2222。输出经过筛选和排序,便于直接比对关键字段。
cfg=$(mktemp)
trap 'rm -f "$cfg"' EXIT
cat >"$cfg" <<'EOF'
Host prod-*
User deploy
Port 22
IdentityFile ~/.ssh/prod_ed25519
Host prod-db
HostName db.internal.example
EOF
ssh -G -F "$cfg" -p 2222 prod-db |
awk '$1 ~ /^(hostname|user|port|identityfile)$/ {print}' |
LC_ALL=C sort预期输出:
hostname db.internal.example
identityfile ~/.ssh/prod_ed25519
port 2222
user deploy读取时先确认 hostname 是否指向预期服务器,再检查 user 和 port。identityfile 可能出现多行,因为该选项可以累积;这不等于所有密钥都会被实际接受,认证阶段还受 IdentitiesOnly、代理和服务端策略影响。
高频用法
| 目的 | 命令模式 |
|---|---|
| 按默认配置展开别名 | ssh -G <alias> |
| 只测试一份指定配置 | ssh -G -F <config-file> <alias> |
| 临时覆盖单个选项 | ssh -G -o ProxyJump=<jump-host> <alias> |
多数标量参数采用“先取得的值生效”。因此更具体的 Host 段通常应放在宽泛的 Host * 之前;IdentityFile、LocalForward 等可重复选项属于例外,应按多值结果检查。
风险与边界
ssh -G 不会发起网络连接,因此不能证明端口可达、主机密钥可信或认证能够成功。需要验证实际握手时再使用 ssh -vvv <alias>,但该命令会连接远端,生产环境中应避免误触发认证锁定或跳板链路。
如果配置包含 Match exec,求值过程可能执行其中定义的本地命令。对来源不明的配置先做静态检查,或复制必要的 Host 段到受控临时文件后使用 -F;不要直接对不可信文件运行 ssh -G -F。
输出可能暴露内网主机名、用户名、密钥路径和代理拓扑。粘贴到工单或聊天前应脱敏;需要共享时只保留与故障有关的字段。
排障清单
- 结果与预期不符:确认传给
ssh -G的是别名而不是展开后的主机名,并检查Host、Match、Include的匹配顺序。 - 通用配置覆盖了专用配置:把具体
Host prod-db放到Host *之前,再重新展开比对。 - 出现多条密钥路径:检查重复的
IdentityFile和Include文件;只允许指定密钥时配合IdentitiesOnly yes。 - 报未知关键字或语法错误:先运行
ssh -V确认客户端版本,再按报错中的文件和行号修复。 - 需要知道参数来自哪一行:
ssh -G只给最终值,不给来源;应检查包含链,或在可控环境使用ssh -vvv观察配置读取日志。
兼容性
现代 OpenSSH 客户端支持 -G。较旧客户端若不识别该选项,只能用详细日志辅助判断,但要注意 ssh -vvv 会尝试连接。Windows OpenSSH 的用户配置通常位于 %USERPROFILE%\.ssh\config,命令参数和输出字段与 Unix 版本基本一致。
查询、添加或删除 known_hosts 中保存的主机公钥记录。
管理 SSH 已知主机记录
known_hosts 保存“连接目标与主机公钥”的绑定。排查主机重装、密钥轮换、端口变更或别名混用时,优先用 ssh-keygen -F 查询、用 ssh-keygen -R 精确删除;新增记录前必须通过可信渠道核对指纹。
文件与记录定位
用户级文件通常是 ~/.ssh/known_hosts,系统级文件通常是 /etc/ssh/ssh_known_hosts。记录中的主机名可能是明文、哈希值或逗号分隔的多个名称;不要直接用 grep 判断哈希记录是否存在。
非默认端口使用 [host]:port 形式,例如 [db.example.com]:2222。配置了 HostKeyAlias 时,应按该别名查询;不确定实际查询键时,可先用 ssh -G <alias> 检查 hostname、port 和 hostkeyalias。
查询与删除示例
下面在临时目录生成一把测试主机密钥,写入模拟的 known_hosts,然后查询、删除并验证结果。示例不会访问网络,也不会改动真实文件。
tmp_dir=$(mktemp -d)
trap 'rm -rf "$tmp_dir"' EXIT
ssh-keygen -q -t ed25519 -N '' -f "$tmp_dir/host_key"
{
printf 'example.internal '
cut -d ' ' -f1-2 "$tmp_dir/host_key.pub"
} >"$tmp_dir/known_hosts"
echo 'QUERY'
ssh-keygen -F example.internal -f "$tmp_dir/known_hosts"
echo 'REMOVE'
ssh-keygen -R example.internal -f "$tmp_dir/known_hosts"
echo 'VERIFY'
if ssh-keygen -F example.internal -f "$tmp_dir/known_hosts" >/dev/null; then
echo 'record still exists'
else
echo 'record removed'
fi预期输出:
QUERY
# Host example.internal found: line 1
example.internal ssh-ed25519 <HOST_PUBLIC_KEY>
REMOVE
# Host example.internal found: line 1
<PATH>/known_hosts updated.
Original contents retained as <PATH>/known_hosts.old
VERIFY
record removed<HOST_PUBLIC_KEY> 和 <PATH> 每次运行都会不同。查询结果中的行号用于定位记录;删除命令会重写目标文件,并把原内容保存在同目录的 .old 备份中。
高频用法
| 目的 | 命令模式 |
|---|---|
| 查询默认端口记录 | ssh-keygen -F <host> -f ~/.ssh/known_hosts |
| 查询非默认端口记录 | ssh-keygen -F '[<host>]:<port>' -f ~/.ssh/known_hosts |
| 删除匹配记录 | ssh-keygen -R <host> -f ~/.ssh/known_hosts |
| 删除非默认端口记录 | ssh-keygen -R '[<host>]:<port>' -f ~/.ssh/known_hosts |
-F 能识别由 HashKnownHosts yes 生成的哈希主机名。-R 可能删除同一查询键对应的多条记录,例如不同密钥算法或重复行,因此执行后应立即再次查询并检查 .old 备份。
安全添加新记录
ssh-keyscan 只负责采集远端当前提供的公钥,不验证对方身份。下面先显示候选指纹,只有通过控制台、资产系统或管理员等独立可信渠道核对一致后,才输入 YES 追加记录。
host=server.example.com
port=22
candidate=$(mktemp)
trap 'rm -f "$candidate"' EXIT
ssh-keyscan -T 5 -p "$port" -t ed25519 "$host" 2>/dev/null >"$candidate"
test -s "$candidate" || { echo 'no host key collected'; exit 1; }
ssh-keygen -lf "$candidate"
printf '指纹已通过可信渠道核对,输入 YES 继续: '
read -r answer
[ "$answer" = YES ] || { echo 'not added'; exit 1; }
mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat "$candidate" >>~/.ssh/known_hosts
chmod 600 ~/.ssh/known_hosts
echo 'record added'预期输出:
256 SHA256:<FINGERPRINT> server.example.com (ED25519)
指纹已通过可信渠道核对,输入 YES 继续: YES
record added实际指纹、主机名显示形式和密钥位数可能不同。若可信渠道给出的指纹不一致,立即停止,不要追加候选记录。
风险与边界
看到 REMOTE HOST IDENTIFICATION HAS CHANGED 时直接执行 ssh-keygen -R,可能掩盖中间人攻击或错误 DNS 指向。先确认主机是否重装、密钥是否按变更流程轮换,并从独立渠道取得新指纹;确认无误后再删除旧记录并添加新记录。
把未经核验的 ssh-keyscan 输出直接追加到 known_hosts,会把采集当成信任,攻击者若能劫持网络即可植入自己的公钥。安全替代方案是使用受控配置管理分发记录、SSH 主机证书,或人工核验指纹后再写入。
修改 /etc/ssh/ssh_known_hosts 会影响所有用户,错误删除可能导致批量连接失败。共享环境优先修改用户级文件;确需修改系统级文件时先备份,并通过变更流程验证依赖该主机的自动化任务。
排障清单
- 查不到记录:核对是否为非默认端口、
HostKeyAlias、展开后的HostName,并确认使用了正确的-f文件。 - 文本搜索无结果但 SSH 仍提示冲突:记录可能已哈希,改用
ssh-keygen -F。 - 删除后仍冲突:检查用户级和系统级文件、
UserKnownHostsFile自定义路径,以及同一主机的其他地址或端口记录。 - 文件无法写入:确保
~/.ssh权限为700、known_hosts为600,并确认文件所有者正确。 - 记录带
@revoked:这表示密钥被显式撤销,不能通过普通追加覆盖;应先确认撤销原因并修复信任源。
兼容性
这些命令适用于 OpenSSH 工具链。Windows OpenSSH 的用户文件通常位于 %USERPROFILE%\.ssh\known_hosts,ssh-keygen.exe 的 -F、-R 和 -f 用法相同;PowerShell 中仍应给 [host]:port 整体加引号。
首次连接或主机变更时核对服务端密钥指纹,防止连接到错误主机。
验证 SSH 主机密钥指纹
首次连接、服务器重装、主机密钥轮换或出现 REMOTE HOST IDENTIFICATION HAS CHANGED 时,用指纹确认当前服务端身份。必须从控制台、资产系统、运维工单或管理员等可信渠道取得基准指纹,再与客户端看到的值比较;仅执行 ssh-keyscan 不能证明主机可信。
在服务端取得基准指纹
优先核对实际启用的 ED25519 主机密钥。以下命令只读取公钥,不会接触或修改私钥。
sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256预期输出:
256 SHA256:<FINGERPRINT> root@<HOSTNAME> (ED25519)256 是密钥位数,SHA256:<FINGERPRINT> 是需要逐字比对的指纹,末尾注释可能因主机名或生成方式不同而变化。若服务端启用了 RSA、ECDSA 等多种主机密钥,可逐个查看 /etc/ssh/ssh_host_*_key.pub。
首次连接时核对
客户端连接时会显示服务端所选算法及指纹。确认主机名、端口和指纹都与可信基准一致后,才输入 yes 写入 known_hosts。
ssh -p 22 user@example.com预期输出:
The authenticity of host 'example.com (<IP>)' can't be established.
ED25519 key fingerprint is SHA256:<FINGERPRINT>.
Are you sure you want to continue connecting (yes/no/[fingerprint])?实际 IP、算法和指纹可能不同。指纹不一致时立即退出,不要尝试密码或继续登录,因为这可能是连错主机、DNS 或路由异常、主机重装未登记,或中间人攻击。
连接前扫描并比较
需要在自动化检查中预取公钥时,可扫描指定算法并直接计算指纹。扫描结果仍须与独立可信渠道提供的基准比较。
ssh-keyscan -T 5 -p 22 -t ed25519 example.com 2>/dev/null | ssh-keygen -lf - -E sha256预期输出:
256 SHA256:<FINGERPRINT> example.com (ED25519)-T 5 设置 5 秒连接超时,-p 指定 SSH 端口,-t ed25519 限定密钥类型。命令无输出时,先检查地址、端口、防火墙和服务监听状态;不要把空结果当作“指纹未变化”。
主机密钥变更处理
出现变更告警时,先通过服务端控制台或管理员确认新指纹和变更原因。确认合法后再删除旧记录并重新连接;未核实时直接清理会失去客户端的攻击告警保护。
ssh-keygen -R example.com
ssh-keygen -R '[example.com]:2222'预期输出:
# Host example.com found: line <LINE>
/home/<USER>/.ssh/known_hosts updated.
Original contents retained as /home/<USER>/.ssh/known_hosts.old非标准端口必须使用 [主机]:端口 形式。<LINE>、<USER> 和路径以实际环境为准;确认新指纹后,可保留 .old 文件用于审计,再按本地策略清理。
风险与边界
不要通过当前可疑 SSH 会话、同一条未验证网络路径或即时扫描结果获取“基准指纹”,否则攻击者可能同时伪造连接和指纹。负载均衡集群若存在多个合法主机密钥,应由运维侧发布全部指纹,或统一使用 SSH 主机证书;不要把随机变化当作正常现象。
速查结论:先从可信渠道拿到 SHA256 指纹,再连接或扫描比对;只有完全一致并确认主机、端口、算法无误时,才接受或更新 known_hosts。
创建适合交互登录或自动化任务使用的公私钥对。
生成 SSH 密钥
需要为交互登录、代码仓库或自动化任务创建独立身份时,使用 ssh-keygen 生成公私钥对。默认优先选择 ED25519,并为人工使用的私钥设置强口令;自动化场景应使用专用密钥和最小权限,避免复用个人登录密钥。
生成交互登录密钥
先创建权限正确的目录,再生成带口令的 ED25519 密钥。命令会交互询问口令;不要把口令写进命令行、Shell 历史或脚本。
umask 077
mkdir -p "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
ssh-keygen -t ed25519 -a 64 -C "user@example.com" -f "$HOME/.ssh/id_ed25519"终端还会显示随机图,以下是需要核对的关键输出:
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/<USER>/.ssh/id_ed25519
Your public key has been saved in /home/<USER>/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:<FINGERPRINT> user@example.com-t ed25519 选择算法,-a 64 增加私钥口令派生轮次,-C 写入便于识别的注释,-f 明确保存路径。<USER> 和 <FINGERPRINT> 是动态值;私钥文件无 .pub 后缀,公钥文件以 .pub 结尾。
自动化任务专用密钥
只有任务无法交互解锁且已有其他防护时,才使用空口令。必须采用独立文件名,防止覆盖个人密钥,并在服务端通过专用账号、来源地址、允许命令和目录权限限制用途。
umask 077
ssh-keygen -t ed25519 -C "deploy@ci" -f "$HOME/.ssh/id_ed25519_ci" -N ''预期输出中的关键行:
Your identification has been saved in /home/<USER>/.ssh/id_ed25519_ci
Your public key has been saved in /home/<USER>/.ssh/id_ed25519_ci.pub
The key fingerprint is:
SHA256:<FINGERPRINT> deploy@ci-N '' 明确设置空口令。它会使拿到私钥文件的人无需二次验证即可使用该身份,因此不应作为个人终端的默认做法;更安全的替代是使用 ssh-agent、硬件安全密钥或具备短期凭据的自动化平台。
验证文件与指纹
生成后检查权限,并输出公钥指纹用于登记。私钥应仅当前用户可读,分发给服务器或代码平台的只能是 .pub 公钥。
chmod 700 "$HOME/.ssh"
chmod 600 "$HOME/.ssh/id_ed25519"
chmod 644 "$HOME/.ssh/id_ed25519.pub"
ssh-keygen -lf "$HOME/.ssh/id_ed25519.pub" -E sha256预期输出:
256 SHA256:<FINGERPRINT> user@example.com (ED25519)若提示文件不存在,检查 -f 指定的路径;若指纹注释不同,只需确认文件路径和 SHA256 指纹。不要使用 cat、邮件、聊天工具或工单上传私钥内容,公钥泄露通常不构成私钥泄露。
兼容性选择
旧设备、特定加密策略或受 FIPS 约束的环境可能不接受 ED25519,可在确认对端要求后生成 RSA 密钥。不要使用已淘汰的 DSA,也不要仅因兼容性不明就降级算法。
ssh-keygen -t rsa -b 3072 -a 64 -C "user@example.com" -f "$HOME/.ssh/id_rsa"预期输出中的关键行:
Your identification has been saved in /home/<USER>/.ssh/id_rsa
Your public key has been saved in /home/<USER>/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:<FINGERPRINT> user@example.com生成前若目标路径已存在,ssh-keygen 会询问是否覆盖。覆盖会使依赖旧公钥的登录立即失效;安全做法是使用新文件名,先部署并验证新公钥,再撤销旧密钥。
将客户端公钥安全写入远程账户的 authorized_keys。
安装登录公钥
用于把客户端公钥追加到远程账户的 ~/.ssh/authorized_keys,并立即验证无密码公钥登录。优先使用 ssh-copy-id,它会创建必要目录、保留已有密钥,并避免把私钥内容传到服务器。
安装前检查
先确认选择的是以 .pub 结尾的公钥,并核对指纹。下面示例默认使用 Ed25519 密钥;如文件名不同,只需修改 pubkey。
pubkey="$HOME/.ssh/id_ed25519.pub"
test -f "$pubkey" || { echo "公钥不存在: $pubkey"; exit 1; }
ssh-keygen -lf "$pubkey"预期输出
256 SHA256:<FINGERPRINT> <COMMENT> (ED25519)<FINGERPRINT> 和 <COMMENT> 会随密钥变化。若出现 invalid format,文件可能不是有效公钥;不要继续复制,更不能把不带 .pub 的私钥发往远程主机。
推荐安装方式
设置远程用户名和主机后执行。首次连接可能要求确认主机指纹,随后输入远程账户密码;安装成功后,公钥会追加到目标账户的 authorized_keys。
user="deploy"
host="server.example.com"
pubkey="$HOME/.ssh/id_ed25519.pub"
ssh-copy-id -i "$pubkey" "$user@$host"预期输出
Number of key(s) added: 1
Now try logging into the machine, with: "ssh 'deploy@server.example.com'"不同发行版的提示文字可能略有差异,关键是新增密钥数为 1 且命令退出码为 0。若显示密钥已存在,通常无需重复追加。
无 ssh-copy-id 时手动安装
客户端缺少 ssh-copy-id 时,可通过现有密码登录通道写入公钥。远程脚本先设置安全的 umask,再按整行精确匹配,避免重复追加同一把密钥。
user="deploy"
host="server.example.com"
pubkey="$HOME/.ssh/id_ed25519.pub"
cat "$pubkey" | ssh "$user@$host" '
umask 077
mkdir -p "$HOME/.ssh"
touch "$HOME/.ssh/authorized_keys"
chmod 700 "$HOME/.ssh"
chmod 600 "$HOME/.ssh/authorized_keys"
key=$(cat)
grep -qxF "$key" "$HOME/.ssh/authorized_keys" ||
printf "%s\n" "$key" >> "$HOME/.ssh/authorized_keys"
'预期结果
无标准输出;命令退出码为 0。该方式依赖一次可用的密码登录或其他已授权密钥。若服务器已禁用所有可用登录方式,应通过云控制台、物理终端或现有运维会话安装,不能绕过服务器认证。
验证登录
明确指定对应私钥并关闭密码回退,才能确认实际使用的是新安装的公钥,而不是 SSH Agent 中的其他密钥或密码认证。
user="deploy"
host="server.example.com"
private_key="$HOME/.ssh/id_ed25519"
ssh -o IdentitiesOnly=yes \
-o PasswordAuthentication=no \
-i "$private_key" \
"$user@$host" 'id -un'预期输出
deploy若失败,使用 ssh -vvv 查看是否出现 Offering public key、Server accepts key,再检查远程文件权限、sshd_config 中的 PubkeyAuthentication 与 AuthorizedKeysFile。
风险与边界
首次连接时直接接受未知主机指纹,可能把公钥和密码交给中间人。应先从云控制台、资产平台或管理员处核对主机指纹,再输入 yes。复制错账户会扩大该账户的登录权限;生产环境应使用个人账户或受控运维账户,不要默认写入 root。
绝不能上传 id_ed25519、id_rsa 等私钥文件。若私钥已经外泄,应立即从所有服务器删除对应公钥、吊销旧密钥并生成新密钥,而不是仅修改文件权限。macOS 或 Windows 客户端若没有 ssh-copy-id,使用上面的手动安装方式。
处理私钥、SSH 目录或 authorized_keys 权限不正确导致的认证失败。
修复密钥文件权限
用于处理客户端提示私钥权限过宽,或服务器因 ~/.ssh、authorized_keys 的属主和模式不安全而拒绝公钥认证。修复时要分别检查客户端私钥和远程账户目录,不能只改其中一端。
修复客户端权限
下面命令将 SSH 目录设为仅本人可进入,私钥设为仅本人可读写,公钥保持可公开读取,并修正误用 sudo 后造成的属主问题。
key="$HOME/.ssh/id_ed25519"
pubkey="${key}.pub"
sudo chown -R "$(id -un):$(id -gn)" "$HOME/.ssh"
chmod 700 "$HOME/.ssh"
chmod 600 "$key"
test ! -f "$pubkey" || chmod 644 "$pubkey"
stat -c '%a %U:%G %n' "$HOME/.ssh" "$key"
test ! -f "$pubkey" || stat -c '%a %U:%G %n' "$pubkey"预期输出
700 <USER>:<GROUP> <HOME>/.ssh
600 <USER>:<GROUP> <HOME>/.ssh/id_ed25519
644 <USER>:<GROUP> <HOME>/.ssh/id_ed25519.pub若没有公钥文件,第三行不会出现。客户端报错 UNPROTECTED PRIVATE KEY FILE 或 Permissions 0644 ... are too open 时,重点确认私钥为 600,且文件属主是当前登录用户。
修复服务器 authorized_keys
应在服务器控制台、已有管理会话或可用的其他登录通道中执行。示例会从系统账户数据库读取家目录和主组,避免把路径写死为 /home/<USER>。
target_user="deploy"
home_dir=$(getent passwd "$target_user" | cut -d: -f6)
group_name=$(id -gn "$target_user")
test -n "$home_dir" || { echo "用户不存在: $target_user"; exit 1; }
test -f "$home_dir/.ssh/authorized_keys" || {
echo "文件不存在: $home_dir/.ssh/authorized_keys"
exit 1
}
sudo chown -R "$target_user:$group_name" "$home_dir/.ssh"
sudo chmod go-w "$home_dir"
sudo chmod 700 "$home_dir/.ssh"
sudo chmod 600 "$home_dir/.ssh/authorized_keys"
sudo stat -c '%a %U:%G %n' \
"$home_dir" \
"$home_dir/.ssh" \
"$home_dir/.ssh/authorized_keys"预期输出
<MODE> deploy:<GROUP> <HOME>
700 deploy:<GROUP> <HOME>/.ssh
600 deploy:<GROUP> <HOME>/.ssh/authorized_keys家目录 <MODE> 可以是 700、750 或 755,但在常见 StrictModes yes 配置下不应允许组或其他用户写入。authorized_keys 必须属于目标用户或 root,通常使用目标用户属主最清晰。
验证服务端规则
在服务器上读取 sshd 最终生效配置,确认严格权限检查是否开启。该命令只读取配置,不会重启服务。
sudo sshd -T | grep '^strictmodes '预期输出
strictmodes yes若不是 yes,权限问题可能不会被服务端拦截,但仍应保持上述安全模式。修改 sshd_config 后应先执行 sudo sshd -t 验证语法,再通过系统服务管理器平滑重载。
验证公钥登录
回到客户端,强制只使用指定私钥并关闭密码回退。成功输出固定标记,说明权限和公钥认证链路均已恢复。
host="server.example.com"
target_user="deploy"
key="$HOME/.ssh/id_ed25519"
ssh -o IdentitiesOnly=yes \
-o PasswordAuthentication=no \
-i "$key" \
"$target_user@$host" 'printf "public-key-ok\n"'预期输出
public-key-ok若失败,执行 ssh -vvv,并在服务器认证日志中搜索 bad ownership or modes、Authentication refused 或 Failed publickey。同时确认 sshd -T 的 authorizedkeysfile 仍指向实际文件。
排障清单
确认 authorized_keys 中每把公钥独占一行,没有被终端换行拆断;确认目标用户家目录来自正确的本地、LDAP 或域账户记录;检查父目录是否被组或其他用户写入,以及 SSH 服务进程是否能读取文件。
启用 SELinux 的系统即使 Unix 权限正确,也可能因安全上下文错误拒绝读取。仅在 SELinux 主机上执行 sudo restorecon -RFv "$home_dir/.ssh";无输出通常表示无需修改,出现 Relabeled 表示上下文已修复。NFS 家目录还要检查属主映射和 root_squash。
风险与边界
对整个家目录递归执行 chmod -R 700 会破坏 Web 文件、共享目录和应用运行权限;安全替代方案是只修复 .ssh、私钥和 authorized_keys,家目录仅移除组与其他用户的写权限。递归 chown 也不要作用于整个家目录,否则可能改变应用文件属主。
在共享组确实需要写入家目录时,直接执行 chmod go-w 可能中断协作。应先确认 StrictModes、目录 ACL 和共享设计,再把 SSH 密钥迁移到管理员控制的位置或使用集中式密钥管理,而不是放宽 authorized_keys 权限。
兼容性
macOS 和 BSD 的 stat 不支持 GNU 格式,可改用 stat -f '%Lp %Su:%Sg %N' <PATH>。Windows OpenSSH 使用 ACL 而不是 chmod 语义,应通过 icacls 移除无关主体对私钥的访问;WSL 内的密钥则按 Linux 权限处理。
缓存已解锁私钥,减少重复输入密钥口令。
使用 ssh-agent
ssh-agent 适合私钥带口令、同一登录会话内需要多次 SSH 或 Git 操作时使用。它只在内存中缓存已解锁私钥,后续认证无需重复输入口令;会话结束、代理退出或手动删除密钥后需要重新添加。
命令定位
先确认当前 shell 是否已有代理。SSH_AUTH_SOCK 有值通常表示代理可用;若为空,再启动新的 ssh-agent,避免无意创建多个代理进程。
printf 'SSH_AUTH_SOCK=%s\n' "${SSH_AUTH_SOCK:-<EMPTY>}"预期输出:
SSH_AUTH_SOCK=/tmp/ssh-<ID>/agent.<PID>输出为 <EMPTY> 时表示当前 shell 未连接代理;路径和进程号会因会话不同而变化。
高频用法
下面完成启动代理、限时加载私钥和确认缓存状态。-t 1h 让密钥一小时后自动移除,适合共享终端、跳板机或临时排障会话。
eval "$(ssh-agent -s)"
ssh-add -t 1h "$HOME/.ssh/id_ed25519"
ssh-add -l预期输出:
Agent pid <PID>
Enter passphrase for /home/<USER>/.ssh/id_ed25519:
Identity added: /home/<USER>/.ssh/id_ed25519 (<COMMENT>)
256 SHA256:<FINGERPRINT> <COMMENT> (ED25519)ssh-add -l 每行显示密钥位数、指纹、注释和算法;出现目标指纹即表示加载成功。清理单个密钥使用 ssh-add -d <KEY_PATH>,清空当前代理全部密钥使用 ssh-add -D。
风险与边界
代理缓存的是可执行签名操作的私钥能力。触发条件是其他进程能访问同一 SSH_AUTH_SOCK;后果是该进程可在缓存有效期内代表你发起认证。安全替代方案是设置较短超时、锁屏前执行 ssh-add -D,并避免在不可信主机上启用 ForwardAgent yes。
ssh-agent 不会修复私钥权限、用户名、目标主机或服务端公钥配置错误。认证仍失败时,应继续检查 IdentityFile、IdentitiesOnly、服务器 authorized_keys 和详细调试日志。
排障清单
Could not open a connection to your authentication agent:当前 shell 没有代理环境变量,重新执行eval "$(ssh-agent -s)"。The agent has no identities:执行ssh-add <KEY_PATH>;若密钥路径错误,先用ls -l ~/.ssh核对。- 加载成功但仍选错密钥:在
~/.ssh/config为目标主机设置IdentityFile与IdentitiesOnly yes,再用ssh -vvv <HOST>查看Offering public key。 - 代理进程过多:退出旧 shell 后清理遗留进程,日常优先复用桌面会话或系统已有代理。
兼容性
OpenSSH 的 ssh-agent 与 ssh-add 在 Linux、macOS 和多数 BSD 系统可用。macOS 可用 ssh-add --apple-use-keychain <KEY_PATH> 将口令写入钥匙串;部分旧版本使用 ssh-add -K。Windows OpenSSH 通常通过 OpenSSH Authentication Agent 服务管理,命令行为与 Unix 环境略有差异。
为不同服务器、代码托管平台或身份选择指定私钥。
管理多个账号与密钥
当多个身份访问同一域名,或不同服务器必须使用不同私钥时,用 ~/.ssh/config 为每个身份定义唯一的 Host 别名。连接和 Git 远程地址使用别名,SSH 会按配置选择目标用户名、端口和密钥,避免代理中多把密钥被逐一尝试。
基本配置
下面为同一 Git 托管域名配置工作和个人两个身份。HostName 保持真实服务器名,Host 只是在本机使用的别名;IdentitiesOnly yes 强制仅尝试当前条目声明的密钥。
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
IdentitiesOnly yes
Host github-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
IdentitiesOnly yes配置文件及私钥权限应限制为当前用户可读:
chmod 700 "$HOME/.ssh"
chmod 600 "$HOME/.ssh/config"
chmod 600 "$HOME/.ssh/id_ed25519_work" "$HOME/.ssh/id_ed25519_personal"
ssh -G github-work | grep -E '^(hostname|user|identityfile|identitiesonly) '预期输出:
user git
hostname github.com
identitiesonly yes
identityfile ~/.ssh/id_ed25519_work字段顺序可能因 OpenSSH 版本不同而变化;关键是工作别名解析到工作密钥,而不是个人密钥。
高频用法
首次验证身份时执行 ssh -T github-work;若平台不提供 shell,返回“认证成功但不提供 shell”也属于正常结果。需要确认实际选中的密钥时使用详细日志:
ssh -vvv -T github-work 2>&1 | grep -E 'Offering public key|Server accepts key|Authenticated to'预期输出:
debug1: Offering public key: /home/<USER>/.ssh/id_ed25519_work ED25519 SHA256:<FINGERPRINT> explicit
debug1: Server accepts key: /home/<USER>/.ssh/id_ed25519_work ED25519 SHA256:<FINGERPRINT> explicit
Authenticated to github.com ([<IP>]:22) using "publickey".路径、指纹、IP 和日志级别会随环境变化。Git 仓库也必须引用别名,例如 git@github-work:<ORG>/<REPO>.git,否则会绕过这组身份配置。
风险与边界
Host * 中过早声明通用 IdentityFile,或省略 IdentitiesOnly yes,可能导致代理中的其他密钥先被尝试;服务器达到认证尝试上限后会返回 Too many authentication failures。安全做法是为敏感目标使用明确别名,并把专用配置放在宽泛规则之前。
不要让多套身份共用同一私钥。密钥泄露时会同时影响所有账号,且审计无法区分身份。应为每个安全边界生成独立密钥,并分别登记、公钥轮换和撤销。
排障清单
- 别名连接正常但 Git 仍用错账号:检查
git remote -v,把真实域名改为配置中的Host别名。 - 日志未出现目标
IdentityFile:执行ssh -G <ALIAS>查看最终配置,排查拼写、Include文件和规则覆盖。 - 出现
Permission denied (publickey):确认公钥已登记到正确账号,并核对私钥与公钥指纹。 - 出现
Too many authentication failures:补充IdentitiesOnly yes,或临时用ssh -o IdentitiesOnly=yes -i <KEY_PATH> <USER>@<HOST>验证。 - 配置修改未生效:SSH 配置无需重启;关闭复用连接,或执行
ssh -O exit <ALIAS>后重连。
兼容性
Include、Match 等高级指令依赖 OpenSSH 版本;基础的 Host、HostName、User、IdentityFile 和 IdentitiesOnly 兼容性最好。Windows OpenSSH 的用户配置通常位于 %USERPROFILE%\.ssh\config,路径可使用正斜杠,文件权限需通过 Windows ACL 控制。
使用 ProxyJump 经堡垒机访问无法直接连接的目标服务器。
通过跳板机连接
当目标服务器仅能从堡垒机访问时,使用 ProxyJump 让本地 SSH 客户端先连接跳板机,再由跳板机建立到目标端口的 TCP 转发。目标机认证仍由本地客户端完成,通常不需要把目标私钥复制到跳板机。
命令定位
临时连接可用 ssh -J ops@bastion.example.com deploy@10.20.0.15;长期使用应分别配置跳板机与目标机,之后执行 ssh internal-app。跳板机必须能访问目标地址和 SSH 端口,本地只需能访问跳板机。

基本配置
下面用临时配置验证匹配结果,不修改现有 ~/.ssh/config。生产使用时可将两个 Host 块合并到用户配置文件,并为不同主机分别设置 IdentityFile。
cat > /tmp/ssh-proxyjump.conf <<'EOF'
Host bastion
HostName bastion.example.com
User ops
Port 22
Host internal-app
HostName 10.20.0.15
User deploy
Port 22
ProxyJump bastion
EOF
ssh -F /tmp/ssh-proxyjump.conf -G internal-app \
| grep -E '^(hostname|port|proxyjump|user) ' \
| LC_ALL=C sort预期输出:
hostname 10.20.0.15
port 22
proxyjump bastion
user deployhostname 和 user 表示最终目标,proxyjump 表示连接必须经过 bastion。确认无误后,将配置写入 ~/.ssh/config 并执行 chmod 600 ~/.ssh/config;连接成功时会进入目标机的远程 Shell,提示符实际值因系统而异。
高频用法
- 单次连接:使用
ssh -J jump-user@jump-host target-user@target-host,适合临时排障,不写配置文件。 - 多级跳转:使用
ProxyJump bastion-a,bastion-b,按从本地到目标的顺序填写;任一中间节点不可达都会导致整条链路失败。 - 分离密钥:在
Host bastion与Host internal-app中分别设置IdentityFile和IdentitiesOnly yes,避免客户端尝试过多密钥而触发认证次数限制。 - 文件传输:配置完成后直接使用
scp file internal-app:/tmp/或sftp internal-app,它们会复用同一目标别名和跳转规则;成功结果分别是文件出现在目标目录或进入sftp>提示符。
风险与边界
不要为省事设置 StrictHostKeyChecking no。当跳板机或目标机被替换时,该设置会跳过身份确认,可能把凭据交给错误主机;安全替代是预先核对并写入两台主机的公钥指纹。通常也不需要 ForwardAgent yes,因为代理转发会让受控跳板机在会话期间调用本地代理;优先使用本地私钥分别完成两跳认证。
同一目标不要同时配置 ProxyJump 和 ProxyCommand。两者会竞争生效顺序,可能造成实际链路与预期不同;安全做法是只保留一种,并用 ssh -G internal-app 检查最终配置。跳板机上的 AllowTcpForwarding 或网络策略若禁止到目标的转发,客户端配置正确也无法建立链路。
排障清单
- 先运行
ssh -G internal-app | grep -E '^(hostname|user|port|proxyjump) ',确认没有被更早的通配Host *或其他配置覆盖;预期至少看到目标地址、用户、端口和跳板机。 - 再运行
ssh -vvv internal-app。若日志在连接跳板机前失败,检查本地 DNS、端口和跳板机密钥;若已通过跳板机但目标认证失败,检查目标用户名、目标私钥和目标机authorized_keys。 - 在跳板机上验证目标端口:
ssh bastion 'nc -vz 10.20.0.15 22'。成功时通常显示succeeded或open,具体文本取决于 netcat 实现;超时或拒绝连接应转查路由、防火墙和目标sshd。 - 若报
Too many authentication failures,为两台主机设置明确的IdentityFile和IdentitiesOnly yes,不要继续向代理中堆叠无关密钥。
兼容性
ProxyJump 与命令行 -J 适用于支持该功能的较新 OpenSSH 客户端;旧客户端应改用 ProxyCommand ssh -W %h:%p ...。Windows 自带 OpenSSH 使用相同配置语法,但配置路径通常为 %USERPROFILE%\.ssh\config;PuTTY 系列工具需要使用其自身的代理或会话配置。
在不支持 ProxyJump 或需要自定义转发时使用 ProxyCommand。
配置兼容代理链路
当客户端不支持 ProxyJump,或链路必须经过自定义脚本、SOCKS/HTTP 代理时,使用 ProxyCommand 启动一个本地代理进程。该进程必须把标准输入和标准输出透明连接到目标 SSH 服务,外层 SSH 再在这条字节流上完成握手与认证。
命令定位
最常见的兼容写法是 ProxyCommand ssh -q -W %h:%p ops@bastion.example.com。%h 会替换为目标 HostName,%p 会替换为目标端口;ssh -W 只负责从堡垒机转发字节流,不在堡垒机上启动交互式 Shell。

基本配置
下面创建一个可独立检查的临时配置。验证命令只解析最终配置,不会真的访问示例主机;把示例域名、地址和用户替换为实际值后再连接。
cat > /tmp/ssh-proxycommand.conf <<'EOF'
Host legacy-app
HostName 10.20.0.15
User deploy
Port 22
ProxyCommand ssh -q -W %h:%p ops@bastion.example.com
EOF
ssh -F /tmp/ssh-proxycommand.conf -G legacy-app \
| awk '$1 == "hostname" {print "hostname " $2}
$1 == "proxycommand" {print "proxycommand configured"}
$1 == "user" {print "user " $2}' \
| LC_ALL=C sort预期输出:
hostname 10.20.0.15
proxycommand configured
user deploy输出说明目标地址、目标用户和代理命令均已生效。生产中将 Host 块写入 ~/.ssh/config,设置权限为 600,再执行 ssh legacy-app;连接成功时会进入目标机 Shell,实际提示符和登录横幅可能不同。
常用链路
使用堡垒机时优先选择 ssh -W,因为它不依赖堡垒机安装 netcat。只有确认本机 nc 支持对应参数后,才使用 SOCKS 或 HTTP CONNECT 代理。
# 经 SSH 堡垒机转发
ProxyCommand ssh -q -W %h:%p ops@bastion.example.com
# 经本地 SOCKS5 代理;参数支持情况取决于 nc 实现
ProxyCommand nc -X 5 -x 127.0.0.1:1080 %h %p
# 经企业 HTTP CONNECT 代理
ProxyCommand nc -X connect -x proxy.example.com:8080 %h %p这些是配置片段,不单独执行。写入目标 Host 块后,用 ssh -G <HOST_ALIAS> | grep '^proxycommand ' 验证;预期结果是一行以 proxycommand 开头的有效命令。若客户端支持 ProxyJump 且无需自定义代理,应优先使用更简洁的 ProxyJump。
风险与边界
ProxyCommand 由本地 Shell 执行。若把不可信输入直接拼进命令,Shell 元字符可能改变执行内容;安全替代是使用固定 Host 别名、固定代理地址,并避免由外部参数动态生成整条命令。代理脚本的标准输出必须完全留给 SSH 数据流,任何欢迎语、调试日志或密码提示都可能造成 banner exchange 或密钥交换失败;日志应写入标准错误或文件。
当命令依赖 nc、connect-proxy 等外部程序时,缺少程序会导致代理进程立即退出,选项差异也可能让同一配置在另一系统失效。部署前应检查 command -v nc 和 nc -h,并准备 ssh -W 作为兼容替代。不要用 StrictHostKeyChecking no 掩盖目标主机密钥错误,代理链路仍应验证最终目标的主机密钥。
排障清单
- 运行
ssh -G legacy-app | grep '^proxycommand ',确认命令存在且目标别名没有被其他Host块覆盖;预期输出以proxycommand开头。 - 运行
ssh -vvv legacy-app。若出现代理进程退出状态127,通常表示命令或依赖不存在;若出现banner exchange、invalid format或握手前断开,优先检查代理程序是否向标准输出写了额外文本。 - 验证堡垒机到目标端口:
ssh ops@bastion.example.com 'nc -vz 10.20.0.15 22'。成功时通常显示succeeded或open;失败则应检查堡垒机路由、防火墙和目标sshd,而不是继续修改外层认证参数。 - 若代理需要交互输入密码,自动化任务会挂起或超时。安全替代是配置密钥认证、使用受控凭据代理,或在批处理环境启用
BatchMode yes让失败立即返回。
兼容性
ProxyCommand 在较老的 OpenSSH 客户端中也可使用,但 ssh -W 需要客户端本身支持标准输入输出转发。不同系统的 netcat 参数并不统一:OpenBSD 风格常支持 -X 与 -x,传统或精简实现可能不支持。Windows OpenSSH 可以调用可执行程序,但路径含空格时必须正确引用,并确认所调用工具不会向标准输出写提示信息。
将本地端口映射到远程网络中的数据库、控制台或内部服务。
创建本地端口转发
当只能通过 SSH 跳板机访问内网数据库、控制台或内部服务时,用本地端口转发在当前电脑上创建一个监听端口。访问本地端口的流量会经 SSH 加密通道送到目标服务;目标主机名由 SSH 服务器一侧解析。
基本语法
ssh -N -L [本地绑定地址:]本地端口:目标主机:目标端口 用户@SSH服务器-L 定义本地监听端口和远端目标,-N 表示只建立转发、不执行远程命令。未指定绑定地址时通常只监听回环地址;需要同时登录远程终端时可去掉 -N。
常用参数
-o ExitOnForwardFailure=yes:本地监听创建失败时立即退出,避免误以为隧道已经可用。-o ServerAliveInterval=30 -o ServerAliveCountMax=3:检测失联连接,连续失败后结束隧道。-v、-vvv:输出连接、认证和通道建立细节,适合定位转发失败。-f:认证完成后转入后台;排障阶段优先保持前台运行,便于观察错误并用Ctrl+C停止。
高频用法
把本地 15432 映射到跳板机可访问的 PostgreSQL 地址:
ssh \
-o ExitOnForwardFailure=yes \
-o ServerAliveInterval=30 \
-o ServerAliveCountMax=3 \
-N \
-L 127.0.0.1:15432:db.internal.example:5432 \
ops@bastion.example.com预期结果:认证成功后命令保持前台运行,通常没有输出。另开终端检查本地监听:
ss -lntp | grep ':15432'预期输出:
LISTEN 0 128 127.0.0.1:15432 0.0.0.0:* users:(("ssh",pid=<PID>,fd=<ID>))出现 LISTEN 说明本地端口已被 SSH 占用;<PID> 和 <ID> 会随系统变化。继续验证目标端口是否能经隧道建立 TCP 连接:
nc -vz 127.0.0.1 15432预期输出:
Connection to 127.0.0.1 15432 port [tcp/*] succeeded!不同 nc 实现的措辞可能略有差异。成功只表示 TCP 已连通,数据库账号、TLS 和应用协议仍需由实际客户端验证。
风险与边界
绑定到 0.0.0.0、:: 或使用允许外部连接的设置,会让同网段甚至公网主机访问该转发端口,可能绕过原有网络边界。安全替代方案是固定绑定 127.0.0.1,并通过主机防火墙限制来源。
ExitOnForwardFailure=yes 只能确认监听端口和转发请求已建立,不能保证目标服务始终在线。SSH 断线后隧道立即失效;长期运行应交给受控的服务管理器,并配置重连、日志和最小权限。
排障清单
- 出现
Address already in use:本地端口已被占用,用ss -lntp找到进程或更换端口。 - 出现
administratively prohibited:检查服务端AllowTcpForwarding、PermitOpen及账号限制。 - 出现
Name or service not known或超时:目标地址从跳板机侧访问,登录跳板机后执行getent hosts、nc -vz检查 DNS、路由和防火墙。 - 本地监听存在但应用失败:用
ssh -vvv观察channel ... open failed,再核对目标端口、服务状态、TLS 和认证参数。
兼容性
Linux、macOS 和 Windows 内置 OpenSSH 的 -L 语法一致。macOS 可用 lsof -nP -iTCP:15432 -sTCP:LISTEN 检查监听;PowerShell 可用 Get-NetTCPConnection -LocalPort 15432。Unix-like 系统监听小于 1024 的本地端口通常需要更高权限,生产环境优先选择非特权端口。
将客户端可访问的本地服务通过远程服务器端口暴露。
创建远程端口转发
当需要让 SSH 服务器访问客户端本机或客户端网络中的服务时,用远程端口转发在服务器侧创建监听端口。连接该远程端口的流量会沿 SSH 通道返回客户端,再由客户端连接目标地址;目标主机名在客户端一侧解析。
基本语法
ssh -N -R [远程绑定地址:]远程端口:目标主机:目标端口 用户@SSH服务器-R 定义服务器侧监听端口和客户端侧目标,-N 表示只建立转发。未指定远程绑定地址时通常只监听服务器回环地址,因此默认只允许服务器本机访问。
常用参数
-o ExitOnForwardFailure=yes:远程监听申请失败时立即退出,避免静默运行但端口未创建。-o ServerAliveInterval=30 -o ServerAliveCountMax=3:及时清理已经失联的反向隧道。-v、-vvv:查看远程监听申请、端口分配和通道错误。-f:认证后转入后台;首次验证时不要使用,确认稳定后再交给服务管理器托管。
高频用法
先在客户端启动一个仅监听本机的测试 HTTP 服务:
python3 -m http.server 3000 --bind 127.0.0.1预期输出:
Serving HTTP on 127.0.0.1 port 3000 (http://127.0.0.1:3000/) ...再开一个客户端终端,把服务器的 127.0.0.1:18080 映射回客户端的 127.0.0.1:3000:
ssh \
-o ExitOnForwardFailure=yes \
-o ServerAliveInterval=30 \
-o ServerAliveCountMax=3 \
-N \
-R 127.0.0.1:18080:127.0.0.1:3000 \
ops@bastion.example.com预期结果:认证成功后命令保持前台运行,通常没有输出。在 SSH 服务器上另开终端验证:
curl -sSI http://127.0.0.1:18080/ | head -n 1预期输出:
HTTP/1.0 200 OK该结果说明请求已从服务器端口穿过 SSH 隧道并到达客户端测试服务。实际应用可将目标端口替换为本地开发服务器、回调接收器或客户端网络内的受控服务。
风险与边界
将远程绑定地址改为 0.0.0.0 或 ::,并在服务端启用 GatewayPorts yes 或 clientspecified 后,其他主机可能通过 SSH 服务器访问客户端服务;若服务器有公网地址,可能形成直接公网暴露。安全替代方案是保持 127.0.0.1,再通过受认证的反向代理、TLS 和防火墙按需开放。
本地服务常默认信任回环来源,远程转发会改变其可达范围。启用前必须确认服务具备认证、访问控制和日志;不要暴露调试面板、数据库管理端口或无鉴权接口。
排障清单
- 出现
remote port forwarding failed for listen port 18080:检查远程端口占用、低端口权限,以及服务端AllowTcpForwarding、PermitListen配置。 - 指定
0.0.0.0后仍只监听回环地址:服务端GatewayPorts可能为默认的no,修改前先确认暴露范围和防火墙规则。 - 服务器能连接端口但 SSH 客户端日志出现
connect failed: Connection refused:客户端目标服务未监听或目标地址写错,先在客户端执行curl http://127.0.0.1:3000/。 - 隧道偶发中断:用
ssh -vvv检查保活、网络重置和认证续期,再由服务管理器实施受控重连。
兼容性
Linux、macOS 和 Windows OpenSSH 客户端都支持 -R。Windows 可用 py -m http.server 3000 --bind 127.0.0.1 启动测试服务。远程端口能否绑定到非回环地址由 SSH 服务器配置决定;监听小于 1024 的远程端口通常要求远程登录账号具备更高权限。
使用动态端口转发为浏览器或命令行工具提供 SOCKS 代理。
创建 SOCKS 代理
用于临时把浏览器、curl 或包管理器的 TCP 流量经 SSH 主机转发。本机只需监听一个 SOCKS5 端口,应用把代理指向 127.0.0.1:1080;远端无需安装额外代理服务。
基本语法
# 仅监听回环地址,避免把无认证 SOCKS 端口暴露给局域网
ssh -N -T -o ExitOnForwardFailure=yes \
-o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
-D 127.0.0.1:1080 user@jump.example.com预期结果:认证成功后终端保持占用且通常没有输出,1080 端口开始监听。按 Ctrl+C 结束代理;需要后台运行时可增加 -f,成功后命令返回 shell。
常用参数
-D [bind_address:]port:创建动态端口转发,由 SSH 客户端实现 SOCKS4/5 代理。-N:不执行远端命令,只保留转发连接。-T:禁用伪终端,适合纯转发会话。ExitOnForwardFailure=yes:监听端口创建失败时立即退出,避免误以为代理已可用。ServerAliveInterval与ServerAliveCountMax:链路失效后主动退出,避免留下看似存活的会话。
验证代理
curl -sS --socks5-hostname 127.0.0.1:1080 https://api.ipify.org
printf '\n'预期输出:
203.0.113.20该地址只是示例,实际应为跳板机或其出口网络的公网地址。--socks5-hostname 会让域名通过 SOCKS 端解析,避免客户端先做本地 DNS 查询;应用只支持 socks5 而不支持远端解析时,仍可能产生 DNS 泄漏。
风险与边界
不要把监听地址改成 0.0.0.0 或公网地址。OpenSSH 动态代理默认没有 SOCKS 用户名和密码认证,任何能访问该端口的主机都可能借用出口发起连接,导致流量滥用、审计归属错误或出口 IP 被封禁。安全替代方案是继续绑定 127.0.0.1,确需共享时再叠加防火墙、专用隧道和严格来源限制。
动态转发主要承载 TCP。依赖 UDP、广播或原生 QUIC 的程序不能按相同方式透传;浏览器或客户端若存在代理绕过规则,也可能让部分流量直连。敏感操作前应分别验证公网出口和 DNS 解析路径。
排障清单
- 出现
Address already in use:本地端口已被占用,检查监听进程或改用其他高位端口。 - 出现
administratively prohibited:远端sshd禁止转发,检查AllowTcpForwarding、DisableForwarding或目标限制策略。 - SSH 已连接但目标站点打不开:从跳板机直接验证目标地址和端口,确认远端 DNS、路由与防火墙可达。
- 浏览器正常而命令行直连:确认工具显式配置了 SOCKS 代理;环境变量
HTTP_PROXY不一定会自动转换为 SOCKS。
兼容性
该方式适用于 OpenSSH 客户端,包括常见 Linux、macOS 和安装了 OpenSSH 的 Windows 环境。不同应用对 SOCKS5 远端 DNS 的配置名称不同,应优先选择 socks5h、proxy DNS 或等价选项。
通过 ControlMaster 减少重复握手并加快连续连接。
复用 SSH 连接
当同一用户需要连续执行 ssh、scp 或 rsync 时,可让后续会话复用首个 SSH 传输连接,省去重复的 TCP、密钥交换和认证过程。复用是否发生由 ControlPath 是否一致决定。
配置
先创建仅当前用户可访问的控制套接字目录:
install -d -m 700 ~/.ssh/control预期结果:成功时没有输出,目录权限为 700。随后把以下配置写入 ~/.ssh/config:
Host app-prod
HostName 203.0.113.10
User deploy
ControlMaster auto
ControlPath ~/.ssh/control/%C
ControlPersist 10mControlMaster auto 会优先复用现有主连接,不存在时再创建;ControlPersist 10m 让最后一个会话退出后继续保留主连接十分钟;%C 使用连接关键信息生成哈希,能减少套接字名称冲突和路径过长问题。
验证复用
ssh app-prod 'hostname'
ssh app-prod 'hostname'
ssh -O check app-prod预期输出:
app01
app01
Master running (pid=<PID>)主机名和 <PID> 会按实际环境变化。第一条命令建立主连接,第二条命令应直接复用;ssh -O check 用于确认控制连接仍在运行。需要观察复用细节时,可临时增加 -vv,日志通常会出现连接控制套接字的提示。
高频用法
配置生效后,scp file.txt app-prod:/tmp/ 和以 app-prod 为目标的 rsync -e ssh 会自动尝试复用同一主连接。需要提前预热连接时使用 ssh -MNf app-prod,成功时通常无输出;需要立即关闭主连接时使用 ssh -O exit app-prod,预期显示 Exit request sent.。单次绕过复用可使用 ssh -S none app-prod。
风险与边界
控制套接字相当于当前主连接的本地入口。若目录可被其他用户写入或套接字放在共享目录,其他本地账户可能劫持会话或借用已有认证。安全做法是把目录置于用户家目录并保持 700 权限,不使用可预测且可共享的 /tmp 路径。
主连接建立后,代理路径、主机密钥协商、身份文件和部分连接级选项不会因配置文件修改而重新执行。更换密钥、调整 ProxyJump、撤销权限或处理安全事件后,应先执行 ssh -O exit app-prod,再建立新连接;否则旧连接可能在失效前继续可用。
排障清单
- 未发生复用:用
ssh -G app-prod对比有效的hostname、user、port和controlpath,任一不同都会进入另一条连接。 - 出现
Control socket connect或Connection refused:先运行ssh -O check app-prod;确认没有主进程后,再删除ssh -G app-prod显示的旧套接字。 - 出现
unix_listener: path too long:缩短控制目录并继续使用%C,不要在文件名中展开过长的用户名和主机名。 - 新转发或认证配置不生效:关闭现有主连接后重试,避免继续沿用旧连接的连接级状态。
- 并发首次连接偶发冲突:使用
ControlMaster auto,不要强制每个进程都以yes创建主连接。
兼容性
这些指令属于 OpenSSH 客户端配置。PuTTY、Plink 等客户端使用不同的会话复用机制,不能直接照搬 ControlMaster、ControlPath 和 ControlPersist。
减少空闲连接被防火墙、网关或 NAT 提前断开的情况。
配置连接保活
用于 SSH 会话空闲一段时间后被防火墙、NAT 或负载均衡器提前清理的场景。通过客户端发送 SSH 协议层探测包,可以维持链路并在对端失联时及时退出,但不能保证断线后的远端进程继续运行。
命令定位
客户端保活通常写入 ~/.ssh/config,只影响当前用户发起的连接。临时测试也可通过 ssh -o 传参;只有需要统一管理所有客户端时,才修改服务端的 sshd_config。
基本配置
下面为单个生产主机每 30 秒检测一次、连续 3 次无响应后断开的配置:
Host app-prod
HostName 203.0.113.20
User deploy
ServerAliveInterval 30
ServerAliveCountMax 3ServerAliveInterval 表示客户端在未收到服务端数据时,等待多少秒发送一次加密探测;ServerAliveCountMax 表示最多允许多少次探测未收到响应。此配置通常在约 90 秒持续无响应后终止连接,实际时间可能因网络调度略有偏差。
验证最终匹配到的配置,不必真正建立连接:
ssh -G app-prod | grep '^serveraliveinterval '
ssh -G app-prod | grep '^serveralivecountmax '预期输出:
serveraliveinterval 30
serveralivecountmax 3高频用法
跨公网的交互式运维连接可先使用 30/3;移动网络或频繁切换出口时可使用 15/4;内网链路稳定但中间设备空闲超时较长时,可使用 60/3。间隔应小于网关的空闲连接回收时间,例如网关 60 秒回收时可设置为 30 秒。
需要对多数主机生效时,可在配置文件末尾添加默认规则:
Host *
ServerAliveInterval 60
ServerAliveCountMax 3OpenSSH 对同一参数通常采用首次取得的值,因此具体主机规则应放在 Host * 之前。修改后重新建立的连接才会读取新配置,已有会话不会自动更新。
风险与边界
将间隔设置得过短会增加网关状态刷新、移动设备耗电和大规模跳板机的探测流量;将计数设置得过大则会让失效连接长时间假死。安全做法是根据中间设备的空闲超时设置稍短的探测间隔,并将失联检测时间控制在可接受范围内。
TCPKeepAlive 使用操作系统 TCP 探测,默认周期通常较长,也可能无法满足 NAT 空闲回收场景,不能替代 ServerAliveInterval。反过来,SSH 保活只能维护和检测连接,网络中断后仍可能丢失前台任务;长任务应在远端使用 tmux、screen 或服务管理器运行。
服务端的 ClientAliveInterval 和 ClientAliveCountMax 会主动清理未响应客户端。若数值过小,网络短暂抖动可能导致所有用户被断开;修改前应保留现有管理会话,先执行 sshd -t 检查语法,再平滑重载服务。
排障清单
ssh -G <别名>显示仍为0:检查Host模式是否匹配,以及/etc/ssh/ssh_config、Include文件和命令行参数是否覆盖配置。- 设置后仍按固定时长断开:确认探测间隔确实短于防火墙或 NAT 的空闲超时,并排查代理、VPN、跳板机各段链路。
- 会话断开但远端任务必须继续:不要继续增大保活计数,改用
tmux、screen、systemd-run或作业调度器托管任务。 - 连接长时间卡住不退出:降低
ServerAliveCountMax,并结合连接超时设置,避免只配置保活而没有失败退出策略。
为人工操作和自动化任务设置连接超时、批处理及失败退出行为。
限制连接等待时间
用于 SSH 自动化任务在目标不可达、认证需要交互或远端命令卡住时尽快失败。ConnectTimeout 和 BatchMode 负责限制建连与交互等待;如需限制整个任务时长,还必须在 SSH 外层增加进程级超时。
命令定位
ConnectTimeout 限制 TCP 建连及初始 SSH 握手的等待时间,ConnectionAttempts 控制连接尝试次数,BatchMode yes 禁止密码、私钥口令和确认问题等交互提示。三项组合适合 CI、发布脚本、健康检查和定时任务。
基本配置
下面的配置要求连接在 8 秒内完成、只尝试一次,并在需要人工输入时直接失败:
Host ci-app
HostName 203.0.113.30
User deploy
ConnectTimeout 8
ConnectionAttempts 1
BatchMode yes验证客户端解析后的最终值:
ssh -G ci-app | grep '^connecttimeout '
ssh -G ci-app | grep '^connectionattempts '
ssh -G ci-app | grep '^batchmode '预期输出:
connecttimeout 8
connectionattempts 1
batchmode yes配置文件中的时间单位为秒。数值过短会在高延迟、首次密钥交换或拥塞链路上产生误报,公网自动化通常可从 5~15 秒开始调整。
高频用法
不修改配置文件时,可直接为单次任务指定失败策略:
ssh -o ConnectTimeout=8 -o ConnectionAttempts=1 -o BatchMode=yes ci-app 'echo ok'预期输出:
okConnectTimeout 不限制远端命令的总运行时间。Linux 自动化脚本可使用 GNU timeout 增加 20 秒总时限,并在普通终止无效后等待 5 秒再强制结束:
timeout --signal=TERM --kill-after=5s 20s ssh ci-app 'echo ok'正常完成时预期输出:
ok若超过 20 秒,timeout 通常以状态码 124 退出;SSH 自身发生连接、认证或协议错误时通常返回 255。远端命令已启动但连接随后被终止时,命令是否继续运行取决于远端会话和信号处理方式。
输出与退出码
自动化脚本不应只判断是否有标准输出,应读取退出码:远端命令正常结束时,SSH 返回该命令的退出码;连接失败、认证失败或协议错误通常返回 255;GNU timeout 达到时限时通常返回 124。因此远端命令本身不宜使用 255 作为业务退出码,否则难以区分连接故障。
可按以下方式保留退出码并输出诊断信息:
ssh -o ConnectTimeout=8 -o ConnectionAttempts=1 -o BatchMode=yes ci-app 'exit 7'
status=$?
printf 'ssh_status=%s\n' "$status"预期输出:
ssh_status=7风险与边界
BatchMode yes 会在私钥需要口令但 ssh-agent 未加载、主机密钥需要确认或只能使用密码认证时立即失败。安全替代方案是预先加载专用部署密钥、正确配置代理,并通过可信渠道预置 known_hosts,而不是使用 StrictHostKeyChecking no 绕过主机身份验证。
ConnectTimeout 不是整个任务的绝对截止时间。DNS 解析、ProxyCommand、多段 ProxyJump、认证尝试以及远端命令执行都可能需要额外限制;生产脚本应同时设置 SSH 建连超时和任务执行器的总超时。
总超时触发后直接杀死 SSH 可能使远端任务处于未知状态,例如部署命令已执行一半但结果未返回。对有副作用的操作应设计幂等检查、事务或任务 ID,并在重试前查询远端实际状态。
排障清单
- 自动化仍等待密码或确认:使用
ssh -G确认batchmode yes已生效,并检查脚本是否通过其他-o BatchMode=no覆盖。 - 很快返回
255:使用人工会话确认密钥、用户名、主机密钥和跳板配置;BatchMode下不会弹出修复提示。 ConnectTimeout生效但任务仍长时间运行:卡点位于认证后或远端命令阶段,应增加外层总超时,而不是继续缩短建连时间。- 偶发超时但手工连接正常:适当提高
ConnectTimeout,检查 DNS、代理链路和首次密钥交换耗时,避免把网络抖动误判为主机故障。 - macOS 找不到
timeout:系统默认不提供 GNUtimeout,可使用任务编排器自身的超时能力,或安装 GNU coreutils 后调用gtimeout。