Add Xvfb documentation for headless server and remote access

README.md

@@ -112,6 +112,10 @@ auth:
 http://127.0.0.1:3737
 ```
 
+### 无头服务器启动
+
+[配置步骤](docs/Xvfb.md)
+
 ### 远程访问
 
 OpenCodex本身不提供远程访问服务，如果需要在其他设备中远程访问，请使用Tailscale、ZeroTier、Cloudflare Tunnel、企业自建 VPN 等方式搭建网络，然后在启动器中打开局域网模式进行访问。

docs/Xvfb.md

@@ -0,0 +1,178 @@
+# Xvfb 无头运行指南
+
+OpenCodex 本身是一个 Codex Desktop Web 中间层，让浏览器访问 Codex。原版仅支持 macOS/Windows，通过 Xvfb 可使其在无显示器的 Linux 服务器上运行。
+
+## 原理
+
+Codex Desktop 基于 Electron，需要一个 X Window 显示环境渲染界面。Xvfb（X Virtual Framebuffer）在内存中模拟一个虚拟显示器，Electron 将画面输出到虚拟显示器上，无需物理屏幕或桌面环境。
+
+```
+无头服务器                 用户浏览器
+┌──────────────────┐      ┌─────────────┐
+│  Xvfb :99        │      │             │
+│  (虚拟 framebuffer)│     │ 手机/平板/   │
+│       ↑          │      │ 另一台电脑   │
+│  Codex Desktop   │◄────►│             │
+│  (Electron)      │ HTTP │             │
+│       ↑          │  +WS │             │
+│  OpenCodex        │      │             │
+│  Gateway         │────►│             │
+└──────────────────┘      └─────────────┘
+```
+
+## 前置条件
+
+安装 Xvfb：
+
+```bash
+# Debian/Ubuntu
+sudo apt install xvfb
+
+# CentOS/RHEL/Fedora
+sudo yum install xorg-x11-server-Xvfb
+```
+
+另需 Node.js、pnpm 以及 Codex Desktop Linux 版。
+
+## 获取 Codex Desktop Linux
+
+Codex Desktop 官方仅提供 macOS/Windows 版。Linux 版由社区项目 [ilysenko/codex-desktop-linux](https://github.com/ilysenko/codex-desktop-linux) 自动从上游 macOS DMG 构建：
+
+```bash
+git clone https://github.com/ilysenko/codex-desktop-linux.git
+cd codex-desktop-linux
+make bootstrap-native
+```
+
+产物位于 `codex-app/` 目录，结构为：
+
+```
+codex-app/
+├── electron        # Electron 二进制
+├── resources/
+│   └── app.asar    # Codex Desktop 应用代码
+├── locales/
+└── ...
+```
+
+OpenCodex 默认期望 `CODEX_DESKTOP_PATH` 指向此目录。
+
+## 启动 Xvfb
+
+```bash
+Xvfb :99 -screen 0 1920x1080x24 -ac +extension GLX +render -noreset &
+```
+
+| 参数 | 说明 |
+|------|------|
+| `:99` | 显示编号，通过 `DISPLAY=:99` 引用 |
+| `-screen 0 1920x1080x24` | 分辨率 1920×1080，24 位色深 |
+| `-ac` | 关闭访问控制 |
+| `+extension GLX` | 启用 GLX 扩展（某些 Electron 应用需要） |
+| `+render` | 启用 Render 扩展 |
+| `-noreset` | 不自动重置 |
+
+确认运行：
+
+```bash
+pgrep -a Xvfb
+```
+
+## 环境变量
+
+启动前需设置的关键环境变量：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `DISPLAY` | Xvfb 显示编号 | `:99` |
+| `CODEX_DESKTOP_APP_PATH` | Codex Desktop 安装目录（含 `app.asar`） | `/tmp/codex-desktop-linux/codex-app` |
+| `CODEX_DESKTOP_EXECUTABLE_PATH` | Electron 可执行文件路径 | `/tmp/codex-desktop-linux/codex-app/codex` |
+| `CODEX_CLI_PATH` | Codex CLI 二进制路径 | `/opt/codex-cli/codex` |
+| `CODEX_HOME` | Codex 配置目录 | `~/.codex` |
+
+`DISPLAY` 指向 Xvfb。其余变量让 OpenCodex 知道 Electron 和 Codex CLI 的位置，以及配置文件存放路径。
+
+## 修改 Electron 启动参数
+
+原始仓库 `gateway/dev/run-gateway.cjs` 中仅传入 `--user-data-dir`：
+
+```js
+const officialRuntimeArgs = [`--user-data-dir=${officialUserDataDir}`];
+```
+
+在无头 Linux 上需改为：
+
+```js
+const officialRuntimeArgs = [
+  `--user-data-dir=${officialUserDataDir}`,
+  '--no-sandbox',
+  '--disable-setuid-sandbox',
+  '--disable-dev-shm-usage',
+];
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--no-sandbox` | 服务器环境下 Chrome 沙箱通常不可用（root 运行或容器环境），不加会导致 Electron 启动失败 |
+| `--disable-setuid-sandbox` | 配合 `--no-sandbox` 禁用 setuid 辅助进程 |
+| `--disable-dev-shm-usage` | 避免 `/dev/shm` 过小（容器默认 64MB）导致崩溃，改用普通内存 |
+
+## 启动 OpenCodex
+
+```bash
+export DISPLAY=:99
+export CODEX_DESKTOP_APP_PATH=/tmp/codex-desktop-linux/codex-app
+export CODEX_DESKTOP_EXECUTABLE_PATH=/tmp/codex-desktop-linux/codex-app/codex
+export CODEX_CLI_PATH=/opt/codex-cli/codex
+
+cd /path/to/OpenCodex
+pnpm install
+PORT=3737 pnpm run web:dev
+```
+
+访问 `http://服务器IP:3737` 即可使用。
+
+如设置了密码，先编辑 `config.yaml`：
+
+```yaml
+auth:
+  password: "你的密码"
+```
+
+## 与 systemd 集成
+
+```ini
+# /etc/systemd/system/xvfb.service
+[Unit]
+Description=X Virtual Frame Buffer Service
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/Xvfb :99 -screen 0 1920x1080x24 -ac +extension GLX +render -noreset
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now xvfb.service
+```
+
+## 常见问题
+
+### Electron 无法启动 / "Cannot open display"
+
+- 确认 Xvfb 是否运行：`pgrep -a Xvfb`
+- 确认 `DISPLAY` 已设置：`echo $DISPLAY`
+- 测试连接：`xdpyinfo -display :99`
+- Xvfb 启动后未完全就绪，添加 `sleep 2` 等待
+
+### 渲染异常 / 白屏
+
+部分 Electron 应用依赖 GPU 加速，Xvfb 默认软件渲染可能不兼容。尝试禁用 GLX 扩展：
+
+```bash
+Xvfb :99 -screen 0 1920x1080x24 -ac -extension GLX &
+```