Go SFTP 怎样用临时文件与重命名完成上传交接

Go SFTP 上传交接可以采用“同目录临时名写入，成功关闭后再重命名为正式名”的约定。消费端只读取正式名，忽略临时后缀；上传端必须处理复制和关闭错误，只有这两项均成功才尝试交接。这样可以避免正常上传过程中，消费端把尚未写完的内容当成完成文件。

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

这里使用 github.com/pkg/sftp。示例选用服务端支持的 PosixRename 执行覆盖式交接，并要求同一目标只有一个发布者。普通 Rename、扩展重命名以及服务端底层存储不能不加区分地概括成“任何服务器都绝对原子”。

先把交接约定写清楚

假设业务生成一个供下游导入的报表文件。直接打开正式名写入，会让文件名在上传开始时就出现，下游如果按目录轮询，可能在文件写完之前读取它。解决这个问题需要上传端和消费端共同约定名称规则，而不是只在客户端加一个随机后缀。

临时文件采用点号前缀、随机标识和 .part 后缀，正式文件使用业务认可的名称。消费端必须显式忽略临时名，不能假设所有目录扫描器都自动忽略点号文件。正式目标与临时文件放在同一远端目录，以避免主动引入跨文件系统搬移问题；实际存储语义仍由服务端实现决定。

服务端能力决定采用哪种重命名

库提供普通 Rename 和使用 posix-rename@openssh.com 扩展的 PosixRename。后者明确允许替换已存在的目标。因此，选择 API 之前应先回答业务问题：同名文件是覆盖、拒绝，还是改用新批次名？

本文的函数选择“允许覆盖”，但不承担多个发布者竞争同一正式名的协调。通过 HasExtension 确认服务端宣布支持约定扩展后才开始上传；不支持时直接返回错误，由调用方选择另一种双方认可的交接协议。不要在失败后自动执行“删除正式文件，再 Rename”，这会人为制造正式名不存在的窗口。

连接应由调用方完成，并校验 SSH 主机身份、采用受控认证材料。远端目录预先建立，授予专用账号完成创建、写入和重命名所需的最小权限。示例不会演示跳过主机身份校验，也不会在错误信息中包含认证信息。

把写入、关闭和交接放进同一个函数

以下是可放入 Go 包中的原创函数，接收已经建立的 SFTP 客户端和数据源，不负责建立或关闭共享连接。代码使用 errors.Join，需要 Go 1.20 或更新版本。远端路径按斜杠语义使用 path；不根据客户端操作系统选择 filepath。

package handoff

import (
    "crypto/rand"
    "encoding/hex"
    "errors"
    "fmt"
    "io"
    "os"
    "path"
    "strings"

    "github.com/pkg/sftp"
)

// UploadReplace 要求调用方拥有同名目标的独占发布权。
// 失败时返回已创建的临时路径；不自动删除或重试重命名。
func UploadReplace(c *sftp.Client, src io.Reader, dir, name string) (temp string, err error) {
    if c == nil || src == nil {
        return "", errors.New("客户端或数据源为空")
    }
    if !path.IsAbs(dir) || name == "" || name == "." || name == ".." ||
        strings.ContainsAny(name, "/\\") || strings.ContainsRune(name, 0) {
        return "", errors.New("目录必须为绝对路径，文件名必须为单个成员")
    }
    if _, ok := c.HasExtension("posix-rename@openssh.com"); !ok {
        return "", errors.New("服务端不支持约定的 POSIX 重命名扩展")
    }

    var token [16]byte
    if _, err := rand.Read(token[:]); err != nil {
        return "", fmt.Errorf("生成临时名称: %w", err)
    }
    final := path.Join(dir, name)
    candidate := path.Join(dir, "."+name+"."+hex.EncodeToString(token[:])+".part")
    // 排他创建，避免意外截断已有文件；父目录由部署阶段预建。
    f, err := c.OpenFile(candidate, os.O_WRONLY|os.O_CREATE|os.O_EXCL)
    if err != nil {
        return "", fmt.Errorf("创建临时文件: %w", err)
    }
    temp = candidate
    closed := false
    defer func() {
        if !closed {
            // 提前退出也关闭句柄，并保留关闭错误。
            if closeErr := f.Close(); closeErr != nil {
                err = errors.Join(err, fmt.Errorf("关闭临时文件: %w", closeErr))
            }
        }
    }()

    // 在写入数据前限制访问；远端目录本身也必须隔离。
    if err = c.Chmod(temp, 0600); err != nil {
        return temp, fmt.Errorf("设置文件权限: %w", err)
    }
    if _, err = io.Copy(f, src); err != nil {
        return temp, fmt.Errorf("上传临时文件: %w", err)
    }
    closeErr := f.Close()
    closed = true
    if closeErr != nil {
        return temp, fmt.Errorf("完成文件关闭: %w", closeErr)
    }
    // 此示例允许覆盖正式目标；失败后不先删除旧目标。
    if err = c.PosixRename(temp, final); err != nil {
        return temp, fmt.Errorf("远端交接结果需确认: %w", err)
    }
    return "", nil
}

返回值约定是：成功返回空临时路径和 nil；已创建文件后发生错误，返回该临时路径与错误。调用方据此记录恢复线索，而不是丢弃错误后重新生成任务。示例未连接真实服务器，也没有把示例描述为实测记录。

函数明确调用 Close，而不是只在函数退出时 defer Close：如果关闭错误尚未被处理，就提前重命名，便失去了“写入完成后才能交接”的判断点。提前退出的 defer 则用于释放资源，并把关闭错误合并到原错误中。

0600 只是本示例的访问策略。下游若使用另一个账号，需要提前设计同组权限或其他受控授权，并在交接前完成相应属性设置。不要在正式名已经可见后，才临时补权限。随机名称和排他创建也不能代替目录隔离；可被无关账号修改的目录不适合作为可信交接区。

失败阶段决定恢复方式

网络在服务端完成重命名后断开，客户端可能没有收到成功响应。因此，“返回错误”不必然证明远端未发生修改。此时盲目重传同一个正式名，可能覆盖已经交接的数据。建议使用不可重复的批次标识、明确的任务状态和下游确认机制，把重试决策放在任务层。

残留临时文件可以由受控清理任务回收，但应限定专用目录、名称规则及足够的保留时间，并排除仍在上传的任务。上面的函数保留失败路径，是为了不在结果不确定时擅自执行破坏性清理。

交接成功还不等于持久化和消费完成

重命名解决的是名称可见性交接，不能直接证明断电后数据一定保留，也不能证明下游已经导入。库的 File.Sync 请求刷新到稳定存储，依赖 fsync@openssh.com 扩展；如果业务要求使用它，应在 Close 之前明确调用并处理错误，同时与服务端确认所需持久化保证。本示例没有启用这项额外要求。

对于多个文件共同组成一个批次的场景，逐个改名也不意味着整个批次一起提交。可以围绕批次目录、清单或完成标记另行设计消费约定，但不要把多文件事务的保证直接套在单文件重命名上。

临时文件一定要放在系统临时目录吗？不需要。这里选择目标同目录，减少跨存储位置带来的差异，并统一权限管理。

不允许覆盖时能直接复用这个函数吗？不能。它明确采用覆盖语义。应使用独立批次正式名，或由服务端提供并确认“不覆盖”的提交约定；先查询目标不存在再覆盖，也不能消除并发竞争。

函数为什么不关闭 SFTP Client？连接的生命周期属于创建它的调用方，本函数只负责自己创建的远端文件句柄。共享连接不应因一份文件上传结束就被关闭。

参考：PosixRename API；File.Sync API；SFTP 客户端实现。