Go SFTP 怎样流式下载远端文件并保留错误

我第一次把 SFTP 下载接进定时任务时，最容易忽略的不是网络，而是“失败后留下了什么”。直接把远端内容写进最终文件，传输中断会留下半截文件；把 Close 错误全部丢进 defer，又会让日志只显示“下载成功”。现在我的做法是：远端文件作为流交给 io.Copy，本地先写到临时文件，传输和两端关闭错误都保留，全部成功后再改名。

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

先保护最终文件，再谈下载速度

对我来说，这个任务里真正要保护的资产有三个：远端文件流、本地临时文件和最终目标文件。攻击路径不一定是恶意攻击，也可能是网络断开、权限变化、磁盘写满或进程被终止。若临时状态直接暴露成最终文件，下游任务就可能把不完整内容当成有效输入。

因此把路径分成“远端只读输入 → 本地 .part 临时文件 → 最终文件”更稳。临时文件名不要由未经处理的远端路径拼接出来；实际服务里还应把本地目录固定在允许的工作区，并限制 SFTP 账号权限。下面的图是静态结构说明，不是运行截图。

用 io.Copy 把远端文件流式写入临时文件

sftp.Client.Open 返回远端 File。官方文档说明，整文件传输时优先使用 WriteTo，而 io.Copy 会自动发现这条优化路径；这比手写循环读取更少出错，也不会把整个文件装进内存。

package download

import (
	"fmt"
	"io"
	"os"
	"path/filepath"

	"github.com/pkg/sftp"
)

// Download 将远端文件写入临时路径，成功后再替换最终文件。
func Download(client *sftp.Client, remotePath, localPath string) (written int64, err error) {
	remote, err := client.Open(remotePath)
	if err != nil {
		return 0, fmt.Errorf("打开远端文件: %w", err)
	}
	defer func() {
		// 只有前面没有更具体的错误时，才用远端关闭错误作为返回值。
		if closeErr := remote.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("关闭远端文件: %w", closeErr)
		}
	}()

	tmpPath := localPath + ".part"
	local, err := os.OpenFile(tmpPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
	if err != nil {
		return 0, fmt.Errorf("创建临时文件: %w", err)
	}
	defer func() {
		// 本地 Close 失败也要留下记录，但不覆盖更早的传输错误。
		if local != nil {
			if closeErr := local.Close(); err == nil && closeErr != nil {
				err = fmt.Errorf("关闭本地文件: %w", closeErr)
			}
		}
		if err != nil {
			// 失败的 .part 不能被下游误当成完整文件。
			_ = os.Remove(tmpPath)
		}
	}()

	written, err = io.Copy(local, remote) // 流式传输；错误和已写字节数都会保留。
	if err != nil {
		return written, fmt.Errorf("传输远端文件: %w", err)
	}
	if closeErr := local.Close(); closeErr != nil {
		local = nil
		return written, fmt.Errorf("关闭本地文件: %w", closeErr)
	}
	local = nil // 关闭成功后再改名，避免跨平台文件句柄占用目标路径。
	if err = os.Rename(tmpPath, filepath.Clean(localPath)); err != nil {
		return written, fmt.Errorf("提交最终文件: %w", err)
	}
	return written, nil
}

这个写法有一个需要提前说明的边界：示例为了突出错误传播，把临时文件关闭放在改名之后的 defer 中。生产代码可以把“关闭临时文件、检查关闭错误、再改名”拆成显式步骤，以便让改名只发生在本地句柄已经成功关闭之后；关键原则不变——传输未完成时不能提交最终路径。

哪些错误要保留，哪些优化不要误用

io.Copy 返回的是已写入字节数和传输错误。远端读取失败、网络中断和本地写入失败都应作为原始错误的包装根因。示例里的 defer 只在尚无错误时接管关闭错误，避免用“关闭失败”覆盖更早发生的“读取失败”。如果日志系统支持错误链，应保留 %w，让上层可以用 errors.Is 或 errors.As 继续判断。

官方还提供了 ReadFrom 与 ReadFromWithConcurrency，它们更适合把本地读取器写入远端 SFTP 文件；本题是“远端下载到本地”，优先让 io.Copy(local, remote) 走远端文件的 WriteTo。不要因为看到并发参数就把普通下载改成多路写入，先确认链路延迟、服务端限制和目标文件是否允许分段写。

我的上线清单：把错误写进审计记录

我会把“远端文件名、最终文件名、字节数、错误类型和任务 ID”放进同一条结构化日志，避免日志里出现密码、私钥或完整连接串。这样排查时能区分“没打开”“传到一半”“关闭失败”和“提交失败”，也不会因为重试方便就掩盖权限或磁盘问题。

常见问题

为什么不用 os.Create 直接写最终文件？

网络或磁盘中途失败时，最终路径会留下半成品。临时文件成功完成后再改名，更容易让下游只看到完整文件。

io.Copy 会不会把整个远端文件读进内存？

不会。它按流复制，并且会利用 sftp.File 提供的整文件传输接口；返回值仍应检查。

关闭错误一定要覆盖传输错误吗？

通常不应覆盖。先保留更早的传输或写入根因，同时把另一个关闭错误写进结构化日志，才能兼顾诊断信息。