Linux sftp 命令:通过 SSH 上传、下载与批量传输文件

sftp 是一个通过 SSH(Secure Shell,安全外壳协议)连接传输文件和管理远程文件的程序。基本连接格式是 sftp user@host,并且可以使用 SSH 主机密钥验证和公钥认证。

示例中的 user、example.com、文件路径和 fileserver 都须替换为自己的已获授权环境;example.com 不是可直接登录的测试服务器。先准备好本地目录和远程文件,再逐条执行对应例子。

sftp user@example.com

SFTP(SSH File Transfer Protocol,SSH 文件传输协议)与文件传输协议 FTP、使用传输层安全协议 TLS 的 FTPS 是不同协议,不能仅按名称相近互换客户端。服务器必须启用 SSH 的 SFTP 子系统,通常使用与 SSH 相同的 TCP 端口。

SFTP 的功能及连接前检查

OpenSSH 的 sftp 可以通过加密的 SSH 连接执行文件传输,并且可以使用 SSH 功能,如公钥认证、SSH 配置文件和跳板主机。完整选项和交互命令可以在 OpenSSH sftp 官方手册 中查找。

  • 服务器地址和 SSH 端口
  • 登录用户账号
  • 密码或 SSH 私钥
  • 用于核对服务器主机密钥指纹的可信渠道
  • 远程目录的读写权限

首次连接时,请将显示的主机密钥指纹与从服务器管理员或可信管理界面获得的值进行比较。如果未经验证就批准,就可能连接到冒充的或错误的服务器。

如何连接到服务器

基本连接

sftp user@example.com

连接成功后会出现 sftp> 提示符。此时输入的是 SFTP 交互命令,不是终端 Shell 命令;下文下载、上传等代码省略提示符,只列命令本身。离开会话可输入 bye 或 exit。

使用不同的 SSH 端口

sftp -P 2222 user@example.com

SFTP 的端口选项是大写的 -P。小写的 -p 是一个不同的选项,用于请求保留修改时间、访问时间和文件权限,所以不要混淆它们。

指定私钥

sftp -i ~/.ssh/id_ed25519 user@example.com

限制私钥文件的权限,以便其他用户无法读取,并且如果可能的话,设置密钥口令(passphrase),再通过 SSH agent 管理已解锁的密钥。不要将私钥复制到服务器或共享目录。

区分本地和远程路径

SFTP 交互命令分别操作远程端和本地端。远程文件操作通过 SFTP 协议请求服务器完成,并不等于拥有服务器 Shell 执行权限。

命令 目标 描述
pwd 远程 显示远程服务器的当前目录。
lpwd 本地 显示运行 SFTP 的计算机的当前目录。
cd path 远程 更改远程目录。
lcd path 本地 更改本地目录。
ls 远程 显示远程文件列表。
lls 本地 显示本地文件列表。
mkdir 远程 创建远程目录。
lmkdir 本地 创建本地目录。

操作前先查看 pwd 与 lpwd,确认两个基准目录。受限账户看到的远程根目录可能是隔离后的虚拟根,不能直接套用服务器上的绝对路径。

下载文件

下载单个文件

假设远程当前目录下已有可读的 reports/daily.csv。不指定本地路径时,它会下载到 lpwd 所示目录,已有同名文件可能被覆盖。

get reports/daily.csv

可以将本地保存路径指定为第二个参数。

先在本地创建 download 目录,或在 SFTP 中运行 lmkdir download;不带 -p 的 lmkdir 不会递归创建缺失的父目录,get 也不会替你准备这段目录层级。

get reports/daily.csv ./download/daily.csv

下载多个文件和目录

get reports/*.csv
get -R reports

通配符可以匹配远程文件名。在递归下载目录时,SFTP 不会跟随树中的符号链接,并且具体支持情况以客户端版本和服务器能力为准。这里的 get -R 是交互命令的递归选项;启动程序时 sftp -R 数值 则设置并发请求数量,两者不能混用。

恢复中断的下载

reget archive.tar.zst

或者可以使用 get -a 恢复部分传输。这假设本地部分文件与远程文件的开头完全匹配,因此如果远程文件已更改,结果可能会损坏。续传不会自动验证文件前缀或修复已有的错误字节,重要文件传输后仍须比较校验和。

上传文件

上传单个文件

本地当前目录须有 release.tar.zst,远程须有写入权限。未指定远程目标时,文件保存到 pwd 所示目录,显式指定 uploads 路径时应先确认该远程目录存在。

put ./release.tar.zst

可以将远程保存路径或名称作为第二个参数指定。

put ./release.tar.zst uploads/release.tar.zst

递归上传目录

put -R ./assets uploads/assets

由于现有文件可能被覆盖,请先检查远程路径。多用户部署时,应采用每次任务独有的临时文件名,传完并验证后,再按服务器支持的规则发布到最终名称;固定临时名称也会发生竞争。

恢复中断的上传

reput ./large-image.img

put -a 也尝试恢复部分上传。如果远程的部分文件与本地文件的开头不匹配,可能会创建损坏的文件,因此续传前应确认来源未变,完成后再验证哈希值。

处理路径、空格和文件名

将包含空格的路径用引号括起来。

get "Monthly Reports/September Report.csv"
put "./Release Files/app package.tar.zst" uploads/

SFTP 的交互命令不是普通 Shell 语法。空格路径需加引号,文件名中作为字面值使用的通配符等 glob 特殊字符还需按客户端规则用反斜杠转义;加引号本身不一定取消通配匹配。操作前先用列表核对名称,自动化宜使用清晰、可预测的文件名。

使用 SSH 配置文件管理连接信息

用 Host 条目保存常用连接选项

在 ~/.ssh/config 中保存主机别名、用户、端口和身份文件路径后,可用别名连接。该文件由 SSH 客户端读取。

Host fileserver
    HostName sftp.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
sftp fileserver

配置文件写的是私钥路径,不是密码或私钥内容。限制文件权限;一般按命令行、用户配置、系统配置的顺序取值,多数参数使用首先获得的值,因此具体 Host 条目通常应放在通用 Host * 之前。IdentityFile 等可累加参数有例外,详见 ssh_config 官方手册。

通过跳板主机连接

sftp -J bastion.example.com user@internal.example.com

-J 使用 SSH 的 ProxyJump 功能,通过跳板建立到目标的转发连接。两台主机的密钥都要核验;ProxyJump 本身不要求开启 agent forwarding(代理转发)。跳板的用户、端口等参数可能需要独立的 Host 配置,目标配置不会自动全部套用到跳板。

使用批处理模式自动传输

创建批处理文件

例如,将以下 SFTP 命令保存到 upload.sftp 中。

先准备远程可写目录 incoming 和本地 ./exports/report.csv。lcd ./exports 相对于启动 sftp 时的本地工作目录;批处理中的路径不会自动相对于 upload.sftp 文件所在目录解析。任务前还须通过可信渠道完成目标主机密钥登记,并让所需密钥可非交互使用。

cd incoming
lcd ./exports
put report.csv report.tmp
rename report.tmp report.csv
bye

先上传临时文件再改名,可避免消费者把尚未传完的文件当成成品。此例使用固定的 report.tmp,适合串行演示;并发任务应采用独有名称。最终文件已经存在时,rename 可能失败或替换,取决于服务器实现与扩展;不能保证跨文件系统原子替换,也不能把改名等同于断电后一定持久保存。

运行批处理文件

sftp -b upload.sftp fileserver

批处理模式不应依赖用户交互输入密码。请使用受限的专用账户和公钥认证,并根据服务器策略限制密钥权限、访问来源和允许路径。不要在脚本或命令行中放置密码。

理解失败处理

在批处理模式下,如果诸如 get、put 或 rename 的关键命令失败,操作通常会停止。可以通过在命令前放置 - 来忽略失败,但应选择性使用,因为即使必要的文件缺失,也可能使操作看起来成功。

自动化应同时检查 SFTP 进程退出状态、目标文件大小,并在可行时核验校验和;预先制定失败通知和重试策略,避免重试时误覆盖已经发布的版本。

安全和操作检查清单

  • 主机密钥: 在首次连接和密钥更改时,通过可信渠道验证指纹。
  • 认证: 对于自动化,请使用通过服务器策略限制权限的密钥和专用账户,而不是密码。
  • 私钥: 最小化读取权限,不要上传到代码仓库、共享备份目录或服务器。
  • 路径权限:仅登录成功不代表只能访问指定目录。限制目录需要文件权限及服务器隔离策略;参见 sshd_config 的 ChrootDirectory、ForceCommand 与转发限制。
  • 覆盖: 检查目标路径和现有文件,并使用临时名称和版本保留策略。
  • 完整性: 对于重要传输,在双方生成并比较可信的校验和。
  • 日志: 应记录传输成功或失败及其目标,避免把密码、私钥或敏感文件内容写入日志。

SFTP、SCP、rsync 对比

工具 适用场景 功能
sftp 交互式文件管理与批量传输 提供远程列表、目录导航、续传和批量命令功能。
scp 简单文件复制 一条命令即可复制;当前 OpenSSH scp 默认使用 SFTP 协议,但不提供 sftp 那样的交互管理会话。
rsync 重复同步和大目录 提供增量传输、排除规则和删除同步,但也需要服务器端的支持环境。

仅使用 SSH 并不能自动保证账户权限和部署流程的安全。应根据传输目的和故障恢复方式进行选择。

常见问题解答

SFTP 是应用了 TLS 的 FTP 吗?

不是。SFTP 是 SSH 文件传输协议,通过 SSH 连接进行操作。FTPS 是另一种方法,将 TLS 应用于 FTP,具有不同的服务器设置和端口结构。

为什么出现 Connection refused?

地址或端口可能不正确、SSH 服务未监听,或者防火墙主动拒绝连接。请核对服务器地址、大写 -P 指定的端口、SSH 服务状态和网络策略。

出现 Permission denied 应如何排查?

需要区分是身份验证本身失败,还是登录后文件权限不足。使用 sftp -v 检查连接诊断信息,但不要在公共日志中分享用户名、路径和服务器详细信息。

如何核验上传已经完成?

检查退出状态和远程文件的大小,并计算和比较本地和远程系统上重要文件的校验和,例如 SHA-256(256 位安全散列算法)。如果 SFTP 服务器使用的受限账户不允许执行任意命令,则可能需要单独的校验接口(API)或服务器端处理程序。

总结

连接 sftp user@host 后,使用 get 进行下载,使用 put 进行上传。区分 pwd 和 lpwd,以及 cd 和 lcd,可以帮助减少远程和本地路径的错误。

在传输自动化中,关键点是公钥认证、主机密钥验证,以及检查批处理退出状态和文件完整性。不要在脚本中存储密码;使用专用账户和最小权限限制传输范围。