Go SFTP 怎样限制同一文件传输的并发请求数量

Go SFTP 要限制“同一文件传输时同时发出的请求数”，核心配置是 sftp.MaxConcurrentRequestsPerFile(n)。它限制的是单个远端文件的在途请求上限，默认值是 64；多个文件任务是否同时运行，还要由应用层的任务池或信号量另行控制。下载和上传则分别看 UseConcurrentReads、UseConcurrentWrites，需要精确控制一次上传时，可直接调用 ReadFromWithConcurrency。

官方地址：https://pkg.go.dev/github.com/pkg/sftp

生产环境建议先把单文件请求上限设成一个小而明确的值，再根据服务端能力和链路延迟调整。下面用 8 个在途请求和一次 4 路写入说明配置边界，示例只展示结构与错误处理，不依赖本地 SFTP 服务。

先分清“单文件请求”与“文件任务”

MaxConcurrentRequestsPerFile 的作用域是“一个文件”。它不会把整个 sftp.Client 变成只能处理 8 个请求，也不会限制业务队列里同时有多少个文件。假设任务池同时传输文件 A 和文件 B，客户端选项为 8，那么 A、B 各自最多使用 8 个在途请求，文件任务池的总并发仍要由应用代码决定。

初始化客户端时把这个边界显式写出来，便于在配置审查和日志中追溯：

package transfer

import (
    "github.com/pkg/sftp"
    "golang.org/x/crypto/ssh"
)

func newSFTPClient(sshClient *ssh.Client) (*sftp.Client, error) {
    // 只限制单个文件的在途请求数，不代替文件任务池的并发控制。
    return sftp.NewClient(
        sshClient,
        sftp.MaxConcurrentRequestsPerFile(8),
        // 读取并发默认开启；这里显式写出，便于生产配置审查。
        sftp.UseConcurrentReads(true),
        // 上传并发需要结合失败后的截断策略再决定是否开启。
        sftp.UseConcurrentWrites(false),
    )
}

这里的 8 不是通用最佳值。远端服务器的请求承载能力、网络往返时间和单文件大小都会影响取值；先用保守上限保护服务端，再在有指标的情况下调整。

按传输方向选择并发策略

下载与上传不是同一种风险。官方文档说明，读取并发通常安全，并默认启用；写入并发在发生错误时可能让文件长度超过真正写成功的位置，因此需要额外考虑 Truncate。如果对端属于会因打开文件后 Stat 而删除文件的“read once”服务，则应评估是否关闭读取并发。

下载时可以保持读取并发；上传时若要开启写并发，必须把失败后的文件处理写进方案。下面这个函数采用默认安全路线：为单次上传显式设定 4 路请求，同时在错误时关闭文件并保留错误。

package transfer

import (
    "fmt"
    "io"

    "github.com/pkg/sftp"
)

func uploadWithLimit(client *sftp.Client, source io.Reader, remotePath string) (err error) {
    // Create 返回的远端文件句柄必须关闭，关闭错误也不能静默丢弃。
    remote, err := client.Create(remotePath)
    if err != nil {
        return fmt.Errorf("创建远端文件: %w", err)
    }
    defer func() {
        if closeErr := remote.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("关闭远端文件: %w", closeErr)
        }
    }()

    // 4 表示本次写入希望使用的并发度；客户端总上限仍会裁剪它。
    written, err := remote.ReadFromWithConcurrency(source, 4)
    if err != nil {
        return fmt.Errorf("上传远端文件: %w", err)
    }
    if written == 0 {
        return fmt.Errorf("上传结果为空")
    }
    return nil
}

ReadFromWithConcurrency 的并发参数小于 1 时会采用客户端上限，传入更大的值也会被客户端最大并发裁剪。因此它适合表达“这一次传输想用多少路”，而 MaxConcurrentRequestsPerFile 适合表达“这个客户端对单文件允许到哪里”。

把生产限制拆成三层

稳定的配置通常要拆成三层：第一层是单文件请求上限，防止一个大文件占满连接；第二层是文件任务池，防止多个文件把总连接和带宽推高；第三层是服务端与网络的承载上限，决定前两层的安全范围。只调高第一层，不能替代后两层。

如果开启 UseConcurrentWrites(true)，建议把失败后的截断动作和临时文件策略一起设计；不要只在配置文件里把开关改成 true，却没有处理部分写入。读取侧则要关注对端对 Stat/Fstat 的兼容性，必要时关闭读取并发或改用适合该服务的读取方式。

发布前检查这几项

• 确认单文件上限和文件任务池上限是两个独立参数，日志里分别打印。
• 确认 ReadFrom 是否会因为输入源无法确定长度而退化为顺序处理；需要保证并发时使用显式的 ReadFromWithConcurrency。
• 确认并发写入失败时不会把未完成文件直接当成最终文件，必要时执行 Truncate 或使用临时路径。
• 确认所有远端文件句柄和客户端连接都能关闭，并保留关闭阶段的错误。

归纳起来：用 MaxConcurrentRequestsPerFile 设定单文件安全上限，用应用层任务池控制文件数量，再根据方向选择读写并发；要精确控制单次上传，使用 ReadFromWithConcurrency。这三层分开后，调参和故障定位都会更清楚。

常见问题

把并发参数设为 1 会发生什么？

单个文件的在途请求会被限制到 1，通常更保守，但吞吐可能下降。它仍然不限制其他文件任务是否并行。

ReadFromWithConcurrency 传入 100 会突破客户端上限吗？

不会。该方法会把本次请求的并发度限制在客户端配置的最大并发范围内。