diff --git a/docs/zh-CN/configuration/configuration.md b/docs/zh-CN/configuration/configuration.md index fa1492d..b806757 100644 --- a/docs/zh-CN/configuration/configuration.md +++ b/docs/zh-CN/configuration/configuration.md @@ -1 +1,27 @@ # 配置 + +termscp 支持大量用户自定义参数。termscp 将这些参数存储在一个 TOML 文件和若干目录中，但你无需手动编辑这些文件：所有配置都完全在用户界面中完成。 + +要进入配置界面，请在 termscp 主页按下 ``。 + +termscp 要求以下路径可访问： + +- Linux/BSD 上的 `$HOME/.config/termscp/` +- macOS 上的 `$HOME/Library/Application Support/termscp` +- Windows 上的 `FOLDERID_RoamingAppData\termscp\` + +## 参数 + +可以配置以下参数： + +- **文本编辑器**：要使用的文本编辑器。默认情况下，termscp 会为你查找默认编辑器；通过此选项你可以强制使用某个编辑器（例如 `vim`）。也支持 GUI 编辑器，除非它们会从父进程中分离（`nohup`）。 +- **默认协议**：termscp 中使用的文件传输协议的默认值。它适用于登录页面以及地址命令行参数。 +- **显示隐藏文件**：是否默认显示隐藏文件。你也可以在运行时按 `A` 切换隐藏文件的显示。 +- **检查更新**：如果设置为 `yes`，termscp 会查询 GitHub API 以检查是否有新版本的 termscp 可用。 +- **替换已有文件时提示**：如果设置为 `yes`，每当文件传输会替换目标主机上已有的文件时，termscp 都会请求确认。 +- **目录分组**：文件浏览器中是否将目录分组。如果选择 `Display first`，目录会按配置的方法排序，但显示在文件之前；如果选择 `Display last`，则显示在文件之后。 +- **远程文件格式化语法**：用于在远程浏览器中显示每个文件信息的语法。参见 [文件浏览器格式](explorer-format.md)。 +- **本地文件格式化语法**：用于在本地浏览器中显示每个文件信息的语法。参见 [文件浏览器格式](explorer-format.md)。 +- **启用通知**：如果设置为 `Yes`，则会显示桌面通知。参见 [通知](notifications.md)。 +- **通知：最小传输大小**：如果传输大小大于或等于指定值，则显示传输通知。可接受的格式为 `{UNSIGNED} B/KB/MB/GB/TB/PB`。 +- **SSH 配置路径**：连接到 SCP/SFTP 服务器时使用的 SSH 配置文件。如果留空，则不使用任何文件。你可以指定以 `~` 开头的路径来表示主目录（例如 `~/.ssh/config`）。termscp 支持的属性列于 [ssh2-config 公开的属性](https://github.com/veeso/ssh2-config#exposed-attributes)。另请参见 [SSH 密钥存储](ssh-keys.md)。 diff --git a/docs/zh-CN/configuration/explorer-format.md b/docs/zh-CN/configuration/explorer-format.md index 96e8a04..a3ccc23 100644 --- a/docs/zh-CN/configuration/explorer-format.md +++ b/docs/zh-CN/configuration/explorer-format.md @@ -1 +1,42 @@ # 文件浏览器格式 + +你可以通过配置为文件浏览器定义自定义格式。本地主机和远程主机都支持此功能，因此你可以使用两种不同的语法。这两个字段分别名为 **文件格式化语法（本地）** 和 **文件格式化语法（远程）**，它们定义了文件条目在文件浏览器中的显示方式。 + +## 语法 + +格式化器的语法如下： + +```text +{KEY1}... {KEY2:LENGTH}... {KEY3:LENGTH:EXTRA} {KEYn}... +``` + +花括号中的每个键都会被替换为相关的属性，而花括号之外的所有内容则保持不变。 + +- 键名是必填的，且必须是下列键之一。 +- `LENGTH` 描述了用于显示该字段所保留的宽度。静态属性不支持它（`GROUP`、`PEX`、`SIZE`、`USER`）。 +- `EXTRA` 仅由部分键支持，并提供一个附加选项。请查看下面的键以确认是否支持 `EXTRA`。 + +## 键 + +以下是格式化器支持的键： + +| 键 | 说明 | +| --------- | ------------------------------------------------------------------------------------------------ | +| `ATIME` | 最后访问时间（默认 `%b %d %Y %H:%M`）；`EXTRA` 为时间格式（例如 `{ATIME:8:%H:%M}`） | +| `CTIME` | 创建时间（默认 `%b %d %Y %H:%M`）；`EXTRA` 为时间格式（例如 `{CTIME:8:%H:%M}`） | +| `GROUP` | 所属组 | +| `MTIME` | 最后修改时间（默认 `%b %d %Y %H:%M`）；`EXTRA` 为时间格式（例如 `{MTIME:8:%H:%M}`） | +| `NAME` | 文件名（如果根目录与首个祖先目录之间的文件夹长度超过 `LENGTH`，则会被省略） | +| `PATH` | 文件绝对路径（如果根目录与首个祖先目录之间的文件夹长度超过 `LENGTH`，则会被省略） | +| `PEX` | 文件权限（UNIX 格式） | +| `SIZE` | 文件大小（目录省略） | +| `SYMLINK` | 符号链接目标（如果有，`-> {FILE_PATH}`） | +| `USER` | 所属用户 | + +## 默认格式 + +如果留空，则使用默认的格式化语法： + +```text +{NAME:24} {PEX} {USER} {SIZE} {MTIME:17:%b %d %Y %H:%M} +``` diff --git a/docs/zh-CN/configuration/logging.md b/docs/zh-CN/configuration/logging.md index 65c2dbd..3dd3032 100644 --- a/docs/zh-CN/configuration/logging.md +++ b/docs/zh-CN/configuration/logging.md @@ -1 +1,23 @@ # 日志 + +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` 文件相同。 diff --git a/docs/zh-CN/configuration/notifications.md b/docs/zh-CN/configuration/notifications.md index e0eab74..b9cbb40 100644 --- a/docs/zh-CN/configuration/notifications.md +++ b/docs/zh-CN/configuration/notifications.md @@ -1 +1,17 @@ # 通知 + +termscp 会针对以下事件发送桌面通知： + +- **传输完成**：在传输成功完成后发送。仅当总传输大小至少达到所配置的 `Notifications: minimum transfer size` 时才会显示。 +- **传输失败**：在传输因错误而失败后发送。仅当总传输大小至少达到所配置的 `Notifications: minimum transfer size` 时才会显示。 +- **有可用更新**：每当有新版本的 termscp 可用时发送。 +- **更新已安装**：每当新版本的 termscp 安装完成时发送。 +- **更新失败**：每当更新安装失败时发送。 + +## 禁用通知 + +要关闭通知，请进入设置并将 `Enable notifications?` 设置为 `No`。 + +## 更改最小传输大小 + +要更改用于控制传输通知的阈值，请进入设置并将 `Notifications: minimum transfer size` 设置为适合你的值。 diff --git a/docs/zh-CN/configuration/password-security.md b/docs/zh-CN/configuration/password-security.md index 9a96820..5388ae3 100644 --- a/docs/zh-CN/configuration/password-security.md +++ b/docs/zh-CN/configuration/password-security.md @@ -1 +1,33 @@ # 密码安全 + +书签连同其密码一起保存在你的配置目录中。密码不会以明文存储：它们使用 AES 加密。 + +用于加密密码的密钥会尽可能存储在操作系统的密钥存储中： + +- Windows 上的 Windows Vault +- Linux 上的系统密钥环 +- macOS 上的 Keychain + +这由你的操作系统直接管理。 + +在 BSD 和 WSL 上没有这样的密钥存储，因此加密密钥会保存在磁盘上的 `$HOME/.config/termscp`。该位置通过文件权限保护密钥，使其无法被其他用户读取，但你仍应避免在这些系统上为暴露于互联网上的服务器保存密码。 + +## Linux 密钥环 + +在 Linux 上，你的系统中可能没有安装密钥环。密钥存储需要一个在 D-Bus 上暴露 `org.freedesktop.secrets` 的服务，而只有少数服务提供它： + +- 如果你使用 GNOME 作为桌面环境（例如 Ubuntu 用户），密钥环已经由 `gnome-keyring` 提供，一切应该开箱即用。 +- 对于其他桌面环境，你可以使用 [KeepassXC](https://keepassxc.org/) 来获取一个密钥环。它必须经过设置才能与 termscp 配合使用；参见下面的 [KeepassXC 设置](#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 为该组暴露的密钥。 diff --git a/docs/zh-CN/configuration/ssh-keys.md b/docs/zh-CN/configuration/ssh-keys.md index ed2ddda..10dc05e 100644 --- a/docs/zh-CN/configuration/ssh-keys.md +++ b/docs/zh-CN/configuration/ssh-keys.md @@ -1 +1,17 @@ # SSH 密钥存储 + +除了配置之外，termscp 还为 SFTP/SCP 客户端提供了一项重要功能：SSH 密钥存储。 + +要访问 SSH 密钥存储，请进入配置界面并切换到 `SSH Keys` 选项卡。 + +## 管理密钥 + +在 `SSH Keys` 选项卡中你可以： + +- **添加新密钥**：按 ``。系统会提示你提供与该密钥关联的主机名/IP 地址和用户名，然后会打开一个文本编辑器：将 **私有** SSH 密钥粘贴到编辑器中，保存并退出。 +- **删除现有密钥**：在要删除的密钥上按 `` 或 ``，即可将其从 termscp 中永久删除。 +- **编辑现有密钥**：在要编辑的密钥上按 ``，即可更改私有密钥。 + +## 受密码保护的密钥 + +支持受密码保护的私有密钥。你在 termscp 中提供的用于身份验证的密码，对用户名/密码认证和密钥认证都有效。 diff --git a/docs/zh-CN/configuration/themes.md b/docs/zh-CN/configuration/themes.md index 6beb38d..94a69d1 100644 --- a/docs/zh-CN/configuration/themes.md +++ b/docs/zh-CN/configuration/themes.md @@ -1 +1,97 @@ # 主题 + +termscp 允许你为应用程序中的多个组件设置颜色。有两种方式可以自定义 termscp： + +- 通过 **配置菜单** +- 导入 **主题文件** + +## 通过配置菜单自定义 + +要通过配置菜单自定义 termscp，请在认证界面按 `` 进入配置，然后按两次 `` 到达 `themes` 面板。使用 `` 和 `` 移动以选择你想更改的样式，如下面的 gif 所示： + +![Themes](https://github.com/veeso/termscp/blob/main/assets/images/themes.gif?raw=true) + +## 导入主题文件 + +你也可以导入主题文件。你可以从仓库 `themes/` 目录中随 termscp 附带的某个主题获取灵感，或直接使用它。通过运行以下命令导入主题： + +```sh +termscp theme +``` + +如果一切正常，termscp 会确认主题已导入。 + +## 颜色语法 + +termscp 接受以下颜色格式： + +- 显式十六进制：`#rrggbb` +- RGB：`rgb(r, g, b)` +- [CSS 颜色名称](https://www.w3schools.com/cssref/css_colors.asp)（例如 `crimson`） +- 特殊关键字 `Default`，它使用与情境相关的默认前景色或背景色（文本和线条使用前景色，其余使用背景色） + +## 从无法加载的主题中恢复 + +更新后，已保存的主题可能无法加载。这发生在向主题添加新键时：之前保存的主题不再包含该键。有两种快速修复方法： + +1. 重新导入官方主题。每次发布后，官方主题都会被修补，因此从仓库下载更新后的主题并重新导入： + + ```sh + termscp theme + ``` + +2. 手动编辑你的主题。如果你使用自定义主题，请编辑该文件并添加缺失的键。主题位于 `$CONFIG_DIR/termscp/theme.toml`，其中 `$CONFIG_DIR` 为： + + - FreeBSD/Linux：`$HOME/.config/` + - macOS：`$HOME/Library/Application Support` + - Windows：`%appdata%` + + 缺失的键会在你刚安装的版本的 CHANGELOG 中 `BREAKING CHANGES` 部分列出。 + +## 样式 + +下面的表格描述了每个样式字段。请注意，样式 **不** 适用于配置页面，因此即使你不小心更改了某些内容，配置页面也始终保持可用。 + +### 认证页面 + +| 键 | 说明 | +| ---------------- | -------------------------- | +| `auth_address` | IP 地址输入框的颜色 | +| `auth_bookmarks` | 书签面板的颜色 | +| `auth_password` | 密码输入框的颜色 | +| `auth_port` | 端口号输入框的颜色 | +| `auth_protocol` | 协议单选框组的颜色 | +| `auth_recents` | 最近记录面板的颜色 | +| `auth_username` | 用户名输入框的颜色 | + +### 传输页面 + +| 键 | 说明 | +| -------------------------------------- | -------------------------------------------------- | +| `transfer_local_explorer_background` | 本地主机浏览器的背景色 | +| `transfer_local_explorer_foreground` | 本地主机浏览器的前景色 | +| `transfer_local_explorer_highlighted` | 本地主机浏览器的边框及高亮颜色 | +| `transfer_remote_explorer_background` | 远程浏览器的背景色 | +| `transfer_remote_explorer_foreground` | 远程浏览器的前景色 | +| `transfer_remote_explorer_highlighted` | 远程浏览器的边框及高亮颜色 | +| `transfer_log_background` | 日志面板的背景色 | +| `transfer_log_window` | 日志面板的窗口颜色 | +| `transfer_progress_bar_partial` | 部分进度条的颜色 | +| `transfer_progress_bar_total` | 总进度条的颜色 | +| `transfer_status_hidden` | 状态栏 "hidden" 标签的颜色 | +| `transfer_status_sorting` | 状态栏 "sorting" 标签的颜色；也适用于文件排序对话框 | +| `transfer_status_sync_browsing` | 状态栏 "sync browsing" 标签的颜色 | + +### 杂项 + +这些样式适用于应用程序的不同部分。 + +| 键 | 说明 | +| ------------------- | -------------------------------- | +| `misc_error_dialog` | 错误消息的颜色 | +| `misc_info_dialog` | 信息对话框的颜色 | +| `misc_input_dialog` | 输入对话框的颜色（例如复制文件） | +| `misc_keys` | 按键文本的颜色 | +| `misc_quit_dialog` | 退出对话框的颜色 | +| `misc_save_dialog` | 保存对话框的颜色 | +| `misc_warn_dialog` | 警告对话框的颜色 |