远程开发与管理

本指南涵盖两方面的内容：一是将本地的 VelaTerm 打开，允许其他设备访问；二是连接到远程机器，以便在远程端进行开发及会话管理。

1. 两个入口，两个方向

所有远程功能都位于标题栏的右侧（主题切换器旁边）：

地球图标代表 远程访问（浏览器）——即打开该机器，让手机、平板电脑或其他电脑能够通过浏览器使用你的 VelaTerm。箭头图标代表 连接到远程服务器——此时该机器作为客户端，连接到另一台机器上进行开发。当服务器正在运行时，地球图标会显示为绿色。

2. 打开本机（远程访问）

2.1 启动服务器

点击地球图标，设置端口（默认为 8799；如果已被占用则需更改）和访问密码，然后点击“启动服务器”：

任何设备都需要输入访问密码才能接入。该密码仅在服务器运行时有效；停止运行后，下次需设置新的密码。

2.2 连接设备

服务器启动后，面板会显示状态、证书指纹以及自动生成的配对链接：

要连接，请将配对链接发送到自己的设备（可通过 AirDrop、发消息给自己等方式），在浏览器中打开链接并输入访问密码。链接中包含加密后的配对凭证；浏览器与主机之间的通信采用端到端加密。有两点需要注意：

• 该链接即为一把密钥。仅可与自己的设备共享。如果怀疑链接泄露，请点击“重新生成链接”——旧链接会立即失效，所有已连接的设备也会断开，直到它们使用新链接为止。
• 首次连接时，浏览器会因证书不可信而发出警告——对于自签名证书来说这是正常现象。请将浏览器显示的指纹与面板中的“证书指纹”进行比对；如果一致，说明你正在与自己的机器通信。

如果存在多个网络接口（有线、Wi-Fi、VPN），面板会显示首选地址，其余地址汇总在“还有 1 个 URL”下方——请选择与连接设备处于同一网络的地址。

在手机上打开同一链接会自动切换到移动端界面（两级导航结构加上终端键栏）——无需额外设置。

2.3 浏览器端的体验

连接设备所看到的登录页面及主界面如下：

浏览器客户端与桌面端共享相同的实时会话：相同的界面结构、相同的终端输出，双方都可以输入内容，且能实时看到对方的操作。窗口布局（打开的标签页、分屏显示等）由每个客户端独立决定。

终端大小有“所有者”概念：当一个会话在多个客户端上同时打开时，终端大小会跟随所有者变化，其他客户端看到的则是缩放后的镜像版本，并会显示一条“镜像……点击以适配此窗口”的提示条（如上图终端右上角）——点击该提示条即可接管当前窗口的大小控制。

2.4 设备管理

面板中的“已配对设备”列表会显示所有已连接的设备：

要禁止某个设备，点击其旁边的“阻止”并确认——该设备会立即断开连接且无法重新连接（需要新的配对链接）；其他设备则不受影响。设备名称由客户端自行报告——应将其视为标签，而非设备的真实身份。要一次性断开所有连接，可使用“重新生成链接”功能。

2.5 停止服务器

在面板底部点击“停止服务器”。浏览器客户端会断开连接；正在运行的会话则不受影响——因为这些会话属于桌面端应用程序本身。

3. 连接到远程端（连接到远程服务器）

点击标题栏中的连接按钮，面板会提供 SSH 模式和 URL 模式。

3.1 SSH 模式：远程端只需 SSH

适用于未安装任何 VelaTerm 组件的远程开发机（通常是 Linux 或 macOS）。连接时会自动执行整个流程：探测远程端的操作系统和架构 → 传输匹配的 vela-server → 以持久进程形式启动它 → 设置本地端口转发 → 打开远程窗口并自动登录。

输入 user@host[:port] 并点击“连接”。以下是值得了解的细节：

首次连接时的主机密钥验证：新的主机会显示其 SSH 主机密钥指纹供你验证；确认后选择“指纹匹配，连接”，该主机就会被添加到 known_hosts 文件中——之后再连接该主机时就不会出现提示。如果已知主机的指纹发生变化，面板会变为红色——在确认之前需查明原因（可能是操作系统重新安装、使用了不同机器，或是有人篡改了链接）。

身份验证：你现有的 SSH 设置（如 ssh-agent、~/.ssh/config、密钥等）会被透明地复用；只有当公钥认证失败时才会出现密码输入提示。“记住密码”功能会将密码存储在系统密钥链中（而非数据库中），下次会自动使用该密码。

数据模式：“使用远程桌面应用的数据库”。 未勾选（默认）时，远程服务器会使用独立数据目录（~/.velaterm/data），与该机器上安装的 VelaTerm 桌面应用完全隔离。勾选后，服务器会改用远程桌面应用的数据库——双方将看到相同的会话树，适合“该机器平时运行 VelaTerm，而我需要远程处理同一批项目”的场景。共享的是磁盘上的数据库文件，而非正在运行的进程（见 §4.1）；建议两端保持相同版本。

**最近访问的主机。**此处列出了你已连接过的主机；点击某台主机仅会填充输入框（不会自动连接）——请检查后点击“连接”。钥匙图标表示已保存密码；×则表示已忘记该主机及其保存的密码。

**连接进度。**首次连接时会传输服务器二进制文件（数十 MB）——按钮会显示“准备中”/“传输中”并附带进度百分比。重新连接时会复用远程端的服务器，速度会快得多。

3.2 URL 模式：对方已开启远程访问功能

适用于另一台机器的 VelaTerm 已开启远程访问功能（§2）且你拥有其配对链接的情况。与在普通浏览器中打开链接相比，此方式会提供一个专用窗口，支持钥匙链自动登录，还会由应用程序处理指纹验证。

粘贴配对链接，输入对方设置的访问密码，然后点击“连接”。首次连接时会验证 TLS 证书的指纹（需与对方面板上显示的证书指纹进行比对）；之后，只要指纹一致即可直接连接。记住密码的原理相同，也是通过系统钥匙链实现。

4. 断开连接、关闭窗口及数据保留情况

4.1 三层状态机制

“断开连接后这些内容是否仍然存在”取决于你所关注的层级：

前两个层级从设计上就是安全的。唯一需要考虑的层级是第三个：只要远程服务器进程仍在运行，你的正在运行的会话就会存在。

4.2 关闭窗口的含义

SSH 模式：该远程服务器是通过此连接启动的且属于你，因此关闭窗口时会询问你要执行什么操作——“停止服务器”会在远程端关闭它（从而结束其正在运行的会话）；“继续运行”仅会断开你的端点，让服务器保持运行状态，这样下次连接到该机器时所有会话都会完好无损地继续使用。如果你希望在你离开时智能体仍能继续工作，请选择“继续运行”。

URL 模式：你是以访客身份接入已在另一端运行的程序的。关闭窗口仅表示你离开，另一端会继续运行，你回来时一切依旧。

4.3 断开与重新连接

当网络出现故障时，远程窗口顶部会出现红色的重新连接条，并自动尝试重新连接；正在运行的会话不会受到影响——在 SSH 模式下，远程服务器会与 SSH 会话分离（其设计初衷就是能够承受网络中断）。

需要注意的一点是：自动重新连接仅适用于从窗口到本地转发端口的路径。如果 SSH 隧道进程或远程服务器本身已崩溃，红色条会一直旋转，重新连接功能也无法解决问题——需返回主窗口并再次连接。连接流程会检测远程服务器是否仍然存活：若存活则继续使用该服务器（会话保持不变）；只有当服务器已崩溃时才会启动新的服务器。

另外：如果远程机器进入睡眠状态、登出或重启，SSH 模式下的服务器及其正在运行的会话也会终止；不过存储在磁盘上的会话树不会受到影响。

4.4 快速参考

5. 安全模型概览

密码（SSH 账户密码、远程登录密码）仅存储在系统密钥链中，绝不会存储在数据库中，且仅在你明确同意的情况下才会存储。局域网浏览器访问通过带有自签名证书的 TLS 协议进行；配对链接会传输端到端加密的凭证，服务器会拒绝未配对的明文连接。SSH 主机密钥和远程 TLS 证书均采用“首次使用即信任”机制：已知且未变更的连接可直接通过；新目标会触发一次验证提示；指纹发生变化时会显示红色警告——请在确认前进行调查。可以随时阻止特定设备（参见§2.4），并且可以随时重新生成配对链接。

还有一点：如果远程窗口的标题栏显示红色的“⚠ vX ≠ vY”标识，说明你的客户端界面与远程服务器的版本不同——功能可能不兼容；请将两端升级到相同版本。

6. 常见问题解答

**已连接，但侧边栏仍为空或红色进度条一直旋转？**很可能是 SSH 隧道或远程服务器已断开——窗口内的重新连接无法解决此问题（§4.3）。请返回主窗口并再次连接。

**端口 8799 无法启动？**可能有其他程序占用了该端口；请在面板中选择其他端口，然后重新启动。

**浏览器提示证书不可信？**自签名证书会出现此情况——请验证指纹后继续操作（§2.2）。如需跳过各浏览器的警告，可通过配对链接进入，由应用程序自动处理信任问题。

**希望在离开时远程智能体仍能继续工作？**在 SSH 模式下，选择“关闭窗口时继续运行”；这样会让会话在远程端继续进行。稍后重新连接即可从上次中断处继续。

**手机上的终端显示很小？**这是跟随桌面分辨率自动缩放的显示效果——点击终端右上角的“点击以适配此窗口”即可让终端根据当前设备调整大小。