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 版本支援,也可以掃描 QR Code)
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。