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 版本支援，也可掃描 QR code）
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. Finder → 前往 → 連接伺服器
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.