如果你在 Java 或 Android 项目里用 SSH 客户端库连远程服务器对 createCommunicationsException 这个名字应该不陌生。它经常整条贴在日志里com.jcraft.jsch.JSchException: createCommunicationsException: ...。说实话异常名本身没多少信息量真正值钱的是冒号后面那一句还有异常链里有没有嵌套的 IOException。它会出现在任何需要 SSH/SFTP 通信的场景里App 里往服务器传日志、后端定时同步远端文件、CI 脚本连接代码仓库只要网络链路或认证配置不对它就冒出来。这篇文章我不会跟你念 API 文档而是从实际排查经验出发把这个问题拆成几个层面告诉你每一步怎么验证、怎么改、怎么避免踩坑。不管你是刚接触 SSH 的小白还是被线上告警折腾过几次的老手都能找到可以直接抄的解决方案。1. createCommunicationsException 不只是连接失败它是一层包装纸1.1 异常从哪里来SSH 客户端库的通信层封装先说结论createCommunicationsException 并不是一个业务错误码也不是某个从Exception直接继承出来的独立类名。它更多是 SSH 客户端库在建立连接、发送数据、读取服务端响应的过程中把底层网络异常统一包装后生成的那句提示。底层的IOException可能是连接被拒绝、连接超时、连接重置、读不到数据、Socket 被关闭等等。客户端库为了让你在业务层只和JSchException打交道就把这些五花八门的网络问题收进同一个方法里然后再抛出来。所以你经常会看到日志里的异常消息长成下面这样com.jcraft.jsch.JSchException: createCommunicationsException: Connection refused这里Connection refused才是真正值得看的内容。再往下翻如果打开了整个堆栈还能看到java.net.ConnectException之类的嵌套根因。遇到这类异常第一反不要“这库怎么这么不稳定”而是“底层网络到底发生了什么”。我在排查线上问题时经常在群里看到有人直接贴一行异常消息截图这信息量是不够的。正确姿势是把getCause()打出来或者至少把异常的完整toString()和堆栈打出来。很多团队用的日志框架会默认吞掉 cause 细节只记录 message导致你查了半天也看不到真实原因。try { session.connect(15_000); } catch (JSchException e) { // 重点把 cause 一起打出来 log.error(SSH session connect failed: {}, e.getMessage(), e); if (e.getCause() ! null) { log.error(Root cause: {} - {}, e.getCause().getClass().getName(), e.getCause().getMessage()); } }日志里也有可能出现连续两个createCommunicationsException: createCommunicationsException: ...这是因为它内部某个环节又调用了同样的包装逻辑不用被这种重复吓到继续往里追 cause 就好。1.2 真正要看的是伴随信息异常名只是入口我把实际遇到过的伴随信息整理成了几个典型的“信号词”每个信号词背后对应的排查方向完全不同。如果你只盯着 createCommunicationsException 这一个名字很容易把问题统一归结为“网络故障”然后在服务器上重启、换端口、改乱七八糟的配置浪费时间。日志里的伴随信息大概率原因优先排查方向Connection refused服务端端口未监听、防火墙拒绝连接端口连通性、服务状态、防火墙/安全策略Connection timed out网络不通、安全策略丢包、服务器负载太高路由、链路质量、服务端负载Connection reset连接被服务端强制断开服务端 sshd 日志、登录限制、网络中间设备Algorithm negotiation fail客户端和服务端支持的加密算法交集为空SSH 算法协商配置、客户端库版本UnknownHostExceptionDNS 解析失败域名解析、hosts 配置Auth fail认证失败但还没到网络层用户名密码、密钥、服务端认证方式Host key verification failed主机密钥校验失败known_hosts、主机指纹变化这个表格你可以直接截图保存。真正排查的时候先看异常消息属于哪一类再跳到后面的对应小节效率会高很多。后面我也会按这个思路把每类问题展开讲。2. 动手前先把环境复现起来别靠猜2.1 最小复现样例一个简单的 SFTP 上传程序很多人一看到连接异常第一反应是去翻服务器配置或者检查网络。但我的习惯是先在本地把问题稳定复现出来因为只有能稳定复现的问题才有办法验证修复方案。下面这个例子我用的是 Java 里最常见的 SSH 客户端库。你可以建一个最简单的 Maven 工程只跑一段main方法连目标服务器的 SFTP 端口尝试上传一个小文件。代码尽量精简减少变量干扰。dependency groupIdcom.jcraft/groupId artifactIdjsch/artifactId version0.2.20/version /dependencyimport com.jcraft.jsch.*; import java.io.FileInputStream; import java.util.Properties; public class SftpUploadDemo { public static void main(String[] args) throws Exception { String host 192.0.2.10; int port 22; String user someuser; String password somepassword; JSch jsch new JSch(); // 如果使用公钥登录取消下一行注释并换成你自己的私钥路径 // jsch.addIdentity(/path/to/id_rsa); Session session jsch.getSession(user, host, port); session.setPassword(password); session.setTimeout(10_000); Properties config new Properties(); // 推荐使用 yes第一次连接时人工确认指纹并把指纹写入 known_hosts config.put(StrictHostKeyChecking, yes); config.put(PreferredAuthentications, publickey,password,keyboard-interactive); session.setConfig(config); try { session.connect(15_000); } catch (JSchException e) { e.printStackTrace(); if (e.getCause() ! null) { e.getCause().printStackTrace(); } return; } ChannelSftp sftp (ChannelSftp) session.openChannel(sftp); sftp.connect(10_000); try (FileInputStream in new FileInputStream(/local/file.txt)) { sftp.put(in, /remote/file.txt); } sftp.disconnect(); session.disconnect(); } }这个代码里用了文档保留地址192.0.2.10实际测试时换成你自己的服务器地址。跑起来之后如果异常复现了你就有了一个可以反复调整的最小环境。接下来做任何配置变更都先在这里验证不要在线上直接盲改。2.2 打开 SSH 客户端日志让异常自己开口复现出异常之后很多人会立刻去服务端翻日志但如果客户端日志里能看到 SSH 握手走到了哪一步很多问题当场就能定案。JSch 自带了一个Logger接口默认情况下是不输出的。我们需要在程序初始化时挂一个简单实现把所有日志打到控制台。JSch.setLogger(new JSch.Logger() { Override public boolean isEnabled(int level) { return true; } Override public void log(int level, String message) { System.out.println(JSCH[ level ] message); } });加上这段之后再跑一次程序你会看到类似下面的输出JSCH[1] Connecting to 192.0.2.10 port 22 JSCH[1] Connection established JSCH[1] Remote version string: SSH-2.0-OpenSSH_8.9 JSCH[1] SSH_MSG_KEXINIT sent JSCH[1] SSH_MSG_KEXINIT received JSCH[1] SSH_MSG_KEXINIT failed注意看两行关键日志Connection established出现说明 TCP 层已经通了再往后如果 KEXINIT 后失败问题基本就在算法协商如果连Connection established都没出现说明是网络层问题。这比看业务层异常要精准得多。客户端日志配合服务端日志基本能把问题定位到某一个具体环节。2.3 四个影响连接成败的 session 配置项这里我特别提醒四个配置每一个都有可能导致 createCommunicationsException而且踩坑的概率非常高。第一个是StrictHostKeyChecking。很多老教程图省事直接设成no然后线上就裸奔。正确做法是保持yes或ask并提前把服务器公钥指纹写入 known_hosts。后面我会专门讲这个校验机制。第二个是PreferredAuthentications。如果服务端只支持公钥认证而你默认走密码登录就会失败。一般我会把publickey,password,keyboard-interactive都列上让客户端按顺序尝试。第三个是Session.setTimeout()。这个超时是 Socket 读写超时不是连接超时。如果你只设置了session.connect()的超时参数但服务端一直不返回数据客户端可能会一直等下去。合理的做法是两个都设setTimeout(10_000)加上connect(15_000)。第四个是Channel的连接超时。很多人只设置了session.connect(15_000)却忘了channel.connect()也要给超时时间。SFTP 通道建立失败时同样会包装成连接类异常但不一定有createCommunicationsException字样。为了统一排查给通道也设上超时。private static final int SESSION_TIMEOUT_MS 15_000; private static final int CHANNEL_TIMEOUT_MS 10_000; private static final int READ_TIMEOUT_MS 10_000; Session session jsch.getSession(user, host, port); session.setPassword(password); session.setTimeout(READ_TIMEOUT_MS); session.connect(SESSION_TIMEOUT_MS); ChannelSftp sftp (ChannelSftp) session.openChannel(sftp); sftp.connect(CHANNEL_TIMEOUT_MS);3. 排查 createCommunicationsException 的四个层面3.1 网络层连接是被拒绝、被中断还是没响应拿到 createCommunicationsException 之后我第一件事永远是判断 TCP 层是否真的通。很多看起来像应用层的问题其实是安全策略把端口挡了或者服务器只允许特定来源 IP 访问。最简单的验证方式是用nc命令探测端口。Linux 和 macOS 下一般都有这个工具。nc -vz 192.0.2.10 22如果返回succeeded说明 22 端口从你当前所在网络是可达的。如果报Connection refused可能是服务没起来也可能是防火墙直接拒绝了。如果长时间卡住不动最后timed out那大概率是安全策略丢包或者链路不可达。在 Java 程序里也可以写一个非常轻量的 Socket 测试排除 SSH 客户端库的干扰import java.net.InetSocketAddress; import java.net.Socket; public class TcpProbe { public static void main(String[] args) throws Exception { String host 192.0.2.10; int port 22; try (Socket socket new Socket()) { socket.connect(new InetSocketAddress(host, port), 5_000); System.out.println(TCP connect ok); } catch (Exception e) { e.printStackTrace(); } } }如果这个 Socket 测试都连不上那就别折腾 SSH 客户端了先解决网络层面。常见原因包括服务端防火墙没放行 22 端口、服务端 sshd 没启动、来源 IP 被限制、路由器或云平台安全策略拦截。还有一种情况是服务器端fail2ban之类的保护机制把来源 IP 临时封禁了表现也是Connection refused或超时。遇到这类问题去服务端查一查系统日志比如/var/log/auth.log或/var/log/secure。3.2 认证层账号密码与公钥登录的坑TCP 通了但 SSH 客户端日志停在版本号交换之后然后抛Auth fail这就是认证层的问题。认证层并不复杂但变种很多。第一检查用户名和密码是否真的正确。密码里如果有特殊字符比如、#、$在配置文件和代码里要注意转义。我见过有人把密码写在 YAML 里结果#被当成注释截断了。第二确认服务端支持的认证方式。OpenSSH 服务端的/etc/ssh/sshd_config里可以这样配置允许的认证方法PasswordAuthentication yes PubkeyAuthentication yes KbdInteractiveAuthentication no如果你的服务端关闭了密码认证只允许公钥登录而客户端默认在尝试密码你就会看到一遍遍的Permission denied。此时需要把客户端PreferredAuthentications改成publickey并正确加载私钥。第三私钥文件本身有问题。OpenSSH 新版生成的私钥默认是 OpenSSH 格式某些老版本的 SSH 客户端库并不能直接读取这种格式会报invalid privatekey或者解析失败。解决办法是把私钥转成 PEM 格式ssh-keygen -p -m PEM -f id_rsa转换过程会要求你输入私钥密码不想设密码就直接回车。转换之后再用原来的客户端去加载。第四私钥文件权限太宽。Linux 下 OpenSSH 对私钥权限要求很严格如果id_rsa是 644 或者 777服务端会直接拒绝使用。用下面命令修正chmod 600 id_rsa认证失败时服务端日志会给出更多线索。如果有系统日志权限直接看/var/log/auth.log或/var/log/secure里面会记录类似Failed password for invalid user、Connection closed by authenticating user、User someuser from ... not allowed because not listed in AllowUsers的信息。这个信息比客户端日志准得多。3.3 算法协商Algorithm negotiation fail 的正确解法算法协商失败是我遇到最多的一类也是最容易让人一头雾水的。日志会显示createCommunicationsException: Algorithm negotiation fail字符串里没有 IP没有用户名没有具体算法。只有打开客户端完整日志才可能看到SSH_MSG_KEXINIT failed。服务端日志里通常会有这样一行Unable to negotiate with 192.0.2.20 port 50231: no matching key exchange method found. Their offer: diffie-hellman-group-exchange-sha256,diffie-hellman-group14-sha256,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521这说明客户端发出去的密钥交换算法列表和服务端能接受的列表没有交集。为什么会出现这个情况最典型的原因是服务器升级了 OpenSSH 版本新版本默认禁用了一些旧的、不够安全的算法而你的客户端库版本太老还是只支持旧算法。比如某些老版本客户端还在使用diffie-hellman-group1-sha1或ssh-rsa签名当服务器端把这些算法关掉后两边就谈不拢了。正确的解法是升级客户端库让客户端支持新算法。如果你用的是老的 SSH 客户端库建议升级到较新版本新版本通常会支持curve25519-sha256、rsa-sha2-512等更安全的算法。升级之后重新运行之前的最小复现程序绝大多数算法协商失败都会消失。另一种是临时兼容方案在服务端sshd_config里把旧算法加回来。这个方案我不建议在生产环境长期使用因为旧的加密和签名算法存在已知弱点等于是主动把安全水位拉低。如果一定要做可以考虑在调试阶段临时验证确认客户端的真实问题后尽快升级客户端并移除这些兼容配置。此外主机密钥算法也会出现协商失败报错类似no matching host key type found. Their offer: ssh-ed25519, ssh-rsa。这种情况同样优先升级客户端或者临时在服务端追加兼容的主机密钥算法。3.4 主机密钥校验StrictHostKeyChecking 不是开关是安全机制主机密钥校验失败时报的通常是Host key verification failed但它同样会被包装成 createCommunicationsException 系列异常。你可能会看到下面的完整消息com.jcraft.jsch.JSchException: createCommunicationsException: Host key verification failed这背后的机制是SSH 客户端第一次连接服务器时会拿到服务器的公钥指纹。为了防中间人攻击客户端会把这个指纹记进 known_hosts 文件。之后每次连接都会比对如果服务器公钥变了就会拒绝连接。最常见的场景是服务器重装系统或者重新生成了主机密钥导致客户端 known_hosts 里保存的还是旧指纹。这时候不要简单粗暴地设置StrictHostKeyCheckingno而是应该用带外渠道重新获取服务器指纹更新 known_hosts。比如先用你信任的安全通道登录服务器执行ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub拿到类似下面的指纹256 SHA256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234 hostname (ED25519)然后再在客户端机器上用ssh-keyscan把当前服务器的公钥保存到 known_hosts并人工确认得到的指纹和服务器上读到的一致ssh-keyscan -t ed25519 192.0.2.10 ~/.ssh/known_hosts在 Java 代码里可以通过下面方式显式指定 known_hosts 文件jsch.setKnownHosts(/home/app/.ssh/known_hosts);如果你在代码里看到了任何把StrictHostKeyChecking设成no的老代码建议抓紧改成yes并把服务器指纹管理起来。这个校验不是用来恶心人的它保证你连的服务器就是你以为的那台。4. 一个线上连接失败的完整排查实录4.1 现象定时任务导数据全部失败某公司的内部数据同步项目每天的定时任务会从一台远程 Linux 服务器拉取 CSV 文件到本地处理。某天早上开始任务大面积失败日志里清一色是com.jcraft.jsch.JSchException: createCommunicationsException: Algorithm negotiation fail负责排查的同学一开始怀疑网络测了ping和ncTCP 端口是通的。又怀疑账号被锁但换了几组账号都一样。后来把客户端完整日志打开发现 SSH 握手在SSH_MSG_KEXINIT阶段就断了并且服务端日志明确提示算法不匹配。4.2 服务端 sshd 日志里的关键信息登录服务器看/var/log/auth.log找到了几行关键日志Unable to negotiate with 192.0.2.20 port 50231: no matching key exchange method found. Their offer: diffie-hellman-group-exchange-sha1,diffie-hellman-group14-sha1,rsa-sha2-256,rsa-sha2-512这里的Their offer是客户端提出来的算法列表但服务端已经没有交集了。再看服务端sshd_config里面已经显式配置了只接受更强的算法。也就是说服务器最近做了安全加固把旧算法都禁掉了而客户端还停留在非常老的版本只能提出已经很弱甚至禁用的算法。4.3 客户端低版本算法库不匹配的修复过程这次修复没有去动服务端配置而是从客户端入手。第一件事是升级 Java 项目里的 SSH 客户端依赖库到较新版本。升级前先用一个临时脚本打印客户端支持的算法列表确认新版本里已经支持curve25519-sha256和rsa-sha2-512这些服务端接受的算法。升级后同样的最小复现程序一次就连接成功。这里我特意补充一点升级依赖库之后不要只看日志“连接成功”还要重新验证 SFTP 的上传、下载、删除、重命名这些核心操作因为新版本库对某些 API 的默认行为可能有调整。比如有的版本对FilenameEncoding的默认值不同可能导致中文文件名处理结果不一样。4.4 事后加固熔断、重试与告警这次问题解决之后还做了一些加固避免下次再被类似问题折腾半天。连接工具类里增加了统一的异常分类方法把JSchException的 message、cause、以及是否属于认证失败、算法协商失败、网络超时区分开分别输出到不同日志级别并记录到监控系统。在重试策略上我加了一个简单的指数退避重试第一次失败等 2 秒第二次失败等 4 秒第三次失败等 8 秒最多重试 3 次。但是对Auth fail这类认证失败不做重试因为账号密码错误重试多少次都一样只会增加服务器封禁风险。对Host key verification failed同样不做重试避免误报刷屏。如果你也要写重试逻辑建议参考下面这段伪代码int maxRetry 3; int attempt 0; long backoffMs 2_000; Exception lastException null; while (attempt maxRetry) { try { SftpResult result executeSftpTask(); return result; } catch (SftpAuthException e) { throw e; // 认证失败直接抛出 } catch (SftpNetworkException e) { attempt; Thread.sleep(backoffMs * attempt); } }另外告警不能只监控“抛出异常”这个级别。我一般还会监控 SSH 连接耗时如果连接耗时突然从几百毫秒涨到十几秒即使最终成功也说明网络或者服务端已经不正常了可以提前介入。5. 常见问题速查与三个易漏点5.1 createCommunicationsException 常见场景速查表我把实际工作中遇到过的问题整理成了一张速查表遇到问题时可以直接对着查。场景典型日志特征解决方案服务器 22 端口不通Connection refused/Connection timed out检查服务、端口、防火墙、安全策略云平台安全策略未放行TCP 探测超时调整入站规则只放行需要访问的 IP服务端禁用密码登录Auth fail/Permission denied改用公钥登录或临时开启密码认证做验证客户端私钥格式过老invalid privatekey将私钥转为 PEM 格式算法版本不匹配Algorithm negotiation fail升级 SSH 客户端库服务端做临时兼容需谨慎主机密钥变更Host key verification failed重新获取服务器指纹并更新 known_hosts连接空闲被服务端断开Connection reset/session down开启ServerAliveInterval保活DNS 解析失败UnknownHostException检查域名解析配置和 hosts 文件服务端来源 IP 限制TCP 通但 SSH 握手被断开检查AllowUsers、DenyUsers、防火墙规则这张表只能帮你快速定位方向具体到某个线上环境还是要结合服务端系统日志来看。5.2 三个容易忽略的细节第一个细节是Session不能被多个线程共享。很多人写一个连接管理类整个应用共用一个Session然后并发去开多个 Channel结果偶尔报channel is not opened、session is down或者莫名其妙的连接中断。SSHSession是有状态的推荐每个工作线程一个Session或者使用连接池按需创建。并发量太高时必须限制并发连接数否则服务端会因为MaxStartups限制而拒绝新连接。第二个细节是服务端会话超时设置。OpenSSH 默认的LoginGraceTime是 120 秒如果客户端在建立连接后迟迟没有完成认证服务端会主动断开。反过来如果网络链路比较慢客户端可以适当调大connect()超时时间。不过如果连接过程耗时太久更应该关注的是网络质量而不是盲调超时。第三个细节是 SSH 客户端库的日志默认是关的。线上环境第一次出现 createCommunicationsException 时很容易因为缺少客户端日志而只能靠猜。建议在测试环境把日志级别打开验证通过后再关闭或者使用动态开关只对特定用户、特定请求开启。这样既能保留排障能力又不会因为日志刷屏影响性能。还有一个我认为非常重要的习惯看到任何连接类异常先把getCause()的异常类型记下来。java.net.ConnectException、java.net.SocketTimeoutException、java.net.NoRouteToHostException三条路径对应的处理方式完全不同。排查时顺着根因走比在 SSH 配置里反复试错要靠谱得多。我在实际排查中最大的体会是createCommunicationsException 本身不是答案它只是一个路标。真正要看的是客户端日志和服务端日志交汇在一起后那个断掉的 SSH 握手阶段。连接被拒、认证失败、算法不匹配、主机密钥变化这四类问题闭上眼睛都能数出来但每次定位还是要把根因链打开不能省这一步。安全配置更别顺手关掉主机密钥校验宁可第一次多花五分钟同步指纹也不要留一个能被中间人利用的口子。下次线上再报这个异常你就知道它不是在说“网络不通”一句废话而是整个 SSH 连接流程里某一个环节没走通需要你一层层去把它找出来。
如果你在 Java 或 Android 项目里用 SSH 客户端库连远程服务器对 createCommunicationsException 这个名字应该不陌生。它经常整条贴在日志里com.jcraft.jsch.JSchException: createCommunicationsException: ...。说实话异常名本身没多少信息量真正值钱的是冒号后面那一句还有异常链里有没有嵌套的 IOException。它会出现在任何需要 SSH/SFTP 通信的场景里App 里往服务器传日志、后端定时同步远端文件、CI 脚本连接代码仓库只要网络链路或认证配置不对它就冒出来。这篇文章我不会跟你念 API 文档而是从实际排查经验出发把这个问题拆成几个层面告诉你每一步怎么验证、怎么改、怎么避免踩坑。不管你是刚接触 SSH 的小白还是被线上告警折腾过几次的老手都能找到可以直接抄的解决方案。1. createCommunicationsException 不只是连接失败它是一层包装纸1.1 异常从哪里来SSH 客户端库的通信层封装先说结论createCommunicationsException 并不是一个业务错误码也不是某个从Exception直接继承出来的独立类名。它更多是 SSH 客户端库在建立连接、发送数据、读取服务端响应的过程中把底层网络异常统一包装后生成的那句提示。底层的IOException可能是连接被拒绝、连接超时、连接重置、读不到数据、Socket 被关闭等等。客户端库为了让你在业务层只和JSchException打交道就把这些五花八门的网络问题收进同一个方法里然后再抛出来。所以你经常会看到日志里的异常消息长成下面这样com.jcraft.jsch.JSchException: createCommunicationsException: Connection refused这里Connection refused才是真正值得看的内容。再往下翻如果打开了整个堆栈还能看到java.net.ConnectException之类的嵌套根因。遇到这类异常第一反不要“这库怎么这么不稳定”而是“底层网络到底发生了什么”。我在排查线上问题时经常在群里看到有人直接贴一行异常消息截图这信息量是不够的。正确姿势是把getCause()打出来或者至少把异常的完整toString()和堆栈打出来。很多团队用的日志框架会默认吞掉 cause 细节只记录 message导致你查了半天也看不到真实原因。try { session.connect(15_000); } catch (JSchException e) { // 重点把 cause 一起打出来 log.error(SSH session connect failed: {}, e.getMessage(), e); if (e.getCause() ! null) { log.error(Root cause: {} - {}, e.getCause().getClass().getName(), e.getCause().getMessage()); } }日志里也有可能出现连续两个createCommunicationsException: createCommunicationsException: ...这是因为它内部某个环节又调用了同样的包装逻辑不用被这种重复吓到继续往里追 cause 就好。1.2 真正要看的是伴随信息异常名只是入口我把实际遇到过的伴随信息整理成了几个典型的“信号词”每个信号词背后对应的排查方向完全不同。如果你只盯着 createCommunicationsException 这一个名字很容易把问题统一归结为“网络故障”然后在服务器上重启、换端口、改乱七八糟的配置浪费时间。日志里的伴随信息大概率原因优先排查方向Connection refused服务端端口未监听、防火墙拒绝连接端口连通性、服务状态、防火墙/安全策略Connection timed out网络不通、安全策略丢包、服务器负载太高路由、链路质量、服务端负载Connection reset连接被服务端强制断开服务端 sshd 日志、登录限制、网络中间设备Algorithm negotiation fail客户端和服务端支持的加密算法交集为空SSH 算法协商配置、客户端库版本UnknownHostExceptionDNS 解析失败域名解析、hosts 配置Auth fail认证失败但还没到网络层用户名密码、密钥、服务端认证方式Host key verification failed主机密钥校验失败known_hosts、主机指纹变化这个表格你可以直接截图保存。真正排查的时候先看异常消息属于哪一类再跳到后面的对应小节效率会高很多。后面我也会按这个思路把每类问题展开讲。2. 动手前先把环境复现起来别靠猜2.1 最小复现样例一个简单的 SFTP 上传程序很多人一看到连接异常第一反应是去翻服务器配置或者检查网络。但我的习惯是先在本地把问题稳定复现出来因为只有能稳定复现的问题才有办法验证修复方案。下面这个例子我用的是 Java 里最常见的 SSH 客户端库。你可以建一个最简单的 Maven 工程只跑一段main方法连目标服务器的 SFTP 端口尝试上传一个小文件。代码尽量精简减少变量干扰。dependency groupIdcom.jcraft/groupId artifactIdjsch/artifactId version0.2.20/version /dependencyimport com.jcraft.jsch.*; import java.io.FileInputStream; import java.util.Properties; public class SftpUploadDemo { public static void main(String[] args) throws Exception { String host 192.0.2.10; int port 22; String user someuser; String password somepassword; JSch jsch new JSch(); // 如果使用公钥登录取消下一行注释并换成你自己的私钥路径 // jsch.addIdentity(/path/to/id_rsa); Session session jsch.getSession(user, host, port); session.setPassword(password); session.setTimeout(10_000); Properties config new Properties(); // 推荐使用 yes第一次连接时人工确认指纹并把指纹写入 known_hosts config.put(StrictHostKeyChecking, yes); config.put(PreferredAuthentications, publickey,password,keyboard-interactive); session.setConfig(config); try { session.connect(15_000); } catch (JSchException e) { e.printStackTrace(); if (e.getCause() ! null) { e.getCause().printStackTrace(); } return; } ChannelSftp sftp (ChannelSftp) session.openChannel(sftp); sftp.connect(10_000); try (FileInputStream in new FileInputStream(/local/file.txt)) { sftp.put(in, /remote/file.txt); } sftp.disconnect(); session.disconnect(); } }这个代码里用了文档保留地址192.0.2.10实际测试时换成你自己的服务器地址。跑起来之后如果异常复现了你就有了一个可以反复调整的最小环境。接下来做任何配置变更都先在这里验证不要在线上直接盲改。2.2 打开 SSH 客户端日志让异常自己开口复现出异常之后很多人会立刻去服务端翻日志但如果客户端日志里能看到 SSH 握手走到了哪一步很多问题当场就能定案。JSch 自带了一个Logger接口默认情况下是不输出的。我们需要在程序初始化时挂一个简单实现把所有日志打到控制台。JSch.setLogger(new JSch.Logger() { Override public boolean isEnabled(int level) { return true; } Override public void log(int level, String message) { System.out.println(JSCH[ level ] message); } });加上这段之后再跑一次程序你会看到类似下面的输出JSCH[1] Connecting to 192.0.2.10 port 22 JSCH[1] Connection established JSCH[1] Remote version string: SSH-2.0-OpenSSH_8.9 JSCH[1] SSH_MSG_KEXINIT sent JSCH[1] SSH_MSG_KEXINIT received JSCH[1] SSH_MSG_KEXINIT failed注意看两行关键日志Connection established出现说明 TCP 层已经通了再往后如果 KEXINIT 后失败问题基本就在算法协商如果连Connection established都没出现说明是网络层问题。这比看业务层异常要精准得多。客户端日志配合服务端日志基本能把问题定位到某一个具体环节。2.3 四个影响连接成败的 session 配置项这里我特别提醒四个配置每一个都有可能导致 createCommunicationsException而且踩坑的概率非常高。第一个是StrictHostKeyChecking。很多老教程图省事直接设成no然后线上就裸奔。正确做法是保持yes或ask并提前把服务器公钥指纹写入 known_hosts。后面我会专门讲这个校验机制。第二个是PreferredAuthentications。如果服务端只支持公钥认证而你默认走密码登录就会失败。一般我会把publickey,password,keyboard-interactive都列上让客户端按顺序尝试。第三个是Session.setTimeout()。这个超时是 Socket 读写超时不是连接超时。如果你只设置了session.connect()的超时参数但服务端一直不返回数据客户端可能会一直等下去。合理的做法是两个都设setTimeout(10_000)加上connect(15_000)。第四个是Channel的连接超时。很多人只设置了session.connect(15_000)却忘了channel.connect()也要给超时时间。SFTP 通道建立失败时同样会包装成连接类异常但不一定有createCommunicationsException字样。为了统一排查给通道也设上超时。private static final int SESSION_TIMEOUT_MS 15_000; private static final int CHANNEL_TIMEOUT_MS 10_000; private static final int READ_TIMEOUT_MS 10_000; Session session jsch.getSession(user, host, port); session.setPassword(password); session.setTimeout(READ_TIMEOUT_MS); session.connect(SESSION_TIMEOUT_MS); ChannelSftp sftp (ChannelSftp) session.openChannel(sftp); sftp.connect(CHANNEL_TIMEOUT_MS);3. 排查 createCommunicationsException 的四个层面3.1 网络层连接是被拒绝、被中断还是没响应拿到 createCommunicationsException 之后我第一件事永远是判断 TCP 层是否真的通。很多看起来像应用层的问题其实是安全策略把端口挡了或者服务器只允许特定来源 IP 访问。最简单的验证方式是用nc命令探测端口。Linux 和 macOS 下一般都有这个工具。nc -vz 192.0.2.10 22如果返回succeeded说明 22 端口从你当前所在网络是可达的。如果报Connection refused可能是服务没起来也可能是防火墙直接拒绝了。如果长时间卡住不动最后timed out那大概率是安全策略丢包或者链路不可达。在 Java 程序里也可以写一个非常轻量的 Socket 测试排除 SSH 客户端库的干扰import java.net.InetSocketAddress; import java.net.Socket; public class TcpProbe { public static void main(String[] args) throws Exception { String host 192.0.2.10; int port 22; try (Socket socket new Socket()) { socket.connect(new InetSocketAddress(host, port), 5_000); System.out.println(TCP connect ok); } catch (Exception e) { e.printStackTrace(); } } }如果这个 Socket 测试都连不上那就别折腾 SSH 客户端了先解决网络层面。常见原因包括服务端防火墙没放行 22 端口、服务端 sshd 没启动、来源 IP 被限制、路由器或云平台安全策略拦截。还有一种情况是服务器端fail2ban之类的保护机制把来源 IP 临时封禁了表现也是Connection refused或超时。遇到这类问题去服务端查一查系统日志比如/var/log/auth.log或/var/log/secure。3.2 认证层账号密码与公钥登录的坑TCP 通了但 SSH 客户端日志停在版本号交换之后然后抛Auth fail这就是认证层的问题。认证层并不复杂但变种很多。第一检查用户名和密码是否真的正确。密码里如果有特殊字符比如、#、$在配置文件和代码里要注意转义。我见过有人把密码写在 YAML 里结果#被当成注释截断了。第二确认服务端支持的认证方式。OpenSSH 服务端的/etc/ssh/sshd_config里可以这样配置允许的认证方法PasswordAuthentication yes PubkeyAuthentication yes KbdInteractiveAuthentication no如果你的服务端关闭了密码认证只允许公钥登录而客户端默认在尝试密码你就会看到一遍遍的Permission denied。此时需要把客户端PreferredAuthentications改成publickey并正确加载私钥。第三私钥文件本身有问题。OpenSSH 新版生成的私钥默认是 OpenSSH 格式某些老版本的 SSH 客户端库并不能直接读取这种格式会报invalid privatekey或者解析失败。解决办法是把私钥转成 PEM 格式ssh-keygen -p -m PEM -f id_rsa转换过程会要求你输入私钥密码不想设密码就直接回车。转换之后再用原来的客户端去加载。第四私钥文件权限太宽。Linux 下 OpenSSH 对私钥权限要求很严格如果id_rsa是 644 或者 777服务端会直接拒绝使用。用下面命令修正chmod 600 id_rsa认证失败时服务端日志会给出更多线索。如果有系统日志权限直接看/var/log/auth.log或/var/log/secure里面会记录类似Failed password for invalid user、Connection closed by authenticating user、User someuser from ... not allowed because not listed in AllowUsers的信息。这个信息比客户端日志准得多。3.3 算法协商Algorithm negotiation fail 的正确解法算法协商失败是我遇到最多的一类也是最容易让人一头雾水的。日志会显示createCommunicationsException: Algorithm negotiation fail字符串里没有 IP没有用户名没有具体算法。只有打开客户端完整日志才可能看到SSH_MSG_KEXINIT failed。服务端日志里通常会有这样一行Unable to negotiate with 192.0.2.20 port 50231: no matching key exchange method found. Their offer: diffie-hellman-group-exchange-sha256,diffie-hellman-group14-sha256,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521这说明客户端发出去的密钥交换算法列表和服务端能接受的列表没有交集。为什么会出现这个情况最典型的原因是服务器升级了 OpenSSH 版本新版本默认禁用了一些旧的、不够安全的算法而你的客户端库版本太老还是只支持旧算法。比如某些老版本客户端还在使用diffie-hellman-group1-sha1或ssh-rsa签名当服务器端把这些算法关掉后两边就谈不拢了。正确的解法是升级客户端库让客户端支持新算法。如果你用的是老的 SSH 客户端库建议升级到较新版本新版本通常会支持curve25519-sha256、rsa-sha2-512等更安全的算法。升级之后重新运行之前的最小复现程序绝大多数算法协商失败都会消失。另一种是临时兼容方案在服务端sshd_config里把旧算法加回来。这个方案我不建议在生产环境长期使用因为旧的加密和签名算法存在已知弱点等于是主动把安全水位拉低。如果一定要做可以考虑在调试阶段临时验证确认客户端的真实问题后尽快升级客户端并移除这些兼容配置。此外主机密钥算法也会出现协商失败报错类似no matching host key type found. Their offer: ssh-ed25519, ssh-rsa。这种情况同样优先升级客户端或者临时在服务端追加兼容的主机密钥算法。3.4 主机密钥校验StrictHostKeyChecking 不是开关是安全机制主机密钥校验失败时报的通常是Host key verification failed但它同样会被包装成 createCommunicationsException 系列异常。你可能会看到下面的完整消息com.jcraft.jsch.JSchException: createCommunicationsException: Host key verification failed这背后的机制是SSH 客户端第一次连接服务器时会拿到服务器的公钥指纹。为了防中间人攻击客户端会把这个指纹记进 known_hosts 文件。之后每次连接都会比对如果服务器公钥变了就会拒绝连接。最常见的场景是服务器重装系统或者重新生成了主机密钥导致客户端 known_hosts 里保存的还是旧指纹。这时候不要简单粗暴地设置StrictHostKeyCheckingno而是应该用带外渠道重新获取服务器指纹更新 known_hosts。比如先用你信任的安全通道登录服务器执行ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub拿到类似下面的指纹256 SHA256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234 hostname (ED25519)然后再在客户端机器上用ssh-keyscan把当前服务器的公钥保存到 known_hosts并人工确认得到的指纹和服务器上读到的一致ssh-keyscan -t ed25519 192.0.2.10 ~/.ssh/known_hosts在 Java 代码里可以通过下面方式显式指定 known_hosts 文件jsch.setKnownHosts(/home/app/.ssh/known_hosts);如果你在代码里看到了任何把StrictHostKeyChecking设成no的老代码建议抓紧改成yes并把服务器指纹管理起来。这个校验不是用来恶心人的它保证你连的服务器就是你以为的那台。4. 一个线上连接失败的完整排查实录4.1 现象定时任务导数据全部失败某公司的内部数据同步项目每天的定时任务会从一台远程 Linux 服务器拉取 CSV 文件到本地处理。某天早上开始任务大面积失败日志里清一色是com.jcraft.jsch.JSchException: createCommunicationsException: Algorithm negotiation fail负责排查的同学一开始怀疑网络测了ping和ncTCP 端口是通的。又怀疑账号被锁但换了几组账号都一样。后来把客户端完整日志打开发现 SSH 握手在SSH_MSG_KEXINIT阶段就断了并且服务端日志明确提示算法不匹配。4.2 服务端 sshd 日志里的关键信息登录服务器看/var/log/auth.log找到了几行关键日志Unable to negotiate with 192.0.2.20 port 50231: no matching key exchange method found. Their offer: diffie-hellman-group-exchange-sha1,diffie-hellman-group14-sha1,rsa-sha2-256,rsa-sha2-512这里的Their offer是客户端提出来的算法列表但服务端已经没有交集了。再看服务端sshd_config里面已经显式配置了只接受更强的算法。也就是说服务器最近做了安全加固把旧算法都禁掉了而客户端还停留在非常老的版本只能提出已经很弱甚至禁用的算法。4.3 客户端低版本算法库不匹配的修复过程这次修复没有去动服务端配置而是从客户端入手。第一件事是升级 Java 项目里的 SSH 客户端依赖库到较新版本。升级前先用一个临时脚本打印客户端支持的算法列表确认新版本里已经支持curve25519-sha256和rsa-sha2-512这些服务端接受的算法。升级后同样的最小复现程序一次就连接成功。这里我特意补充一点升级依赖库之后不要只看日志“连接成功”还要重新验证 SFTP 的上传、下载、删除、重命名这些核心操作因为新版本库对某些 API 的默认行为可能有调整。比如有的版本对FilenameEncoding的默认值不同可能导致中文文件名处理结果不一样。4.4 事后加固熔断、重试与告警这次问题解决之后还做了一些加固避免下次再被类似问题折腾半天。连接工具类里增加了统一的异常分类方法把JSchException的 message、cause、以及是否属于认证失败、算法协商失败、网络超时区分开分别输出到不同日志级别并记录到监控系统。在重试策略上我加了一个简单的指数退避重试第一次失败等 2 秒第二次失败等 4 秒第三次失败等 8 秒最多重试 3 次。但是对Auth fail这类认证失败不做重试因为账号密码错误重试多少次都一样只会增加服务器封禁风险。对Host key verification failed同样不做重试避免误报刷屏。如果你也要写重试逻辑建议参考下面这段伪代码int maxRetry 3; int attempt 0; long backoffMs 2_000; Exception lastException null; while (attempt maxRetry) { try { SftpResult result executeSftpTask(); return result; } catch (SftpAuthException e) { throw e; // 认证失败直接抛出 } catch (SftpNetworkException e) { attempt; Thread.sleep(backoffMs * attempt); } }另外告警不能只监控“抛出异常”这个级别。我一般还会监控 SSH 连接耗时如果连接耗时突然从几百毫秒涨到十几秒即使最终成功也说明网络或者服务端已经不正常了可以提前介入。5. 常见问题速查与三个易漏点5.1 createCommunicationsException 常见场景速查表我把实际工作中遇到过的问题整理成了一张速查表遇到问题时可以直接对着查。场景典型日志特征解决方案服务器 22 端口不通Connection refused/Connection timed out检查服务、端口、防火墙、安全策略云平台安全策略未放行TCP 探测超时调整入站规则只放行需要访问的 IP服务端禁用密码登录Auth fail/Permission denied改用公钥登录或临时开启密码认证做验证客户端私钥格式过老invalid privatekey将私钥转为 PEM 格式算法版本不匹配Algorithm negotiation fail升级 SSH 客户端库服务端做临时兼容需谨慎主机密钥变更Host key verification failed重新获取服务器指纹并更新 known_hosts连接空闲被服务端断开Connection reset/session down开启ServerAliveInterval保活DNS 解析失败UnknownHostException检查域名解析配置和 hosts 文件服务端来源 IP 限制TCP 通但 SSH 握手被断开检查AllowUsers、DenyUsers、防火墙规则这张表只能帮你快速定位方向具体到某个线上环境还是要结合服务端系统日志来看。5.2 三个容易忽略的细节第一个细节是Session不能被多个线程共享。很多人写一个连接管理类整个应用共用一个Session然后并发去开多个 Channel结果偶尔报channel is not opened、session is down或者莫名其妙的连接中断。SSHSession是有状态的推荐每个工作线程一个Session或者使用连接池按需创建。并发量太高时必须限制并发连接数否则服务端会因为MaxStartups限制而拒绝新连接。第二个细节是服务端会话超时设置。OpenSSH 默认的LoginGraceTime是 120 秒如果客户端在建立连接后迟迟没有完成认证服务端会主动断开。反过来如果网络链路比较慢客户端可以适当调大connect()超时时间。不过如果连接过程耗时太久更应该关注的是网络质量而不是盲调超时。第三个细节是 SSH 客户端库的日志默认是关的。线上环境第一次出现 createCommunicationsException 时很容易因为缺少客户端日志而只能靠猜。建议在测试环境把日志级别打开验证通过后再关闭或者使用动态开关只对特定用户、特定请求开启。这样既能保留排障能力又不会因为日志刷屏影响性能。还有一个我认为非常重要的习惯看到任何连接类异常先把getCause()的异常类型记下来。java.net.ConnectException、java.net.SocketTimeoutException、java.net.NoRouteToHostException三条路径对应的处理方式完全不同。排查时顺着根因走比在 SSH 配置里反复试错要靠谱得多。我在实际排查中最大的体会是createCommunicationsException 本身不是答案它只是一个路标。真正要看的是客户端日志和服务端日志交汇在一起后那个断掉的 SSH 握手阶段。连接被拒、认证失败、算法不匹配、主机密钥变化这四类问题闭上眼睛都能数出来但每次定位还是要把根因链打开不能省这一步。安全配置更别顺手关掉主机密钥校验宁可第一次多花五分钟同步指纹也不要留一个能被中间人利用的口子。下次线上再报这个异常你就知道它不是在说“网络不通”一句废话而是整个 SSH 连接流程里某一个环节没走通需要你一层层去把它找出来。
