DeskVNCServer - 指南

快速上手

1. 设置密码

打开设置（底部工具栏的齿轮图标）并填写 VNC 密码。标准 VNC 客户端使用 RFB DES 挑战认证，只识别前 8 个 ASCII 兼容字节 — 请设置不超过 8 个字符的密码。

2. 启动服务器

1. 在主窗口中，点击 启动。状态指示器会切换为 运行中.
2. 四个监听器会同时启动：VNC 5900、QREX 控制 5911、QREX 媒体 4010，以及文件 API 8766.
3. 点击 复制信息 可将包含主机、端口和当前 PIN 的一行文本复制到剪贴板。

3. 连接客户端

使用标准 VNC 查看器（macOS 屏幕共享、RealVNC、TightVNC、移动端 VNC 应用）时：

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

使用 QuickRemote 应用时：

1. 在手机或平板上打开 QuickRemote，选择 添加 Mac
2. 输入 DeskVNCServer 显示的 6 位配对 PIN（若您的 QuickRemote 版本支持，也可扫描二维码）
3. QuickRemote 会保存返回的 Bearer 令牌并解锁扩展功能 — 输入法、音频、剪贴板同步与文件传输

界面概览

状态栏

操作按钮

• 启动 — 启动全部四个监听器。
• 停止 — 关闭所有监听器并断开活动会话。
• 复制信息 — 将简短的连接摘要（主机、VNC 端口、控制端口、PIN）复制到剪贴板，便于分享给客户端。

连接面板

显示绑定主机、端口、当前服务器 ID 以及当前的配对 PIN。设置变更时文本会自动刷新。

QuickRemote API 面板

服务器所支持协议的速查表。列出支持的 RFB 版本、QREX 端点格式以及输入法命令集，让 QuickRemote（或您自己的客户端）了解可用功能。

协议与端口

认证

• VNC 客户端 — RFB DES 密码（所配置密码的前 8 个 ASCII 兼容字节）。
• QREX 客户端 — 首先在 POST /qr/v1/pair 进行 6 位 PIN 交换以获取 Bearer 令牌。之后的每个 QREX HTTP 调用和 WebSocket 帧都必须包含 Authorization: Bearer <token>.
• 如果 VNC 密码为空，服务器会声明标准 RFB 免认证模式。仅建议在可信的局域网段中使用。

QREX 端点速查

GET  /qr/v1/capabilities    # 公开，返回支持的功能
POST /qr/v1/pair            # 公开，用 PIN 换取 Bearer 令牌
GET  /qr/v1/ws              # WebSocket，需要认证
POST /qr/v1/ime/get         # 需要认证，查询当前输入法
POST /qr/v1/ime/list        # 需要认证，列出可用输入法
POST /qr/v1/ime/set         # 需要认证，切换输入法
POST /qr/v1/ime/toggle      # 需要认证，开关输入法
POST /qr/v1/ime/commit      # 需要认证，提交文本字符串

设置

客户端示例

macOS 屏幕共享

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

cURL — 查询可用功能

能力查询命令：curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — 配对并调用输入法桥接

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

# 2. 通过输入法桥接提交文本
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 可静默重连。
• 使用 复制信息 是通过聊天或邮件发送连接信息的快捷方式 — 其中包含客户端所需的一切内容。
• 请将 启用文件写入操作 保持关闭，除非您确实需要上传。只读模式已足以浏览截图、笔记或下载内容。
• 不使用音频 API 时请将其禁用。空闲的编解码器在编码链路上仍会占用少量 CPU。

疑难解答

服务器无法启动

• 可能已有其他 VNC 服务器（例如 macOS 屏幕共享）占用了 5900 端口。请在系统设置 → 通用 → 共享中将其停止，或在 DeskVNCServer 的设置中更换端口。
• 5911 / 4010 / 8766 端口必须全部空闲。可使用 lsof -i :5911 等命令检查。

VNC 客户端认证失败

• 请确认密码最多为 8 个 ASCII 兼容字节。多字节字符或更长的字符串会被 RFB DES 认证静默截断。
• 如果您确实不想设置密码，请将该字段留空，并使用支持 VNC 免认证的查看器连接。

QuickRemote 无法配对

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

远程控制感觉卡顿

• 请在设置中降低帧率与最大画面尺寸。
• 禁用您未使用的功能（音频、剪贴板、输入法）以释放 CPU。

文件无法传输

• 请确认 启用文件传输 已开启。只读列表无需 启用文件写入操作.
• 即可使用。如果上传失败，请同时启用 启用文件写入操作。否则文件 API 只会响应读取请求。

隐私

• 所有会话都在客户端与您的 Mac 之间直接进行。没有云端中继、没有遥测、没有分析。
• VNC 密码、QREX Bearer 令牌、配对 PIN 和固定服务器 ID 仅保存在本地应用设置中。
• 文件写入操作默认关闭。在您明确授予写入权限之前，远程客户端只能读取。
• 您可以随时禁用任意扩展功能（音频、剪贴板、文件传输、输入法、远程输入），以立即撤销该能力。
• 如果您希望服务器仅限本机使用，请将绑定主机设为 127.0.0.1.