# SSH 连接管理

SSH 仍然是 NyaTerm 最完整的一类会话。除了基础登录外，SSH 连接还可以进一步挂接：

- SFTP 文件浏览器
- 远程资源监控、GPU 监控、进程管理、Docker 管理
- 代理
- 跳板机
- OTP 绑定与自动填充
- 端口隧道
- SSH 算法偏好

先把 SSH 连接配置好，再逐步接上文件传输、终端增强和网络能力。

## 创建 SSH 连接

在 **新建连接** 窗口切换到 **SSH** 标签后，可以填写这些信息：

### 基本信息

| 字段 | 说明 |
|------|------|
| 连接名称 | 在已保存连接列表中的显示名称 |
| 主机 | 服务器 IP 或域名 |
| 端口 | 默认 `22` |
| 用户名 | 登录用户名 |
| 图标 | 用于区分不同环境或服务 |
| 分组 | 把连接整理到文件夹中 |
| 描述 | 记录用途、环境或备注 |

### 认证方式

NyaTerm 支持四种 SSH 认证方式：

- **密码**
- **私钥**
- **无认证（none）**
- **SSH Agent**

先在 **登录身份** 中选择手动填写或已保存账户，再选择认证方式。账户有用户名时，界面只读显示实际登录的用户名；账户没有用户名时，填写当前连接的用户名。切回手动填写会恢复本次编辑中输入的用户名。

密码来源按 **连接时询问 / 保存在此连接 / 使用账户密码** 排列。明确选择或更换账户时，密码认证会在账户有密码时使用账户密码，否则改为连接时询问；私钥、Agent 和无认证模式保持当前选择。切换认证方式或密码来源会保留本次输入，保存时只使用当前模式的配置。

可以在账户选择器旁新建或编辑账户。新建后会自动选中，编辑已有账户后保留当前连接草稿。已选账户被删除时会显示错误，需要重新选择。RDP/VNC 的账户引用仅提供密码，用户名仍由连接独立填写。

**无认证（none）** 适用于通过其他方式完成认证的主机（例如部分跳板机或网关流程，或接受空认证的服务器）。仅在目标主机确实不需要任何 SSH 层凭证时才使用。

密码认证用于临时测试机、还未发放私钥的环境，以及与 OTP 组合使用的账号。私钥认证用于日常运维、多台主机复用同一身份，以及需要配合跳板机或自动化流程的场景。

私钥和账户都在 **Security/Auth** 面板中统一管理。账户名称必填，用户名和密码至少保留一项。编辑时默认只显示密码保存状态；修改、移除及撤销都在点击“保存”后才写入，取消不会更改账户。查看原密码和复制密码分别操作，并沿用解锁流程。引用连接列表可以展开查看，账户变更在下次认证时生效。

#### SSH Agent 认证

SSH Agent 模式只使用本机 Agent 提供的签名能力，私钥和硬件密钥不会导入 NyaTerm。基础认证区域只能选择一个 Agent endpoint；可根据当前设备选择自动发现、环境变量、Unix 域套接字、Pageant 或 Windows OpenSSH Agent。`Auto` 会使用当前平台的默认 Agent。Agent 不可用或没有匹配身份时，连接会失败并显示原因。

Agent endpoint 和 forwarding 开关属于设备本地连接配置。跨设备同步时不会覆盖目标设备的这些值，因此 macOS 的 Unix socket 配置不会被同步到 Windows。

当 Agent 正在等待硬件触摸、PIN 或桌面确认时，NyaTerm 会显示确认弹窗。Agent 超时或认证失败后可以选择“重试”；重试会丢弃当前连接并重新建立完整的 SSH/跳板机链路。选择“取消”会终止本次连接。

### 交互式认证请求

当服务器要求额外的键盘交互输入、OTP 或重新认证时，NyaTerm 用专用的 SSH 认证请求窗口收集信息，而不把提示混在终端输出里。窗口会区分这几种情况：

- 普通密码 / 私钥认证
- 键盘交互认证
- OTP 或二次确认提示
- 需要重新开始的认证流程

如果某次认证请求来自未预期的主机或会话，请先核对连接信息再输入敏感内容。

### 连接类型与终端类型

SSH 表单提供 **连接类型** 和 **终端类型** 设置。

**标准服务器** 用于普通 Linux / Unix shell，保留 SFTP 浏览、目录跟随、Shell 检测、Shell Integration、远程资源统计和自动图标识别。

**网络设备** 用于交换机、路由器等非 Linux shell 的设备 CLI。选择后，NyaTerm 会在运行时关闭 SFTP 浏览、目录跟随、Shell 检测、Shell Integration、远程资源统计和自动图标识别，避免把设备 CLI 当作完整 shell 探测；这个选择不会改写已保存的 SFTP 选项。

终端类型会影响 SSH 会话向远端声明的 `$TERM`，可在 `xterm-256color`、`xterm`、`vt100`、`vt220`、`ansi`、`linux` 之间选择。连接老旧设备或字符界面异常时，可以尝试更保守的终端类型。

## 高级配置

高级区域配置的是连接的工作流部分：代理、跳板机、转发、算法和登录后行为。

### 代理

如果需要通过代理建立 SSH 连接，可以直接为当前连接选择已保存的代理配置。

当前代理支持：

- **SOCKS5**
- **HTTP**
- **ProxyCommand**

代理记录中可保存：

- 名称
- 协议
- 主机
- 端口
- 用户名 / 密码

### SSH Agent 转发

在高级配置的 **SSH Agent** 页签中可以单独启用 Agent 转发。未勾选时，NyaTerm 不会因为转发而建立本地 Agent 连接，也不会向服务器发送转发请求；如果认证方式本身选择了 SSH Agent，认证仍会使用 Agent。勾选后仅交互式终端会请求转发，SFTP、隧道和跳板机连接不会隐式开启本地 Agent 转发。

转发端点与登录认证端点相互独立。转发可以按顺序添加多个外部 SSH Agent，例如主 SSH Agent 和 gpg-agent 的 SSH-compatible socket。登录认证端点不会自动加入 forwarding；转发来源只由外部 SSH Agent 列表和 NyaTerm 已保存密钥开关决定，两类来源使用同一套 fingerprint 白名单或全量策略。

默认使用 fingerprint 白名单，空白名单表示远端看不到任何身份。切换为全量策略前会显示风险确认；它会暴露已启用来源当前及未来出现的身份。单个转发端点不可用时，身份选择器会显示局部错误，并保留其他端点的结果。身份按端点顺序合并，并受 SSH Agent 协议的 1,024 项和 256 KiB 响应上限约束；达到上限时，选择器会明确提示仅显示并转发确定性的前缀。

已建立的保存密钥 forwarding channel 会在保存密钥成功新增、替换或删除后失效，重新建立的 channel 才会读取当前密钥集合。Broker 和 legacy raw relay 共用有界的本地 channel 配额，Broker channel 具有首帧和空闲超时。Backup 跨操作系统恢复时会移除目标平台不支持的设备专属 Agent 端点，但损坏的值仍会拒绝校验。

:::warning
Agent 转发会让远端进程能够通过 SSH 使用所选外部 Agent 或 NyaTerm 保存密钥的签名能力。仅对可信服务器启用，并在不需要时保持关闭。Agent endpoint 和 forwarding 策略属于设备本地连接配置；外部硬件密钥不会被导入，NyaTerm 保存密钥是否进入现有加密 snapshot/sync 继续遵循应用已有策略。
:::

### 跳板机

如果目标主机不能直连，可以为当前 SSH 连接指定另一个已保存的 SSH 连接作为 **跳板机**。

典型链路：

- 先进入堡垒机，再访问内网服务器
- 分环境隔离的生产网络
- 多层 SSH 登录链路

NyaTerm 会校验跳板机链路，阻止缺失引用和环路引用，避免连接时出现无限递归或难以排查的代理链路。

### 登录后命令

可以为当前 SSH 连接配置一条在登录后自动执行的命令。会话建立、shell 就绪后，NyaTerm 会自动运行它。

常见用途：

- 切换到固定的工作目录（`cd`）
- 激活某个环境（例如 tmux/screen、conda）
- 在连接时执行一条固定的初始化命令

该命令会在登录后作为终端输入发送，因此其行为等同于你自己手动输入这条命令。

### X11 转发

X11 转发允许远端 Linux 图形程序通过 SSH 显示到本机。

NyaTerm 不内置 X server，用户需要自行安装并启动：

- Windows: VcXsrv / Xming
- macOS: XQuartz
- Linux: Xorg / Xwayland

远端服务器需要：

- `sshd_config` 开启 `X11Forwarding yes`
- 安装 `xauth`

如果需要覆盖本机 DISPLAY，可以在 **设置 → 终端 → 本地 X11 DISPLAY** 中填写，例如 Windows 常用 `localhost:0`，Linux/macOS 常用 `:0`。

### SSH 算法偏好

可以为每个连接单独控制 SSH 握手时协商的加密算法，位于高级配置的 **SSH 算法** 卡片中，提供三种模式：

- **兼容（默认）**：使用较宽的算法列表，包含部分旧算法，便于连接老旧服务器或网络设备
- **安全**：只使用现代算法，排除旧的兼容项
- **自定义**：分别在 **密钥交换 / 加密 / MAC / 主机密钥** 四类中勾选并调整顺序

每个算法都会带有风险标记：

- **现代**（绿色）
- **旧版**（黄色，例如 `ssh-rsa`、`*-cbc`）
- **不安全**（红色，例如 `3des-cbc`、`hmac-sha1`、`ssh-dss`）

保存自定义配置时，NyaTerm 会校验每一类都不能为空，并拒绝无法识别的算法名。如果不确定该选什么，保留 **兼容** 模式即可；对安全性要求较高的环境建议使用 **安全** 或自定义收紧算法列表。

### 多路复用 SSH 会话

NyaTerm 可以在同一条 SSH 连接上多路复用多个终端会话。向同一主机打开新的终端时，会复用已有的已认证连接，而不必每次重新认证。

带来的好处：

- 新终端打开更快
- 更少的认证提示 / OTP 输入
- 对服务器的负载更低

### OTP 绑定

如果目标环境要求二次验证码，可以把一个 OTP 条目绑定到当前 SSH 连接。

绑定后有两种常见工作方式：

- 只是在认证时快速取码
- 开启 **自动填充 OTP**，在支持的交互流程中直接带入验证码

这部分可以结合 [OTP 与认证](./otp-and-auth) 一起使用。

## 已保存连接的管理

保存后的连接会出现在右侧 **已保存连接** 面板中。常见操作包括：

- 双击直接连接
- 按分组组织连接
- 编辑已有配置
- 复制连接作为新模板
- 重新连接已存在的会话来源

主机数量多时，用分组、图标和描述区分环境、项目和角色。

## 临时 SSH 链接

如果只是想临时连一次，不想保存连接，可以使用 **临时 SSH 链接**。在已保存连接面板中打开该对话框（也可通过全局快捷键唤起），粘贴一段地址即可直接建立一次性会话。

支持两种输入形式：

- `ssh://user@host:port` 形式的 URL
- `ssh [-p port] [-l user] user@host` 形式的命令字符串

约定与限制：

- 默认用户名为 `root`，默认端口为 `22`
- 使用密码认证，不带代理、跳板机、登录后命令或 X11
- 出于安全考虑，所有 URL 和命令形式的内联密码（`user:pass@host`）都会被拒绝；`-J`、`-L/-R/-D`、`-i`、`-o ProxyJump/ProxyCommand` 等不支持的选项同样会被拒绝

临时会话不会写入已保存连接：NyaTerm 会剥离连接 ID、代理、跳板机、登录后命令、X11 与算法偏好，因此它始终只是一次性会话。

## 外部调用与协议调用

可以从浏览器、脚本和启动器打开 SSH、Telnet 或本地终端。外部连接默认复用最近使用的工作区；没有可用窗口时创建窗口。直接启动程序、不带参数时默认新开窗口，`--reuse-window` 可显式复用。

```powershell
NyaTerm.exe ssh://root@example.com:22
NyaTerm.exe --reuse-window
NyaTerm.exe --local --cwd "C:\中文 目录"
NyaTerm.exe --local "--cwd=C:\My Projects"
```

安装版的稳定版声明 `nyaterm`、`ssh`、`telnet` 协议，预览版只声明 `nyaterm-preview`。系统可能要求选择默认处理器。卸载仅移除仍指向当前安装的注册；便携包不会主动注册协议。

支持的链接示例（预览版将自定义前缀替换为 `nyaterm-preview://`）：

- `ssh://user@host:port?mode=terminal`
- `ssh://user:password@host:port?mode=sftp`
- `telnet://host:port`
- `nyaterm://connect/ssh?host=host&port=22&username=user&mode=standard`
- `nyaterm://connect/telnet?host=host&port=23`
- `nyaterm://connect/local?cwd=C%3A%5CMy%20Projects`

SSH 默认用户名为 `root`、端口为 `22`；Telnet 默认端口为 `23`。支持 IPv6（例如 `ssh://user@[2001:db8::1]:2222`），协议名称不区分大小写。用户名、密码和查询值按 UTF-8 百分号编码，严格解码一次，例如 `user%40realm` 和 `p%40ssword`。`--cwd PATH` 和 `--cwd=PATH` 仅配合 `--local` 使用；目录不能为空，连接后台验证存在性与访问权限，不将路径当作启动命令。

SSH 的 `mode` 可选：

| 模式 | 行为 |
| --- | --- |
| `standard` | 普通 SSH；服务器拒绝 shell 但支持 SFTP 时降级为文件会话。 |
| `terminal` | 仅终端，不启动 SFTP、目录跟随或远程监控；shell 不可用时连接失败。 |
| `sftp` | 认证并验证 SFTP 后进入文件浏览，不请求 PTY/shell，不执行登录后命令，不启用终端 AI 执行、X11、agent forwarding 或远程监控。已保存连接禁用 SFTP 时会报错。 |

未指定模式时保持普通 SSH。运行模式仅影响本次会话，重连、复制、窗口间移动和已保存连接的启动恢复保留该模式，不回写连接配置；旧恢复数据按普通模式处理，不支持的模式会保留原值并跳过恢复。

不含密码的链接优先匹配同协议、规范化主机和端口的已保存连接；SSH 显式用户名还需精确匹配。唯一匹配直接使用，多匹配时弹窗选择已保存连接、临时连接或取消。已保存的有效登录后命令仍需确认，SFTP 模式不会执行该命令。取消只结束当前请求。

一次性密码仅允许放在 `ssh://` 用户信息中。带密码的链接始终创建临时会话，不匹配或修改已保存凭据；密码仅驻留当前进程供重连使用，不进入恢复、备份或同步数据。应用重启后需要重新认证。链接可能进入调用工具或浏览器的历史记录，请按敏感信息处理。

链接不允许传入启动命令、代理、跳板机、私钥和转发配置；未知或重复参数、非法端口和非法编码均被拒绝。批量调用逐项处理，某个链接无效不会阻止其他合法链接；最多处理 16 项连接意图，每项参数最长 4 KiB。重复系统投递在 500ms 内去重。请求会等待启动、恢复和解锁完成，其他弹窗占用时排队；窗口关闭会取消其剩余请求。

## 会话输入同步

需要同时对多台主机执行相同操作时，用 **同步输入组** 把一个终端里的输入广播到多个会话。它不限于 SSH，串口会话同样可以加入。

配置方式、筛选、广播控制和发送命令面板见 [工作区与布局 → 同步输入组](./layout-and-workspace#同步输入组)。

## 导入其他客户端的会话

NyaTerm 支持导入其他客户端的会话配置，目前可导入：

- **Xshell**（`.xts`）
- **MobaXterm**（`.mxtsessions`）
- **WindTerm**（`.sessions`）
- **SecureCRT**（`.xml`）
- **FinalShell**（`conn` 目录）
- **Termius**（本机 IndexedDB）
- **NyaTerm JSON**（`.json`）

### 从 Termius 导入

选择 **Termius** 后，NyaTerm 会读取本机 Termius 的 IndexedDB，并通过系统凭据管理器 / Keychain / Secret Service 中的 `Termius/localKey` 解密会话数据。

可导入内容包括 SSH 主机、分组、用户名、密码和 SSH 私钥。为了避免产生半可信配置，只要任何 Termius 加密字段无法解密，本次导入会整体失败且不会写入连接。

如果默认路径未找到，可以手动选择 Termius 的 `file__0.indexeddb.leveldb` 目录。

### 从 NyaTerm JSON 导入

选择 **NyaTerm JSON** 可以导入一个 `.json` 文件，用于从脚本、资产清单或其他系统批量生成会话数据。

示例文件：[session-import-sample.json](/examples/session-import-sample.json)

JSON 顶层字段：

- `version`：当前为 `1`
- `groups`：要预先创建的会话分组，使用 `path` 表示层级
- `passwords`：可复用的已保存密码条目，使用 `ref` 在本文件内引用
- `ssh_keys`：可复用的已保存私钥条目，使用 `ref` 在本文件内引用
- `sessions`：要导入的会话列表

支持的会话类型：

- `ssh`
- `local_terminal`
- `telnet`
- `serial`
- `rdp`

SSH 认证支持：

- 直接密码：`"auth": { "mode": "password", "password": "replace-me" }`
- 已保存密码：`"auth": { "mode": "password", "password_ref": "prod-root-password" }`
- 已保存密钥：`"auth": { "mode": "key", "key_ref": "ops-ed25519" }`
- SSH Agent：`"auth": { "mode": "agent" }`
- 无认证：`"auth": { "mode": "none" }`

`password` 与 `password_ref` 二选一；`key` 模式必须提供 `key_ref`。`agent` 模式不会导入私钥，只会在连接时使用当前设备可用的 SSH Agent。`ref` 只在当前 JSON 文件内有效，导入后 NyaTerm 会生成真实的本地 ID。

:::warning
JSON 文件中的密码和私钥是明文。导入后请删除该文件，或至少按敏感文件方式保存。
:::

导入后建议逐条检查：

- 主机与端口
- 用户名
- 是否需要补充代理 / 跳板机 / OTP 绑定
- 本地保存的密码或私钥是否已经匹配

## 主机密钥策略

NyaTerm 会为 SSH 主机维护已知主机记录，并提供三种主机密钥策略：

| 策略 | 行为 |
|------|------|
| 提示 | 首次连接未知主机时询问是否信任（默认） |
| 接受 | 自动接受并记录新的主机密钥 |
| 严格 | 拒绝所有未知主机 |

已知主机记录保存在本地 redb 的 `known_hosts` 文本文档中；旧版 redb 文本文档中的 `known_hosts` 内容会按兼容路径导入，不承诺扫描任意文件系统位置的旧文件。

生产环境应先确认主机密钥来源，再决定是否接受。

## 什么时候用 SSH

需要远程文件浏览器 / SFTP、OTP、跳板机、代理、隧道或远程主机监控时都必须用 SSH——这些能力只在 SSH 会话上存在。只想开一个本机 shell 时用 [本地终端](./session-types#本地终端)。