// 用户指南

// 添加主机

在主机列表界面点击 + 按钮添加新服务器。

必填字段

• 主机名 / IP — 服务器地址或 IP，支持 IPv4 和 IPv6。
• 端口 — 默认为 22。如果服务器使用其他端口运行 SSH，请修改此项。
• 用户名 — 要登录的 Unix 用户（例如 ubuntu、root、deploy）。
• 认证方式 — 选择密码或 SSH 密钥（推荐）。

主机指纹验证

首次连接时，SSHBorg 会显示服务器指纹并要求您确认。这是一项安全检查，确保您连接的是正确的服务器而非冒充者。接受前请通过可信渠道核实指纹与服务器管理员提供的一致。

确认后，指纹将保存在本地。若日后连接时指纹发生变化，SSHBorg 将发出警告——这可能表示服务器重建、密钥轮换或中间人攻击。

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

// SFTP 文件管理器

SFTP 文件管理器让您直接从手机浏览、上传、下载、重命名和删除服务器上的文件。在主机列表界面点击 SFTP 开启 SFTP 会话。

浏览

点击文件夹进入。使用返回箭头或点击路径栏中的任意段落跳转到上级目录。

符号链接显示有小链接图标角标。点击符号链接会导航到其目标：若指向目录则进入，若指向文件则与普通文件相同。

上传文件

点击 上传 按钮（↑）从手机存储中选择一个或多个文件。上传立即开始，进度显示在界面顶部。

下载文件和文件夹

点击任意文件即可立即下载。要下载整个文件夹，点击其旁边的 下载 图标——SSHBorg 将下载整个目录树并保存到手机的 Downloads 文件夹。

如果目标位置已存在同名文件，对话框将询问您是 覆盖、跳过该文件，还是 取消整个传输。

批量选择与操作

长按任意项目进入选择模式，然后继续点击其他项目以建立选择。工具栏显示当前选择的操作：

• 下载 — 一次性下载所有选中的文件和文件夹，带进度对话框和取消支持。
• 删除 — 删除所有选中的项目。删除非空文件夹会递归删除其所有内容。此操作不可撤销。

// SSH 密钥

基于密钥的认证比密码更安全，设置完成后无需记忆或输入任何内容。

生成密钥

前往 设置 → SSH 密钥 → 生成新密钥。SSHBorg 支持：

• Ed25519 — 推荐。快速、紧凑且安全。
• ECDSA（P-256 / P-384） — 与旧版服务器有良好兼容性。
• RSA（2048 / 4096 位） — 最大兼容性，但速度较慢。

为密钥取一个有意义的名称（例如 my-vps 或 work-server），便于日后识别。

在服务器上授权密钥

生成密钥后，点击密钥查看其 公钥。复制并粘贴到服务器上目标用户的 ~/.ssh/authorized_keys 文件中。

1. 在手机上，打开 SSHBorg → 设置 → SSH 密钥 → 点击密钥 → 复制公钥。
2. 登录您的服务器（使用密码或已有密钥）。
3. 将公钥追加到授权密钥文件：

   mkdir -p ~/.ssh
   chmod 700 ~/.ssh
   echo "ssh-ed25519 AAAA...您复制的密钥..." >> ~/.ssh/authorized_keys
   chmod 600 ~/.ssh/authorized_keys

4. 尝试用 SSHBorg 连接——应无需密码即可登录。

密钥额外加密

SSHBorg 提供可选的 额外密码短语（设置 → SSH 密钥 → 点击密钥 → 启用加密）。启用后，密钥将使用 SSHBorg 不存储的密码短语加密——每次使用密钥时都需要输入。

如果您在手机上存储了敏感服务器凭据，或已禁用生物识别锁，强烈建议启用此功能。

// 命令建议

在终端输入时，SSHBorg 会在键盘上方显示建议栏。建议来自您所连接用户的 Shell 历史记录。

工作原理

终端会话开启时，SSHBorg 从远程服务器读取 Shell 历史文件，依次尝试以下位置：

1. ~/.bash_history — Bash Shell 的默认位置
2. ~/.zsh_history — Zsh 的默认位置（若设置了 $HISTFILE 也会检查）
3. ~/.local/share/fish/fish_history — Fish Shell 用户

使用第一个存在且可读的文件。输入时，命令会实时过滤并以标签形式显示在建议栏。点击标签即可插入命令。

故障排除

没有建议出现

• 历史文件可能尚不存在（首次登录，或 Shell 未配置保存历史）。
• 确保 Shell 已配置写入历史。对于 Bash，在 ~/.bashrc 中添加：

  HISTFILE=~/.bash_history
  HISTSIZE=10000
  HISTFILESIZE=20000

• 对于 Zsh，在 ~/.zshrc 中添加：

  HISTFILE=~/.zsh_history
  HISTSIZE=10000
  SAVEHIST=10000
  setopt APPEND_HISTORY SHARE_HISTORY

建议来自错误的用户

// 终端手势

终端除键盘输入外，还响应以下触摸手势：

• 滚动历史 — 上下滑动浏览终端回滚缓冲区。
• 缩放 — 捏合手势放大或缩小文字。
• 复制文本 — 长按终端任意位置进入选择模式。拖动控制柄调整选择区域，然后点击 复制选中内容 只复制高亮文本，或点击 全部复制 复制所有输出。点击其他位置取消。
• 粘贴 — 使用键盘打开时可见的扩展键栏中的 粘贴 按钮。

// 额外按键栏

软键盘打开时，上方会出现一排快捷按键。左右滑动按键栏可访问所有按键。

修饰键

Ctrl 和 Alt 是粘滞切换键——点击其中一个，再点击字母键即可发送组合键。每次按键后自动重置。

• Ctrl+C — 中断正在运行的进程。
• Ctrl+D — 发送 EOF / 关闭 shell。
• Ctrl+Z — 暂停进程。
• Ctrl+L — 清屏。

文字模式

拼写检查图标可在终端模式和文字模式之间切换键盘。终端模式（默认）下自动更正和词语建议被禁用——适合输入命令和文件路径。文字模式下键盘像普通文本框一样工作，启用词语建议和自动更正。通过 SSH 输入自然语言时很有用，例如使用 Claude Code 或其他交互式工具。

导航与编辑

• ESC — Escape 键。
• Tab — shell 自动补全。
• ↑ ↓ ← → — 光标方向键。
• Home / End — 跳到行首或行尾。
• PgUp / PgDn — 向上翻页 / 向下翻页。
• Del — 向前删除（光标右侧的字符）。
• 粘贴 — 将剪贴板内容粘贴到终端。

功能键

向右滑动按键栏可访问 F1 至 F12 功能键。

// 代理转发

SSH 代理转发允许 SSHBorg 中存储的密钥用于验证从远程服务器内部发起的进一步连接——例如 git clone 私有仓库，或跳转到第二台服务器。

在 SSHBorg 中启用转发

添加或编辑主机时，启用 代理转发 开关。SSHBorg 将作为该会话的 SSH 代理。

服务器端配置

服务器必须允许代理转发。检查 /etc/ssh/sshd_config：

AllowAgentForwarding yes

大多数系统默认如此。修改后重启 SSH 守护进程：

sudo systemctl restart sshd

每主机客户端配置（可选）

如果您也从笔记本或台式机连接此服务器，可在本地 ~/.ssh/config 中持久配置转发：

Host myserver
    HostName 203.0.113.42
    User ubuntu
    ForwardAgent yes

// 连接断开与终端复用器

SSH 是手机与服务器之间的实时 TCP 连接。一旦连接中断——哪怕只是一秒——会话及其中运行的一切都会丢失。

移动端连接断开的原因

移动网络特别容易断开连接，原因如下：

• IP 地址变更 — 出行或切换基站时，运营商可能分配新的公网 IP。由于 TCP 连接与 IP 地址绑定，现有 SSH 会话立即失效。
• Wi-Fi ↔ 移动数据切换 — 在 Wi-Fi 和移动数据之间切换会改变 IP 并中断所有开放的 TCP 连接。
• 空闲超时 — 运营商和 NAT 路由器通常在几分钟后断开空闲连接。长时间运行但静默的会话（查看日志、等待输入）容易受此影响。
• 信号丢失 — 隧道、地下车库或信号弱区域都可能短暂断网，足以终止会话。

解决方案：tmux 或 screen

终端复用器在服务器上运行持久会话，完全独立于 SSH 连接。连接断开时，会话及其中运行的一切继续运行。重新连接后，重新附加即可找到一切如常。

这是从手机管理服务器最有用的习惯。

tmux 快速入门

tmux 在大多数现代 Linux 发行版上可用，是推荐的选择。

# 开始一个新命名会话
tmux new -s work

# 从会话分离（保持运行）
Ctrl+B，然后 D

# 列出正在运行的会话
tmux ls

# 重新附加到会话
tmux attach -t work

# 附加到最近的会话
tmux attach

screen 快速入门

screen 较旧，但在几乎所有 Unix 系统上都可用，包括可能未安装 tmux 的最小服务器镜像。

# 开始一个新命名会话
screen -S work

# 从会话分离
Ctrl+A，然后 D

# 列出正在运行的会话
screen -ls

# 重新附加到会话
screen -r work

移动端推荐工作流程

1. 用 SSHBorg 连接服务器。
2. 立即开始或重新附加 tmux/screen 会话：tmux attach || tmux new -s main
3. 在复用器内运行命令。
4. 若连接断开，重新连接即可——会话仍然存在。

// 跳板机

跳板机（也称堡垒主机）是一台中间服务器，用于访问无法从互联网直接到达的目标服务器。SSHBorg 原生支持单跳和多跳链。

在 SSHBorg 中配置跳板机

1. 在 SSHBorg 中将堡垒服务器添加为普通主机（例如 bastion）。
2. 将目标服务器添加为另一台主机。
3. 在目标主机设置中，将 跳板机 设为您创建的堡垒主机。
4. 在堡垒主机条目上启用 代理转发——这允许密钥通过堡垒转发到目标服务器进行认证。

多跳链

如果需要跳过多台中间服务器（例如 互联网 → 堡垒 → DMZ → 目标），为每跳创建一个条目并链接：

• bastion — 无跳板机，启用代理转发
• dmz — 跳板机 = bastion，启用代理转发
• target — 跳板机 = dmz

等效的手动配置（仅供参考）

桌面端 ~/.ssh/config 中的等效配置如下：

Host bastion
    HostName bastion.example.com
    User admin
    ForwardAgent yes

Host target
    HostName 10.0.1.50
    User ubuntu
    ProxyJump bastion
    ForwardAgent yes

使用此配置，笔记本上的 ssh target 会透明地跳过堡垒。

防火墙要求

• 您的手机必须能在 SSH 端口（通常为 22）上访问堡垒。
• 堡垒必须能在其 SSH 端口上访问目标。
• 目标不需要从手机直接可达。

// 多会话

SSHBorg 允许您同时保持多个 SSH 终端会话和 SFTP 文件管理器会话，甚至可以连接到不同的服务器。

• 在主机列表界面点击 终端 或 SFTP 开启会话。
• 使用界面顶部的会话选择器在已开启的会话之间切换。
• 只要网络连接正常，会话在后台保持活跃。
• 主机列表在每台主机旁显示小角标，标明活跃的 SSH 和 SFTP 会话数量，方便一目了然。

// 应用安全

生物识别锁

在 设置 → 安全 → 生物识别锁 中启用。启用后，SSHBorg 在显示任何主机、凭据或会话数据前，都需要指纹或人脸解锁。

您可以设置不活动超时——在后台等待该时长后，应用会自动锁定。

截图保护

SSHBorg 默认阻止截图和录屏，防止敏感的终端内容通过最近应用界面或截屏工具泄露。

如果需要截图（例如分享终端输出），可在 设置 → 安全 → 允许截图 中临时禁用截图保护。

凭据存储

所有凭据（密码、私钥、密码短语）均使用 Android 密钥库（Android 10+ 提供的硬件支持的安全飞地）加密存储。它们永不写入外部存储或在任何地方传输。

// 配置备份

SSHBorg 可以将主机配置导出并导入为 JSON 文件。这样您可以将服务器列表转移到另一台设备，或保留一份可移植的配置备份。

导出

前往 设置 → 备份 → 导出主机。通过系统文件选择器选择文件保存位置。文件默认命名为 sshborg_hosts.json。

导入

前往 设置 → 备份 → 导入主机。选择之前导出（或手动创建）的 .json 文件。SSHBorg 将其与现有主机列表合并：

• 名称与现有条目匹配的主机将被更新。
• 具有新名称的主机将被添加。
• 文件中不存在的主机保持不变。

JSON 格式

导出文件是一个标准 JSON 对象。您也可以手动创建它，从其他来源批量导入服务器列表。

{
  "version": 1,
  "exported_at": "2026-05-14T10:00:00Z",
  "hosts": [
    {
      "label":           "我的 VPS",
      "hostname":        "203.0.113.42",
      "port":            22,
      "username":        "ubuntu",
      "agentForwarding": false,
      "jumpMode":        "simple",
      "jumpHosts":       null,
      "jumpHostIdList":  null,
      "portForwardings": null,
      "sftpStartMode":   "last",
      "sftpStartDir":    null
    }
  ]
}

字段说明

• label — SSHBorg 中显示的名称。导入时用作唯一合并键。必填。
• hostname — 服务器地址或 IP（IPv4 或 IPv6）。必填。
• port — SSH 端口。默认值：22。
• username — 登录用户名。必填。
• agentForwarding — true 启用 SSH 代理转发。默认值：false。
• jumpMode — "simple"（使用 jumpHosts 文本）或 "host_list"（使用 SSHBorg 内部主机 ID）。手动创建文件时请使用 "simple"。
• jumpHosts — 以逗号分隔的跳板机列表，格式为 [用户名@]主机[:端口]。仅在 jumpMode 为 "simple" 时使用。
• portForwardings — 以换行符分隔的本地端口转发规则，使用 SSH -L 语法，例如 "8080:localhost:8080"。
• sftpStartMode — SFTP 起始目录："last"（记住上次访问的目录）、"fixed"（始终使用 sftpStartDir）、"home"（服务器主目录）。默认值："last"。
• sftpStartDir — 当 sftpStartMode 为 "fixed" 时使用的路径。