Orca Headless Linux 服务器部署：orca serve 完整实战指南

Orca Headless Linux 服务器部署：orca serve 完整实战指南

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca

Orca 是一款可运行并行编码 Agent 集群的 AI 编排平台（ADE），支持用你自己的订阅驱动任意 CLI 编码 Agent。通过内置的orca serve命令，你可以在没有图形界面的 Headless Linux 服务器（如 Ubuntu VPS）上直接启动 Orca 运行时，让 Agent 24/7 持续工作，并在桌面端或手机上随时查看、接管任务。本文带你从零完成一次完整的生产部署。

orca serve 是什么？为什么要无头部署 🖥️

日常使用中，Orca 是一个桌面应用；而orca serve会让 Orca 只启动运行时服务、不打开桌面窗口，并通过 WebSocket 监听端口对外提供服务。

无头部署的典型收益：

• 持续运行：VPS 常驻，Agent 任务不必依赖你的电脑开机；
• 移动管理：手机 App 或网页端配对后，即可远程查看进度、追加指令；
• 多客户端共享：桌面、手机、Web 同时连接同一个运行时。

📖 本文依据官方无头部署指南编写，完整文档见仓库中的docs/reference/headless-linux-server.md，系统兼容性说明见docs/reference/linux-glibc-compatibility.md。

部署前系统要求（一分钟核对）

两点提醒：

• Orca 在无DISPLAY时会自动启动 Xvfb（:99显示），无需单独搭建 D-Bus 会话，但xvfb包必须预装；
• FUSE 并非必需。Docker 容器通常没有 FUSE 设备，可用--appimage-extract一次性解包后直接运行squashfs-root/AppRun。

一键安装步骤：准备依赖与下载 AppImage

在服务器终端执行：

sudo apt-get update sudo apt-get install -y curl file jq xvfb zlib1g-dev # Ubuntu 22.04 额外安装：libfuse2 sudo mkdir -p /opt/orca # 从项目发布页（Releases）下载最新版 orca-linux.AppImage 到 /opt/orca sudo chmod +x /opt/orca/orca-linux.AppImage

如果Xvfb不在/usr/bin下，用command -v Xvfb确认其绝对路径，systemd 单元里要用到它。

最快启动命令：先前台运行验证

创建服务之前，务必先在前台跑通一次：

LIBGL_ALWAYS_SOFTWARE=1 /opt/orca/orca-linux.AppImage serve --port 6768

如果客户端在别的机器上，追加--pairing-address告知客户端应当连接的地址（私有服务器推荐 Tailscale 地址）：

LIBGL_ALWAYS_SOFTWARE=1 /opt/orca/orca-linux.AppImage serve \ --port 6768 \ --pairing-address 100.64.1.20

启动成功后，标准输出会打印一段就绪信息：

Orca server ready Bound endpoint: ws://0.0.0.0:6768 Advertised endpoint: ws://100.64.1.20:6768 Pairing URL: orca://pair?code=...

理解这两个端点的关键区别：

• boundEndpoint：进程实际监听的位置；
• advertisedEndpoint：客户端实际拨号的位置（由--pairing-address决定）。

--pairing-address只是"广告"地址，不会改变监听绑定。省略端口时会自动使用真实绑定端口；*、0.0.0.0、::这类通配地址不能作为广告地址。

面向自动化/进程管理器，可加--json获得单行 JSON 就绪契约（type: orca_server_ready），配合jq解析即可做健康检查。前台进程按Ctrl+C停止。

systemd 后台常驻部署配置

1️⃣ 创建专用服务用户

以服务用户（而非 root）运行，可以保留 Chromium 沙箱的安全边界：

sudo useradd --system --create-home --shell /usr/sbin/nologin orca sudo chown root:root /opt/orca /opt/orca/orca-linux.AppImage sudo chmod 755 /opt/orca /opt/orca/orca-linux.AppImage

安装目录保持 root 属主：服务只需读取和执行 AppImage，不能替换它。

2️⃣ 编写 orca-serve 服务单元

创建/etc/systemd/system/orca-serve.service（把示例中的地址换成你的局域网 / Tailscale / 隧道地址）：

[Unit] Description=Orca runtime server After=network-online.target Wants=network-online.target StartLimitIntervalSec=300 StartLimitBurst=5 [Service] Type=simple User=orca WorkingDirectory=/home/orca Environment=LIBGL_ALWAYS_SOFTWARE=1 ExecStart=/opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20 StandardOutput=journal StandardError=journal KillMode=mixed Restart=on-failure RestartPreventExitStatus=3 RestartSec=5 [Install] WantedBy=multi-user.target

这段配置的三个设计细节值得注意：

• KillMode=mixed：优雅停止信号只发给 Orca 主进程，让它可以"带走"自启的 Xvfb 直到 Electron 干净断开；
• RestartPreventExitStatus=3：退出码 3 表示别的进程已占用该数据目录（userData profile），此时应停止服务而不是重试；
• StartLimitBurst=5+StartLimitIntervalSec=300：把 5 分钟内启动次数限制在 5 次，防止坏启动进入"无限重启"风暴。

3️⃣ 启用并做就绪健康检查

sudo systemctl daemon-reload sudo systemctl enable --now orca-serve.service sudo journalctl -u orca-serve.service -f

自动化脚本里可以用一行命令过滤出就绪 JSON：

sudo journalctl -u orca-serve.service -o cat \ | jq -Rrc 'fromjson? | select(.type == "orca_server_ready" and .schemaVersion == 1)'

💡 如果希望虚拟显示的生命周期完全由 systemd 托管，可以单独建一个orca-xvfb.service运行Xvfb :99 -screen 0 1280x1024x24 -nolisten tcp，再给 Orca 单元加上Environment=DISPLAY=:99。默认情况下这一步可省略——orca serve会自动起 Xvfb。

客户端配对：桌面、手机、Web 三种接入方式

服务就绪后，Orca 会生成一个形如orca://pair?code=...的配对 URL。把它交给目标客户端（桌面端、手机 App 或 Web 端）即可完成端到端加密配对。

配对排错时记住四条规则：

1. 配对凭据是敏感信息：只分享给目标客户端，不要让它进入反向代理的访问日志；
2. 网络要真正可达：DNS、防火墙、Docker 端口发布、Tailscale 策略、反向代理，任何一环不通，"看起来有效"的配对也连不上；
3. 反向代理必须支持 WebSocket upgrade：TLS 在代理侧终结时，广告地址要用wss://或https://，不要透过 HTTPS 端点广告ws://；
4. 端口不匹配 = 外部路由配错：Orca 不会篡改你显式指定的代理端口。

无头安装 Agent Skills：不用打开设置界面 🧩

桌面端通常从"设置"里一键安装技能（Agent Skills）；无头主机没有设置界面，改用 CLI：

orca skills install # 列出可安装技能 orca skills install --skill orca-cli --skill orchestration orca skills install --all --dry-run # 只打印将执行的命令

该命令要求主机装有node/npx，但不需要 Orca 运行时在跑。它会自动根据主机上检测到的编码 Agent 确定安装目标；检测不到时会停下来要求你显式传--agent（如--agent claude-code,codex），避免盲目装进所有 Agent。

升级与回滚要点（比安装更重要 ⚠️）

• orca serve永不自动更新：无头模式不接线任何自动更新器，升级永远是"替换 AppImage + 重启服务"这一刻意动作；
• 数据与二进制分离：持久化状态全部位于/home/orca/.config/，与/opt/orca/orca-linux.AppImage无关。替换二进制绝不触碰项目、worktree 元数据、终端历史和已配对设备密钥——升级后手机和 Web 客户端无需重新配对即可重连；
• 严禁原地覆盖：AppImage 是 FUSE 挂载，运行中直接覆盖可能让进程崩溃。正确做法是下载到.new临时名 → 用file校验架构 → 原子mv换入；
• 记录版本：Orca 无头模式没有--version命令，建议显式指定 Release 标签下载，并把版本号写入/opt/orca/VERSION以便审计；
• 回滚必须"备份 + 换二进制"双管齐下：新版本一旦启动，可能把orca-data.json迁移到新 schema；只换回旧二进制、不恢复旧数据，旧版本可能丢弃它不认识的状态字段。官方升级/回滚脚本（见docs/reference/headless-linux-server.md的 Upgrade 章节）会自动生成带时间戳的.ready回滚包，包含旧二进制、版本记录与 profile 备份，三者必须成对使用。

常见报错排错清单

总结

一次标准的 Orca 无头部署可以概括为四步：装依赖（xvfb等）→ 前台跑通orca serve→ systemd 常驻 + 就绪 JSON 健康检查 → 客户端配对。只要数据存放在服务用户主目录、二进制通过原子替换升级、回滚包成对保留，你的 VPS 上就能稳定跑起一支 24/7 的并行 Agent 集群，并从口袋里随时接管。

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca