termscp

termscp 是一款功能丰富、带有 TUI（终端用户界面）的终端文件传输客户端与浏览器。它让你能够连接到远程服务器以上传和下载文件，同时还能与本地文件系统进行交互。termscp 可运行于 Linux、macOS、FreeBSD、NetBSD 和 Windows。

功能特性

• 支持多种传输协议：SFTP、SCP、FTP 和 FTPS、Kube、S3、SMB 以及 WebDAV。
• 双面板浏览器，可同时浏览并操作远程和本地文件系统：创建、删除、重命名、搜索、查看和编辑文件。
• 书签和最近连接记录，帮助你快速重新连接到常用的主机。
• 使用你喜爱的编辑器查看和编辑文件。
• SFTP/SCP 认证支持 SSH 密钥或用户名与密码。
• 内置终端，可在你的系统上运行命令。
• 个性化定制：主题、自定义文件浏览器格式、可自定义的文本编辑器，以及可自定义的文件排序。
• 当大文件传输完成时弹出桌面通知。
• 文件监视器，使你的更改与远程主机保持同步。
• 将密码保存在操作系统的密钥保险库中。
• 基于 Rust 构建，注重性能。

准备好试用了吗？请参阅安装。

安装

termscp 可在多种平台上使用。请在下方选择与你的系统相匹配的安装方式。

Linux、FreeBSD 与 macOS

下面的 shell 脚本只需一条命令即可在你的系统上安装 termscp：

curl --proto '=https' --tlsv1.2 -sSLf https://termscp.rs/install.sh | sh

在 macOS 上，安装需要 Homebrew；否则将安装 Rust 编译器以从源码构建 termscp。

Windows

只需一条命令即可在 PowerShell 中安装 termscp：

irm https://termscp.rs/install.ps1 | iex

或者，使用 Chocolatey 安装：

choco install termscp

NetBSD

从官方仓库安装 termscp：

pkgin install termscp

Arch Linux

从官方仓库安装 termscp：

pacman -S termscp

系统要求

运行 termscp 需要以下系统依赖。

• Linux 用户：
  • libdbus-1
  • pkg-config
  • libsmbclient
• FreeBSD 和 NetBSD 用户：
  • dbus
  • pkgconf
  • libsmbclient

可选依赖

运行 termscp 并不需要这些依赖，但要使用其全部功能则需要它们。

• Linux 和 FreeBSD 用户，若要通过 V 打开文件（以下至少需要一项）：
  • xdg-open
  • gio
  • gnome-open
  • kde-open
• Linux 用户：一个密钥环管理器。请在密码安全页面了解更多。
• WSL 用户，若要通过 V 打开文件：
  • wslu

更新 termscp

要将 termscp 更新到最新版本，请在命令行中运行：

(sudo) termscp update

有关所有平台和安装方式，请参阅 https://termscp.rs/install。

连接到服务器

termscp 可以根据你传入的参数以三种不同的方式启动。

• 不带参数：termscp 打开认证表单，你在其中提供连接到远程主机所需的参数。
• 带地址参数：termscp 跳过认证表单，直接连接到远程主机。
• 通过 -b <bookmark-name> 传入书签名称：termscp 将参数解析为已保存的书签并进行连接。重复使用 -b 可打开多个书签。

当你提供地址参数或书签名称时，还可以为本地主机提供一个起始工作目录。

认证表单

当 termscp 在不带地址的情况下启动时，会显示认证表单。填写协议、地址、端口、用户名和密码，然后进行连接。连接成功后，termscp 将打开双面板浏览器。

地址参数语法

通用地址参数采用以下语法：

[protocol://][username@]<address>[:port][:wrkdir]

这种语法很方便，你很可能会用它来代替交互式表单。下面是一些示例。

使用默认协议（在你的配置中定义）连接到 192.168.1.31。如果未提供端口，则使用所选协议的默认端口。用户名为当前用户的名称。

termscp 192.168.1.31

使用默认协议连接到 192.168.1.31，用户名为 root：

termscp root@192.168.1.31

使用 SCP 连接到 192.168.1.31，端口为 4022，用户名为 omar：

termscp scp://omar@192.168.1.31:4022

使用 SCP 连接到 192.168.1.31，端口为 4022，用户名为 omar，并以目录 /tmp 作为起始目录：

termscp scp://omar@192.168.1.31:4022:/tmp

有关各协议专属的地址语法（S3、Kube、WebDAV 和 SMB），请参阅连接参数。

密码的提供方式

当你以参数形式提供地址时，地址本身没有用于填写密码的字段。你可以通过三种方式提供密码：

• 系统会提示你输入密码。这是默认方式：如果你不使用下面的任何方法，termscp 会像 scp、ssh 等经典工具一样提示你输入密码。

• -P, --password 选项：直接在命令行上传入密码。不推荐这种方法，因为它不安全：密码可能会保留在你的 shell 历史记录中。

• 通过 sshpass：借助 sshpass 提供密码，例如：

  sshpass -f ~/.ssh/topsecret.key termscp cvisintin@192.168.1.31
  

连接参数

每种协议都有其各自的认证表单字段以及各自的命令行地址语法。本页将逐个协议加以说明。

SFTP / SCP

认证表单字段：

• 主机（地址）
• 端口（默认 22）
• 用户名
• 密码或 SSH 密钥

你可以使用用户名和密码进行认证，也可以使用 SSH 密钥进行认证。有关如何管理密钥，请参阅 SSH 密钥存储。

地址语法：

[protocol://][username@]<address>[:port][:wrkdir]

FTP / FTPS

认证表单字段：

• 主机（地址）
• 端口（默认 21）
• 用户名
• 密码
• 安全（FTPS）：启用 TLS 以使用 FTPS 而非明文 FTP

地址语法：

[protocol://][username@]<address>[:port][:wrkdir]

Kube

认证表单字段：

• 命名空间
• 集群 URL（Kubernetes API URL）
• 用户名
• 客户端证书路径
• 客户端密钥路径

地址语法：

kube://[namespace][@<cluster_url>][$</path>]

S3

termscp 同时支持 AWS S3 和其他兼容 S3 的端点。

认证表单字段：

• 存储桶名称
• 区域（用于 AWS S3）或端点（用于其他兼容 S3 的服务器）
• 配置文件
• 访问密钥
• 私有访问密钥
• 安全令牌
• 会话令牌
• 新路径风格

所需字段和可选字段会因端点不同而有所差异：

• AWS S3：
  • 存储桶名称（必填）
  • 区域（必填）
  • 配置文件（可选；默认为 default）
  • 访问密钥（除非存储桶为公开，否则必填）
  • 私有访问密钥（除非存储桶为公开，否则必填）
  • 安全令牌（如有需要）
  • 会话令牌（如有需要）
  • 新路径风格：否
• 其他 S3 端点：
  • 存储桶名称（必填）
  • 端点（必填）
  • 访问密钥（除非存储桶为公开，否则必填）
  • 私有访问密钥（除非存储桶为公开，否则必填）
  • 新路径风格：是

地址语法：

s3://<bucket>@<region>[:profile][:/wrkdir]

例如：

s3://buckethead@eu-central-1:default:/assets

S3 凭证

要连接到 AWS S3 存储桶，你必须提供凭据。有三种方式可以做到这一点。

1. 认证表单：提供访问密钥（通常必填）、私有访问密钥（通常必填）、安全令牌和会话令牌。如果你将该 S3 连接保存为书签，访问密钥和私有访问密钥将以加密的 AES-256/BASE64 字符串形式保存在你的书签文件中。安全令牌和会话令牌不会被保存，因为它们本身就是临时凭据。

2. 凭据文件：使用 aws configure 配置 AWS CLI。随后你的凭据将被存储在 ~/.aws/credentials。如果你使用的是 default 以外的配置文件，请在认证表单的配置文件字段中提供它。

3. 环境变量：以环境变量的形式提供你的凭据。这些变量始终会覆盖凭据文件中的凭据。以下变量通常是必需的：

   • AWS_ACCESS_KEY_ID：AWS 访问密钥 ID（通常以 AKIA... 开头）
   • AWS_SECRET_ACCESS_KEY：私有访问密钥

   如果你配置了更强的安全机制，可能还需要：

   • AWS_SECURITY_TOKEN：安全令牌
   • AWS_SESSION_TOKEN：会话令牌

你的凭据是安全的：termscp 不会直接操作这些值。它们由 s3 crate 直接使用。

SMB

认证表单字段：

• 服务器（地址）
• 共享
• 用户名
• 密码
• 端口（仅其他系统；默认 445）
• 工作组（仅其他系统）

在 Windows 上，端口和工作组字段不会被使用。

Windows 地址语法：

\\[username@]<server-name>\<share>[\path\...]

其他系统地址语法：

smb://[username@]<server-name>[:port]/<share>[/path/.../]

WebDAV

认证表单字段：

• URI（WebDAV 的基础端点）
• 用户名
• 密码

地址语法：

http(s)://<username>:<password>@<url></path>

文件浏览器

当你与远程主机建立连接后，termscp 会显示文件浏览器。浏览器由三个面板组成。

• 本地浏览器面板：显示在屏幕左侧。它展示本地主机上当前目录中的条目。
• 远程浏览器面板：显示在屏幕右侧。它展示远程主机上当前目录中的条目。
• 查找结果面板：在你搜索文件后显示。根据你搜索的位置（本地或远程），它会替换本地浏览器面板或远程浏览器面板，并列出与你的搜索条件匹配的条目。

在面板之间切换

使用以下按键在面板之间移动。

• <LEFT>：移动到本地浏览器面板。
• <RIGHT>：移动到远程浏览器面板。
• <TAB>：切换当前活动的浏览器选项卡。
• <ESC>：在查找结果面板中时，退出该面板并返回上一个面板。

如需查看浏览器中可用按键的完整列表，请参阅键盘快捷键。

键盘快捷键

以下按键可在文件浏览器中使用。随时按 <H|F1> 可打开应用内帮助。

批量操作文件

termscp 允许你一次对多个文件执行操作。使用以下控制方式来构建选择。

• <M>：将高亮的文件标记为已选择。
• <CTRL+A>：选择当前目录中的所有文件。
• <ALT+A>：取消选择所有文件。

一旦某个文件被标记为已选择，它会以高亮背景显示。

当存在选择时，只有被选中的文件会被纳入操作处理；当前高亮的条目会被忽略。你也可以在查找结果面板中对多个文件进行操作。

对选择执行的操作

所有操作在处理多个文件时都可用，但其中一些行为略有不同。当存在选择时，你输入的名称指的是目标目录，而不是单个目标文件。

• 复制：系统会提示你输入目标位置。当选中多个文件时，该名称是所有文件被复制到的目标目录。
• 重命名：与复制相同，但文件会被移动到目标目录。
• 另存为：与复制相同，但文件会被写入目标目录。

传输队列

如果你在某个目录（例如 /home）中选择了一个文件，然后切换目录，该文件仍会保持被选中状态，并显示在底部面板的传输队列中。

当某个文件被选中时，当时活动的远程目录会与其条目相关联。如果该文件随后被传输，它会被传输到与之关联的远程目录。

示例

假设你在远程面板位于 /tmp 时选择了本地文件 /home/a.txt，然后移动到 /var，在远程面板位于 /home 时选择了 /var/b.txt，最后执行传输。结果是：

• /home/a.txt 被传输到 /tmp/a.txt
• /var/b.txt 被传输到 /home/b.txt

同步浏览

同步浏览会让两个浏览器面板之间的导航保持同步。启用后，每当你在一个面板中更改工作目录时，相同的更改会在另一个面板中重现。

要启用同步浏览，请按 <Y>。再次按 <Y> 即可禁用。启用后，状态栏会将同步浏览状态显示为 ON。

打开与编辑文件

termscp 可以使用外部应用程序打开文件，并在你配置的编辑器中编辑文本文件。本地和远程文件均受支持。

打开与使用指定程序打开

按 <V> 可使用系统针对该文件类型的默认应用程序打开文件。termscp 依赖于你操作系统的默认打开程序（由 open crate 提供支持），因此请确保你的系统上至少具备以下之一。

• Windows：通过 start 命令自动处理。
• macOS：通过 open 自动处理，该命令已预装。
• Linux：必须安装 xdg-open、gio、gnome-open 或 kde-open 之一。
• WSL：需要 wslview。请安装 wslu。

按 <W> 可使用你指定的程序打开文件。

编辑文本文件

按 <O> 可在你配置的文本编辑器中打开文件。仅支持文本文件，不支持二进制文件。

如果文件位于远程主机上，它会先被下载到你的临时文件目录，然后仅在你对其进行了更改时才会重新上传到远程主机。termscp 通过检查文件的最后修改时间来检测更改。

编辑远程文件

你无法直接从远程面板就地编辑远程文件。当你打开远程文件时，它会被下载到临时目录，但 termscp 无法创建监视器来检测你用于打开它的外部程序何时关闭，因此无法判断你何时完成编辑。要编辑远程文件，请先将其下载到本地目录，在本地编辑后再重新上传。

书签与最近主机

termscp 允许你将常用的主机保存为书签，随后可从主界面快速加载它们。termscp 还会保留你最近连接过的 16 个主机。这两项功能都让你只需在认证表单下方的选项卡中选择一个条目，即可重新加载连接到某个远程所需的全部参数。

书签的存储位置

书签会在可能的情况下保存在配置目录中：

• Linux/BSD 上为 $HOME/.config/termscp/
• macOS 上为 $HOME/.config/termscp/
• Windows 上为 %USERPROFILE%\.termscp\

保存密码

仅对于书签，你可以选择性地保存用于认证的密码。这不适用于最近主机，它们从不保存密码。默认情况下不保存密码；在你创建新书签时，系统会提示你选择是否保存。

如果你担心为书签保存的密码的安全性，请参阅我的密码安全吗？

创建书签

1. 在认证表单中填写连接到远程服务器的参数。
2. 按 <CTRL+S>。
3. 输入你想为书签指定的名称。
4. 选择是否记住密码。
5. 按 <ENTER> 提交。

加载书签

要使用先前保存的连接，请按 <TAB> 导航到书签列表，然后按 <ENTER> 将书签参数加载到表单中。

保持文件同步

文件监视器会将本地路径同步到远程路径。当在被监视的本地路径上检测到更改时，该更改会在大约 5 秒内传播到配置的远程路径。

你可以监视任意数量的路径。

监视路径

1. 将光标置于本地浏览器上你想保持同步的文件或目录上。
2. 在远程面板中，导航到应报告更改的目录。
3. 按 <T>。
4. 在弹窗中回答 <YES>。

取消监视路径

你可以通过两种方式停止监视某个路径：

• 在被监视的本地路径（或其任意子文件夹）上按 <T>。
• 按 <CTRL+T>，然后在你想取消监视的路径上按 <ENTER>。

传播的更改

以下更改会被报告到远程主机：

• 新建文件和文件更改
• 文件被移动或重命名
• 文件被删除或取消链接

监视器仅在单一方向上工作（从本地到远程）。在远程主机上所做的更改不会被同步回本地主机。

配置

termscp 支持大量用户自定义参数。termscp 将这些参数存储在一个 TOML 文件和若干目录中，但你无需手动编辑这些文件：所有配置都完全在用户界面中完成。

要进入配置界面，请在 termscp 主页按下 <CTRL+C>。

termscp 要求以下路径可访问：

• Linux/BSD 上的 $HOME/.config/termscp/
• macOS 上的 $HOME/.config/termscp/
• Windows 上的 %USERPROFILE%\.termscp\

参数

可以配置以下参数：

• 文本编辑器：要使用的文本编辑器。默认情况下，termscp 会为你查找默认编辑器；通过此选项你可以强制使用某个编辑器（例如 vim）。也支持 GUI 编辑器，除非它们会从父进程中分离（nohup）。
• 默认协议：termscp 中使用的文件传输协议的默认值。它适用于登录页面以及地址命令行参数。
• 显示隐藏文件：是否默认显示隐藏文件。你也可以在运行时按 A 切换隐藏文件的显示。
• 检查更新：如果设置为 yes，termscp 会查询 GitHub API 以检查是否有新版本的 termscp 可用。
• 替换已有文件时提示：如果设置为 yes，每当文件传输会替换目标主机上已有的文件时，termscp 都会请求确认。
• 目录分组：文件浏览器中是否将目录分组。如果选择 Display first，目录会按配置的方法排序，但显示在文件之前；如果选择 Display last，则显示在文件之后。
• 远程文件格式化语法：用于在远程浏览器中显示每个文件信息的语法。参见 文件浏览器格式。
• 本地文件格式化语法：用于在本地浏览器中显示每个文件信息的语法。参见 文件浏览器格式。
• 启用通知：如果设置为 Yes，则会显示桌面通知。参见 通知。
• 通知：最小传输大小：如果传输大小大于或等于指定值，则显示传输通知。可接受的格式为 {UNSIGNED} B/KB/MB/GB/TB/PB。
• SSH 配置路径：连接到 SCP/SFTP 服务器时使用的 SSH 配置文件。如果留空，则不使用任何文件。你可以指定以 ~ 开头的路径来表示主目录（例如 ~/.ssh/config）。termscp 支持的属性列于 ssh2-config 公开的属性。另请参见 SSH 密钥存储。

文件浏览器格式

你可以通过配置为文件浏览器定义自定义格式。本地主机和远程主机都支持此功能，因此你可以使用两种不同的语法。这两个字段分别名为 文件格式化语法（本地） 和 文件格式化语法（远程），它们定义了文件条目在文件浏览器中的显示方式。

语法

格式化器的语法如下：

{KEY1}... {KEY2:LENGTH}... {KEY3:LENGTH:EXTRA} {KEYn}...

花括号中的每个键都会被替换为相关的属性，而花括号之外的所有内容则保持不变。

• 键名是必填的，且必须是下列键之一。
• LENGTH 描述了用于显示该字段所保留的宽度。静态属性不支持它（GROUP、PEX、SIZE、USER）。
• EXTRA 仅由部分键支持，并提供一个附加选项。请查看下面的键以确认是否支持 EXTRA。

键

以下是格式化器支持的键：

默认格式

如果留空，则使用默认的格式化语法：

{NAME:24} {PEX} {USER} {SIZE} {MTIME:17:%b %d %Y %H:%M}

SSH 密钥存储

除了配置之外，termscp 还为 SFTP/SCP 客户端提供了一项重要功能：SSH 密钥存储。

要访问 SSH 密钥存储，请进入配置界面并切换到 SSH Keys 选项卡。

管理密钥

在 SSH Keys 选项卡中你可以：

• 添加新密钥：按 <CTRL+N>。系统会提示你提供与该密钥关联的主机名/IP 地址和用户名，然后会打开一个文本编辑器：将 私有 SSH 密钥粘贴到编辑器中，保存并退出。
• 删除现有密钥：在要删除的密钥上按 <DEL> 或 <CTRL+E>，即可将其从 termscp 中永久删除。
• 编辑现有密钥：在要编辑的密钥上按 <ENTER>，即可更改私有密钥。

受密码保护的密钥

支持受密码保护的私有密钥。你在 termscp 中提供的用于身份验证的密码，对用户名/密码认证和密钥认证都有效。

主题

termscp 允许你为应用程序中的多个组件设置颜色。有两种方式可以自定义 termscp：

• 通过 配置菜单
• 导入 主题文件

通过配置菜单自定义

要通过配置菜单自定义 termscp，请在认证界面按 <CTRL+C> 进入配置，然后按两次 <TAB> 到达 themes 面板。使用 <UP> 和 <DOWN> 移动以选择你想更改的样式，如下面的 gif 所示：

导入主题文件

你也可以导入主题文件。你可以从仓库 themes/ 目录中随 termscp 附带的某个主题获取灵感，或直接使用它。通过运行以下命令导入主题：

termscp theme <theme_file>

如果一切正常，termscp 会确认主题已导入。

颜色语法

termscp 接受以下颜色格式：

• 显式十六进制：#rrggbb
• RGB：rgb(r, g, b)
• CSS 颜色名称（例如 crimson）
• 特殊关键字 Default，它使用与情境相关的默认前景色或背景色（文本和线条使用前景色，其余使用背景色）

从无法加载的主题中恢复

更新后，已保存的主题可能无法加载。这发生在向主题添加新键时：之前保存的主题不再包含该键。有两种快速修复方法：

1. 重新导入官方主题。每次发布后，官方主题都会被修补，因此从仓库下载更新后的主题并重新导入：

   termscp theme <theme.toml>
   

2. 手动编辑你的主题。如果你使用自定义主题，请编辑该文件并添加缺失的键。主题位于 $CONFIG_DIR/theme.toml，其中 $CONFIG_DIR 为：

   • FreeBSD/Linux：$HOME/.config/termscp
   • macOS：$HOME/.config/termscp
   • Windows：%USERPROFILE%\.termscp

   缺失的键会在你刚安装的版本的 CHANGELOG 中 BREAKING CHANGES 部分列出。

样式

下面的表格描述了每个样式字段。请注意，样式 不 适用于配置页面，因此即使你不小心更改了某些内容，配置页面也始终保持可用。

认证页面

传输页面

杂项

这些样式适用于应用程序的不同部分。

通知

termscp 会针对以下事件发送桌面通知：

• 传输完成：在传输成功完成后发送。仅当总传输大小至少达到所配置的 Notifications: minimum transfer size 时才会显示。
• 传输失败：在传输因错误而失败后发送。仅当总传输大小至少达到所配置的 Notifications: minimum transfer size 时才会显示。
• 有可用更新：每当有新版本的 termscp 可用时发送。
• 更新已安装：每当新版本的 termscp 安装完成时发送。
• 更新失败：每当更新安装失败时发送。

禁用通知

要关闭通知，请进入设置并将 Enable notifications? 设置为 No。

更改最小传输大小

要更改用于控制传输通知的阈值，请进入设置并将 Notifications: minimum transfer size 设置为适合你的值。

日志

termscp 会为每个会话写入一个日志文件，位于：

• Linux/BSD 上的 $HOME/.cache/termscp/termscp.log
• macOS 上的 $HOME/Library/Caches/termscp/termscp.log
• Windows 上的 FOLDERID_LocalAppData\termscp\termscp.log

日志不会轮转：每次启动 termscp 时都会被截断。如果你想报告问题并附上日志文件，请在再次启动 termscp 之前将日志保存到安全的位置。

默认情况下，日志以 INFO 级别记录，因此不是很详细。

以 TRACE 级别复现问题

要提交问题，请通过使用 -D 命令行选项启动 termscp，将日志级别设置为 TRACE 来复现问题。

禁用日志

要关闭日志，请使用 -q 或 --quiet 选项启动 termscp。你可以为 termscp 设置别名，使其永久生效。

安全性

日志文件不包含任何明文密码。它暴露的信息与同级的 bookmarks 文件相同。

密码安全

书签连同其密码一起保存在你的配置目录中。密码不会以明文存储：它们使用 AES 加密。

用于加密密码的密钥会尽可能存储在操作系统的密钥存储中：

• Windows 上的 Windows Vault
• Linux 上的系统密钥环
• macOS 上的 Keychain

这由你的操作系统直接管理。

在 BSD 和 WSL 上没有这样的密钥存储，因此加密密钥会保存在磁盘上的 $HOME/.config/termscp。该位置通过文件权限保护密钥，使其无法被其他用户读取，但你仍应避免在这些系统上为暴露于互联网上的服务器保存密码。

Linux 密钥环

在 Linux 上，你的系统中可能没有安装密钥环。密钥存储需要一个在 D-Bus 上暴露 org.freedesktop.secrets 的服务，而只有少数服务提供它：

• 如果你使用 GNOME 作为桌面环境（例如 Ubuntu 用户），密钥环已经由 gnome-keyring 提供，一切应该开箱即用。
• 对于其他桌面环境，你可以使用 KeepassXC 来获取一个密钥环。它必须经过设置才能与 termscp 配合使用；参见下面的 KeepassXC 设置。
• 如果你不想安装这些服务中的任何一个，termscp 会照常工作，并回退到将密钥保存在文件中，正如它在 BSD 和 WSL 上所做的那样。

KeepassXC 设置

按照以下步骤为 termscp 设置 KeepassXC：

1. 安装 KeepassXC。
2. 在工具栏中进入 “Tools” > “Settings”。
3. 选择 “Secret service integration” 并启用 “Enable KeepassXC freedesktop.org secret service integration”。
4. 如果你还没有数据库，请创建一个：在工具栏中，“Database” > “New database”。
5. 在工具栏中，进入 “Database” > “Database settings”。
6. 选择 “Secret service integration” 并启用 “Expose entries under this group”。
7. 选择将保存 termscp 密钥的组。请注意，任何其他应用程序都可以读取通过 D-Bus 为该组暴露的密钥。

命令行用法

termscp 可以通过以下调用形式启动：

termscp [options]... [protocol://user@address:port:wrkdir] [protocol://user@address:port:wrkdir] [local-wrkdir]

或

termscp [options]... -b [bookmark-name] -b [bookmark-name] [local-wrkdir]

以及两者的任意组合。

如果未提供额外参数，termscp 会显示身份验证表单。如果提供了地址参数或书签名称，termscp 会跳过该表单并直接连接到远程服务器。当提供地址或书签时，你还可以将本地主机的起始工作目录作为最后一个位置参数提供。

选项

不推荐使用 -P 选项，因为密码可能会保留在 shell 历史记录中。请参阅书签和密码安全章节，了解更安全的凭据提供方式。

子命令

termscp 提供以下子命令。

导入主题

termscp theme <theme-file>

导入在 <theme-file> 中定义的主题。

安装最新版本

termscp update

下载并安装 termscp 的最新可用版本。

导入 ssh 主机

termscp import-ssh-hosts [ssh-config-file]

将指定 ssh 配置文件中的所有主机作为书签导入到 termscp 中。如果未提供 [ssh-config-file]，则使用默认位置 ~/.ssh/config。身份文件也会作为 ssh 密钥导入到 termscp 中。

打开配置

termscp config

直接在配置（setup）界面中启动 termscp。

开发者手册

欢迎阅读 termscp 的开发者手册。本章不包含 termscp 各模块的文档，相关文档可以在 Rust Docs 上找到：https://docs.rs/termscp。本章描述 termscp 的工作原理，以及实现诸如文件传输和用户界面扩展等功能的指南。

termscp 使用 Rust 编写（edition 2024，MSRV 1.89.0）。用户界面使用 tuirealm v3 构建，它运行在 crossterm 之上。

termscp 的工作原理

termscp 基本上由 3 个核心模块组成：

• host：host 模块提供与文件系统交互的函数。它暴露 HostBridge trait，该 trait 抽象了对本地主机（Localhost）和远程主机（RemoteBridged）的文件操作。
• ui：该模块包含用户界面的实现。如下一章所示，这是通过 activities 实现的。
• activity_manager：activity manager 负责管理 activities。它运行用户界面的 activities，并根据它们的状态决定何时终止当前 activity 以及接下来运行哪个 activity。

除了这 3 个核心模块之外，随着时间推移又添加了其他模块：

• config：提供配置 schema 及其序列化方法。
• explorer：暴露 explorer 结构，用于处理 ui 中的文件资源管理器。它们存储当前目录模型和视图状态（例如排序、是否显示隐藏文件、传输队列）。
• filetransfer：定义 FileTransferProtocol 枚举和 RemoteFsBuilder，后者根据连接参数构造合适的 RemoteFs 客户端。
• system：提供与配置、ssh 密钥存储和书签交互的方式。
• utils：包含几乎整个项目都会使用的工具。

termscp 支持以下协议：SFTP、SCP、FTP/FTPS、Kube、S3、SMB 和 WebDAV。

Activities

本段对 activities 做一个简短的概述。请阅读代码和文档，以清晰地了解 ui 的工作方式。

实现用户界面有很多方法。本项目借鉴了不同框架中各自最佳的部分：

• 顶层的 Activities：每个“视图”都是一个 Activity，并由 Activity Manager 来处理它们。这种方法受 Android 启发。它适用于具有不同视图的 ui，每个视图都有自己的组件和逻辑。Activities 与 Context 协作，Context 是用于在 activities 之间共享数据的数据持有者。
• Activities 显示 Applications：每个 activity 可以显示不同的 Applications。一个 application 包含一个 View，它基本上是一个 components 列表，每个组件都有其属性。view 是组件的门面，同时也处理焦点，即当前处于活动状态的组件。你不能拥有多个活动组件，因此必须对此进行处理；与此同时，如果当前组件被销毁，焦点必须交还给之前处于活动状态的组件。Application 负责处理所有这些工作。要了解更多信息，请阅读 https://github.com/veeso/tui-realm。
• Components：components 是围绕 tui 构建的，以便复用控件。这是通过 Component trait 实现的，该 trait 受 React 启发。每个组件都有其 Properties，并且可以拥有其 States。每个组件必须处理输入事件、接受新的属性，并提供一个用于渲染自身的方法。这一逻辑现在位于 tui-realm 中。
• Messages：基于 Elm 的方法：输入事件采用受 Elm 启发的方法来处理。在 Elm 中，你使用三个基本函数来实现 ui：update、view 和 init。termscp 将 Elm update 函数的等价实现编写为一个递归函数内部的大型 match 分支，你可以在每个 activity 的 update.rs 文件中找到它。这个 match 分支处理组件为响应传入的输入事件而产生的消息，并促使 activity 改变其状态。

termscp 实现了一个名为 Activity 的 trait，它是 Android activity 的一个大幅精简版本。该 trait 提供以下方法：

• on_create：初始化 activity。context 被传递给 activity，activity 成为 Context 的唯一所有者，直到该 activity 终止。
• on_draw：每当用户界面应当更新时被调用。它基本上就是 activity 的运行方法，同时也处理输入事件。界面不应在每次调用时都被绘制（该方法每秒可能被调用数百次），而只应在确实发生变化时（例如在某次输入事件之后）才绘制。
• will_umount：返回 activity 是否应当被销毁。如果是，它会返回一个 ExitReason，用于指示该 activity 应当终止的原因。activity manager 会根据该原因决定是停止 termscp 的执行，还是启动一个新的 activity 以及启动哪一个。
• on_destroy：终结 activity 并将其释放。该方法将 Context 返回给调用方（activity manager）。

Context

context 是一个保存 activities 之间共享数据的结构。每次某个 Activity 启动时，Context 都会被该 activity 取走，直到它被销毁时，context 才最终返回给 activity manager。context 保存以下数据：

• Localhost：本地主机结构。
• File Transfer Params：当前用于连接到远程主机的参数。
• Config Client：一个提供访问用户配置的函数的结构。
• Store：一个可以保存任意类型数据的键值存储。它可用于在 activities 之间共享状态，或为繁重或缓慢的任务（例如检查更新）保持持久化。
• Terminal：用于在终端上渲染 tui。

实现抽象的文件传输客户端

当 termscp 的实现于 2020 年 12 月开始时，文件传输处于设计的核心，因为它是 termscp 的核心所在。最初的实现由一个 filetransfer 模块组成，该模块暴露了一个名为 FileTransfer 的 trait，它提供了与远程文件系统进行通用交互的方法。

随着时间推移，由于不同用户都希望有一个专门的库，这种情况发生了变化。在 2021 年最后一个季度，remotefs 诞生了：一个用于操作远程设备文件系统的抽象库。remotefs 提供了一个 RemoteFs trait，它暴露了所有核心文件系统功能，并且自 0.8.0 版本起，它已经取代了 FileTransfer trait。

文件传输模块仍然存在，但它唯一的任务是通过 RemoteFsBuilder 根据文件传输参数构建一个 RemoteFs 客户端实现。