GsDesk VPS 自托管教程：Docker 部署开源远程桌面，支持 WebRTC P2P、浏览器远程控制

GsDesk VPS 自托管

桌面数据依旧采用 WebRTC P2P 直连，服务器不会中转桌面视频流，因此即使配置较低的 VPS，也能轻松承载大量远程连接。项目还支持 Windows 客户端、浏览器控制端、手机远程控制、SQLite 数据库、本地文件存储、JWT 身份认证、OTP 一次性密码、永久访问密码、自定义 Web 控制路径 等完整功能。

本教程详细介绍 GsDesk VPS 版本的安装部署、Docker Compose 配置、环境变量说明、SQLite 数据持久化、Web 控制端构建、Cloudflare 与 VPS 的区别、后端切换方式以及常见问题排查，帮助开发者快速搭建属于自己的开源远程桌面系统。VPS 与 Cloudflare Worker 协议相同：API + WebSocket 信令 + 可配置 Web 控制端。根路径 GET / 返回 success；手机/浏览器控制界面在 WEB_APP_PATH（默认 /app/）。

Windows 主客户端请用 GsDesk-client.exe；浏览器控制无需安装 exe。

HTTP 路由与 Worker 共享：apps/worker/src/app.ts（createCoreApp）。

Cloudflare 部署见 deploy.md。

快速启动

git clone https://github.com/gsvps/GsDesk.git
cd GsDesk
npm install
cp apps/server/.env.example apps/server/.env   # 按需修改
npm run dev:server    # http://127.0.0.1:8787

验证：

curl http://127.0.0.1:8787/              # success
curl http://127.0.0.1:8787/api/health    # 含 web_app_entry: "/app/"

浏览器打开 http://127.0.0.1:8787/app/ 可测试 Web 控制端。

运行 GsDesk-client.exe，设置 → API 地址 http://127.0.0.1:8787，令牌与 .env 中 CONTROLLER_JWT_SECRET 一致。

环境变量

复制 apps/server/.env.example 并按需修改：

示例：

PORT=8787
GsDesk_DATA=./data
CONTROLLER_JWT_SECRET=请更换为强随机字符串
WEB_APP_PATH=/app
SKIP_SIGNATURE_VERIFY=false

Web 控制端静态资源

VPS 从 apps/web/dist 提供 SPA（需预先构建）：

npm run build:web:app   # 读取 wrangler.toml 或 WEB_APP_PATH 环境变量
npm run dev:server

修改 WEB_APP_PATH 后必须重新 build:web:app，否则 Vite base 与路由不一致。

GET /api/health 返回的 web_app_entry 供客户端设置页显示完整手机链接。

Docker Compose

docker compose up -d --build

• 监听 8787
• 数据持久化到卷 ./data
• 环境变量通过 docker-compose.yml 或 .env 注入

部署前建议在宿主机执行 npm run build:web:app，确保镜像内 apps/web/dist 与 WEB_APP_PATH 匹配（若 compose 未在构建阶段自动执行）。

访问：

• http://服务器IP:8787/ → success
• http://服务器IP:8787/app/ → Web 控制端

与 Cloudflare 的差异

切换后端

Cloudflare Worker 与 VPS 数据不共享。切换时：

1. 在新后端重新注册设备（Agent 会获得新 device_id）
2. 客户端 设置 更新 API 地址与 JWT
3. 重新配置 OTP / 永久密码

故障排查

VPS 同样不中转桌面视频流；远控画面经 WebRTC P2P 直连。

`