文档 / SSH worktrees

Orca 可以通过 SSH 驱动远程机器上的代理——适用于长时间运行的构建、GPU 机器，或任何不适合在笔记本电脑上执行工作的环境。

SSH 是将代理部署到远程计算的一种方式。对于本地、自托管服务器和临时虚拟机，请参阅 运行 Orca 的方式。

添加 SSH 目标¶

1. 打开 设置 → SSH。
2. 点击 添加目标。主机表单会在模态框中打开（而不是在列表下方内联显示），因此即使主机列表很长，主机、高级和保存仍可访问。编辑使用相同的对话框，并显示目标标签以及 user@host:port。
3. 填写主机、用户、端口和可选的身份文件——或者在同一对话框中打开 OpenSSH 配置 选择器，以搜索 ~/.ssh/config（包括 Include 的文件），选择一个主机并预填表单。已在 Orca 中保存的主机会显示 已在 Orca 中 徽章。当该流程可用时，你仍可以从配置中批量导入主机。
4. 如果密钥受密码短语保护，Orca 会在首次使用时提示。
5. 点击 测试 以验证连接，然后点击 保存。

未完成的添加/编辑表单会忽略外部点击，因此意外点击其他地方不会丢弃你的字段；请使用 Escape、取消 或 × 来丢弃。

主机密钥验证¶

Orca 会将内置 SSH 连接与你的有效 OpenSSH known_hosts 文件以及它之前保存的密钥进行比对。现有匹配项会静默连接。在默认策略下，Orca 会在首次接触时接受并记住主机，并显示其指纹；StrictHostKeyChecking yes 会拒绝未知主机，而 no / off 会接受但不保存信任记录。

如果密钥已更改、被吊销或出现意外不同的密钥类型，Orca 会在请求密码或密钥密码短语之前拒绝连接。如果你有意重建或重新配置了主机，请先验证其新指纹，然后按照错误中的恢复路径操作。对于 known_hosts 不匹配，Orca 会提供相应的 ssh-keygen -R 命令（在需要时包括带括号的主机和端口）。

使用目标¶

创建 worktree 时，选择 SSH 目标而不是本地目标。Orca 将：

• 在远程主机上创建 git worktree。
• 通过 SSH 连接在远程运行代理。
• 同步文件事件，使编辑器、差异和浏览器仍然感觉像本地。

高级连接选项¶

打开 设置 → SSH，编辑一个目标，并在主机需要代理、跳板主机或 SSH 多路复用覆盖时展开 高级连接。Orca 默认启用 复用 SSH 连接以加快设置，它在 macOS 和 Linux 上使用 OpenSSH 连接复用，因此设置命令不必每次都进行新的 SSH 握手。仅当主机的 SSH 策略拒绝多路复用会话时，才将其关闭。

密码短语¶

密码短语会在 Orca 会话期间保存在内存中。关闭 Orca 会清除它们。你可以在 SSH 设置中选择更长的 TTL。

状态¶

远程 worktree 会显示一个带有实时 SSH 状态的徽章——绿色表示已连接，黄色表示正在重连，红色表示已断开。当 SSH 主机仍在连接时，Orca 可以从 持久化的本地元数据 中列出工作区，以便在实时提供程序启动之前侧边栏不会为空；一旦连接稳定，这些行会刷新为权威的远程状态。断开连接不会终止正在运行的代理；Orca 会重新连接并重新附加，重放滚动输出，并从其已渲染的帧恢复全屏应用窗格，而不是让它们返回空白或碎片化状态。当主机断开时，受影响的工作区卡片可以显示内联 连接 / 重连控件，这样你无需打开终端覆盖层或查找状态栏即可恢复。如果 SSH 中继以 "Multiplexer disposed" 风格的故障断开，Orca 会自动恢复，而不是让窗格卡住直到你重启。代理状态（工作中 / 空闲 / 阻塞）会通过 SSH 以与本地相同的方式传播，因此侧边栏和 代理动态 会实时反映远程代理。

应用关闭后的会话¶

关闭桌面应用不再终止你的远程 PTY 会话。远程终端会话通过运行在远程主机上的中继进行租约，因此它们可以在你的笔记本电脑上关闭 Orca 后存活。当你重新打开应用并重新连接到目标时，已租约的 PTY 会以 已附加 状态恢复到其标签页中，滚动缓冲区保持完整。默认情况下完全没有倒计时：每个目标都启用了 在重置前保持终端存活，因此分离的会话会持续运行，直到你显式结束它们——结束远程终端、重置中继、删除目标或关闭标签页。在 高级连接 下关闭该开关，可以为该目标设置有限的 断开连接后超时；表单默认从 24 小时开始，接受 60 秒到 7 天，之后中继会拆除分离的会话。与主机失去联系并不证明其工作已停止，因此当前无法访问的远程会话不应被假定已死亡——在同一个 worktree 上启动第二个代理之前，请先检查主机。

下载远程文件和文件夹¶

在 SSH worktree 文件资源管理器中右键点击：

• 文件 → 下载 — 原生保存对话框；将文件复制到你的笔记本电脑。
• 文件夹 → 下载文件夹 — 递归下载到你选择的文件夹（仅限桌面端）。

Orca 使用与连接相同的 SSH 传输路径。只有当连接声明支持递归文件夹传输（通常是完整 SFTP）时，才会显示文件夹下载。仅使用系统 OpenSSH 传输的连接可能仍然可以下载 文件，但不会显示 下载文件夹。

这是仅限桌面端的操作——Web 客户端不暴露下载，因为它依赖 Electron 的保存对话框。

在 VS Code 中打开远程工作区¶

对于 SSH worktree，当配置的应用是 VS Code 或 VS Code Insiders（code / code-insiders，或指向这些启动器的直接路径）时，worktree 菜单的 打开方式 列表可以将远程路径交给 VS Code Remote-SSH。

1. 配置 设置 → 常规 → 打开方式菜单，使 VS Code 出现在列表中（预设或自定义命令）。
2. 右键点击 SSH worktree（或使用 worktree 溢出菜单）→ 打开方式 → VS Code。
3. Orca 会针对该主机和 worktree 路径（--remote ssh-remote+<host> <path>）使用 Remote-SSH 启动 VS Code。菜单项可能显示 Remote SSH 徽章。

此远程路径不支持： Cursor、Zed、复合 shell 命令，或通过 Remote Orca Server 活动运行时打开（这些保持 仅限本地）。仅对本地路径使用 Finder/Explorer 项。

Kerberos / GSSAPI¶

如果 OpenSSH 配置中的某个主机设置了 GSSAPIAuthentication yes，Orca 会优先为该目标使用 系统 OpenSSH 传输（内置 ssh2 客户端不支持 GSSAPI）。连接前请保留有效的 Kerberos 票据（kinit / 你所在组织的 SSO）。手动目标在配置为系统 SSH 时也可以启用 GSSAPI。

对于从配置导入的主机，你无需切换单独的“Kerberos 模式”开关——导入/ssh -G 会携带该标志。

FIDO2 / security keys¶

基于硬件的 OpenSSH 身份（ed25519-sk、ecdsa-sk，包括由代理支持的安全密钥）也使用 系统 OpenSSH，而不是内置 ssh2 客户端。Orca 会从你的身份文件中检测密钥类型，并将连接交给操作系统的 OpenSSH 二进制文件，以便触摸 / PIN 提示按常规工作。常规 Ed25519、ECDSA 和 RSA 密钥仍使用内置传输。如果机器上不可用 OpenSSH，则这些 FIDO2 目标无法进行身份验证，直到安装 OpenSSH 并将其置于 PATH（或位于常见的 Windows/macOS/Linux 位置）中。

Linux hosts without a C/C++ toolchain¶

首次连接时，Orca 会在远程安装一个小型中继。远程终端需要一个原生 node-pty 模块。Linux 包通常会在主机上编译；macOS/Windows 中继使用预构建版本。

如果远程缺少 make、C++ 编译器和 python3，Orca 仍会完成针对文件、git 和编辑器的连接，但在安装构建工具之前，远程终端将无法工作。Orca 可能显示的示例安装提示：

• Debian/Ubuntu：sudo apt-get install -y build-essential python3
• Fedora/RHEL：sudo dnf install -y make gcc gcc-c++ python3
• Alpine：sudo apk add build-base python3
• Arch：sudo pacman -S --needed base-devel python

安装这些工具，然后重新连接，以便中继可以安装原生模块。

Port forwarding¶

对于远程 worktree，右侧边栏会显示 端口 选项卡（使用 Cmd+Shift+I 切换）。Orca 会扫描远程的 /proc/net/tcp，并在 已检测 下列出监听端口——单击即可将它们转发到你的笔记本电脑。你也可以手动添加转发、编辑它们或移除它们。转发会在应用重启和 SSH 重连后保留，并且特权远程端口会自动在本地重新映射（例如远程 80 → 本地 10080）。