Spring Boot SFTP服务隔日故障求助：Failed to list files异常排查

核心错误定位 #

异常发生在SFTP目录列表查询阶段，报错中的SFTP错误码4对应协议定义的通用失败（Failure），结合"隔日出现"的规律，重点排查以下周期性触发的问题：

1. 服务器端周期性资源/权限变更 #

特定SFTP服务器可能存在隔日执行的定时任务：

• 比如每日固定时段的权限批量刷新、磁盘配额重置、系统进程清理等操作，在任务执行期间，目标目录的读取权限被临时限制，或者服务器CPU/内存/磁盘IO被占满，导致无法响应目录列表请求。此时文件实际存在，但服务器无法返回列表结果。
• 部分SFTP服务器会周期性清理闲置会话或限制并发连接数，刚好隔日到达阈值，导致新的list请求被拒绝。

2. 客户端连接会话复用失效 #

如果使用了SFTP连接池，可能存在以下问题：

• 连接池配置的会话超时时间远长于服务器端的闲置会话清理时间，隔日期间客户端持有的会话已被服务器主动回收，但客户端仍尝试复用该失效会话执行list操作，触发失败。
• 连接池没有配置会话有效性校验，无法提前检测到失效会话，导致请求直接失败。

3. 网络层面周期性波动 #

目标服务器所在网络存在隔日周期性的管控：

• 防火墙规则隔日更新、带宽限流时段、路由切换等，导致客户端与SFTP服务器之间的连接在特定时段不稳定，list操作的数据包丢失或超时，触发错误码4的通用失败。

4. 代码层面的容错缺失 #

当前代码存在以下不足，放大了临时故障的影响：

• operations.list()操作没有针对临时失败的重试逻辑，遇到服务器端或网络的临时问题时直接报错退出，无法自动恢复。
• 异常日志仅打印e.getMessage()，丢失了完整的堆栈信息，无法定位底层具体原因（比如是权限问题、连接超时还是服务器端异常）。

代码优化建议 #

• 增加重试机制：针对list操作添加指数退避重试，尤其是捕获到错误码4这类临时失败场景，避免单次故障导致任务失败。
• 完善连接池配置：确保连接池的会话超时时间与服务器端的闲置清理策略匹配，添加会话有效性校验（比如在获取连接前执行简单的目录校验）。
• 增强日志信息：异常日志改为打印完整堆栈，比如LOG.error("SFTP目录列表查询失败", e);，便于定位底层问题。
• 前置目录校验：在执行list前，先调用operations.exists(sftpProperties.getRemoteDirectory())校验目录可达性，提前排查目录访问问题。

内容的提问来源于stack exchange，提问作者Sharvari Nagesh