Orca systemd 服务配置完整指南：4步让 Orca 服务器开机自启与崩溃自动重启
【免费下载链接】orca Orca 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 是一款并行 AI 编程 Agent 编排平台（ADE），将它以常驻服务形式部署在 Linux 服务器上后，可随时通过桌面端或手机操控服务器上的 Agent。本文带你完整走一遍把 Orca 配置为 systemd 服务的全部流程，实现开机自启与崩溃自动重启，重启服务器后无需任何手动操作。
为什么要把 Orca 放到服务器上 7×24 运行 🚀
把 Orca 服务器交给 systemd 托管，能换来三件事：
- 整夜并行跑 Agent：同一个任务扇出给多个 Agent，各自在独立 worktree 中工作，睡一觉起来看结果
- 手机随时接管：Orca 手机伴侣 App 会在 Agent 完成或需要你决策时推送通知，出差路上就能发后续指令
- 桌面端无缝接入：通过应用内的 SSH 设置连接远程服务器，文件、终端、Git 全都在
以上场景都有一个前提：服务器上的 Orca 稳定存活——开机自启、崩溃自愈。这正是 systemd 的看家本领。
第1步：安装 headless 依赖并部署 Orca AppImage ⚙️
systemd 服务配置在 Ubuntu 20.04 / 22.04 / 24.04 与 Debian 最新稳定版上最省心（要求 glibc ≥ 2.31）：
sudo apt-get update
sudo apt-get install -y curl file jq xvfb zlib1g-dev
# Ubuntu 22.04 需额外安装 libfuse2（24.04 / Debian 上可能叫 libfuse2t64）
其中 Xvfb 是无头部署的关键：Orca 在没有图形界面时会自动在 :99 显示器上启动 Xvfb，你只需提前装好即可。
然后把 AppImage 部署到安装目录：
sudo mkdir -p /opt/orca
# 从官方 release 下载最新的 orca-linux.AppImage 到 /opt/orca 后执行：
sudo chmod +x /opt/orca/orca-linux.AppImage
第2步：先前台验证，确认 Orca 服务器健康 ✅
写 unit 文件之前，先手动跑一次，确保服务器本身没问题：
LIBGL_ALWAYS_SOFTWARE=1 /opt/orca/orca-linux.AppImage serve \\
–port 6768 –pairing-address 100.64.1.20
看到如下输出说明服务就绪（按 Ctrl+C 停止）：
Orca server ready
Bound endpoint: ws://0.0.0.0:6768
Advertised endpoint: ws://100.64.1.20:6768
两点说明：
- –pairing-address 只是通告给客户端的地址，不改变实际监听端口，请替换为客户端可达的内网 / Tailscale / 反向代理地址
- 仅供本机使用的话，可以省略该参数
第3步：创建专属 orca 服务用户 🔒
不要用 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，但不能替换它——后续升级与回滚都会更安全。
第4步：编写 orca-serve.service 单元文件，实现崩溃自动重启 🛠️
创建 /etc/systemd/system/orca-serve.service：
[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
关键指令逐条解读：
| Restart=on-failure | 进程异常退出后自动重启，这是自愈的核心 |
| RestartSec=5 | 每次重启间隔 5 秒 |
| RestartPreventExitStatus=3 | 退出码 3 表示配置档案已被其他进程占用，此时不重试，避免无意义循环 |
| StartLimitIntervalSec=300 + StartLimitBurst=5 | 5 分钟内最多启动 5 次，防止坏版本把机器刷爆 |
| KillMode=mixed | 优雅停止只发往 Orca 主进程，Xvfb 会保持到 Electron 干净断开 |
| LIBGL_ALWAYS_SOFTWARE=1 | 强制软件渲染，VPS 上没有独立显卡也不会报 GPU 错误 |
💡 Orca 的持久化数据存放在 /home/orca/.config/，与二进制文件完全隔离——重启服务或升级程序都不会动到项目、worktree 与配对设备数据。
启用开机自启并验证自动重启 📱
三条命令完成启用与验证：
sudo systemctl daemon-reload
sudo systemctl enable –now orca-serve.service
sudo journalctl -u orca-serve.service -f
enable 就是开机自启的关键（在 multi-user.target 后自动拉起），–now 顺便立即启动。
日志中出现 Orca server ready 块、且端口与配置一致，说明服务健康。再手动验证一次自动重启：
sudo systemctl restart orca-serve.service
重启后 5 秒内服务会重新就绪。注意：如果连续快速启动 5 次触发限流，单元会进入 failed 状态，先执行下面命令清除即可：
sudo systemctl reset-failed orca-serve.service
可选：独立的 Xvfb 虚拟显示服务 🖥️
默认情况下 Orca 自行管理 Xvfb，大多数主机只需一个服务。如果你想让 systemd 完整接管显示生命周期，再加一个 orca-xvfb.service：
[Unit]
Description=Virtual X display for Orca
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x1024x24 -nolisten tcp
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
然后在 orca-serve.service 的 [Service] 段加上 Environment=DISPLAY=:99，最后一起启用：
sudo systemctl daemon-reload
sudo systemctl enable –now orca-xvfb.service orca-serve.service
常见问题速查表 🔍
| dlopen(): error loading libfuse.so.2 | 安装 libfuse2 |
| Missing X server or $DISPLAY | 安装 xvfb，或启用独立 Xvfb 服务并设置 DISPLAY=:99 |
| Xvfb not found | 用 command -v Xvfb 找到真实路径，把绝对路径写入 unit |
| 客户端连不上 | 确认 –pairing-address 对客户端可达，防火墙放行 6768 端口 |
| 退出码 3，单元停留在 failed | 另一进程占用了配置档案，pgrep -af orca 找到并停掉，再 reset-failed + 启动 |
| GPU / DRI 警告 | 保留 LIBGL_ALWAYS_SOFTWARE=1（上文 unit 已包含） |
总结：4步实现 Orca 服务器开机自启
| 1 | 安装 xvfb 等依赖，部署 AppImage 到 /opt/orca | headless 环境就绪 |
| 2 | 前台运行 orca serve 看到 ready 块 | 确认服务器健康 |
| 3 | useradd orca + 编写 unit 文件 | 定义"怎么跑、怎么重启" |
| 4 | systemctl enable –now | 开机自启 + 故障自动重启 |
配置完成后，Orca 就会成为一台真正的 7×24 Agent 服务器。关于版本升级、原子化回滚和 JSON 健康检查契约等进阶内容，完整的脚本与细节参见官方 headless 服务器文档 docs/reference/headless-linux-server.md。
【免费下载链接】orca Orca 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），仅供参考
