如何配置SFTP以支持断点续传

SFTP断点续传配置与实现指南

一、核心原理与前提

• SFTP本身不提供“自动断点续传”开关，是否可续传取决于客户端是否实现了“从指定偏移量继续传输”的能力，以及服务器是否允许对已有文件进行写入（追加/覆盖）。
• 常见实现思路：
  • 上传：客户端先获取远程已存在文件大小，打开本地文件并seek到该偏移，再以追加方式写入；若服务器或库支持续传模式则直接传入偏移/续传标志。
  • 下载：客户端获取本地已下载大小，远程文件seek到该偏移，客户端以追加模式写入本地文件。
• 适用场景：网络不稳定、传输大文件、跨公网链路等需要“可恢复”的传输任务。

二、服务器与账号侧配置要点

• 账号权限：确保用户对目标目录具备写入/创建/覆盖权限；若采用“追加写入”的续传方式，目录与文件权限需允许追加。
• 磁盘与配额：续传会向已有文件追加数据，确认磁盘空间与配额充足。
• 连接稳定性：保持SSH/SFTP服务稳定（避免频繁重启），并尽量使用长连接或可靠的作业编排，以减少因连接中断导致的重复传输。
• 安全策略：如需免交互登录，使用SSH密钥并妥善管理known_hosts，避免因为交互确认导致自动化续传失败。

三、客户端实现步骤与示例

• 通用流程
  1. 连接SFTP；2) 获取远程文件大小（不存在则视为0）；3) 获取本地文件大小；4) 计算偏移量；5) 本地文件seek到偏移；6) 以追加/续传模式上传或下载；7) 完成后校验大小或校验和。
• Python Paramiko 示例（上传/下载）
  • 安装依赖：pip install paramiko
  • 上传（支持从断点续传）
    • 思路：stat远程文件→本地seek→putfo追加
    • 代码示例：
      • import paramiko, os
      • def sftp_resume_upload(host, port, user, pwd, local, remote):
        • ssh = paramiko.SSHClient(); ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
        • ssh.connect(host, port=port, username=user, password=pwd)
        • sftp = ssh.open_sftp()
        • try: remote_size = sftp.stat(remote).st_size
        • except FileNotFoundError: remote_size = 0
        • local_size = os.path.getsize(local)
        • if remote_size < local_size:
          • with open(local, ‘rb’) as f:
            • f.seek(remote_size)
            • sftp.putfo(f, remote)
        • sftp.close(); ssh.close()
  • 下载（支持从断点续传）
    • 思路：本地存在则获取大小→远程seek→本地以追加模式写入
    • 代码示例：
      • import paramiko, os
      • def sftp_resume_download(host, port, user, pwd, remote, local):
        • ssh = paramiko.SSHClient(); ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
        • ssh.connect(host, port=port, username=user, password=pwd)
        • sftp = ssh.open_sftp()
        • remote_size = sftp.stat(remote).st_size
        • local_size = os.path.getsize(local) if os.path.exists(local) else 0
        • if local_size < remote_size:
          • with sftp.file(remote, ‘rb’) as rf:
            • rf.seek(local_size)
            • with open(local, ‘ab’) as lf:
              • while True:
                • buf = rf.read(8192)
                • if not buf: break
                • lf.write(buf)
        • sftp.close(); ssh.close()
• Java JSch 示例（上传，使用续传标志）
  • 思路：lstat获取远程大小→RandomAccessFile seek→ChannelSftp.put(…, ChannelSftp.RESUME)
  • 代码示例：
    • import com.jcraft.jsch.; import java.io.;
    • JSch jsch = new JSch();
    • Session session = jsch.getSession(“user”, “host”, 22);
    • session.setPassword(“pwd”); session.connect();
    • ChannelSftp sftp = (ChannelSftp) session.openChannel(“sftp”); sftp.connect();
    • long remoteSize = 0; try { remoteSize = sftp.lstat(“/remote/file”).getSize(); } catch (SftpException e) {}
    • RandomAccessFile raf = new RandomAccessFile(“/local/file”, “r”);
    • raf.seek(remoteSize);
    • OutputStream os = sftp.put(“/remote/file”, null, ChannelSftp.RESUME);
    • byte[] buf = new byte[1024*1024]; int n;
    • while ((n = raf.read(buf)) != -1) os.write(buf, 0, n);
    • os.close(); raf.close(); sftp.disconnect(); session.disconnect();
• 其他可选库
  • Python的pysftp也可通过获取远程大小、本地seek、putfo从断点继续上传，适合轻量脚本场景。

四、校验与可靠性建议

• 完整性校验：传输完成后对比文件大小；对关键文件建议再做**哈希校验（如MD5/SHA-256）**以确保一致性。
• 幂等与恢复：在作业层实现“可重入”逻辑——每次运行先比较大小/哈希，仅在未完成时续传，避免重复覆盖。
• 网络与容错：为脚本增加重试机制与指数退避；对长时间任务建议记录已传偏移与日志，便于人工介入。
• 性能优化：根据链路与磁盘选择合适的块大小（如8KB–1MB）；在极端不稳定网络下优先保证“可恢复”，而非极限吞吐。

五、常见问题与排查

• 已存在但大小不一致：优先以“远程大小 < 本地大小”作为续传条件；若远程文件可能损坏，先备份后删除并全量重传。
• 权限不足或目录不存在：检查用户对目标路径的读写权限与父目录是否存在。
• 续传无效（仍从0开始）：确认客户端确实执行了seek与“追加/续传”逻辑；部分库/模式需要显式传入续传标志或打开方式。
• 连接中断频繁：优化网络质量、启用保持连接参数、减少并发连接数，或使用更稳定的作业调度。
• 大文件校验慢：先比对大小，再抽样或分块哈希，必要时使用专用校验工具。