AuraTerm User Manual

AuraTerm 用户手册

从安装、连接、文件传输到端口转发、自动化与端到端加密云同步的完整使用指南。

概述与安装

欢迎使用 AuraTerm——一款现代化的跨平台终端模拟器，可在 Windows、macOS 和 Linux 上运行。无论你是要 SSH 进入远程服务器、调试串口设备、连接 Telnet 主机，还是只想打开一个本地 Shell，AuraTerm 都希望让这一切既顺手又愉快。

AuraTerm 是什么

AuraTerm 是一个统一的终端工作台，把日常常用的连接方式集中到一个应用里。它支持四类连接：SSH2、Telnet、串口和本地 Shell。在此基础上，它提供多标签页与分屏、书签侧栏、命令面板、文件传输（SFTP 与 Zmodem）、端口转发隧道、快捷按钮、输出规则等贴近实际工作流的能力。

在技术上，AuraTerm 基于 Tauri v2 构建，前端采用 Vue 3，核心后端使用 Rust。SSH 连接由 Rust 的 russh 库驱动。这套架构让安装包保持小巧、启动迅速，同时把凭据加密、主机密钥校验等安全敏感的操作放在原生 Rust 层处理。

支持的平台

  • Windows：通过安装程序（.exe）安装。
  • macOS：通过磁盘映像（.dmg）安装。
  • Linux：以 AppImage 形式发布，下载后赋予可执行权限即可直接运行。

下载与安装

请从 AuraXLab 官网或项目发布页获取对应平台的安装包，再按下面的步骤安装。所有平台都使用同一个版本号，请尽量选择最新版本。

Windows：双击 setup 安装程序（文件名形如下方示例），按提示完成安装。安装完成后可从开始菜单或桌面快捷方式启动 AuraTerm。

AuraTerm_0.2.8_x64-setup.exe

macOS：打开下载的 .dmg，将 AuraTerm 拖入「应用程序」文件夹，然后从启动台或「应用程序」中打开它。

AuraTerm_0.2.8_aarch64.dmg

Linux：下载 AppImage 后，给它加上可执行权限即可运行，无需系统级安装。

chmod +x AuraTerm_0.2.8_amd64.AppImage && ./AuraTerm_0.2.8_amd64.AppImage
示例文件名中的版本号（如 0.2.8）和架构标识（x64 / aarch64 / amd64）仅供参考，请以你实际下载到的文件为准。

首次启动

首次打开 AuraTerm 时，你会看到带自定义标题栏的主窗口和一个空的工作区。此时还没有任何已保存的连接，你可以直接新建一个连接，或先把常用主机加入书签侧栏以便日后快速重连。

AuraTerm 默认不会强制你设置主密码。在没有设置主密码时，凭据会用设备本地生成的随机密钥加密保存（v3 模式）；你也可以随时在设置中启用主密码，改为由主密码派生密钥（v2 模式），获得更强的保护。这些都可以稍后在「设置」里调整，首次启动无需立即决定。

当你首次连接某台 SSH 主机时，AuraTerm 会采用「首次信任」（TOFU）机制记录其主机密钥指纹；若日后指纹发生变化，会弹出不匹配提示，默认在 180 秒后拒绝连接。这是正常的安全防护，请留意此类提示。

配置文件存储在哪里

AuraTerm 把所有设置、连接、凭据和安全数据保存在操作系统的应用配置目录中，目录以应用标识符 com.auraxlab.auraterm 命名。各平台的位置如下。

Windows:  %APPDATA%\com.auraxlab.auraterm
macOS:    ~/Library/Application Support/com.auraxlab.auraterm
Linux:    ~/.config/com.auraxlab.auraterm

该目录中你通常会看到这些文件：

  • settings.json——应用设置（主题、字体、渲染器等）。
  • connections.json——已保存的连接与书签元数据（不含明文密钥）。
  • credentials.enc——加密保存的凭据（密码、私钥、口令）；在设备本地密钥模式下还会有一个 credentials.key。
  • ssh_known_hosts.json——记录每个 host:port 的 SHA-256 主机密钥指纹。
  • sync_config.enc——加密保存的云同步配置（启用云同步后生成）。
  • security_audit.log——安全审计日志，例如主机密钥不匹配的覆盖记录。
凭据始终与连接元数据分开存放，并使用 AES-256-GCM 加密，密钥由 Argon2id 从主密码派生（v2 模式），或在未设主密码时使用设备本地随机密钥（v3 模式）；内存中的明文密钥在使用后会被清零。这意味着 connections.json 等文件不包含任何明文密码，但 credentials.enc 仍属敏感数据，请妥善备份与保管。

界面与标签页

AuraTerm 的主界面围绕一个自定义标题栏和一个多标签的终端区域构建。本节介绍如何管理标签页、拆分窗格、使用书签侧栏和命令面板，以及调整查找、字号、全屏和渲染器等显示相关的设置。

自定义标题栏

AuraTerm 在 Windows、macOS 和 Linux 上都使用一个统一的自定义标题栏，而非系统原生的窗口边框。标题栏承载着标签页和窗口控制，使三大平台上的外观保持一致。

多标签管理

每个连接都在自己的标签页中打开。你可以随时新建标签、关闭标签，并在打开的标签之间切换。

  • 新建 / 关闭 / 切换：创建新标签、关闭不再需要的标签，并在已打开的标签之间切换。
  • 拖拽重排：直接拖动标签即可调整它们的顺序。
  • 右键重命名：右键点击某个标签即可为它指定一个自定义名称。
  • 自动 NATO 字母后缀：当同一连接打开多个标签时，AuraTerm 会自动追加 NATO 字母后缀（如 Alpha、Bravo、Charlie）以便区分。

拆分窗格

在单个标签页内，你可以将终端区域拆分为多个窗格，从而在同一屏幕上并排查看多个会话——非常适合一边查看日志、一边输入命令的场景。

书签侧栏

书签侧栏让你保存常用连接，并通过它快速重新连接。书签可以按任意深度的嵌套文件夹分组管理，侧栏还提供过滤/搜索框，便于在大量条目中快速定位。

  • 折叠状态会被持久化保存——下次打开 AuraTerm 时，各文件夹的展开/折叠状态与你上次离开时一致。
  • 你可以导入 OpenSSH config 和 PuTTY 的 .reg 文件，导入时会自动去重。

命令面板

命令面板是不离开键盘就能触达各项功能的最快方式。按 Ctrl/Cmd+Shift+P 打开它，然后输入关键字即可进行模糊匹配搜索，快速跳转到对应命令。

终端查找

按 Ctrl/Cmd+F 可在当前终端的输出中进行查找。查找支持区分大小写、全词匹配和正则表达式三种匹配选项。

字号缩放与全屏

  • 放大字号：Ctrl + +
  • 缩小字号：Ctrl + -
  • 重置字号：Ctrl + 0
  • 切换全屏：F11

渲染器设置（WebGL / DOM）

AuraTerm 提供 WebGL 与 DOM 两种终端渲染器供你在设置中选择。WebGL 渲染器通常更适合高刷新率和大量输出的场景；如果在某些显卡或驱动上遇到显示异常，可以切换到 DOM 渲染器以获得更好的兼容性。

很多界面操作既能用鼠标完成，也能通过命令面板（Ctrl/Cmd+Shift+P）触发。如果记不住某个快捷键，打开命令面板按名称搜索通常是最快的途径。

建立连接

AuraTerm 支持四种会话类型：SSH（基于 russh 的 SSH2）、Telnet、串口（Serial）和本地 Shell。无论哪种类型，你都可以即时连接，也可以将连接保存为书签以便日后快速重连。本节介绍如何创建每种连接、配置认证与重连，以及连接成功后的自动化处理。

创建 SSH 会话

SSH 是最常用的连接方式。填写主机地址、端口和用户名，选择一种认证方式即可连接。AuraTerm 提供三种认证方式：密码、私钥和 SSH agent。

  • 密码：直接输入登录密码。密码作为凭据被单独加密存储，不会与连接元数据混在一起。
  • 私钥：使用本地私钥文件认证；如果私钥设有口令（passphrase），AuraTerm 会提示输入并可安全保存。
  • SSH agent：复用系统中正在运行的 SSH agent 所持有的密钥，无需在 AuraTerm 中重复配置私钥。

多因素认证（MFA）

当服务器要求键盘交互式认证（例如一次性验证码、动态令牌或额外的安全问题）时，AuraTerm 会在连接过程中弹出交互式 MFA 提示，逐项显示服务器发来的问题并等待你输入。按提示完成后继续登录。

跳板机（Jump Host）

如果目标主机位于内网、需要经过一台或多台中转主机才能到达，可配置跳板机。AuraTerm 支持 ProxyJump 链，即可以串联多级跳板逐跳连接到最终目标，无需手动建立多层隧道。

Agent 转发与主机密钥信任

Agent 转发允许在远端会话中使用本地 SSH agent 的密钥（例如从远端再跳到第三台主机）。出于安全考虑，agent 转发默认关闭，仅在你信任目标主机时才应开启。

AuraTerm 对主机密钥采用 TOFU（首次使用即信任）策略：首次连接某主机时记录其密钥指纹，之后每次连接都会校验。已知主机的指纹以 SHA-256 形式按 host:port 保存。

如果某主机的密钥与之前记录的不一致，AuraTerm 会弹出不匹配提示。该提示默认在 180 秒后自动按“拒绝”处理，任何信任覆盖操作都会写入安全审计日志。可疑的不匹配可能意味着中间人攻击，请谨慎确认后再继续。受信任的主机可在“设置”中查看、管理和重置。

重连模式

SSH 会话断开后，按 R 可重新连接。AuraTerm 提供四种重连模式，决定重连后会话状态如何恢复：

  • manual（手动）：仅在你手动触发时重连，不做额外处理。
  • simple（简单）：自动重新建立 SSH 连接并开启新的 shell。
  • tmux：重连后接回远端的 tmux 会话，从而恢复之前正在运行的程序与窗口。
  • screen：与 tmux 类似，但接回远端的 GNU screen 会话。
tmux 和 screen 模式依赖远端服务器上已安装并运行相应工具。如果远端没有可接回的会话，效果将退回为新开 shell。

Telnet 会话

Telnet 连接只需主机地址和端口。请注意 Telnet 是明文协议，不提供加密；仅建议在受信任的本地网络或访问不支持 SSH 的老旧设备时使用。

串口（Serial）会话

创建串口会话时，AuraTerm 会自动枚举系统中可用的串口供你选择。你可以分别配置波特率、数据位、停止位、校验位和流控制。

为省去逐项设置的麻烦，AuraTerm 内置了三个常用预设，一键套用：

  • 115200-8N1：115200 波特、8 数据位、无校验、1 停止位（最常见）。
  • 9600-8N1：9600 波特、8 数据位、无校验、1 停止位。
  • 57600-8N1：57600 波特、8 数据位、无校验、1 停止位。

本地 Shell 会话

本地 Shell 让你在 AuraTerm 中直接打开本机的命令行环境。你可以选择具体使用哪种 shell：

  • 自动检测：优先使用 Git Bash，若不存在则回退到 CMD。
  • PowerShell、cmd.exe：直接指定 Windows 上的对应 shell。
  • 自定义路径：指向任意可执行 shell 的完整路径，用于使用其他 shell。

连接后命令与自动登录

会话建立后，AuraTerm 可以自动发送预设的命令，省去每次手动输入的步骤。常见用途包括连接后自动切换目录、设置环境变量、启动监控程序，或在交互式登录流程中按规则自动应答。

对于需要逐步交互的登录（例如先连后再输入用户名/密码的设备），可结合输出规则的自动应答能力：当终端输出匹配到指定关键字或正则时，自动发送对应的响应文本，从而实现自动登录。规则可设为全局或仅对特定主机生效。

保存为书签

任何类型的连接都可以保存为书签，并归入可任意嵌套的文件夹分组，便于检索和快速重连。书签支持过滤搜索，并会记住分组的折叠状态。你还可以直接导入 OpenSSH 配置或 PuTTY 的 .reg 文件，导入时会自动去重。

所有密码、私钥和口令等机密都与连接元数据分开存储：凭据保存在以 AES-256-GCM 加密的 credentials.enc 中，密钥由主密码经 Argon2id 派生，或在未设置主密码时使用设备本地随机密钥。使用过的机密在内存中会被及时清零。

书签管理

书签让你把常用的连接保存下来，下次一键重连，无需重新填写主机、端口、认证方式等参数。书签适用于所有连接类型——SSH、Telnet、串口和本地 Shell。保存后的书签显示在左侧的书签侧边栏中，可随时打开、搜索或整理。

保存连接为书签

在新建或编辑连接时，将连接配置保存为书签即可。书签会记录该连接的全部元数据——主机地址、端口、用户名、认证方式、跳板机链、重连模式、串口波特率等参数。对于 SSH，你还可以把端口转发隧道一并保存进书签（可设置 autoStart 自动启动），重连后隧道会自动重建。

嵌套文件夹分组

书签可以放进文件夹分组中，分组支持任意层级嵌套——你可以按团队、环境（生产 / 测试）、机房或客户等维度组织成一棵清晰的树。每个分组的展开 / 折叠状态会被持久化保存，下次打开 AuraTerm 时会保持你上次的整理视图。

筛选与搜索

当书签数量增多时，使用侧边栏顶部的筛选 / 搜索框可以快速定位目标连接。输入关键字即可按书签名称等进行过滤，从一长串列表中迅速找到你要的那一个。

快速重连

在侧边栏中找到书签后，双击（或点击打开）即可用保存的配置立即发起连接，在新标签页中打开会话。这就是书签的核心价值：把日常重复的连接操作压缩为一次点击。

对于 SSH 会话，断开连接后可直接按 R 重连；重连行为遵循书签中保存的重连模式（手动 / simple / tmux / screen）。

导入 OpenSSH config 与 PuTTY .reg

如果你已经在其他工具中维护了大量主机配置，无需手动重建。AuraTerm 可以导入标准的 OpenSSH config 文件，以及从 PuTTY 导出的 .reg 注册表文件，把其中的主机定义批量转换为书签。

  • OpenSSH config：解析 Host 条目及其主机名、端口、用户、身份文件等设置。
  • PuTTY .reg：读取从 PuTTY 导出的已保存会话，转换为对应的书签。

导入时会自动去重：与已有书签重复的条目不会被再次添加，因此你可以放心地多次导入或合并来自不同来源的配置，而不会在侧边栏里堆出一堆重复项。

书签元数据与密钥分别存储

AuraTerm 在设计上将连接元数据与敏感密钥分开存放。书签本身（主机、端口、用户名、分组结构、隧道定义等非敏感配置）保存在应用配置目录下的 connections.json 中。

密码、私钥、密钥口令等机密绝不会写入书签文件，而是单独保存在加密文件 credentials.enc 中：使用 AES-256-GCM 加密，密钥由 Argon2id 从主密码派生（v2 模式），或在未设置主密码时由设备本地随机密钥派生（v3 模式，此时还会有一个 credentials.key 文件）。机密在使用后会在内存中清零。

这种分离意味着即使有人拿到了 connections.json，也只能看到连接元数据，无法获得你的密码或私钥。如果你使用云同步，书签始终会被同步，而保存的凭据只有在主密码已解锁时才会一并同步。

文件传输（SFTP 与 Zmodem）

AuraTerm 为 SSH 会话提供两种文件传输方式：图形化的 SFTP 浏览器，适合浏览目录、批量上传下载与就地编辑文本；以及内联的 Zmodem（rz/sz），适合在终端命令行中快速收发单个文件。两者可以配合使用。

SFTP 浏览器

SFTP 浏览器在远程主机的文件系统上提供一个可视化的文件管理面板。你可以将它配置为在 SSH 连接建立后自动打开，从而立即获得文件视图；该自动打开行为是可选的，可按需启用或关闭。

在浏览器中，你可以执行以下常见操作：

  • 浏览目录、进入子目录并在远程文件系统中导航。
  • 上传本地文件到当前远程目录，下载远程文件到本地。
  • 新建目录（mkdir）。
  • 删除文件或目录。

上传也支持拖放：直接把本地文件拖入 SFTP 浏览器即可开始上传，无需先点击上传按钮。

传输队列与断点续传

多个传输会进入一个顺序队列，逐个执行而非同时进行，这样可以保持稳定、可预期的传输节奏。对于较大的文件，你可以启用可选的断点续传，在传输中断后从已完成的位置继续，而不必从头重传。

就地编辑文本文件

在 SFTP 浏览器中双击一个文本文件即可直接打开编辑，省去先下载、再上传的往返过程。编辑完成后用 Ctrl/Cmd+S 保存，更改会写回远程文件。

就地文本编辑有 2 MiB 的大小上限。超过该上限的文件无法以此方式编辑，请改用下载、在本地编辑后再上传的方式处理。

内联 Zmodem（rz / sz）

AuraTerm 内置对 Zmodem 的支持，可在终端会话中内联收发文件。当你在远程主机上运行 rz（接收，即从本地上传到远程）或 sz（发送，即从远程下载到本地）时，AuraTerm 会自动检测到 Zmodem 传输并接管处理，无需额外的菜单操作。

rz
sz <filename>

传输期间会显示进度，你也可以随时取消正在进行的 Zmodem 传输。

通过 sz 下载的文件会保存到一个可配置的下载路径。如果默认位置不合适，可在设置中调整该路径，以决定接收到的文件落地到哪个本地目录。

SFTP 浏览器与 Zmodem 均面向 SSH 会话的文件传输。两者各有所长：需要在目录树中浏览、批量传输或就地改文本时用 SFTP；只想在命令行里快速发一个文件时用 rz/sz 更顺手。

端口转发与隧道

AuraTerm 可以在 SSH 连接之上建立端口转发隧道，把本地或远端的网络流量安全地穿过加密通道。它支持三种经典的转发模式——本地转发（-L）、远程转发（-R）和动态转发（-D，SOCKS5 代理），并提供一个集中的隧道管理器来添加、编辑、启停和监控每条隧道。

三种转发模式

本地转发（-L）把你本机上的一个端口映射到从 SSH 服务器看得到的某个目标地址。本机上对该端口的连接会经由隧道转发到远端目标。常用于从本地访问只在服务器内网可达的数据库、Web 后台等服务。

远程转发（-R）方向相反：它在 SSH 服务器上打开一个端口，服务器端对该端口的连接会被转发回你本机能访问的目标地址。常用于把本地正在开发的服务临时暴露给远端环境。

动态转发（-D）在本机上启动一个 SOCKS5 代理。把浏览器或其他应用的代理指向这个端口后，它们的流量都会经由 SSH 服务器出站，相当于一个轻量的按需 VPN。

隧道管理器

隧道的创建与运维都在隧道管理器中完成。你可以从工具（Tools）菜单打开它，也可以通过命令面板（Ctrl/Cmd+Shift+P）搜索并打开。

在管理器中，你可以对隧道执行以下操作：

  • 添加 / 编辑 / 删除隧道，并选择其转发类型（-L、-R 或 -D）。
  • 逐条启动 / 停止隧道，互不影响。
  • 查看每条隧道的状态：starting（启动中）、active（已就绪）或 error（出错）。

当某条隧道显示 error 时，通常意味着本地端口被占用、目标地址不可达，或服务器端不允许该转发。修正配置后重新启动即可。

把隧道保存到书签

隧道可以保存到某个书签上，与连接信息一同持久化。这样，每当你打开该书签建立连接时，就不必再手动重建隧道。

  • 启用 autoStart（自动启动）后，连接建立时对应的隧道会自动开启。
  • 保存到书签的隧道会在重连后自动重建，因此在简单、tmux、screen 等重连模式下掉线再连接时，隧道无需手动恢复。
端口转发依托于底层的 SSH 连接：连接断开时隧道也会随之中断。只有保存到书签的隧道才会在重连后自动重建；临时创建、未保存的隧道在断线后需要手动重新启动。

输入工具栏与自动化

AuraTerm 的输入工具栏把日常重复的击键变成可复用、可参数化、可自动响应的操作。本节介绍三件配合使用的工具：底部的输入栏，用于撰写并发送多行命令；快捷按钮 / 片段，把常用命令收纳成一键即发的工具栏；以及输出规则，让终端在匹配到关键字时自动高亮、提醒或回复。本节最后讲解基于 OSC 133 的 Shell 集成，它让 AuraTerm 理解命令的边界与退出码。

输入栏

输入栏位于终端窗口底部，是一个支持多行编辑的编辑框。你可以在这里完整地拼好一条长命令或一段脚本，确认无误后再一次性发送给会话，避免在终端里边打边纠错。

  • 发送：按 Ctrl+Enter 将当前内容发送到会话。单独的 Enter 用于在输入栏内换行，便于撰写多行内容。
  • 调整高度：拖动输入栏的边缘即可改变它的高度，给较长的内容腾出空间。
  • 折叠：双击输入栏即可将其折叠收起，把更多空间留给终端输出；再次操作可重新展开。
  • 历史记录：用 PageUp / PageDown 在之前发送过的内容之间向前 / 向后翻阅，快速复用历史命令。

快捷按钮 / 片段

快捷按钮（也称片段）是把常用命令固定成一键即发的小按钮。你可以创建多个工具栏，并在工具栏内用分组来归类，让数量众多的按钮保持井井有条。

  • 主机 / 书签组绑定：按钮或工具栏可以绑定到特定主机或书签组，这样它们只在相关连接中出现，不会让无关会话被无用按钮淹没。
  • {{变量}} 参数：在按钮内容里写入 {{变量}} 形式的占位符，发送前 AuraTerm 会提示你填入实际值，便于把同一条命令模板复用到不同目标或参数上。
  • 原始控制字符：按钮可以发送原始控制字符（如 Ctrl 组合键、转义序列），适合发送中断信号或与全屏程序交互等场景。

输出规则

输出规则会持续监视终端输出，当某段文本与你设定的条件匹配时自动触发动作。这对盯日志、等待长任务完成、或应答可预测的交互提示都非常有用。

  • 匹配方式：可按关键字或正则表达式匹配。
  • 动作：命中后可执行高亮显示、响铃、桌面通知，或自动回复（向会话回发一段预设文本）。
  • 冷却时间：为规则设置冷却时间，避免在短时间内反复触发造成刷屏式通知或重复回复。
  • 作用范围：规则可设为全局生效，或限定到某台主机（按主机范围生效）。
自动回复会把文本真实地发回会话——请谨慎为生产主机设置，并尽量使用精确的匹配条件，避免误触发把意外内容发给服务器。

Shell 集成（OSC 133）

当远端 Shell 发出 OSC 133 转义序列时，AuraTerm 就能识别每条命令的起止边界，这一能力称为 Shell 集成。启用后，终端不再只是字符流，而是能按“命令”进行结构化理解。

  • 命令标记与退出码：每条命令都会被打上标记，并记录其退出码，便于一眼区分成功与失败的命令。
  • 命令间导航：用 Ctrl/Cmd+Shift+Up / Down 在上一条 / 下一条命令的标记之间跳转，快速回溯长输出。
  • 重新运行与复制：针对已标记的命令，可以重新运行它，或复制该命令本身。
Shell 集成依赖远端 Shell 主动发送 OSC 133 序列。若你的 Shell 尚未配置发送这些标记，命令导航与退出码等功能将无法生效。

凭据安全与加密

AuraTerm 把连接信息和敏感凭据分开存放。主机名、端口、用户名、串口参数等连接元数据保存在 connections.json 里；而真正的秘密——密码、私钥、私钥口令——则被单独加密保存在 credentials.enc 中。即使有人拿到了你的连接列表，也读不到其中的任何凭据。

加密是怎么做的

凭据文件使用 AES-256-GCM 进行认证加密（既保密又防篡改），加密所用的密钥不会直接存盘，而是通过 Argon2id 这一抗暴力破解的密钥派生函数推导出来。秘密在内存中使用完毕后会被立即清零（zeroize），尽量缩短它停留在内存里的时间。

两种密钥模式：主密码 vs 设备本地密钥

根据你是否设置了主密码，AuraTerm 会以两种模式之一保护凭据：

  • 主密码模式（mode v2）：加密密钥由你的主密码经 Argon2id 派生。秘密真正掌握在你手中——主密码不会被存盘，没有它就无法解密 credentials.enc。这是最强的保护方式。
  • 设备本地密钥模式（mode v3）：当你没有设置主密码时，AuraTerm 会在本机生成一个随机密钥并保存为 credentials.key，凭据用它来加密。这样无需每次输入密码就能直接使用，方便，但保护强度取决于该设备本身的安全性——任何能读取这两个文件的人都能解密你的凭据。
设备本地密钥模式下，credentials.enc 和 credentials.key 通常就放在同一个应用配置目录里。如果有人能够访问这个目录（例如未加密的磁盘、备份或共享账户），你的凭据就形同明文。在共享或不受信任的设备上，请务必设置主密码。

设置、解锁、修改与停用主密码

  • 设置：首次设定主密码后，AuraTerm 会把凭据从设备本地密钥模式迁移到主密码模式（v3 → v2），并用新派生的密钥重新加密。
  • 解锁：启用主密码后，每个会话首次需要用到凭据时都会要求你输入主密码进行解锁；解锁后才能读取保存的密码和私钥。
  • 修改：你可以更换主密码。AuraTerm 会用旧密码解密、再用新密码重新加密所有凭据。
  • 停用：停用主密码会让凭据退回设备本地密钥模式（v2 → v3）。此后无需密码即可直接使用，但保护强度也随之降低。
主密码无法找回。它不会被存盘，AuraTerm 里也没有任何后门或重置入口。一旦忘记，已加密的凭据将无法解密——你需要重新录入这些密码和密钥。请妥善保管，并考虑用密码管理器备份。

在本机记住主密码（OS 钥匙串）

如果每次解锁都输入主密码太麻烦，你可以选择 “在本设备上记住”。AuraTerm 会把主密码托管给操作系统的钥匙串，下次启动便可自动解锁。此选项仅在 macOS 和 Windows 上提供。

“记住”相当于用本机操作系统账户的安全性来换取便利：任何能登录该系统账户的人都可以在无需输入主密码的情况下解锁凭据。在你独占且已设登录密码、磁盘加密的个人设备上使用最合适；共享设备上请不要勾选。

SSH 主机密钥信任（known-hosts）

首次连接某个 SSH 服务器时，AuraTerm 采用首次连接即信任（TOFU）策略：它会记录该 host:port 的主机密钥 SHA-256 指纹，保存到 ssh_known_hosts.json。之后每次连接都会用这个指纹校验对方身份。

如果某台主机的密钥与已记录的指纹不一致，AuraTerm 会弹出变更告警。这可能意味着服务器重装了系统，也可能是中间人攻击的信号。出于安全考虑，该提示默认在 180 秒后自动拒绝连接——给你时间核实，又不会让连接在无人确认时悄悄放行。

遇到指纹不匹配时，不要不假思索地接受。先通过可信渠道（如服务器管理员、带外记录或云控制台）核对新指纹。只有确认服务器确实合法变更后，再选择信任新密钥。

审计日志与受信主机管理

每当你在指纹变更告警中选择覆盖（接受新密钥）时，这一决定都会被写入 security_audit.log。这份审计日志让你日后能够追溯何时、对哪台主机做出过信任变更。

你可以在设置中管理受信主机：查看已记录的指纹、移除某台主机，或一键重置全部 known-hosts。重置后，相关主机会在下次连接时重新进入“首次连接即信任”流程。

实用安全建议

  • 在共享、便携或不受信任的设备上，务必设置主密码，不要依赖设备本地密钥模式。
  • 为主密码选用一个足够长、独一无二的口令，并在密码管理器中留有备份——因为它无法找回。
  • “在本设备上记住”仅适合个人专用设备，并应配合系统登录密码与全盘加密。
  • 首次连接重要服务器时，养成核对主机指纹的习惯；遇到指纹变更告警时保持警惕，先核实再决定。
  • 定期查看 security_audit.log，确认其中的信任变更都是你本人有意作出的。

云同步（端到端加密）

云同步让你的书签、一份精选设置子集和 SSH known-hosts（已知主机）在多台设备之间保持一致——例如把家里的台式机和公司的笔记本对齐。它无需自建后端：你可以选择 GitHub Gist、Gitee Gist、WebDAV，或 AuraXLab 账户作为存储后端。无论用哪一个，服务器或提供商只会看到密文，永远拿不到你的明文数据。

打开方式：File（文件） > Preferences（首选项） > Cloud Sync（云同步），或在命令面板（Ctrl/Cmd+Shift+P）中搜索 “Cloud Sync”。

零知识模型：你的数据如何被保护

AuraTerm 采用零知识设计。在任何数据上传之前，AuraTerm 会先在你的设备本地用一个专用的同步口令（sync passphrase）对全部内容加密（Argon2id 派生密钥 + AES-256-GCM）。也就是说，离开你设备的只有密文。服务器、Gist 提供商或 WebDAV 主机都无法解密、读取或重建你的书签和设置。

同步口令与主密码（master password）是两个完全不同的东西。主密码用于保护本机的 credentials.enc 凭据库；同步口令则专门用于加密上传到云端的内容。它们彼此独立，可以设成不同的值。

  • 同步口令永远不会上传——它只存在于当前会话的内存中。
  • 点击 Lock（锁定） 会把口令从内存中清除；下次同步前需要重新输入。
  • 所有设备必须使用同一个同步口令，否则无法互相解密对方上传的数据。
⚠️ 请务必牢记你的同步口令。由于采用零知识加密，它从不离开你的设备，一旦遗失，云端数据将无法恢复——AuraTerm、AuraXLab 以及任何提供商都无法帮你找回或重置。建议把它保存在密码管理器中。

选择并配置提供商

在 Cloud Sync 面板中选择一个提供商，并填入其凭据。下面按提供商分别给出设置步骤。

提供商 1：GitHub Gist

  • 登录 GitHub，进入 Settings > Developer settings > Personal access tokens，创建一个个人访问令牌（PAT）。
  • 为该令牌勾选 gist 权限范围（scope）。这是唯一必需的权限。
  • 复制生成的令牌，回到 AuraTerm 的 Cloud Sync 面板，提供商选择 GitHub Gist，把令牌粘贴进去。
  • 无需手动创建 Gist：首次 Push（推送） 时会自动创建一个 私密 Gist，其 Gist ID 会被自动填入面板。

提供商 2：Gitee Gist

  • 登录 Gitee，进入个人设置中的私人令牌（private token）页面，生成一个新的私人令牌。
  • 为令牌勾选 gists 权限范围。
  • 在 AuraTerm 中将提供商选为 Gitee Gist，粘贴该私人令牌。

提供商 3：WebDAV

  • 在你的 WebDAV 服务上准备好访问凭据，并确定一个用于存放同步文件的 文件 URL。
  • 在 AuraTerm 中将提供商选为 WebDAV，填入文件 URL、用户名和密码。
https://dav.example.com/auraterm/auraterm-sync.enc

提供商 4：AuraXLab 账户

  • 在 AuraTerm 中将提供商选为 AuraXLab account，并填入服务器地址。
https://auraxlab.com
  • 使用已有账户登录（sign in），或自助注册（self-register）一个新账户。
  • 如果是新注册，请先完成邮箱确认（email confirmation）。账户必须经过邮箱确认后才能开始同步。
  • 登录成功后会存储一个令牌（token），用于后续的同步请求。

“同步什么”开关

你可以控制哪些类别参与同步：

  • 书签（bookmarks）——始终同步。
  • 设置子集（settings subset）——主题、字体、快捷按钮（quick buttons）、输出规则（output rules）。设备相关的项目会被排除，包括窗口大小/位置、工作区布局、串口历史、主密码哈希。
  • SSH known-hosts（已知主机）——主机指纹信任记录。
  • 已保存的凭据（saved credentials，可选）——勾选此项需要先解锁主密码。

各项操作（Actions）

  • Save（保存）——保存当前的提供商配置与“同步什么”选项。
  • Test（测试）——验证提供商凭据与连接是否可用。
  • Pull (merge)（拉取并合并）——下载云端数据，并按合并规则与本地数据合并。
  • Pull (replace)（拉取并替换）——用云端数据覆盖本地对应数据。
  • Push（推送）——加密并上传本地数据到云端。
  • Sync now（立即同步）——执行一次双向同步（合并后再上传）。

合并规则

  • 书签按 id 合并；发生冲突时，最近上传的那一份获胜。
  • known-hosts 取并集合并；当同一主机存在分歧时，本地的信任获胜。
  • 设置子集采用覆盖方式（不做逐项合并）。
  • 凭据按连接 id 合并。

两台设备上手演练

  • 设备 A：打开 Cloud Sync，选择提供商并填好凭据，点击 Test 确认可用，设定同步口令，点击 Save，再点击 Push 把本地数据上传。（若用 GitHub Gist，私密 Gist 会在此时自动创建。）
  • 设备 B：配置相同的提供商，并输入完全相同的同步口令。（GitHub Gist 用户需要确保指向同一个 Gist ID。）
  • 在设备 B 上点击 Pull (merge)，把设备 A 的书签、设置子集与 known-hosts 合并进来。
  • 此后日常使用中，在任一台设备上点击 Sync now 即可保持双向同步。

设备标签

每台设备都有一个标签（label），用于在多设备同步中标识这台机器，便于你区分各台设备。

故障排查

  • 解密错误 / decrypt error：几乎总是因为同步口令输错了。请确认这台设备用的同步口令与上传数据的设备完全一致（注意大小写与空格）。
  • AuraXLab 409 冲突：表示服务器上已有更新的数据。请先 Pull，再 Push。
  • 账户未确认 / unconfirmed account：AuraXLab 账户必须先完成邮箱确认才能同步。请检查注册邮箱中的确认邮件并完成验证。
  • 勾选了同步凭据却无法进行：同步已保存的凭据需要先解锁主密码。

快捷键参考

以下是 AuraTerm 中常用的键盘快捷键。带斜杠的组合键表示平台差异：在 Windows 和 Linux 上使用 Ctrl，在 macOS 上使用 Cmd。

命令面板

  • Ctrl/Cmd+Shift+P — 打开命令面板，支持模糊搜索快速查找并执行命令。

查找

  • Ctrl/Cmd+F — 在终端中打开查找，支持区分大小写、全词匹配和正则表达式。

发送与输入历史

  • Ctrl+Enter — 从输入栏发送当前内容。
  • PageUp — 在命令历史中向上翻阅（较早的命令）。
  • PageDown — 在命令历史中向下翻阅（较新的命令）。

字体缩放

  • Ctrl++ — 增大终端字号。
  • Ctrl+- — 减小终端字号。
  • Ctrl+0 — 将字号重置为默认值。

全屏

  • F11 — 切换全屏模式。

重新连接

  • R — 在 SSH 断开连接后按下以重新连接。

命令导航

  • Ctrl/Cmd+Shift+Up — 跳转到上一条命令（基于 OSC 133 shell 集成的命令标记）。
  • Ctrl/Cmd+Shift+Down — 跳转到下一条命令。
命令导航依赖通过 OSC 133 实现的 shell 集成。只有当远端 shell 输出命令标记时，上一条/下一条命令的跳转才可用。

常见问题与故障排查

本章汇总了使用 AuraTerm 时最常遇到的问题，涵盖配置文件位置、忘记密码、SSH 主机密钥变化、串口检测、云同步冲突以及隐私安全等方面。每个问题都给出了明确的处理步骤。

我的配置文件保存在哪里？

AuraTerm 把所有数据存放在操作系统的应用配置目录中。主要文件包括：连接元数据、加密后的凭据、SSH 已知主机记录、云同步配置以及安全审计日志。卸载应用通常不会删除这些文件，因此你可以放心升级。

settings.json
connections.json
credentials.enc  (+ credentials.key 仅在设备本地模式下)
ssh_known_hosts.json
sync_config.enc
security_audit.log

其中 connections.json 只保存连接元数据（主机、端口、用户名等），不包含任何密码或密钥；所有敏感信息都集中在 credentials.enc 中，并经过 AES-256-GCM 加密。

我忘记了主密码（Master Password），怎么办？

主密码用于通过 Argon2id 派生密钥来加密你保存的凭据。如果你忘记了它，已保存的密码、私钥和口令无法被找回——这正是端到端加密的设计目的，连我们也无法解密。

不过你仍然可以重置：重新设置一个新的主密码会丢弃旧的加密凭据库，你的连接条目（主机、端口、用户名）依然保留，只需为它们重新输入并保存一次密码或密钥即可。

如果你之前在 macOS 或 Windows 上启用了“在本设备上记住”（使用系统钥匙串），应用可能仍能自动解锁。但一旦系统钥匙串中的记录被清除，且你又忘记了主密码，凭据就无法恢复。

我忘记了同步口令（Sync Passphrase），数据还能找回吗？

不能。同步口令是独立于主密码的一把专用密钥，它在数据上传之前用 Argon2id + AES-256-GCM 对全部内容进行加密。该口令永远不会被上传，只在当前会话的内存中保留，并会在你点击“锁定（Lock）”时清除。

如果同步口令丢失，云端存储的密文将无法解密、无法恢复。请务必把它单独妥善保存。如果你在另一台仍处于解锁状态的设备上还能访问数据，可以从那里重新建立同步并设置新的口令。

另外请注意：如果你输错了同步口令（而非忘记），同步时会直接报出解密错误。此时只需用正确的口令重新解锁即可，无需重置任何数据。

连接 SSH 时弹出“主机密钥已变更”的警告，我该怎么办？

AuraTerm 对每个 host:port 采用“首次信任（TOFU）”策略：第一次连接时记录该主机的 SHA-256 指纹。之后若服务器出示的指纹与记录不符，应用会弹出不匹配提示，默认在 180 秒后自动拒绝连接，以防你在不知情时连入被冒充的主机。

  • 如果这次变更是预期内的（例如服务器重装系统、更换了主机密钥），请向管理员核对新指纹无误后再选择接受。
  • 如果你没有预期到任何变更，这可能是中间人攻击的信号，请保持拒绝并立即排查网络与服务器。

每次接受变更（覆盖原指纹）都会写入安全审计日志（security_audit.log）。你可以在“设置（Settings）”中查看、管理或重置已信任的主机列表。

AuraTerm 检测不到我的串口，怎么排查？

AuraTerm 会自动枚举系统中可用的串口。如果你的设备没有出现在列表里，可按以下顺序检查：

  • 确认 USB 转串口适配器已正确插入，并已安装对应的驱动（如 CH340、FTDI、CP210x 等）。
  • 确认该端口没有被其他程序占用——串口同一时间只能由一个应用独占。请关闭其他终端或烧录工具后重试。
  • 重新打开串口选择界面以触发一次重新枚举；必要时拔插设备或重启应用。

端口能识别后，请按设备要求设置波特率、数据位、停止位、校验位和流控。AuraTerm 内置了常用预设：115200-8N1、9600-8N1 和 57600-8N1，可一键套用。

云同步报错 409（AuraXLab 账户），是什么意思？

针对 AuraXLab 账户提供商，409 表示服务器上已有比你本地更新的数据。这是一种保护机制，防止你的推送覆盖掉来自另一台设备的较新改动。

处理方式很简单：先 Pull（拉取/合并），再 Push（推送）。拉取会按合并规则把云端的较新内容并入本地，之后再推送就不会再冲突。你也可以直接使用“Sync now（双向同步）”一步完成。

合并时遵循固定规则：书签按 id 合并，冲突时以最近上传的副本为准；已知主机取并集，且以本地信任为准；设置子集整体覆盖；凭据按连接 id 合并。了解这些规则有助于你预判合并结果。

如果你的 AuraXLab 账户始终无法同步，请先确认邮箱已完成确认——新注册的账户必须先通过邮件确认才能同步。

同步服务商（或 AuraXLab 服务器）能读到我的数据吗？

不能。AuraTerm 的云同步是端到端加密、零知识的：所有内容都在你的设备上、用同步口令加密之后才上传。无论是 GitHub Gist、Gitee Gist、WebDAV 还是 AuraXLab 账户，服务端只会存储密文，看不到明文。

因为解密密钥（同步口令）从不离开你的设备，所以即使提供商遭到入侵或被要求交出数据，攻击者拿到的也只是无法解读的密文。这也再次说明：请务必妥善保管你的同步口令。