spring

　　用Spring Integration做SFTP上传时，失败的原因通常不在上传适配器本身，而是在连接握手、主机校验、远端目录权限、文件覆盖模式这几个点上。你先把上传链路拆成连接建立与文件传输两段，再按顺序验证，就能很快把问题从一团日志缩小到一两个配置项。

　　一、Spring Integration SFTP上传失败怎么办

　　上传失败先别急着改一堆配置，按从最容易出错到最能快速验证的顺序检查，定位会更快。SFTP Outbound Channel Adapter本质是一个MessageHandler，收到消息后连接远端目录并执行文件传输，所以问题要么出在会话建立，要么出在传输参数与远端文件系统。

　　1、先确认你传进来的payload类型是不是适配器支持的那几类

　　检查你上游流里发到SFTP出站适配器的payload，优先用java.io.File或Resource做基线验证，避免一开始就用InputStream导致可读性与关闭时机不好排查。官方文档明确列出了File、byte数组、String、InputStream、Resource等支持类型。

　　2、把远端目录和分隔符固定成明确值再测一次

　　把remote-directory先写成一个确定存在的路径，并把remote-file-separator固定为斜杠，先排除路径拼接导致的找不到目录或写错层级。适配器支持remote-directory与remote-file-separator等参数，先用最朴素的配置跑通再做动态表达式。

　　3、文件已存在时的行为要选对，否则看起来像随机失败

　　如果远端已有同名文件，你用的mode不同，结果完全不一样。先把mode临时设为REPLACE验证链路，再根据业务需要改为FAIL或IGNORE等模式，避免测试时因为同名文件导致异常。文档对FileExistsMode的模式枚举与默认覆盖行为有说明。

　　4、开启临时文件上传，排除半文件被对端消费或权限异常

　　把use-temporary-filename打开，让上传先写临时名再改名，这样即使传输中断也更容易识别是传输未完成还是权限拒绝。适配器示例里提供了use-temporary-filename属性。

　　5、远端权限问题用chmod做一次验证

　　如果你能上传但对端读不到，或上传后权限不符合要求，直接配置chmod做一次收敛验证，先确认问题是不是落在远端权限而不是上传本身。文档提到可用chmod参数在上传后修改远端文件权限。

　　6、把异常接到统一错误通道并打开日志，先拿到可解释的失败信息

　　在Spring Integration里，出站适配器抛出的异常如果被上游吞掉，看起来就像没触发。你可以先在IDE里用【Run】启动应用，再把org.springframework.integration.sftp与org.apache.sshd相关日志级别调到DEBUG，让握手与传输阶段的错误码完整输出，先做到一眼能看出是认证失败、主机校验失败还是写入失败。

　　二、Spring Integration SFTP密钥认证在哪里设置

　　密钥认证设置点在SFTP SessionFactory上，最常用的是DefaultSftpSessionFactory。你不需要在出站适配器里塞密钥，适配器只拿SessionFactory去建连接，认证材料必须配置在SessionFactory层。SessionFactory属性里明确有privateKey与privateKeyPassphrase等字段。

　　1、在DefaultSftpSessionFactory里配置privateKey资源位置

　　把私钥文件放到应用可读的位置，例如classpath或挂载目录，再在SessionFactory里把privateKey指向对应的Resource。文档说明privateKey是一个Resource，代表用于认证的私钥位置，如果不提供privateKey则需要提供password。

　　2、私钥有口令时配置privateKeyPassphrase

　　如果你的私钥文件带口令，需要同时设置privateKeyPassphrase，否则会表现为认证阶段失败。文档对privateKeyPassphrase的语义与可选性有明确描述。

　　3、主机指纹校验用knownHostsResource控制

　　生产环境更建议把known_hosts文件纳入部署资产，在SessionFactory里用knownHostsResource指定该文件，内容格式需与OpenSSH known_hosts一致。文档指出当allowUnknownKeys为false时，knownHostsResource需要预先填好。

　　4、联调阶段需要先跑通可临时放宽allowUnknownKeys

　　如果你遇到Server key did not validate这类主机校验错误，先确认known_hosts是否缺失或指纹变化。联调时可以短期把allowUnknownKeys设为true用来验证账号与密钥是否正确，但上线前应回到受控的knownHostsResource。allowUnknownKeys的默认值与含义在SessionFactory属性说明里写得很清楚。

　　5、连接不稳定或卡住时先把timeout设成可观测的值

　　DefaultSftpSessionFactory的timeout同时影响socket超时与默认连接超时，建议先设一个明确的秒数，避免无限等待导致线程堆积，方便你用日志对齐失败时点。

　　三、SFTP连接链路怎么排查

　　当你已经确认密钥放对了但仍然上传失败，下一步要把失败点精确落在握手阶段还是传输阶段，按下面顺序做能更快收敛。

　　1、看到主机校验失败先处理known_hosts与allowUnknownKeys

　　这类失败通常发生在会话建立早期，还没到传输步骤。你要么补齐known_hosts并确认指纹正确，要么在联调期临时放宽allowUnknownKeys验证其余链路，避免把问题误判为密钥格式错误。

　　2、看到认证失败再区分是私钥不可读还是口令不匹配

　　先检查私钥文件是否被容器挂载到正确路径，应用进程是否有读权限，再检查privateKeyPassphrase是否与实际私钥口令一致。SessionFactory对privateKey与passphrase的定义决定了这里的排查顺序。

　　3、看到上传阶段失败优先核对远端目录权限与覆盖模式

　　如果握手成功但传输报错，优先回到remote-directory、mode与chmod这三个点，目录不存在或无写权限会直接导致写入失败，同名文件且mode为FAIL也会表现为上传异常。

　　4、把链路跑通后再谈复用会话与性能参数

　　DefaultSftpSessionFactory支持isSharedSession等会话复用能力，连接稳定前不要先打开共享会话，避免把偶发连接问题混成复用问题。属性列表对isSharedSession的语义与默认值有说明。

　　5、需要更深层定位时再用SshClient定制做对照实验

　　从6.4开始SessionFactory暴露了SshClientConfigurer，可用于调整内部SshClient参数。只有当你确认是加密算法协商、包大小或NIO线程相关问题时再动这里，否则容易扩大变量范围。

　　总结

　　SFTP上传失败要分两段看，先保证SessionFactory能稳定建连，再处理出站适配器的传输参数。密钥认证的设置入口在DefaultSftpSessionFactory，通过privateKey与privateKeyPassphrase完成，主机校验通过knownHostsResource与allowUnknownKeys控制。把握手错误与传输错误分开排查，再配合mode与临时文件上传这些可控开关，绝大多数问题都能快速定位并修复。