DeskVNCServer - 指南

入门

1. 设置密码

打开"设置"(底部工具栏的齿轮图标),填写 VNC password。标准 VNC 客户端使用 RFB DES 质询认证,只识别前 8 个 ASCII 兼容字节 — 请选择不超过 8 个字符的密码。

2. 启动服务器

1. 在主窗口点击 Start。状态指示器切换为 Running。
2. 同时启动四个监听器: VNC 5900、QREX control 5911、QREX media 4010 和 File API 8766。
3. 点击 Copy Info 可将包含主机、端口和当前 PIN 的一行信息复制到剪贴板。

3. 连接客户端

对于标准 VNC 查看器(macOS Screen Sharing、RealVNC、TightVNC、移动端 VNC 应用):

1. 打开查看器并输入 vnc://<your-mac-ip>:5900 作为地址
2. 输入您在第 1 步设置的 VNC password
3. 立即控制您的 Mac — 通过 RFB 进行键盘、鼠标、复制/粘贴操作

对于 QuickRemote 应用:

1. 在手机或平板上打开 QuickRemote,选择 Add Mac
2. 输入 DeskVNCServer 显示的 6 位配对 PIN(如果您的 QuickRemote 版本支持,也可以扫描二维码)
3. QuickRemote 保存返回的 Bearer 令牌,并解锁扩展功能 — IME、音频、剪贴板同步和文件传输

界面概览

状态行

操作按钮

• Start — 启动所有四个监听器。
• Stop — 关闭所有监听器并断开活动会话。
• Copy Info — 将简短的连接摘要(主机、VNC 端口、控制端口、PIN)复制到剪贴板,以便与客户端共享。

连接面板

显示绑定主机、端口、当前 Server ID 和活动配对 PIN。设置更改时文本会自动刷新。

QuickRemote API 面板

关于服务器所使用协议的快速参考。列出支持的 RFB 版本、QREX 端点结构和 IME 命令集,让 QuickRemote(或您自己的客户端)了解可用功能。

协议与端口

认证

• VNC 客户端 — RFB DES 密码(已配置密码的 ASCII 兼容前 8 字节)。
• QREX 客户端 — 在 POST /qr/v1/pair 进行初始 6 位 PIN 交换,返回 Bearer 令牌。后续每个 QREX HTTP 调用和 WebSocket 帧都必须包含 Authorization: Bearer <token>。
• 如果 VNC password 为空,服务器会通告标准 RFB no-auth 模式。仅适用于受信任的 LAN 网段。

QREX 端点快速参考

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

设置

客户端示例

macOS Screen Sharing

1. Finder → 前往 → 连接服务器
2. 输入 vnc://<your-mac-ip>:5900
3. 输入 VNC password

cURL — 查询功能

curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — 配对并调用 IME bridge

# 1. Exchange the PIN for a Bearer token
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Commit text via the IME bridge
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

提示

• 在使用慢速 Wi-Fi 或通过 VPN 路由连接时,请降低帧率和最大帧尺寸。
• 每台设备配对一次即可。完成初始 PIN 交换后,Bearer 令牌可在重启后保留,QuickRemote 会无声地重新连接。
• 使用 Copy Info 通过聊天或邮件发送连接详情 — 其中包含客户端所需的全部内容。
• 除非真的需要上传,否则请将 Enable file mutations 保持关闭。只读模式足以浏览截图、笔记或下载内容。
• 不使用音频 API 时请将其禁用。空闲的编解码器仍会在编码路径上占用少量 CPU。

故障排除

服务器无法启动

• 另一个 VNC 服务器(例如 macOS Screen Sharing)可能已占用端口 5900。请从 System Settings → General → Sharing 停止,或在 DeskVNCServer 的设置中更改端口。
• 端口 5911 / 4010 / 8766 必须全部空闲。使用 lsof -i :5911 等命令检查。

VNC 客户端认证失败

• 确保密码不超过 8 个 ASCII 兼容字节。多字节字符或更长的字符串会被 RFB DES 认证静默截断。
• 如果有意不设置密码,请将该字段留空,并使用支持 VNC no-auth 的查看器连接。

QuickRemote 无法配对

• 确认手机或平板与 Mac 处于同一 Wi-Fi 网络。
• 打开连接面板重新查看 PIN。可在"设置"中重新生成 PIN。
• 检查 macOS 防火墙设置 — 必须允许 QREX 端口的入站连接。

远程控制感觉卡顿

• 在"设置"中降低帧率和最大帧尺寸。
• 禁用不使用的功能(音频、剪贴板、IME)以释放 CPU。

文件无法传输

• 确认 Enable file transfer 已开启。无需 Enable file mutations 即可使用只读列表。
• 如果上传失败,请同时启用 Enable file mutations。否则 File API 仅响应读取请求。

隐私

• 所有会话都直接在客户端和您的 Mac 之间进行。没有云中继,没有遥测,也没有分析。
• VNC password、QREX Bearer 令牌、配对 PIN 和 Stable Server ID 仅存储在本地应用设置中。
• 文件变更功能默认关闭。在您明确授予写权限之前,远程客户端只能读取。
• 可随时禁用任何扩展(音频、剪贴板、文件传输、IME、远程输入)以立即撤销该能力。
• 如果想将服务器保持在 Mac 本地,请将绑定主机设置为 127.0.0.1。