Spring Integration SFTP Outbound Gateway无法覆盖远程文件问题排查

问题概况 #

• 执行SFTP PUT操作时无法覆盖服务器上的同名文件，远程目录权限已设为777
• 错误日志：重试5次后触发SFTP error (SSH_FX_FAILURE)，失败环节为临时文件重命名为目标文件

配置代码分析 #

@Bean
@ServiceActivator(inputChannel = "toSftpChannel")
public MessageHandler toSftpChannelHandler() {
    SftpOutboundGateway sftpOutboundGateway =
            new SftpOutboundGateway(
                    sftpDestinationSessionFactory(),
                    AbstractRemoteFileOutboundGateway.Command.PUT.getCommand(),
                    "headers['remote-target-dir']");
    sftpOutboundGateway.setRemoteDirectoryExpression(PARSER.parseExpression("headers['remote-target-dir']"));
    sftpOutboundGateway.setUseTemporaryFileName(true);
    sftpOutboundGateway.setTemporaryFileSuffix(".temp");
    sftpOutboundGateway.setFileExistsMode(FileExistsMode.REPLACE);
    sftpOutboundGateway.setOutputChannelName("deleteLocalFilesChannel");
    sftpOutboundGateway.setAdviceChain(List.of(retryAdvice));
    return sftpOutboundGateway;
}

可能原因及解决方案 #

1. 目标文件权限/所有者限制 #

即使目录权限为777，若目标文件本身是只读权限（如644）或SFTP用户并非文件所有者，用户将无法删除/覆盖该文件。

• 登录SFTP服务器，执行ls -l查看目标文件的权限和所有者信息
• 确保SFTP用户对目标文件拥有写权限和删除权限，必要时修改文件权限（如chmod 666 filename）或所有者（chown user:group filename）

2. SFTP服务器配置限制 #

以Atmoz SFTP为例，部分默认配置可能限制文件覆盖操作：

• 检查Docker Compose中的用户配置，确保未禁用覆盖权限（默认通常允许，但需确认未添加AllowOverwrite no）
• 验证容器映射的本地目录权限：本地挂载目录的UID/GID需与容器内SFTP用户的UID/GID一致，避免权限映射异常

3. 临时文件重命名环节的逻辑冲突 #

当前配置开启了临时文件名（useTemporaryFileName=true），FileExistsMode.REPLACE的执行流程为：上传临时文件 → 删除原有目标文件 → 重命名临时文件。若删除环节失败，会直接导致重命名报错：

• 临时关闭临时文件名功能（setUseTemporaryFileName(false)），直接上传覆盖目标文件，验证是否是重命名环节的问题
• 若直接覆盖成功，说明问题出在临时文件重命名的权限或服务器限制上

4. 重试逻辑干扰 #

配置的retryAdvice可能在首次失败后，因临时文件未清理或目标文件状态锁定，导致后续重试重复失败：

• 临时移除setAdviceChain(List.of(retryAdvice))，测试单次上传覆盖操作是否成功
• 若单次成功，需调整重试逻辑，添加重试前的资源清理步骤（如删除残留的临时文件）

测试环境配置参考（Atmoz SFTP） #

若使用Docker Compose搭建测试环境，确保用户和目录配置正确：

services:
  sftp:
    image: atmoz/sftp
    volumes:
      - ./sftp-data:/home/test/upload
    ports:
      - "2222:22"
    command: test:testpass:1000:1000:upload

• test为SFTP用户名，testpass为密码
• 1000:1000为容器内用户的UID/GID，需与本地./sftp-data目录的UID/GID匹配
• upload为用户可访问的子目录

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