GitHub Actions中FTP部署超时错误的排查与解决

针对你遇到的Timeout (control socket)错误，结合GitHub Actions的网络环境特性，可按以下步骤排查和解决：

1. 强制启用被动模式 #

GitHub Actions的运行器处于受限网络环境，主动FTP模式下服务器无法反向连接到运行器，大概率会触发超时。在action配置中添加被动模式参数：

- name: 📂 Sync files
  uses: SamKirkland/FTP-Deploy-Action@4.0.0
  with:
    server: ftp.example.com
    username: ${{ secrets.ftp_username }}
    password: ${{ secrets.ftp_password }}
    local-dir: ./build/
    server-dir: /
    passive-mode: true # 启用被动模式

2. 延长控制套接字超时时间 #

默认超时时间可能不足以应对网络延迟，手动设置更长的超时值（单位为毫秒）：

- name: 📂 Sync files
  uses: SamKirkland/FTP-Deploy-Action@4.0.0
  with:
    # 其他参数保持不变
    timeout: 60000 # 设置为60秒

3. 切换到SFTP协议（优先推荐） #

如果你的服务器支持SFTP，改用基于SSH的SFTP协议，兼容性更强且无需复杂的端口配置：

- name: 📂 Sync files via SFTP
  uses: SamKirkland/FTP-Deploy-Action@4.0.0
  with:
    server: sftp://ftp.example.com # 指定SFTP协议
    username: ${{ secrets.ftp_username }}
    password: ${{ secrets.ftp_password }}
    local-dir: ./build/
    server-dir: /
    port: 22 # 若服务器用自定义端口则修改对应值

4. 验证运行器与FTP服务器的连通性 #

在工作流中添加端口测试步骤，确认GitHub运行器能正常访问FTP服务器的21端口：

- name: Test FTP port connectivity
  run: nc -zv ftp.example.com 21

如果测试失败，说明服务器防火墙可能限制了GitHub运行器的IP段，需要检查服务器的白名单规则（GitHub运行器IP为动态范围，不建议手动添加，优先用被动模式或SFTP）。

5. 升级到最新版FTP-Deploy-Action #

旧版本可能存在已知的超时bug，尝试升级到最新稳定版：

- name: 📂 Sync files
  uses: SamKirkland/FTP-Deploy-Action@v4.3.4 # 使用最新版本号
  # 其他参数保持不变

6. 检查服务器被动端口配置 #

如果启用被动模式后仍超时，确认FTP服务器已开放被动端口范围（通常是1024-65535），且这些端口未被服务器防火墙或云服务商安全组阻断。

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