# NovalTerm 使用教程

本教程对应当前开发版的实际功能。NovalTerm 是支持 Windows、Linux 和 macOS 的 SSH 工作台，主要用于远程 Linux 运维。界面、终端、文件编辑和帮助阅读均在本机运行，不要求服务器安装专用 Agent。

在软件主窗口中选择“菜单 → 使用帮助”，或按 F1，可离线阅读本教程。左侧选择章节；搜索框会从章节标题和正文中筛选相关章节，清空搜索即可恢复全部目录。

## 01 安装、启动与首次准备

### 使用发布包

1. 从[项目发行版页面](https://gitee.com/lightnehum/noval-term/releases)获取 NovalTerm Windows x64 安装包 `NovalTerm-<版本>-win-x64-Setup.exe`。
2. 运行安装包，选择安装目录；需要桌面快捷方式时，在“附加任务”页勾选。默认安装到当前用户的 `%LOCALAPPDATA%\Programs\NovalTerm`，不要求管理员权限。
3. 从开始菜单或桌面启动 NovalTerm。安装包自带 .NET 运行时，安装时无需额外下载运行时。
4. 首次启动没有终端标签时，主界面会显示欢迎页。点击“新建连接”开始配置。

使用便携 ZIP 时，请完整解压到可写目录，再运行 `NovalTerm.Desktop.exe`，不要只从压缩包内打开 EXE。卸载安装版可通过 Windows“已安装的应用”完成，用户连接配置会保留。系统安装范围和兼容性说明见[打包说明](packaging.md)。

当前版本仍处于开发阶段；真实服务器、终端程序和网络环境的兼容性需按实际情况验证。

Linux 发布包使用 `.tar.gz`，解压后运行 `./NovalTerm.Desktop`；可运行 `sh ./install-desktop.sh` 添加当前用户的桌面入口。macOS 解压后打开 `NovalTerm.app`。目标系统依赖、构建与实际验证范围见 [跨平台迁移记录](avalonia-migration.md)。

### 检查更新

默认开启自动检查更新：每次启动后在后台检查一次 [Gitee 发行版](https://gitee.com/lightnehum/noval-term/releases)，持续运行期间成功检查后间隔 24 小时再检查。后台网络失败不弹窗，并延后重试；设置、编辑器或认证窗口打开时，后台检查会延后。

发现更高的正式版本后显示版本号和更新说明，可选择“立即更新”“稍后提醒”或“跳过此版本”。跳过会保存在本机，只屏蔽该版本的自动提醒，不影响后续新版。右上角“菜单 → 检查更新”随时可以主动检查，即使该版本已跳过也会再次显示。

在“菜单 → 设置 → 软件更新”中取消勾选“自动检查更新”并保存，即可关闭后台检查；手动检查仍可使用。检查只向 Gitee 公共接口请求版本信息，不发送连接配置、凭据或终端内容。

Windows 点击“立即更新”后，在应用内下载匹配当前架构的安装包并显示进度，校验 SHA-256 和安装包格式。下载支持取消、失败重试，下载或校验失败时不会安装。完成后询问是否关闭会话、隧道及传输，未保存的远程文件仍通过原有编辑器确认；取消退出会保持工作区打开。

确认退出后，独立更新助手等待程序完全结束，再静默运行安装包，安装完成后重新启动。安装版沿用当前目录；从源码或便携目录启动时会安装正式版到已有的当前用户安装位置，尚未安装时使用 `%LOCALAPPDATA%\Programs\NovalTerm`，不覆盖源码构建目录。安装失败会留下日志，并尝试重新打开原应用。

当前自动安装仅支持 Windows，且发行版必须提供匹配的 `NovalTerm-<版本>-win-x64-Setup.exe`（或 `win-arm64`）及同名 `.sha256` 附件；附件缺失时“立即更新”不可用。macOS/Linux 保留版本提醒，暂未接入自动安装。SHA-256 用于下载完整性校验，现有发行包未签名，不代表已建立发布者签名验证。

### 从源代码启动

开发环境需要 .NET 10 SDK，在仓库根目录执行：

```powershell
dotnet restore NovalTerm.slnx --configfile NuGet.Config
dotnet run --project src/NovalTerm.Desktop -c Release
```

### 连接前准备

- 服务器地址、SSH 端口（通常为 22）和用户名。
- 登录密码，或本机私钥文件及其口令。
- 从可信渠道获取的服务器主机公钥指纹，用于首次连接核对。
- 如需跳板或代理，准备相应地址和连接配置。
- 确认本机能访问 SSH 端口，服务器 SSH 服务已启动。

## 02 认识工作台

- 左侧是连接列表：搜索、分组、新建及连接配置管理。
- 中间上方是终端标签，每个标签对应一个独立 SSH 会话。
- 中间下方是远程文件与传输区域，随当前选中的会话切换。
- 右侧入口提供系统监控、公共命令库、AI 助手、Docker 和 Kubernetes 面板；入口可展开、收起，部分功能仅在连接及工具检测成功后显示。
- 右上角“菜单”集中设置、检查更新、主机信任、命令片段、快捷键、使用帮助和关于。
- 底部状态栏显示操作结果。出现失败时，结合弹窗中的具体原因处理。

可以拖动终端与文件区之间的分隔条调整高度。右侧面板展开后可拖动左边缘调宽。面板跟随当前会话，执行操作前先核对连接名称和环境标记。

## 03 新建连接与身份认证

### 保存一个常用连接

1. 点击连接栏的“＋”、欢迎页“新建连接”，或按 Ctrl+N。
2. 在“基本信息”中填写连接名称、主机地址和 SSH 端口。
3. 选择分组及环境，必要时填写备注。IPv6 地址与端口分开填写。
4. 在“身份认证”中填写用户名并选择认证方式。
5. 使用密码认证时填写密码；使用私钥认证时选择本机私钥，按需填写私钥口令。
6. 在“网络与跳板”中按需设置连接超时、KeepAlive、跳板链、默认 SFTP 目录和代理。
7. 可先点击“测试连接”，检查当前填写的 SSH 连接和身份认证；通过后点击“保存连接”。保存只记录配置，不会立即联网。
8. 双击左侧连接，或右键选择“连接”，打开会话。

私钥仅引用文件路径，不复制私钥内容。编辑已有连接时，密码或口令留空会保留已有凭据。需要验证码等交互认证时，按连接过程中的提示填写；MFA 验证码不会保存。

“测试连接”会实际联网，按需弹出主机信任或交互认证提示，但不打开终端、不保存此次编辑的连接配置或新输入的凭据。测试通过仅说明 SSH 连接和身份认证成功，SFTP、Docker 等功能仍需连接后检查。

### 快速连接

在连接栏“⋯”中选择“快速连接”，填写连接信息后发起连接。它用于临时访问，不把此次输入的秘密保存为常用连接凭据。需要长期复用时，请使用“新建连接”。

### 主机身份核验

首次连接会显示服务器主机公钥信息。先与管理员提供的指纹核对，再决定信任方式。已经信任的主机发生换钥时，连接会被阻断；先确认是否为服务器重装或管理员主动换钥，再通过“菜单 → 主机信任”处理旧记录。不要把不明换钥当作普通登录失败。

## 04 连接分组、搜索与配置迁移

### 日常整理

- 按 Ctrl+K 聚焦连接搜索，可按名称、主机、用户、分组或环境查找。
- 点击“分组管理”新建、重命名或删除分组；空分组会保留。
- 删除分组会把连接移入“默认”，不会删除服务器数据；默认分组不可重命名或删除。
- 在连接列表中使用 Ctrl 或 Shift 多选，右键“批量移动分组”统一整理。
- 右键连接可编辑、复制IP地址、收藏或删除配置。删除连接配置不会删除远端文件。
- 分组的展开与收起状态保存在本机。

### 导出与导入

1. 在连接栏“⋯ → 导出配置”保存 JSON 文件。
2. 在另一套 NovalTerm 中使用“⋯ → 导入配置”选择该文件。
3. 导入前查看确认信息；同 ID 的已有配置会保留，导入用于新增配置。
4. 在新机器上重新配置凭据和私钥路径，并重新核验主机身份。

导出不包含密码、私钥路径、命令片段、主机信任或会话内容，因此它不是本地全部数据的完整备份。

也可导入 OpenSSH config。先查看解析预览和警告；导入器不会执行 ProxyCommand、Include 或 Match，不读取私钥。导入文件上限为 10 MiB，复杂配置需在导入后逐项核对。

## 05 终端、多会话与断线重连

### 使用终端

连接成功后，在终端中输入命令并按 Enter 执行。例如先确认身份和目录：

```bash
whoami
hostname
pwd
ls -lah
```

点击标签切换服务器，Ctrl+Tab 切换下一个终端。标签右键菜单提供重新连接、输出录制、隧道管理、标签移动及批量关闭，操作对象是右键点击的标签。

终端支持中文输入法，组合输入时先确认候选词再继续输入命令；选词期间不会触发公共命令提示或把确认用的按键作为命令发送。

### 复制、粘贴与选择

- 拖动选择文本；双击选词，三击选行。
- Ctrl+Shift+C 或 Ctrl+Insert 复制。Ctrl+C 有选区时复制，没有选区时向远端发送中断。
- Ctrl+V、Ctrl+Shift+V 或 Shift+Insert 粘贴，按提示核对预览内容。
- Esc 清除选区。远端程序启用鼠标模式时，按住 Shift 强制本地选择。
- 在主工作区按 Ctrl+Shift+F 搜索终端回滚缓冲；可搜索的历史受回滚行数限制。

### 高风险命令确认

可在“菜单 → 设置 → 命令安全”切换“高风险命令提示”，默认开启。保存后立即应用于已有和新建终端（包括容器终端），重启后保留设置。关闭后不再弹出高风险命令确认。

手动输入后按回车、粘贴以及发送命令片段时，会检查常见高风险命令，例如递归或强制删除文件、格式化或覆盖磁盘、关机重启、递归修改权限、删除容器或集群资源等。普通 cd、只读查询和单个文件的普通删除不提示。命中后弹窗只显示命令和具体风险后果，默认取消；只有点击“确认执行”才继续发送。取消手动输入命令时，命令文字可能仍留在远端编辑行中，但不会发送执行用的回车；可按 Ctrl+C 清除。

历史命令和远端补全会尽量从终端显示内容还原命令，只有识别到具体危险操作才提示；无法还原输入本身不会触发风险弹窗。检测适用于普通终端输入，不检查 Vim 等使用备用屏幕的程序内部操作；别名、函数和脚本内容等不能被完整解析，未出现提示不代表命令安全。

### 断线与恢复

软件通过连接心跳检测离线，默认周期为 5 秒，可在设置中改为 1–60 秒。离线后自动重连最多尝试 1 分钟，超时后右键标签选择“重新连接”。网络恢复不代表之前执行的命令已完成，应重新检查远端状态。

重新连接会建立新的 SSH 会话，不能恢复原 Shell 内存、前台程序和未持久化状态。长任务可在服务器上按需使用 tmux 或 screen。

重启软件后会按原顺序恢复已保存连接的离线标签，不会自动联网；点击标签内的“连接”或右键“重新连接”后才建立连接。快速连接不应作为持久工作区依赖。

## 06 命令提示、公共命令库与命令片段

### 输入时查看命令提示

输入 Linux、Docker、Compose 或 kubectl 命令时，候选项会显示中文用途、用法和常用参数。

1. 按 ↓ 开始选择，用 ↑↓ 切换候选项，或按 Ctrl+Space 手动打开并选中第一项。
2. 按 Enter 或单击候选项填入命令。
3. 补充实际参数，检查主机、路径和作用范围。
4. 再按 Enter 执行。填入候选项不会自动执行。

Esc 关闭提示；Tab 保留远端 Shell 原生补全。公共提示是内置命令说明，不代表远端一定安装了命令，也不会自动生成服务器的实时文件列表。

### 浏览公共命令库

打开右侧“命令”面板，按类别筛选或输入关键词搜索，如“docker 日志”。点击“使用”把命令填入当前已连接终端；双击命令查看用途、用法和参数。填入后可继续修改，不自动执行。

### 保存自己的命令片段

通过“菜单 → 命令片段”新建、搜索、编辑和删除片段。新建或编辑时填写名称及命令正文，支持多行内容，点击“保存收藏”保存。选择片段后点击“预览并发送”，确认目标主机和环境。

片段可以使用占位符，例如：

```bash
systemctl status ${service}
```

发送前会逐项询问参数，并提供最终文本预览。参数按原文替换，不自动进行 Shell 转义；含空格或特殊字符时，请自行检查引用方式。发送不追加回车，但片段自身的换行仍可能触发 Shell 执行，多行内容必须完整核对。

## 07 SFTP 文件浏览与传输

### 导航远程目录

连接后，下方文件区显示当前会话的远程目录。双击目录进入，双击“..”返回上级；也可在路径框输入远程路径并按 Enter，点击“刷新”更新列表。

支持 Bash、Zsh、Fish 提示符目录同步：终端返回提示符后，文件区按远端实际目录刷新。进入其他嵌套 Shell、修改提示符钩子或使用 SFTP chroot 时可能无法自动同步，可手动导航。文件区导航不会向正在运行的终端发送 cd。

### 上传与下载

1. 切换到目标连接，先确认远程目录。
2. 点击“上传”选择本地文件，或把本地文件拖入远程列表。
3. 下载单个文件时，选中后点击“下载”并选择本地保存位置；选中文件夹时，选择本地目标目录，程序保留所选文件夹名称并递归下载其内容，包括空目录。
4. 多选文件或文件夹可使用 Ctrl、Shift 或 Ctrl+A；批量下载时一次选择目标目录。
5. 在“传输中心”查看每项进度、速度和失败原因，可单独取消传输。同时最多执行 3 项文件传输，其余排队；标签旁的绿色圆点表示仍有任务传输或排队。

目标文件已存在时，会在启动前逐项询问是否覆盖；取消任一确认会停止本次下载安排。确认后重新下载，原文件保留到新文件下载成功后再替换。Windows 不安全文件名、大小写重名及文件与目录冲突会导致下载被拒绝，请调整保存位置或分别另存。目录下载遇到符号链接会拒绝本次安排，需进入真实目标后下载；目录过深或条目过多时需分批处理。

### 取消、续传与传输记录

传输中显示当前速度，结束后显示本次传输的平均速度。悬停任务可查看完整来源与目标，悬停失败状态可查看完整原因。点击任务右侧“×”取消该项；下载取消或失败后会保留部分文件。

续传通过远程文件右键“续传下载”进入，选择原来的本地保存位置；批量或文件夹续传请选择原目标目录。保留配套的 `<文件名>.novalterm.part` 和 `.novalterm.part.json` 文件，程序会核对服务器、路径、文件版本和部分内容后继续；没有断点时开始新下载。记录缺失或远端已变化时，应另存重新下载。目标成品文件已存在并确认覆盖时，会重新下载。

任务右键“删除记录”仅移除列表记录，不删除文件，也不取消正在进行的传输；需要停止任务时先点击取消。下载成功后可右键“打开文件所在位置”，在资源管理器中定位本地结果。

### 文件操作

右键菜单提供重命名、chmod 权限设置、复制路径及删除。“⋯”菜单可新建目录。重命名、权限修改、编辑仅允许单选。删除支持文件和空目录，不递归删除非空目录；批量删除结束后会汇总失败项。

符号链接以“↗”标记，悬停可查看类型。编辑符号链接文件时需通过真实目标路径打开。

## 08 内置远程文本编辑器

### 打开、编辑与保存

1. 在 SFTP 列表双击文件，或右键“打开 / 编辑”。
2. 文件在独立的编辑窗口中打开，主工作区仍可操作；多个文件以标签展示。
3. 修改后按 Ctrl+S 保存到远程，保存成功后刷新文件列表。
4. 每个文件始终绑定打开时的连接与绝对路径，切换主终端不会改变保存目标。
5. 关闭有未保存修改的标签、编辑窗口或主程序时，按提示决定是否保存。

同一会话的同一路径重复打开会定位到已有标签。Ctrl+Tab 切换文件，Ctrl+W 关闭当前文件；标签右键可关闭其他、全部、左侧或右侧文件。

### 查找、替换与格式化

- Ctrl+F 查找，Ctrl+H 替换；支持区分大小写。
- F3 / Shift+F3 跳转下一处 / 上一处，Esc 收起查找替换栏。
- 替换支持当前匹配或全部非重叠匹配，替换文本留空表示删除；全部替换可一次撤销。
- Ctrl+Z / Ctrl+Y 撤销 / 重做，剪切复制粘贴使用常规 Ctrl+X/C/V。
- Ctrl+Shift+F 格式化 JSON、XML/XAML。含注释的 JSONC 不执行格式化，避免丢失注释。

### 文件支持与保存冲突

支持不超过 2 MiB 的 UTF-8（含 BOM）及带 BOM 的 UTF-16 LE/BE 文本；拒绝二进制和非法编码。保存保留编码、BOM、LF/CRLF 换行和 Unix 权限位。超过 250,000 字符会停用语法配色以保持输入响应。

保存会检查远端内容是否已被他人修改，再通过同目录临时文件和 SFTP POSIX rename 替换。发生冲突或服务器不支持该扩展时，保留当前编辑内容并报告失败。先复制自己的修改，再重新加载、比较并合并，不要直接重复覆盖。

替换文件可能改变所有者、ACL 或硬链接关系；需要保留这些属性的文件，请在保存前评估。未保存内容只在内存中，进程意外退出后无法保证恢复。

## 09 系统监控、进程与大文件排查

连接 Linux 后打开右侧“监控”入口，面板跟随当前终端。收起面板会停止采集，重新展开建立新的采样基线。

### 阅读指标

- 顶部显示连接名称、服务器地址和系统版本。复制地址请在左侧连接列表右键选择“复制IP地址”。
- CPU 首次显示“采样中”，后续按相邻采样计算利用率；悬停可查看型号等信息。
- 内存显示占用，悬停查看百分比和交换空间。
- 网络图显示最近一分钟所有非回环网卡的上传和下载速率，悬停查看时间及数值。
- 磁盘按设备去重显示概览，悬停查看各挂载点。

大小使用 1024 进位，界面单位为 b、K、M、G 等，例如 1536 字节显示 1.50 K；速度追加 /s。

### 排查进程

从 CPU/内存区域打开“进程详情”，点击列标题排序，再次点击切换升降序。查看 PID、用户、内存和完整命令行，刷新会保留排序和选中行。进程 CPU 按单核 100% 计算，多线程进程超过 100% 属正常情况。

### 查找大文件

点击磁盘概览打开大文件窗口，选择挂载点后手动开始扫描。扫描递归子目录、不跨文件系统，列出当前账号可访问的普通文件中最大的十项，按逻辑大小排名。扫描不是自动轮询，可取消，最长 120 秒。该窗口用于定位文件，不会自动清理磁盘。

监控需要可读 /proc、df、awk，进程详情需要 ps，大文件扫描需要 GNU find -printf 和支持 NUL 记录的 awk。缺少工具或权限时按面板错误处理。采集使用独立 SSH 通道，不占用交互终端输入。

## 10 Docker 容器管理

### 打开容器列表

连接后软件检测当前远端账号 PATH 中的 docker，检测成功才显示 Docker 入口。打开面板即可采集列表，包括容器状态、端口映射及运行中容器 CPU/已用内存。可搜索容器定位目标。

Docker 与 Kubernetes 列表支持拖动表头右侧边缘调整每列宽度；同一窗口内按资源类型保留调整结果，列较多时可横向滚动。长内容悬停可查看完整值。状态以圆点和文字颜色表示：绿色表示正常或已完成，黄色表示等待、过渡或副本未完全就绪，红色表示异常，灰色表示已停止或状态未知。

检测到 docker 不代表守护进程可用，也不代表当前账号具有访问权限。面板不会自动提权；出现权限或服务错误时，先在终端检查 docker ps。

### 详情、日志与操作

双击容器打开详情，可切换中文信息表格与 JSON 树，展开节点、搜索或复制原始内容。右键可查看日志、启动、停止和重启，操作前核对目标并确认。

右键操作按当前容器状态启用：运行中可停止、重启或进入容器；已退出或尚未启动的容器可启动。已停止（exited、created、dead）的容器可在右键菜单最下方选择“删除”，确认后删除容器及可写层，保留挂载卷，并立即刷新容器列表；不强制删除运行中的容器。

所有表格列表（文件、命令库、进程、磁盘及资源详情等）均可拖动表头边缘调整列宽，内容超出可用宽度时可横向滚动。

日志在独立窗口持续获取，可暂停或继续，并自动显示末尾。切换选中行不会改变已打开日志的目标；收起或切换面板、切换会话及断线会关闭相关详情和日志窗口。

### 进入运行中的容器

1. 选择运行中的容器，右键“进入容器”。
2. 在独立交互窗口中输入命令，顶部会标明主机与容器。
3. 默认优先 Bash，回退 sh，因此容器中至少需要 sh。
4. 输入 exit 或关闭该窗口只结束容器终端，不影响主机终端。

容器终端复用当前已认证 SSH 连接上的独立 PTY。切换主机不会改变已打开容器终端的目标；断开所属主机会终止它，退出会关闭容器窗口。

## 11 Kubernetes 资源与日志

### 环境与查询

Kubernetes 入口按远端工具检测结果显示，使用服务器当前账号的 kubeconfig 和 context。支持 kubectl，也支持 k3s kubectl 和 microk8s kubectl；本机的 kubeconfig 不会自动上传。

1. 打开 Kubernetes 面板，默认查询全部命名空间的 Pod。
2. 选择资源类型，如 Deployment、StatefulSet、DaemonSet、Service、ConfigMap、Secret、Ingress、PVC、Node 或 Namespace。
3. 选择或手动填写命名空间，点击“查询”应用。Node 等集群级资源不使用命名空间筛选。
4. 双击资源查看中文关键信息及原生 YAML，可复制、查找和查看字段说明。

列举命名空间受限时，可手动填写有权访问的命名空间。Pod CPU/内存指标不可用时仍保留资源列表，不要把指标缺失直接判断为 Pod 离线。

### 日志与重启

Pod、Deployment、StatefulSet、DaemonSet 支持日志；窗口持续获取最近 200 行，可暂停或继续。右键菜单仅显示对应资源支持的操作。

Deployment、StatefulSet、DaemonSet 重启使用 rollout restart。Pod 的“重启”通过删除实现，只有受控制器管理的 Pod 才会自动重建；确认前核对资源归属，独立 Pod 可能不会回来。

所有操作受远端账号的 Kubernetes RBAC 限制。切换类型、查询、面板或会话会关闭相关窗口并取消旧请求；取消不会撤销已在集群生效的操作。

## 12 跳板机、代理与端口转发

### 配置跳板链和代理

先将每台跳板机保存为常用连接，再在目标连接的“网络与跳板 → 跳板链”中按访问顺序填写连接名称，以逗号分隔。例如先经 bastion 再到目标服务器，就填写已保存的 bastion 连接名。逐台检查地址、凭据及主机指纹，避免名称混淆。

网络代理也在此页配置，填写代理主机、端口、协议和用户名；代理主机留空表示关闭。SSH KeepAlive 与应用连接心跳是不同设置，前者用于 SSH 保活，后者用于离线检测与重连。

### 本地转发示例

假设需要从 Windows 访问 SSH 服务器上的 127.0.0.1:5432：

1. 连接服务器，右键该终端标签选择“隧道管理”。
2. 类型选“本地转发”，绑定地址填 127.0.0.1，绑定端口填 15432。
3. 目标主机填 127.0.0.1，目标端口填 5432。
4. 点击“启动隧道”。在本机客户端连接 127.0.0.1:15432。

本地转发的目标地址从 SSH 服务器一侧访问，因此这里的目标 127.0.0.1 指 SSH 服务器自身。

### 其他转发类型

- 远程转发：在 SSH 服务器一侧监听端口，把连接转发到本机一侧可访问的目标。实际监听范围受服务器 GatewayPorts 等设置影响。
- 动态 SOCKS：在本机建立 SOCKS 入口，由支持 SOCKS 的客户端使用；无需填写固定目标。

默认绑定 127.0.0.1。动态 SOCKS 不提供认证；如改为公开监听，需自行限制访问范围。端口已占用、服务端禁止转发或目标服务不可达都会导致失败。隧道随所属会话释放，关闭或重连会话后应重新检查隧道状态。

## 13 输出录制与本地数据

### 输出录制

连接后右键终端标签选择“开始 / 停止录制”，确认提示并选择 .vt 保存位置；再次使用同一菜单停止。录制保存原始 VT 输出字节，不含时间戳，单次上限 100 MiB，不是视频文件。

输出可能包含命令回显、路径、令牌或密码，录制不会自动脱敏。分享前自行检查，并妥善保存录制文件。

### 数据位置与迁移

本地数据默认位于：

```text
%LOCALAPPDATA%\NovalTerm
```

其中 novalterm.db 保存配置等本地数据。Windows 凭据使用当前用户的 DPAPI；macOS / Linux 使用系统钥匙串保存的密钥进行认证加密。直接复制数据库到其他用户、系统或数据目录不保证能解密。跨机器迁移优先使用不含凭据的配置导出，并重新填写凭据。

从旧版 NexTerm 升级时，新版使用独立的 `%LOCALAPPDATA%\NovalTerm` 目录，不会自动读取旧目录。可在旧版导出连接配置后，在 NovalTerm 中导入并重新填写凭据。如需在同一 Windows 用户下保留全部本地数据，请先退出两个版本并备份数据，将 `%LOCALAPPDATA%\NexTerm` 中的内容复制到尚未使用的新目录，同时将 `nexterm.db`、`nexterm.db-wal`、`nexterm.db-shm`（如存在）分别更名为 `novalterm.db`、`novalterm.db-wal`、`novalterm.db-shm`，再启动 NovalTerm。不要覆盖已经使用过的新版数据库；旧目录可保留作备份。

远程编辑内容在内存中处理；“设置 → 清理编辑缓存”用于清理旧版本可能留下的 EditCache，不是恢复未保存文本的入口。请勿将数据库、私钥、真实会话日志或录制文件提交到公开仓库。

## 14 偏好设置与快捷键速查

通过“菜单 → 设置”调整工作区：

- 外观：深色、浅色或跟随 Windows，保存后应用；系统高对比度优先。
- 终端字体样式：下拉选择 Cascadia Mono（保留原默认字体）、JetBrains Mono、Source Code Pro 或 Hack，随软件内置，无需联网下载或额外安装；支持粗体和斜体。只影响终端命令窗口内容，其他界面字体不变；旧版默认配置继续使用 Cascadia Mono。字号范围 8–40。
- 字体和字号：保存后立即应用于所有已打开的终端（包括容器终端），无需重连或重启。
- 回滚行数：0–20000；仅对新建会话生效。
- 系统监控刷新周期：1–60 秒，默认 2 秒，保存后立即应用于监控与进程窗口。
- 连接心跳周期：1–60 秒，默认 5 秒，保存后立即生效。
- 本地数据：查看目录、清理旧编辑缓存、查看凭据引用信息。

### 主工作区

- F1：打开使用帮助。
- Ctrl+N：新建连接。
- Ctrl+K：搜索连接。
- Ctrl+Tab：切换终端标签。
- Ctrl+Shift+F：搜索终端回滚缓冲。

### 终端

- Ctrl+Shift+C / Ctrl+Insert：复制。
- Ctrl+C：有选区时复制，否则发送中断。
- Ctrl+V / Ctrl+Shift+V / Shift+Insert：粘贴。
- Ctrl+Space、↑↓、Enter、Esc：打开、选择、填入和关闭命令提示。
- Tab：远端补全。

### 文件编辑器

- Ctrl+S：保存到远程。
- Ctrl+F / Ctrl+H：查找 / 替换。
- F3 / Shift+F3：下一处 / 上一处。
- Ctrl+Shift+F：格式化 JSON、XML/XAML。
- Ctrl+Tab / Ctrl+W：切换 / 关闭文件。
- Ctrl+Z / Ctrl+Y：撤销 / 重做。

同一快捷键在不同窗口中含义可能不同，例如 Ctrl+Shift+F 在主窗口搜索终端，在编辑器中格式化。可通过“菜单 → 快捷键”快速查看。

## 15 AI 运维助手

### 配置服务商与模型

1. 展开右侧入口，选择“AI”；未连接服务器也能查询命令。
2. 点击输入区底部的模型选择器，在下拉列表底部选择“模型管理”。列表按分组展示配置，可搜索名称、模型 ID 或地址，并按分组和启用状态筛选。每行可直接启用、禁用、编辑或删除模型。
3. 点击“新增模型”进入空白表单，填写名称、分组、实际模型 ID、API 地址和 API Key；只有主动选择服务商预设时才自动填入预设内容。地址不包含 `/chat/completions`，分组可手动输入或选择已有分组，留空归入“未分组”。请求参数留空时使用页面说明的默认值。
4. 点击“保存配置”返回列表。编辑已有模型时回填全部配置，API Key 在密码框中遮盖显示；返回或取消不会保存修改。可分别指定默认对话和复杂诊断模型。禁用模型会解除对应的默认用途，该模型也不会出现在助手选择器中；发送前还会重新核对模型状态。
5. 模型管理列表中的“助手设置”单独打开和保存，控制所有模型共用的历史保留天数、生产环境限制、自动分析冷却时间和请求上限。
6. “测试连接”会发送简短问候请求，可能产生费用，不发送终端数据；再次点击可取消。GLM Coding Plan 使用官方模型候选，不请求 `/models` 列表接口；实际密钥及模型权限通过“测试连接”验证。

API Key 使用当前 Windows 用户身份加密保存。留空保留已有密钥；更换 API 地址时必须重新填写或明确清除密钥，避免将旧密钥发往新地址。本地回环兼容服务允许 HTTP 且可以不填写密钥，其他服务要求 HTTPS。

DeepSeek、Kimi/Moonshot、千问/百炼、智谱 GLM 等使用标准 API 配置。模型 ID、权限和地域须以服务商实际提供的信息为准。阿里云 Token Plan / Coding Plan 和 GLM Coding Plan 的适用资格尚未确认，当前不承诺套餐权益。

### 提问与浏览对话

顶部提供“新对话”“历史记录”图标和“自动识别”开关，鼠标悬停可查看提示。生成期间显示“停止”按钮。

在输入框填写问题，Enter 发送，Shift+Enter 换行；发送按钮的悬停提示也会显示这两个快捷键。输入法组合输入期间 Enter 用于确认输入。点击“停止”可取消当前生成，已有文字会保留并标记未完成。请求失败会保留问题草稿。“新对话”清空当前对话上下文和待发送的附加内容。

用户消息显示为右对齐的圆角气泡，AI 回复显示在气泡下方，不再使用“你 / AI”文字标签。同一轮的多段 AI 回复之间使用细分隔线。

对话区左侧的小圆点用于快速定位各轮问题：悬停预览问题，点击跳转，当前轮次会高亮。最多同时显示 7 个圆点，将鼠标移到圆点区域滚动可查看更多；较早的对话内容会在定位时补载。

查看较早消息时，对话区底部中央会显示向下的悬浮按钮。点击“回到最新消息”跳至底部，到底后按钮自动隐藏；内容不需要滚动时也不显示。

### 分析终端选区

默认使用普通对话模式，不会自动读取终端或查询服务器状态。需要分析输出时，先在终端选中文本，再使用终端右键“AI 解释选区 / AI 分析报错”。这些操作准备问题并附加选区，面板会提示附加的字符数，发送由用户触发。

终端选区超过 16000 字符会截断。程序对常见密钥字段、Authorization 和私钥做基本脱敏，但不能保证识别全部秘密；选择内容前请检查是否包含敏感信息。问题、对话历史及附加内容会发送到所选服务商。使用“新对话”可停止后续携带旧对话内容，不能撤回已发送的数据。

### 助手设置与用量

通过主窗口“菜单 → 设置”，找到“AI 助手”区域，可配置以下项目，点击“保存设置”后立即生效：

AI 对话历史自动加密保存，默认保留 30 天，可在 AI 历史窗口中清空。
- “使用复杂诊断模型”：优先使用模型管理中指定的复杂诊断模型；未指定或不可用时使用当前选择的模型。
- “允许 AI 使用的只读查询”：系统状态、容器状态、进程端口、服务状态默认允许，读取日志默认关闭。连接终端且模型接口支持工具调用时，AI 可按需查询勾选的信息，无需开启“自动识别”。

模型的上下文/输出上限、思考、流式、JSON 回答、用量请求及单价在“模型管理”的模型配置中调整；历史保留天数、生产环境限制、自动分析冷却和请求上限在模型管理列表的“助手设置”中调整。

Token 用量显示在底部模型选择器旁：蓝色“↑”表示输入，绿色“↓”表示输出，两组数字分开显示。悬停可查看输入、输出、合计及已配置价格下的估算费用；费用不是套餐余量。服务商未返回用量时，该位置不显示内容。

### 阅读回答与使用命令

AI 回答按 CommonMark/GFM Markdown 展示，支持六级标题、粗体/斜体/删除线、行内代码、有序/无序及嵌套列表、任务列表、引用、分隔线、表格及列对齐、链接、脚注、定义列表和代码块，额外支持公式和基础 Mermaid 流程/时序图；不支持的图表语法保留源码。流式生成期间先显示正文，完成后呈现完整排版及代码操作；正文可选择复制。代码块显示语言和基础语法高亮，长行可水平滚动。链接点击后才打开浏览器，HTTPS 图片点击“加载图片”后显示；原始 HTML 作为文本展示，不执行脚本。

完整代码块下提供“复制”；明确标注为 Shell 的完整单行命令另有“执行”。点击后自动聚焦绑定终端，一次性发送命令和回车，无需提前点击终端或手动回车。点击前请检查命令、参数和目标；命中本地高风险规则时仍需确认。

终端必须已连接且处于可识别的 Shell 提示符；已有可追踪输入时先显示替换并执行确认，确认后再次检查目标。全屏程序或输入行状态未知时不会执行。代码“预览”可编辑、查看语法配色和复制，并提示命中的本地高风险规则；这不等同于语法校验。多行脚本可选中一条完整单行，点击“执行选中单行”，不会整体发送多行脚本。执行时，`{{name}}` 或 `<name>` 参数由表单填写并进行 Shell 引用，占位符须位于引号外。未完成或中断的回答不会开放执行与应用。

点击“收藏”会先打开可编辑的名称和正文，核对后点击“保存收藏”，即可在“菜单 → 命令片段”中查看、编辑和使用。收藏前会进行基本脱敏，并将 `{{name}}` 转为命令片段使用的 `${name}`；`<name>` 会保留原文，需要取用时询问参数则请自行改为 `${name}`。相同正文不会重复收藏，脱敏占位内容需在使用前检查。

### 历史记录与摘要

对话与草稿按运行期 SSH 会话隔离，切换会话停止原请求；旧回答不能作用于新连接。聊天默认仅存内存，历史记录窗口可查看本次运行中的对话；通过“菜单 → 设置 → AI 助手”启用加密历史。历史窗口支持搜索、重命名、恢复和删除。同一 Windows 用户可解密，默认保留 30 天，可在模型管理的“助手设置”中配置 1–365 天；最多 100 个历史对话。

选中一条对话后可导出，导出先显示可编辑脱敏预览。“重试问题”恢复该对话并将最后一个问题回填到输入框，“生成摘要”恢复该对话后发送摘要请求。重试和摘要需连接对应服务器，且当前没有正在生成的回答。

### 自动识别与连续排障

连接终端后，勾选顶部“自动识别”并确认数据去向，可在提问时附加开启后的新增终端输入输出，并在命令完成后自动分析。未开启时不会自动读取终端输入输出，仍可通过右键等入口手动附加内容。只读信息查询由“菜单 → 设置 → AI 助手”中的查询范围独立控制，无需开启自动识别，日志默认关闭。接口本身需支持工具调用，可在模型配置中“测试工具”。普通模型可直接分析附加内容。

自动附加的终端快照标注时间、目录、序号、退出码及行号，采集不包含当前未提交输入。增量边界不明确时跳过该片段，可选中需要的内容后通过终端右键分析；全屏程序不自动推断命令归属。

连接终端并允许“系统状态”后，可直接提问“这台服务器 CPU 型号是什么”“内存多大”“系统版本是什么”，无需开启自动识别。AI 可调用只读系统信息查询并根据结果回答，无需点击命令的“执行”。此查询受“菜单 → 设置 → AI 助手 → 系统状态”控制，覆盖 CPU 型号/架构/核心线程、内存、系统/内核及磁盘型号容量；实时占用使用状态查询。查询通过绑定服务器的独立 SSH exec 完成，不改变交互终端输入。工具不可用或信息未暴露时应说明原因，不推测结果。完成状态会显示本轮调用次数，结果见回答；若显示“模型未调用只读查询”，代表本轮没有实际查询。

“自动识别”开启后同时读取新增输出并在命令完成后自动分析。完成检测需 Bash/Zsh/Fish 提示符集成。默认冷却 10 秒、每次开启最多 20 次自动请求，可在模型管理的“助手设置”中修改；不按每行输出触发，模型建议仍需用户点击“执行”。收起面板暂停采集/分析，再展开不回补隐藏期间的内容。断开、切换会话会取消请求。关闭自动识别不能撤回已发送数据，需清除上下文可新建对话。模型管理的“助手设置”可禁止生产服务器开启自动识别。

所有查询都使用固定只读模板、串行、超时和每轮最多 5 次的限制，不会自动 sudo。独立 SSH exec 的目录与环境可能不同于交互终端，结果会标注。命令已发送执行或退出码为 0，均不代表业务验证通过。

上下文预算会为回答、工具定义及协议开销预留空间。查询结果较大时，程序先从本次请求移除旧轮次，再按剩余预算保留工具结果头尾，标注中间省略；聊天历史和本地工具记录保留原有长度范围内的内容。状态区会提示压缩情况，省略部分不能视为已验证。如果当前问题、附加内容或思考内容本身已占满预算，仍需缩短内容、减少查询范围，或按模型真实能力调高上下文设置。JSON 模式完整接收后展示 Markdown。

### 其他入口与文件修改

终端右键可解释选区、分析报错、检查当前输入命令。Docker/K8s 面板的“AI 分析”将快照附加到对话，仍由用户点击发送，优先使用所选资源，避免混用其他资源日志。

远程编辑器点击“AI 解释 / 检查 / 修改”，确认文件与问题后发送。返回完整代码块旁有“审阅文件差异”：可编辑建议、比较前后内容及逐行差异，校验 JSON/XML/YAML，然后应用到编辑缓冲区。文件或目标变化会拒绝应用；超出模型预算时不会发送截断的完整文件。建议若包含脱敏占位符，必须在差异窗口本地恢复真实值后才能应用，不能直接将占位符写回配置。保存到服务器仍需手动点击保存并经过原有并发冲突检查。“恢复 AI 修改前内容”恢复缓冲区备份，再保存也检查远端变化。不自动重载服务。

自主执行任意命令、无人值守修复、跨服务器批量操作目前明确保留 TODO。

## 16 常见问题与排查顺序

### 连接超时或被拒绝

先确认地址和端口，再检查本机网络、VPN、代理、跳板链及服务器防火墙。超时通常表示网络链路不可达；连接被拒绝时检查 SSH 服务是否启动、是否监听预期端口。可在 Windows PowerShell 中测试：

```powershell
Test-NetConnection your-server.example.com -Port 22
```

将示例地址和端口替换为实际值。端口可达只说明 TCP 可访问，仍需继续核对 SSH 认证。

### 认证失败或主机指纹变化

认证失败时核对用户名、认证方式、密码、私钥路径和口令，确认服务器是否允许该用户及认证方式。主机指纹变化需先向管理员核实，再处理信任记录，不能通过重输密码解决。

### 文件区与终端目录不一致

确认当前选中的会话，终端命令是否已经结束并返回提示符，以及是否进入未集成的 Shell。手动在文件区输入远程路径并刷新；使用 chroot 时以 SFTP 可见路径为准。

### 文件无法下载、删除或编辑保存

先检查远端权限、文件类型、文件大小、本地目标重名和文件名是否合法。文件夹可递归下载，但其中的符号链接、Windows 路径冲突或目录扫描上限会导致拒绝；非空目录不能递归删除。续传失败时检查部分文件及配套记录是否齐全、保存位置是否正确、源文件是否变化。编辑保存冲突需合并远端变化，不支持 POSIX rename 的服务器需改用其他受控编辑方式。

### Docker 或 Kubernetes 入口未出现

在同一账号下确认命令位于 PATH，必要时重新展开入口触发检测。工具存在后仍报错时，检查 Docker 守护进程、访问权限，或 Kubernetes kubeconfig、context、网络与 RBAC。

### 监控没有数据或网络速率短暂为空

先等待至少两轮采样。确认远端为 Linux，具有 /proc 和所需工具权限；新展开面板时 CPU 和网络需要建立基线。非 Linux 系统或工具缺失应按错误提示处理。

### 断线后任务是否仍在运行

重新连接不会恢复旧 Shell。先在远端确认任务状态，再决定是否重试，尤其避免重复执行发布、迁移或批量修改。长任务建议在服务器上使用 tmux、screen 或适合的后台服务方式。

### 如何反馈问题

记录“菜单 → 关于 NovalTerm”中的版本、Windows 版本、操作步骤、预期结果和实际错误。涉及终端时补充服务器系统及 Shell 类型，涉及文件时补充编码和大小。分享截图或日志前移除密码、令牌、私钥和真实连接敏感信息。