做系统集成的朋友，十有八九都碰到过这种需求：本地是 Windows，生产环境是 Linux，每天要定时把数据文件、配置文件、上传的附件图片传到远程服务器上。很多人第一反应是 FTP，但 FTP 在防火墙、被动模式、明文传输这些环节上坑不少。实际操作中我更推荐在 .Net Core 项目里用 Renci.SshNet 这个库，直接通过 SSH 的 SFTP 子协议把文件安全地传到远程 Linux 服务器，既能复用服务器上已有的账号体系，又避开了 FTP 那堆乱七八糟的兼容性问题。
这篇文章不聊虚的，我把自己在多个项目里实际调试通过的经验完整梳理了一遍，从 NuGet 包安装、连接参数配置、文件上传、远程目录自动创建到常见异常排查，整个链路都给你拆开讲清楚。正在写后台服务、需要和 Linux 服务器交换文件的同学，或者刚开始接触 SFTP 想少走弯路的读者，可以直接把下面的代码和思路拿过去改改就能用，整个过程比你想象的要简单很多。
1. 场景与选型：为什么是 SFTP 而不是 FTP 或 SCP
1.1 先确认你面临的是什么问题
很多人找我帮忙看文件上传的代码，第一句话说“我要传文件到 Linux”。但往下问就会发现，不同人的真实需求差异很大：有的是要把本地生成的一个报表定时丢到服务器指定目录，有的是要接收前端传过来的图片再转发到另一台存储机器，还有的是要从远程 Linux 拉取日志回本地分析。
不同需求对应的技术方案不完全一样。如果只是单台机器之间偶尔传个文件，用 scp 命令都行；如果涉及到程序化操作、需要在上传前确认远程目录结构、还想处理文件重名和校验，那就得用一个完整的协议栈，SFTP 是最合理的答案。SFTP 全称 SSH File Transfer Protocol，注意它跟 FTP 没有任何关系，它是构建在 SSH 协议之上的文件操作协议，默认走 22 端口，传输内容全程加密，能做的操作也不只是上传下载，还包括列目录、建目录、重命名、删除、改权限等。这对“程序化运维”来说太关键了。
我们需要的是一个能在 .Net Core 里跑得稳、API 不反人类、遇到异常能给出明确信息的库。我把常见的几种方案放在一起比对过，结论比较明确。
1.2 对比常见方案：FTP、SCP、手工命令、Web API
| 方案 | 传输加密 | 目录操作能力 | .Net Core 集成度 | 坑点 |
|---|---|---|---|---|
| FTP / FTPS | FTPS 才有加密 | 一般 | 有内置库但API老旧 | 被动模式、防火墙、编码问题多 |
| SCP 命令 | 有 | 弱，只能传文件 | 需要外部进程调用 | 无法精细控制，异常信息少 |
| 手工 scp 命令 + 进程调用 | 有 | 弱 | 几乎没有 | 本地依赖，运维环境不一致就废 |
| Web API 上传 | 取决于实现 | 需服务端配合 | 高 | 要改服务端代码，不能通用管理 Linux |
| Renci.SshNet + SFTP | 有 | 强 | 高，纯托管 | 需要理解连接生命周期，配置项偏多 |
从表格里能看出，SFTP 是功能覆盖最全面的，而 Renci.SshNet 又是 .Net 生态里对 SFTP 协议封装得比较顺手的一个库。它不依赖本机安装任何 SSH 客户端，因为是纯托管代码实现的协议，所以部署到容器或 Linux 服务器上也能跑，这一点在微服务场景里非常实用。
1.3 为什么点名 Renci.SshNet
有人会问，直接用 .NET 内置或者别的库不行吗？.Net 的 BCL 到目前为止还没有内置 SFTP 客户端，网上一些自研 SSH 实现基本是玩具级别的，根本不敢用于生产。Renci.SshNet 是社区里维护时间长、使用面广的一个开源库，NuGet 下载量很高，我实际用下来的感受是它的 API 设计足够贴近 SSH 原生概念：SftpClient 负责文件操作，SshClient 负责执行远程命令，两者可以独立使用，也可以配合起来做“先传文件、再远程执行脚本”的完整链路。
它在 .NET Standard 2.0 上有对应实现，意味着从 .NET Core 3.1 到 .NET 6、7、8 都能直接用，不用额外适配。后续我们所有的代码例子都是基于这个库写的，版本我建议上 2.x 系列，API 稳定一些，踩坑记录也相对充分。
2. 环境准备与依赖安装：从零跑通最小项目
2.1 搭一个最小演示环境需要什么
在开始编码前，你得确保手头有这几样东西：一个可以正常连接的远程 Linux 服务器（IP 或域名、端口、账号、密码或者私钥都准备好），本地一台装了 .NET SDK 的电脑，以及一个你想测试上传的本地文件。
我的建议是先把服务器上 SSH 服务确认好。大多数 Linux 发行版默认安装了 OpenSSH，用systemctl status sshd或service sshd status看一眼就行。如果服务器都没开 SSH，后面写再多代码也没用，这一步别跳过。端口默认是 22，如果改过要记一下，后面连接参数里要写。
本地的话，我一般用命令行工具dotnet new console创建一个最小控制台项目来做连通性验证，比直接塞进业务系统里调试清爽得多，出错时定位也快。验证通过之后，再把代码复制到正式服务里套上依赖注入和日志。先小后大，别一上来就重构大型服务。
2.2 NuGet 安装与命名空间确认
安装依赖就一行命令的事情。在项目根目录执行：
dotnet add package Renci.SshNet如果用的是 Visual Studio，也可以直接在 NuGet 包管理器界面搜索Renci.SshNet，选择最新的 2.x 稳定版本安装。我建议安装时留意一下包是否引用了不兼容的框架版本，.NET Core 3.1 以上基本都兼容，没问题。
安装完成后，代码里需要用到两个命名空间：
using Renci.SshNet; using Renci.SshNet.Sftp;第一个是客户端核心类所在，第二个是 SFTP 文件对象和枚举的所在。装完包之后先写一个最基础的连接测试，确保服务器、账号、网段都通，再进入下一步。连接不上就先去排查网络和安全组，别急着堆业务代码。
3. 连接配置拆解与基础上传实现
3.1 连接参数逐个说清楚
SftpClient 的构造函数有多个重载，实际开发里最常用的是这两种：账号密码连接和私钥文件连接。
// 账号密码方式 var connectionInfo = new ConnectionInfo(host, port, username, new PasswordAuthenticationMethod(username, password)); // 私钥方式 var privateKeyFile = new PrivateKeyFile(privateKeyPath); var connectionInfo = new ConnectionInfo(host, port, username, new PrivateKeyAuthenticationMethod(username, privateKeyFile));这里有个容易忽视的点：ConnectionInfo构造函数里的port是int类型，不是字符串，很多人从配置中心读出来的是字符串“22”，忘记转换就报类型错误。另外Username不要带root@这种前缀，它是单独的参数，不需要合在一起写。
连接相关的属性里，Timeout一定要主动设置，尤其是在内网环境不稳定时，默认值有时候会让你等很久才报错。我习惯设置为 30 秒：
connectionInfo.Timeout = TimeSpan.FromSeconds(30);还有一个Encoding属性也要注意。如果远程服务器的系统编码不是 UTF-8，而你的文件名包含中文，可能会出现上传成功后远程看到的文件名是乱码。这个点我在第 5 部分会详细讲，这里先记住有这个东西。
3.2 最小可运行的上传代码
先给出一段完整的最小可运行代码，我平时做验证时就是从这个骨架开始的：
using Renci.SshNet; string host = "192.168.1.100"; int port = 22; string username = "developer"; string password = "your_password"; string localFilePath = @"C:\temp\testfile.tar.gz"; string remoteFilePath = "/home/developer/uploads/testfile.tar.gz"; using (var client = new SftpClient(host, port, username, password)) { client.Connect(); using (var fileStream = File.OpenRead(localFilePath)) { client.UploadFile(fileStream, remoteFilePath); } client.Disconnect(); }这段代码的逻辑很直白：创建客户端，建立连接，打开本地文件流，通过UploadFile方法上传到远程路径，最后断开连接。using块保证了SftpClient在使用完毕后会被正确释放，这个习惯很重要，SshNet 的连接对象如果不释放，长时间跑下来会占满线程和句柄，后面我会专门讲这个坑。
UploadFile的第一个参数是Stream类型，意味着你传什么流都行，不一定要是文件流。如果你是在 Web API 里收到IFormFile，CopyToAsync一个MemoryStream再传上去也是可以的，不过大文件建议直接落盘再用文件流，别让内存兜底。
3.3 远程路径的几个反直觉注意点
远程路径的处理是新人最容易翻车的地方，我单独拿出来讲。
第一个注意点：SFTP 的路径分隔符永远是/，不管服务器是 Windows 还是 Linux，Renci.SshNet 内部统一按 SFTP 协议处理。你在代码里写\反而会导致FileNotFoundException或者路径解析错误。
第二个注意点：远程路径必须是一个绝对路径，而不是相对路径。/home/developer/uploads/testfile.tar.gz才是有效的，uploads/testfile.tar.gz这种相对路径能不能用取决于服务器上 SSH 登录的默认目录，但为了可控性，建议永远写绝对路径。原因很简单：你自己在代码里控制了完整的路径，就不会因为不同账号的家目录不同而传错位置。
第三个注意点：上传前要确认远程目录存在且当前用户有写权限。UploadFile不会自动创建多级目录，目录不存在时会抛出SftpPathNotFoundException。有经验的开发会在上传前单独做一次目录检查和创建操作，这个我们下一部分细说。
4. 进阶玩法：远程目录自动创建、大文件流式传输与完整性校验
4.1 远程目录不存在时自动创建
上传前检查目录，是生产环境里必须养成的习惯。我见过不少线上事故，就是因为服务器重新初始化之后目录结构变了，上传任务一直在报错。
封装一个工具方法可以解决大部分场景：
private static void EnsureRemoteDirectoryExists(SftpClient client, string remoteDirectory) { if (client.Exists(remoteDirectory)) { return; } // 逐级创建父目录，避免一次性创建时中间目录缺失 var pathParts = remoteDirectory.Split('/', StringSplitOptions.RemoveEmptyEntries); string currentPath = "/"; foreach (var part in pathParts) { currentPath = currentPath == "/" ? $"/{part}" : $"{currentPath}/{part}"; if (!client.Exists(currentPath)) { client.CreateDirectory(currentPath); } } }这里我们要注意一个问题：直接用client.CreateDirectory("/home/developer/uploads/2024/01")时，如果uploads或者2024不存在，SFTP 服务端通常不会帮你递归创建，会直接报错。所以需要像上面这样一级一级建，每建一级之前先检查是否已存在，这样即使部分目录已经存在也不会重复创建报错。
我自己的习惯是把EnsureRemoteDirectoryExists和上传动作封装到一个工具类里，文件名就叫SftpUploader，传入host、username、password、localPath、remoteDirectory、remoteFileName，对外只暴露一个方法。业务层调用时不用关心目录细节，维护起来省心很多。
4.2 大文件上传：用流而不是字节数组
我在评审代码时看到过这种写法：File.ReadAllBytes(localFilePath)把整个文件读进byte[]，然后靠MemoryStream包装上传。文件只有几 MB 时没问题，但当文件到了几百 MB 甚至几个 G，这种写法就是灾难，内存直接爆掉。
正确的做法是让文件流自己处理缓冲：
using var client = new SftpClient(host, username, password); client.Connect(); EnsureRemoteDirectoryExists(client, remoteDirectory); using (var fileStream = new FileStream(localFilePath, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 81920, useAsync: false)) { client.UploadFile(fileStream, remoteFilePath); } client.Disconnect();FileStream默认有自己的内部缓冲区，UploadFile会从这个流里分块读取数据，不会一次性把文件内容全部加载进内存。bufferSize参数我写81920字节也就是差不多 80KB，这个大小是性能和内存开销的平衡点，你也可以根据实际场景调整。
另外要补充一点：如果文件非常大且上传可能要几分钟，考虑在业务层做进度回调。UploadFile的单参数重载没有进度通知，但可以通过实现自定义Stream或直接对UploadFile的返回值做循环校验来实现。对大多数场景来说，先保证上传过程不占用太多内存，就已经解决了主要矛盾。
4.3 上传后做文件大小校验
代码工作正常之后，我们还要面临一个现实问题：怎么保证文件是完整传上去的？SSH 协议本身有传输完整性校验，但应用层仍然建议加上一层校验，防止中途网络抖动导致部分写入以后应用不知道。
最简单的校验是上传之后获取远程文件大小，和本地文件大小对比：
var remoteFile = client.Get(remoteFilePath); long remoteSize = remoteFile.Length; long localSize = new FileInfo(localFilePath).Length; if (remoteSize != localSize) { throw new Exception($"文件大小不一致，本地 {localSize} 字节，远程 {remoteSize} 字节"); }更严格的做法是对比 MD5 或 SHA256。SFTP 本身不直接提供服务端文件的哈希计算接口，所以如果你想做哈希校验，需要先上传一个校验脚本到远程执行，或者下载文件回来对比哈希。这会增加不少复杂度，我的建议是：日常业务用文件大小校验足够，只有对数据完整性要求极其苛刻的场景才做哈希对比。
大小校验这个步骤看着简单，但能挡掉很多偶发问题，尤其是有代理和网关介入的网络环境里，连接中断但客户端没有及时感知到的场景，这个校验就是最后一道防线。
5. 常见问题排查实录
5.1 连接类问题
| 问题 | 可能原因 | 排查方法 |
|---|---|---|
| 连接超时 | 防火墙拦截、端口不是 22、服务器负载高 | 用 telnet 或 ssh 命令验证端口连通性 |
| 连接被拒绝 | SSHD 服务没启动、端口写错 | 服务器上执行systemctl status sshd |
| 认证失败 | 密码错误、账号无权限、私钥格式不对 | 先在终端手动 ssh 一次排除账号问题 |
| 连接被重置 | IP 被限制、安全组未放行 | 检查云厂商安全组规则和防火墙策略 |
连接问题有个通用的调试思路：不管代码怎么写的，先保证你在本机的终端工具里能手动 SSH 连接成功。如果命令行都连不上，那一定是网络或服务端配置问题，跟代码无关。我遇到过好几次同事拿着报错信息来找我，最后发现是服务器防火墙只放行了办公网 IP，而程序部署的机器不在白名单里。
私钥认证还有一个常见的坑：OpenSSH 生成的私钥在某些环境里格式不兼容。如果你把id_rsa直接丢给PrivateKeyFile用不了，可以先用工具转换成 PEM 格式，或者确认服务器端是否支持当前密钥算法。我在 .NET 6 环境里用默认生成的 RSA 私钥是没问题的，但如果服务器升级了 SSH 版本禁用 RSA，就得改用 ECDSA 或 Ed25519 密钥。
5.2 文件操作类问题
| 问题 | 可能原因 | 解决办法 |
|---|---|---|
| SftpPathNotFoundException | 远程目录不存在 | 上传前调用EnsureRemoteDirectoryExists |
| Permission denied | 账号对目标目录没有写权限 | 改用有权限的账号，或者调整目录属主 |
| 中文文件名乱码 | 服务器编码与客户端不一致 | 设置connectionInfo.Encoding = Encoding.UTF8 |
| 上传后文件大小为 0 | 文件流位置在末尾未重置 | 检查MemoryStream.Position，上传前重置为 0 |
| 多线程共用连接 | 一个 SftpClient 同时执行多个操作 | 每个线程创建独立连接，或使用连接池 |
中文文件名乱码这个事我要多说一句。Renci.SshNet 默认使用的编码可能跟服务器不一致，如果你发现上传后远程文件名变成了乱码，试着在创建ConnectionInfo时指定 UTF-8：
var connectionInfo = new ConnectionInfo(host, port, username, new PasswordAuthenticationMethod(username, password)) { Encoding = Encoding.UTF8 };大多数现代 Linux 系统都使用 UTF-8，这个设置基本能解决乱码问题。但我遇到过一个老系统，服务器 locale 是C，这时候无论怎么设编码都白搭，最终只能把文件名改成纯英文拼音的方案。所以生产环境的文件名，能不用中文就尽量不用，这是省心的前提。
5.3 连接泄漏：一个必须重视的点
关于连接泄漏，我需要单独强调。很多人在业务代码里 new 了一个SftpClient，用完忘记Disconnect()，也忘了Dispose()。SshNet 的连接对象在内部有网络连接和线程资源，不释放的话会一直占着。长期跑下来的表现就是：程序内存不大，但句柄数量持续上涨，最终服务器连接数被打满，表现为“系统用一段时间之后就传不了文件”。
正确的用法是用using块：
using (var client = new SftpClient(host, port, username, password)) { client.Connect(); // 执行文件操作 }Dispose方法内部会判断当前是否处于已连接状态，并自动断开底层连接。如果你手动写了Connect，建议也写对应的Disconnect，放在finally或者让using统一处理。
如果你在 ASP.NET Core 里用依赖注入注册了SftpClient，要特别注意生命周期。SftpClient是有状态的，且不是线程安全的，不要注册成Singleton然后到处用同一个实例。多个请求同时上传文件时会互相干扰，轻则报错，重则连接错乱。我的做法是每个调用场景单独创建连接，用完即释放，配合连接参数里的Timeout控制等待时间。虽然频繁建连有一点性能开销，但换来的隔离性和稳定性，在绝大多数场景里是值得的。
6. 生产环境经验：重试、日志与更稳的封装思路
6.1 给上传动作加重试机制
任何涉及网络的操作都不能假设一次成功。文件上传也一样，服务器偶尔重启、网络偶尔抖动、连接池偶尔超时，这些都是正常的。一个不带重试的上传模块，上线之后一定会被半夜的告警叫醒。
重试建议用指数退避策略，不要固定延时。伪代码如下：
int maxRetryCount = 3; int baseDelaySeconds = 2; for (int attempt = 1; attempt <= maxRetryCount; attempt++) { try { UploadCore(); break; } catch (Exception ex) when (attempt < maxRetryCount) { Log.Warning($"上传失败，第 {attempt} 次重试，原因：{ex.Message}"); int delaySeconds = baseDelaySeconds * (int)Math.Pow(2, attempt - 1); Thread.Sleep(delaySeconds * 1000); } }注意重试逻辑只放在连接和传输相关操作的上层，不要放在目录检查那一步内部，否则一个目录权限问题也会触发无意义的重试。另外，如果你的业务本来就在后台任务里跑，建议在重试失败之后把任务记录下来，等下次调度再处理，而不是无限循环阻塞线程。
6.2 日志要记哪些信息
日志是排查问题的眼睛，很多人上线之后才发现日志里只有一个“上传失败”，这种信息等于没记。一个合格的 SFTP 上传日志，至少应该包含以下信息：
- 目标服务器 host 和端口
- 本地文件路径和大小
- 远程目录和文件名
- 上传开始时间和结束时间
- 耗时
- 异常类型和完整堆栈
这样当系统出问题时，你打开日志能直接定位到“哪台服务器、哪个文件、什么时候、发生了什么”。我习惯在日志里把密码排除掉，其它连接参数都可以打。尤其要记录远程目录路径，这能帮你快速判断是不是目录不存在或权限不足导致的问题。
一个小心得：在上传成功之后，把远程文件大小和本地文件大小也打进日志里。排查“传上去的文件是不是坏的”时，这两条信息能省下你重新连接服务器确认的时间。
6.3 模块化封装：把上传变成一个可替换的服务
代码写到一定规模后，我建议把 SFTP 上传抽象成一个接口，比如定义IFileTransferService，里面只暴露UploadAsync(string localPath, string remoteDirectory, string remoteFileName)这样的方法。实现类内部封装 SftpClient 的连接管理和目录检查。
为什么这样做？因为文件传输需求本质上随时可能变化。今天用 SFTP，明天可能因为安全要求切换到别的协议，或者同一个文件需要同时分发到多个服务器。接口隔离之后，业务层只依赖抽象，后续更换协议时不需要改调用的地方。这个设计我在几个项目里都验证过，改动成本比直接散落写一坨using var client = new SftpClient小得多。
另外，如果你的系统本身就在容器里运行，建议把服务器的 host、端口、账号这些参数放到配置中心或环境变量里，不要硬编码进代码。容器环境里镜像是一份，不同环境的 IP 和账号是不同的，硬编码会导致你部署到别的环境就得改代码重新发版，非常痛苦。
6.4 关于连接复用与调用频率的取舍
有些场景上传频率特别高，比如每分钟都往服务器传一个状态文件，每次都新建连接会显得有些浪费。这种情况下，可以考虑用一个简单的连接池思路：在后台任务里保持一个长期存活的上传器，任务开始时连接，任务结束时不断连，让连接留在手上复用。
这里要平衡好两个问题：一是连接可能因为长时间空闲被服务器踢掉，需要在下次使用时重新 Connect；二是如果多线程并发上传，必须为每个线程准备独立的连接，不能用一把锁串行阻塞所有上传。我的建议是：对大多数后台管理系统来说，不需要过度优化连接复用的性能，保持“按操作创建、用后释放”即可。如果你真的在高频上传场景，优先考虑消息队列把文件传给专用上传服务，而不是在一个服务里堆并发连接。
我个人在实际开发中的体会是，文件上传这类功能，90% 的坑都发生在“你以为通了，其实服务端环境变了一点”这类情况里。把目录检查、大小校验、重试和日志这些基础功打扎实，这个模块在生产环境下会安稳运行很久。最后再分享一个小技巧：正式上线后第一周，每天看一眼上传日志里的成功记录和耗时，如果发现耗时从最初的几秒逐渐变成几十秒，通常意味着服务器或网络链路开始出现瓶颈，这时候再去排查，千万不要等到用户投诉再动手。
