Cloudflare Workers 免费搭建开源远程桌面完整教程：无需 VPS，支持 WebRTC P2P、D1、KV、R2、浏览器远程控制、Windows 客户端和文件传输
GsDesk 是一款基于 Cloudflare Workers 与 VPS 自托管 的开源远程桌面项目，支持 WebRTC P2P 直连，服务端仅负责 API、身份认证和 WebSocket 信令，不中转桌面视频流，大幅降低服务器带宽成本。项目支持 Cloudflare 免费套餐 部署，也可以使用 Docker 在 VPS 上自托管，内置 Windows 客户端、浏览器控制端、手机远程控制，支持 8 位设备 ID、OTP 一次性密码、永久密码、Ed25519 设备认证、JWT 身份验证、文件传输、剪贴板同步、自动重连 等完整功能。
gsdesk — 利用Cloudflare Workers + KV + D1 + R2自建免费开源远程桌面
本文详细介绍 gsdesk 的功能特点、系统架构、Cloudflare 部署、VPS 自托管、Windows 客户端、Web 控制端、开发环境、API、安全设计以及完整配置说明，帮助开发者快速搭建属于自己的远程桌面平台。
v0.1.7 · 产品规格 · Cloudflare 部署 · VPS 自托管
gsdesk 是一款开源远程桌面方案：用 Cloudflare Workers（免费套餐可用）或 VPS 自托管 提供 API 与 WebSocket 信令；桌面画面经 WebRTC P2P 直连，服务端不中转视频流。
- Windows 主客户端：
gsdesk-client.exe，本地 UIhttp://127.0.0.1:19527，控制端与被控端合一 - 手机 / 浏览器：通过可配置的安全入口（默认
https://你的域名/app/）打开控制界面 - 根路径
/：仅返回success，表示 API 正常，不是控制页面
国内用户说明 使用 Cloudflare 时，部分操作（绑定支付方式、升级套餐等）可能需要 Visa / Mastercard。若国内银行卡无法验证，可参考：虚拟信用卡实测与开卡指南。
快速开始
| 步骤 | 操作 |
|---|---|
| 1 | 部署 Cloudflare Worker 或 VPS |
| 2 | 下载 gsdesk-client.exe 并运行 |
| 3 | 客户端 设置 → 填写 API 地址与 CONTROLLER_JWT_SECRET → 本机 开启「允许被控」→ 远程控制 输入 8 位设备 ID |
连接密码支持一次性密码（OTP）或永久密码，输入后系统自动识别；永久密码连接成功后会记住，OTP 不会保存。
功能概览
远程控制
- 统一 Windows 客户端：控制端 + 被控端，无需分别安装
- WebRTC P2P：键鼠、剪贴板、桌面画面端到端直连（默认 JPEG，可选 VP8）
- 8 位设备 ID、最近连接、适应 / 铺满 / 画质 / 全屏、断线 30 秒自动重连
安全与访问
- Ed25519 设备密钥 + JWT 控制器令牌
- OTP 可手动刷新；永久密码自定义
- 默认自动接受远程连接；关闭后被控端弹窗确认
- 连接限流与签名校验（生产环境请更换强随机密钥）
部署方式
| 方式 | 说明 |
|---|---|
| Cloudflare Workers | D1 + KV + R2 + Durable Objects，一键 Deploy 按钮 |
| VPS 自托管 | Docker 或 npm run dev:server，SQLite 持久化 |
| 手机浏览器入口 | WEB_APP_PATH 配置（默认 /app），见 配置说明 |
架构一览
┌──────────────────────────────────────────┐
│ 后端（二选一） │
│ Cloudflare Worker 或 VPS apps/server │
│ GET / → success（健康探测） │
│ GET /app/ → 手机/浏览器控制 UI │
│ /api/* /ws/* → API + 信令 │
└─────────────────┬────────────────────────┘
│ HTTPS / WSS
▼
gsdesk-client.exe（Windows）
127.0.0.1:19527 控制 + 被控
│
WebRTC P2P ◄──────────────► 对端 Agent
（画面不经 Worker / VPS 中转）
| 层级 | Cloudflare | VPS 自托管 |
|---|---|---|
| 配置文件 | 根目录 wrangler.toml |
apps/server + .env |
| 数据库 | D1 | SQLite |
| 信令 | Durable Objects | Node WebSocket 房间 |
| 文件存储 | R2 | 本地 / 可扩展 |
部署到 Cloudflare
部署完成后验证：
- 访问
https://你的域名/→ 看到success - 访问
https://你的域名/app/→ 打开手机 / 浏览器控制界面（路径可在wrangler.toml修改） - 在客户端 设置 填入 Worker 地址与
CONTROLLER_JWT_SECRET
git clone https://github.com/gsvps/gsdesk.git
cd gsdesk
npm install
npx wrangler login
npm run deploy:cloudflare # 构建 Web 入口 + 数据库迁移 + 部署 Worker
详见 https://www.gsvps.com/articles/news-20。
VPS 自托管
docker compose up -d --build
# 或本地开发：npm run dev:server
详见 https://www.gsvps.com/articles/news-21。
Windows 客户端
下载 gsdesk-client.exe（最新 Release）
便携免安装。启动后浏览器打开 http://127.0.0.1:19527：
| 左栏 · 本机 | 中栏 · 设置 | 右栏 · 远程控制 |
|---|---|---|
| 允许被控、设备 ID、连接测试 | API 地址、控制器令牌、画质与剪贴板 | 输入 8 位 ID、最近连接、进入远程桌面 |
| 一次性 / 永久密码 | 设备名、下载目录、手机入口链接 | 远程会话与文件传输 |
配置存放位置
- API / 令牌：
localStorage（127.0.0.1:19527页面） - Agent 设置：
%USERPROFILE%\.gsdesk\config.json
自行编译
cd apps/agent
powershell -ExecutionPolicy Bypass -File .\build-client.ps1
手机 / 浏览器控制
Worker 与 VPS 均托管一份轻量 Web 控制端，入口路径由环境变量 WEB_APP_PATH 决定（默认 /app）。
| 场景 | 地址示例 |
|---|---|
| 健康探测 | https://你的域名/ → success |
| 手机控制 | https://你的域名/app/ |
| 健康检查 API | GET /api/health → 含 web_app_entry 字段 |
客户端 设置 页会在连接成功后显示完整手机链接，无需手拼路径。
修改入口路径时（例如改为 /desk）：
- 编辑
wrangler.toml的[vars] WEB_APP_PATH，或 VPS 的.env - 执行
npm run build:web:app（同步 Vitebase路径） - 重新
npm run deploy:cloudflare或重启 VPS
配置说明
Worker（wrangler.toml → [vars]）
| 变量 | 说明 |
|---|---|
WEB_APP_PATH |
手机 / 浏览器控制入口，默认 /app |
CONTROLLER_JWT_SECRET |
控制器 JWT 密钥，生产环境务必更换 |
CLIENT_DOWNLOAD_URL |
客户端 exe 下载地址 |
CLIENT_LATEST_VERSION |
客户端版本号（可选展示） |
VPS（apps/server/.env）
WEB_APP_PATH=/app
CONTROLLER_JWT_SECRET=请更换为强随机字符串
Agent 可选环境变量
$env:gsdesk_SERVER = "https://your-worker.example.com"
本地开发
git clone https://github.com/gsvps/gsdesk.git
cd gsdesk
npm install
| 终端 | 命令 | 说明 |
|---|---|---|
| 1 | npm run db:migrate:local -w @gsdesk/worker |
本地 D1 迁移 |
| 1 | npm run dev:worker |
API @ http://127.0.0.1:8787 |
| 2 | .\apps\agent\gsdesk-client.exe |
客户端；设置 API 为 http://127.0.0.1:8787 |
改 UI 时：npm run dev:web（Vite）；嵌入 exe 前需重新 build-client.ps1。
常用命令
npm run dev:worker # Worker 本地 API
npm run dev:server # VPS 本地 API
npm run dev:web # 前端开发
npm run build:web:app # 按 WEB_APP_PATH 构建托管用 Web UI
npm run deploy:cloudflare # 构建 + 迁移 + 部署
npm run typecheck
npm run test
主要 API
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / |
success（非 UI） |
| GET | /api/health |
健康检查，含 web_app_entry |
| POST | /api/device/register |
Agent 注册 |
| GET | /api/device/:id |
查询设备（需 JWT） |
| POST | /api/session/create |
创建远程会话 |
| GET | /ws/device/:id |
Agent 信令 |
| GET | /ws/session/:id |
控制端信令 |
目录结构
gsdesk/
├── apps/
│ ├── web/ # 控制端 UI（嵌入 exe + Worker/VPS 托管）
│ ├── worker/ # Cloudflare Worker API
│ ├── server/ # VPS 自托管 API
│ └── agent/ # Go 客户端（Release 分发 exe）
├── packages/protocol/
├── scripts/ # build-web-app.mjs 等
├── docs/
└── wrangler.toml
安全说明
- 设备 ID 不是密码；Ed25519 私钥仅保存在 Agent 本机
- WebRTC 媒体经 DTLS 加密；服务端不转发桌面流
- 生产环境使用强随机
CONTROLLER_JWT_SECRET - Cloudflare 与 VPS 为独立后端，切换后需重新注册设备
- 可通过修改
WEB_APP_PATH使用非默认入口，降低被扫描常见路径的概率
常见问题（FAQ）
Cloudflare Workers 真的可以搭建远程桌面吗？
可以。
本项目利用 Cloudflare Workers 提供 API、身份认证和 WebSocket 信令，真正的桌面画面通过 WebRTC P2P 在两台设备之间直接传输，因此 Worker 不负责转发远程桌面视频流。
搭建这个项目需要购买 VPS 吗？
不需要。
项目可以直接部署到 Cloudflare Workers，免费套餐即可正常运行，无需购买 VPS、无需部署中继服务器，也无需维护 Linux 环境。
如果你希望完全自托管，也可以选择部署到自己的 VPS。
Cloudflare 免费套餐可以使用吗？
可以。
gsdesk 从设计之初就兼容 Cloudflare 免费套餐，普通用户可以直接使用 Workers、D1、KV、R2 与 Durable Objects 完成部署。
如果后期访问量增加，也可以根据需要升级 Cloudflare 套餐。
为什么使用 Cloudflare Workers 不会产生很高的流量费用？
因为远程桌面画面不会经过 Cloudflare Workers。
Workers 仅负责：
- API
- WebSocket 信令
- 用户认证
- 会话管理
- 文件信息管理
桌面画面采用 WebRTC P2P 点对点直连，因此绝大部分流量不会经过 Worker。
远程桌面画面会经过 Cloudflare 或 VPS 中转吗？
不会。
gsdesk 默认采用 WebRTC P2P 技术，桌面画面直接在控制端与被控端之间传输。
服务器只负责建立连接，不负责转发视频流，因此可以有效降低服务器带宽占用。
支持哪些部署方式？
目前支持两种部署方式：
- Cloudflare Workers（推荐，无需 VPS）
- Linux VPS 自托管（Docker 或 Node.js）
两种后端协议保持一致，可以根据自己的需求选择部署方式。
Cloudflare Workers 版本和 VPS 版本有什么区别？
Cloudflare Workers 版本使用：
- Workers
- D1
- KV
- R2
- Durable Objects
VPS 版本使用：
- Node.js
- SQLite
- 本地文件存储
- WebSocket
两者功能基本一致，区别主要在部署环境和数据存储方式。
支持浏览器远程控制吗？
支持。
项目提供独立的 Web 控制端，只需打开浏览器访问配置好的控制页面即可连接远程设备，无需安装控制端软件。
同时也支持手机浏览器访问。
支持哪些操作系统？
当前版本提供 Windows Agent。
控制端支持：
- Windows 客户端
- Chrome
- Edge
- Firefox
- Safari
- Android 浏览器
- iPhone Safari
未来计划支持更多平台。
如何连接远程设备？
连接流程非常简单：
- 部署 Cloudflare Workers 或 VPS 后端。
- 下载并运行 Windows 客户端。
- 输入 API 地址和控制器 JWT。
- 输入 8 位设备 ID。
- 输入一次性密码（OTP）或永久密码即可开始远程控制。
支持文件传输吗？
支持。
项目支持远程文件上传和下载。
Cloudflare 部署时可使用 R2 对象存储，VPS 部署则使用本地文件存储。
项目安全吗？
gsdesk 提供多项安全机制，包括：
- Ed25519 设备身份认证
- JWT 控制器认证
- OTP 一次性密码
- 永久访问密码
- WebRTC DTLS 加密
- API 限流
- 登录失败限制
- 可关闭自动接受并要求用户确认连接
生产环境建议使用随机生成的 JWT 密钥，并启用所有默认安全设置。
可以修改浏览器控制入口吗？
可以。
默认浏览器入口为：
https://你的域名/app/
可以通过修改 WEB_APP_PATH 自定义为：
/desk/remote/control
修改后重新构建并部署即可生效。
Cloudflare Workers 版本适合哪些场景？
适合：
- 个人远程办公
- 家庭电脑远程控制
- IT 运维
- 开发者远程调试
- 自建远程桌面平台
- 企业内部远程协助
- 个人 NAS 远程管理
- 开源项目学习与二次开发
无需购买 VPS，即可快速拥有自己的远程控制平台。
