Orca 部署避坑清单:内存、端口、认证——第一晚就会炸的五个点
Orca 部署避坑清单:内存、端口、认证——第一晚就会炸的五个点
Orca 把自己定位为"面向一群并行代理的 ADE":在桌面上把 Codex、Claude Code、OpenCode、Cursor CLI 等任意终端型编码代理塞进各自的 git worktree,一份 prompt 分发给多个代理赛跑,再挑赢家合并。社区里"一款工具同时跑多套编码代理""把一群编程 Agent 管起来的开源编排器"的讨论热度,正来自这套工作流对单人开发者效率的碾压式提升。但正因为它的核心卖点是"并行",部署它的第一晚也最容易在三个维度连环翻车:内存被多个常驻 PTY 吃穿、端口与监听地址配错连不上、打开手机遥控后暴露面失控。这篇文章基于仓库源码与官方文档,把五个高频炸点逐一拆开,给出可直接照抄的处置方案。
炸点一:多代理并行是"乘法"而不是"加法"——内存规划先做对
Orca 的并行模型非常直白:每个 worktree 都是一个真实的 git worktree 磁盘副本,有自己的分支、文件与专属代理终端。官方文档毫不掩饰这一点——创建 worktree 时 git fetch 与 git worktree add 在后台执行,每个新 worktree 会立刻占据一份仓库副本和一条 PTY。问题在于,很多人按"一个代理 = 一个终端窗口"的经验估内存,而 Orca 的实际情况是:
- 每个空闲后台代理都是一条活的 PTY,在内存里持有模型会话状态(hibernation 文档 明确写道"each one is a live PTY holding a model session in memory");
- 每个 worktree 都保持文件监听(file watcher)存活,官方 Troubleshooting 原话是"Close worktrees you're not actively using. Each worktree keeps file watchers alive";
- 拆分布局里多个浏览器标签才是最大的内存黑洞——"Split layouts with many browser tabs are the biggest RAM users"。
所以 5 个并行代理的占用不是"单代理内存 ×5",而是"代理会话 + 工作副本 + 文件监听 + 可选的浏览器渲染"叠加。第一晚最典型的死法:一口气开 8 个 worktree 各挂一个代理,然后去干别的,回来发现系统 Swap 打满、界面卡死。
推荐配置与处置:
- 基线内存:单代理轻量使用 16 GB 起步;经常保持 3 个以上常驻代理并行,直接上 32 GB。这是仓库文档给出的唯一"硬性"性能建议之外的经验值——Orca 本身是 Electron 桌面应用,主进程、渲染进程与代理 CLI 同机竞争内存。
- 打开 Agent hibernation:
Settings → Experimental → Agent hibernation,默认关闭、默认 30 分钟空闲窗口。开启后,处于 done 状态且未被触碰的后台代理终端会被暂停,重开 worktree 时以claude --resume <id>/codex resume <id>原样恢复会话(hibernation)。这是官方给出的内存回收主路径。 - 用 Resource Manager 清理:
Resource Manager → Clean up workspaces可以跨本地 worktree、主 worktree、文件夹工作区乃至断连 SSH 主机批量审视与移除,删除时还能保留含未合并提交的分支供事后 review。 - 用
worktree.sharedDirectories共享大目录:node_modules、.cache这类可重建的 gitignored 目录在orca.yaml里声明共享(macOS 上优先 APFS clone-copy,否则 symlink),避免每个 worktree 各拷一份几 GB 的依赖树(worktrees)。
炸点二:端口 6768 与"通配符监听"——默认安全却让人连不上
Orca 的手机配对与远程服务默认端口是 6768(mobile 文档里写明"Missing port keeps the current port (or defaults to 6768)")。第一晚翻车的经典场景是:orca serve 起来了,手机却死活连不上。原因往往出在监听地址而非端口本身。
看仓库源码 src/main/runtime/pairing-endpoint.ts 就能理解默认行为:
const override = advertisedAddress?.trim()
if (!override) {
// Why: a wildcard listener is not client-reachable; default pairing must remain local-only unless explicitly advertised.
endpoint.hostname = '127.0.0.1'
return valid(formatWebSocketUrl(endpoint))
}
没有显式指定 --pairing-address 时,配对链接默认被钉在 127.0.0.1——这是有意的安全默认(通配符监听不可被客户端直达),但也意味着任何远程客户端、手机、局域网另一台机器都连不上。正确的姿势是给 orca serve 显式声明客户端可达的地址:
# 局域网
orca serve --pairing-address 192.168.1.20
# Tailscale(推荐)
orca serve --pairing-address 100.64.1.20
# 固定端口
orca serve --port 6768 --pairing-address 100.64.1.20
# 无头服务器上给手机出二维码
orca serve --pairing-address 100.64.1.20 --mobile-pairing
注意两点:--port 0 是绑定期请求、不是客户端能拨的端点(源码中显式拒绝);通配符主机名与 127.0.0.1 都不能当作远程客户端的配对地址(--pairing-address 注释明确"Do not use a wildcard address or 127.0.0.1 for a remote client")。另外端口只在需要被防火墙、隧道或服务定义固定时显式指定——systemd 守护场景几乎必然要 --port 6768。
炸点三:局域网、公网与代理场景——"连不上"的三个真实原因
网络是第二大类"第一晚就炸"的重灾区,而且三个子场景成因完全不同:
局域网直连:桌面与手机必须共享同一条网络路径(LAN、Tailscale 或当初配对所用路径)。手机端编辑已配对主机的地址不会重新配对——改地址只改变这台手机的连接去向,token 不变。桌面 App 关闭会直接断掉 direct/LAN 会话,重开即恢复。所以"白天好好的、晚上连不上"最常见的原因就是桌面没开。
Tailscale / 私有网络(推荐路径):Remote Orca Server 文档把"桌面 App + Tailscale"列为最省事方案,要求两端同 tailnet、服务端在线且运行 Orca。Tailscale 地址(通常 100.x.y.z)会被自动排到连接地址选择器第一位。翻车点集中在:tailnet ACL 过严导致对端不可达、服务端休眠掉线、两端版本协议不兼容。
公网 / 代理场景:这是最危险的一类。官方在 remote-servers 里写得很直白——不要把 Orca 端口直接转发到公网,优先 Tailscale、WireGuard、可信 LAN、SSH 转发或认证隧道。原因在"炸点五"展开。另外如果走 HTTP(S) 代理,配对端点会按 WebSocket URL 归一化(源码 resolveFullUrl 走 normalizePairingUrl),ws:// / wss:// 才是配对协议本身接受的形态,地址里塞 http:// 会被自动转换但端口与路径必须正确。
还有一个"第一晚隐藏炸弹"属于 SSH 场景:远程终端需要原生 node-pty 模块,Linux 主机首次连接时 Orca 会在远端装 relay,如果目标机缺 make、C++ 编译器与 python3,文件/git/编辑器照常可用,但终端永远起不来。Debian 系先 sudo apt-get install -y build-essential python3,装完重连即可。
炸点四:认证第一步——配对链接就是密码,账号不一致必炸
Orca 的远程与手机场景全部围绕**配对(pairing)**展开,认证失败的根因高度集中:
- 配对码有有效期:官方文档明确"Pairing codes expire after a few minutes",屏幕上挂久了的码会失效,重新生成即可;
- Relay 配对要求同一账号:优先走 Orca Relay 配对时,只有 Relay 需要登录,且"desktop and phone are signed into the same Orca account"是硬前提;
- 设备令牌与撤销:配对交换会为手机签发 device token;桌面端清空已配对设备后旧 token 即失效,表现为 "Authentication failed / pairing invalid"。此时先点 Retry(瞬时拒绝可自愈),不行就重新配对或移除主机再配对;
- 协议版本强校验:手机与桌面之间是带版本号的移动协议,任一端过旧都会被拦截并引导升级,升级后仍报错就移除主机重新配对。
仓库 src/main/runtime/relay/relay-pairing-authorization.ts 展示了授权模型的严谨程度:直连传输得到 authenticated-direct 模式授权,中继传输必须校验 relayHostId 一致,否则直接抛 stale_relay_connection;配对授权只从不可变的连接元数据推导,绝不信任请求参数。这意味着伪造配对请求在架构层面就被挡掉了——但前提是你自己别把配对链接当成普通分享链接发出去。
炸点五:手机遥控打开后——暴露面从"本机"变成"网络"
这是整份清单里最容易被忽视的一条。打开手机遥控或远程服务后,你的 Orca 运行时从"本机工具"变成了"网络服务",暴露面管理有三层硬规则:
1. Access Link 就是密码。 生成一条配对链接等于授予对该 Orca 运行时的访问权,"Treat it like a password"(官方 Callout 原话)。每个客户端会拿到独立的、可撤销的 token,在 Shared Server Access 列表里逐条管理;生成新链接只会作废上一条未使用的链接,已配对客户端的 grant 会保留到你手动撤销。链接发错人?立刻在服务端撤销对应 grant 再重新生成。
2. 永远别把 6768 捅到公网。 官方文档明确列在安全守则第一条:"Do not forward the Orca port directly to the public internet." 首选 Tailscale/WireGuard/可信 LAN,其次是 SSH 转发或认证隧道。原因很直白:配对端点只认设备令牌,一旦公网可达,暴力尝试面与链接泄露后果都会放大——而 Relay 路径本身已经承担了公网中转职责,没必要再裸开端口。
3. 账号与遥测边界要清楚。 Orca 本身没有账号系统("Orca has no account system"),Orca 账号仅用于 Relay 与 Artifacts 发布;遥测是匿名的、按随机本地 ID 键控,不上传文件内容、prompt、终端输出、仓库名与路径,且 DO_NOT_TRACK=1 或 ORCA_TELEMETRY_DISABLED=1 任一即可关闭(telemetry)。也就是说:认证不绑定任何云端身份,安全完全取决于本地 token 与网络边界——这更要求你别把配对链接当普通分享链接。
收尾:五个炸点速查表
| 炸点 | 典型症状 | 处置 |
|---|---|---|
| 内存按乘法算 | 多代理并行后系统卡死、Swap 打满 | ≥32 GB;开 Agent hibernation(默认 30 分钟);Resource Manager 清理闲置 worktree;orca.yaml 共享 node_modules |
| 端口/监听地址 | orca serve 起来了但手机/客户端连不上 |
默认配对钉在 127.0.0.1,必须显式 --pairing-address 声明可达地址;需要固定端口时加 --port 6768 |
| 网络路径 | 白天好用晚上断、跨网络换地址失联 | 桌面须在配对路径上保持运行;改地址不改配对 token;首选 Tailscale 同 tailnet |
| 认证 | 配对失败、Authentication invalid、版本被拦截 | 配对码过期就重生成;Relay 要求手机与桌面同一 Orca 账号;升级后仍报错则移除主机重新配对 |
| 暴露面 | 把端口映射到公网、链接外泄 | Access Link 视为密码;Shared Server Access 里逐客户端撤销;绝不直接公网转发端口,用 Tailscale/SSH 隧道 |
Orca 的设计里,并行是默认值、安全默认是保守的(本地监听、链接即密码、可撤销 token),这套取舍在源码与文档里都能逐条对上。第一晚别急着开 8 个代理赛跑,先把内存预算、--pairing-address 与访问链接的管理规则过一遍——这五条踩完,后面就是纯收益。

