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/orcaOrca 是一款可运行并行编码 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。部署前系统要求一分钟核对项目要求操作系统Ubuntu 20.04 / 22.04 / 24.04或当前 Debian stableC 库glibc ≥ 2.31对应 libstdcGLIBCXX_3.4.28架构x86_64 或 arm64必装依赖xvfb虚拟显示、curl、file、jq、zlib1g-dev可选依赖libfuse2Ubuntu 22.0424.04 / Debian 为libfuse2t64两点提醒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_SOFTWARE1 /opt/orca/orca-linux.AppImage serve --port 6768如果客户端在别的机器上追加--pairing-address告知客户端应当连接的地址私有服务器推荐 Tailscale 地址LIBGL_ALWAYS_SOFTWARE1 /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解析即可做健康检查。前台进程按CtrlC停止。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] DescriptionOrca runtime server Afternetwork-online.target Wantsnetwork-online.target StartLimitIntervalSec300 StartLimitBurst5 [Service] Typesimple Userorca WorkingDirectory/home/orca EnvironmentLIBGL_ALWAYS_SOFTWARE1 ExecStart/opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20 StandardOutputjournal StandardErrorjournal KillModemixed Restarton-failure RestartPreventExitStatus3 RestartSec5 [Install] WantedBymulti-user.target这段配置的三个设计细节值得注意KillModemixed优雅停止信号只发给 Orca 主进程让它可以带走自启的 Xvfb 直到 Electron 干净断开RestartPreventExitStatus3退出码 3 表示别的进程已占用该数据目录userData profile此时应停止服务而不是重试StartLimitBurst5StartLimitIntervalSec300把 5 分钟内启动次数限制在 5 次防止坏启动进入无限重启风暴。3️⃣ 启用并做就绪健康检查sudo systemctl daemon-reload sudo systemctl enable --now orca-serve.service sudo journalctl -u orca-serve.service -f自动化脚本里可以用一行命令过滤出就绪 JSONsudo 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 单元加上EnvironmentDISPLAY:99。默认情况下这一步可省略——orca serve会自动起 Xvfb。客户端配对桌面、手机、Web 三种接入方式服务就绪后Orca 会生成一个形如orca://pair?code...的配对 URL。把它交给目标客户端桌面端、手机 App 或 Web 端即可完成端到端加密配对。配对排错时记住四条规则配对凭据是敏感信息只分享给目标客户端不要让它进入反向代理的访问日志网络要真正可达DNS、防火墙、Docker 端口发布、Tailscale 策略、反向代理任何一环不通看起来有效的配对也连不上反向代理必须支持 WebSocket upgradeTLS 在代理侧终结时广告地址要用wss://或https://不要透过 HTTPS 端点广告ws://端口不匹配 外部路由配错Orca 不会篡改你显式指定的代理端口。无头安装 Agent Skills不用打开设置界面 桌面端通常从设置里一键安装技能Agent Skills无头主机没有设置界面改用 CLIorca 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 备份三者必须成对使用。常见报错排错清单报错现象原因与解法dlopen(): error loading libfuse.so.2安装libfuse2Missing X server or $DISPLAY安装xvfb或启用独立 Xvfb 服务并设DISPLAY:99Xvfb not foundcommand -v Xvfb查绝对路径填进 systemd 单元VPS 上出现 GPU / DRI 警告保持LIBGL_ALWAYS_SOFTWARE1环境变量Chromium 沙箱报错确认服务以非 root 的orca用户运行/opt/orca对其可读客户端连不上检查--pairing-address对客户端可达防火墙放行--port日志提示Another Orca instance is already running单元退出码 3别的进程占用了数据目录。用systemctl status orca-servepgrep -af orca找到占用者若无人占用则是陈旧锁删掉 userData 里的SingletonLock/SingletonSocket后执行systemctl reset-failed orca-serve systemctl start orca-serve升级后服务崩溃循环直接用回滚包的.ready目录回滚手动systemctl start前记得systemctl reset-failed怀疑缺共享库./orca-linux.AppImage --appimage-extract解包后ldd squashfs-root/orca列出缺失项总结一次标准的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考