🚀 Spring Integration FTP Session Factory 教程

本文专为 Spring 初学者设计，采用 Kotlin + 注解配置 的现代实践，助你轻松掌握 FTP 文件传输的核心配置。

---

🌐 一、FTP Session Factory 是什么？

类比理解：

想象 FTP Session Factory 是快递公司的「物流调度中心」：

• 📦 你的应用 = 电商仓库
• 📮 FTP 服务器 = 收货方地址
• 🔌 Session = 快递运输车
  调度中心（Factory）按需派车（Session），确保包裹（文件）安全送达！

核心作用

---

⚙️ 二、基础配置：FTP Session Factory

使用 DefaultFtpSessionFactory 配置基础连接（非加密 FTP）：

FTPConfig.kt

@Configuration
class FtpConfig {
    @Bean
    fun ftpSessionFactory(): DefaultFtpSessionFactory {
        return DefaultFtpSessionFactory().apply {
            host = "localhost"
            port = 21                   TP 默认端口
            username = "kermit"
            password = "frog"
            setClientMode(0)            // 主动模式 (0=主动, 1=被动)
            setFileType(2)              // 二进制传输模式
            bufferSize = 100000         // 缓冲区大小
        }
    }
}

TIP

模式选择建议：

• 主动模式：客户端开端口 → 适合服务器可访问客户端
• 被动模式：服务器开端口 → 适合客户端在 NAT 后（推荐）

---

🔐 三、安全配置：FTPS Session Factory

使用 DefaultFtpsSessionFactory 启用加密传输（对比 FTP 配置）：

FTPSConfig.kt

@Configuration
class FtpsConfig {
    @Bean
    fun ftpsSessionFactory(): DefaultFtpsSessionFactory {
        return DefaultFtpsSessionFactory().apply {
            host = "secure.server.com"
            port = 990                  TPS 默认端口
            username = "oleg"
            password = "password"
            useClientMode = true        // 客户端模式
            cipherSuites = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" // 加密套件
            protocol = "TLS"            // 加密协议
            needClientAuth = true       // 要求客户端证书
            implicit = true            // 隐式加密 (端口 990)
        }
    }
}

DANGER

安全警告：
避免使用 SSLv3 等已淘汰协议！推荐配置：

protocols = "TLSv1.2,TLSv1.3"
cipherSuites = "TLS_AES_256_GCM_SHA384"

---

⚠️ 四、关键注意事项

1. 会话缓存机制变更

从 Spring Integration 3.0 开始：

// 旧版本 (自动缓存) → 新版本 (默认关闭缓存)
factory.isSessionCache = false

解决方案：按需手动启用缓存（高并发场景推荐）：

val factory = DefaultFtpSessionFactory()
factory.setSessionCache(true) 

2. 连接问题排查

启用 TRACE 日志追踪会话：

# application.properties
logging.level.org.springframework.integration.file=TRACE

当连接失败时检查日志：

• 🔍 Connection refused → 检查防火墙/端口
• 🔍 Login incorrect → 核对凭证
• 🔍 Timeout → 调整网络或超时设置

3. 最佳配置实践

IMPORTANT

永远不要硬编码凭证！ 使用 Spring 属性注入：

@Value("\${ftp.host}") lateinit var host: String
@Value("\${ftp.port}") var port: Int

在 application.yml 中配置：

ftp:
  host: files.example.com
  port: 2121
  username: secure_user
  password: ${FTP_PASSWORD} # 从环境变量读取

---

❓ 五、常见问题解答

Q1：如何选择 FTP 和 FTPS？

类型	场景	安全性
FTP	内网测试环境	❌ 无加密
FTPS	公网传输/敏感数据	✅ SSL/TLS 加密

Q2：clientMode 应该设 0 还是 1？

// 推荐方案：
if (服务器在公网 || 客户端在防火墙后) {
    setClientMode(1) // 被动模式 // [!code tip]
} else {
    setClientMode(0) // 主动模式
}

Q3：大文件传输失败？

// 调整缓冲区大小（默认 8192 字节）
bufferSize = 1024 * 1024 // 1MB 缓冲区

// 并设置超时时间
factory.setConnectTimeout(5000) // 5秒连接超时
factory.setDataTimeout(30000)   // 30秒传输超时

---

💡 六、完整应用示例

模拟从 FTP 下载文件的工作流：

[点击展开] Spring Integration 流程配置

@Configuration
class FtpFlowConfig {
    @Bean
    fun ftpInboundFlow(factory: SessionFactory<FTPFile>) =
        IntegrationFlows
            .from(Ftp.inboundAdapter(factory)
                .localDirectory(File("/local/downloads"))
                .remoteDirectory("/remote/files")
                .regexFilter(".*\\.txt$"),
            { e -> e.poller(Pollers.fixedRate(5000)) }
        )
        .handle { file: File ->
            logger.info("下载文件: ${file.name}")
        }
        .get()
}

流程说明：

1. 📥 每 5 秒轮询 FTP 的 /remote/files 目录
2. 🔍 仅下载 .txt 后缀文件
3. 💾 保存到本地 /local/downloads
4. 📢 打印下载日志

---

✅ 总结

核心要点	关键配置项
基础连接	host, port, username, password
传输模式	clientMode (0主动/1被动)
安全加密	使用 DefaultFtpsSessionFactory
性能调优	bufferSize, 会话缓存
生产实践	属性注入 + 环境变量管理凭证

⚡️ 下一步学习：
掌握 Spring Integration FTP 适配器 实现文件自动同步 →