小柯機器人遠端連線（線上版）

https://github.com/user-attachments/assets/f021ec73-9b7e-444c-8b7d-02eb1b93df44

Windows 11 ↔ Windows 11、Windows 11 ↔ macOS 的遠端協助工具。一端是主控端、一端是被控端：主控端輸入被控端的 ID + 授權碼，即可看到並操作被控端的畫面。

架構參考開源專案 RustDesk：ID 伺服器負責讓兩端找到彼此，畫面、聲音、檔案走 WebRTC 點對點加密直連，直連不通時才經 TURN 中繼。可使用公用伺服器（免設定），也可用 server/ 自架。

功能

	功能	說明
🖥️	遠端操控	ID + 授權碼連線；滑鼠、鍵盤、滾輪；多螢幕切換；特殊鍵（Win、Ctrl+Shift+Esc、Alt+Tab、⌘+Space…）；剪貼簿雙向傳送；Mac ⌘ ↔ Windows Ctrl 自動對應；顯示直連/中繼、解析度、fps、頻寬
📁	一、檔案上傳下載	瀏覽被控端授權資料夾、下載、上傳（可拖曳）、建立資料夾、刪除、傳輸進度與取消；檔案走獨立資料通道，不影響操控
💬	二、互相聊天	文字訊息、語音交談（雙向、可靜音）、畫面擷取傳送（可拖曳裁切；主控端也可擷取遠端畫面）、圖片與任意檔案互傳
🔐	三、資料夾授權	被控端自行設定每個資料夾為「可讀／可寫／可讀寫」；一鍵建立「遠端安裝區」；主控端可要求執行安裝程式，被控端按「允許執行」才會執行（系統安裝協助）
🎓	四、遠端線上教學	主控端把簡報推送到被控端全螢幕顯示：PDF、PowerPoint（.pptx/.ppt，自動轉檔）、Keynote、圖片；同步翻頁、雷射筆、畫筆；也可推送主控端自己的螢幕或某個視窗

| 📺 | 一對多導播監看（v1.1） | 一台主控端同時連線最多 20 台被控端，2×2／3×3／4×4／5×4 分割畫面；縮圖以低畫質（約 640 寬、5fps、350kbps）傳送，點一下或按數字鍵 1～9 放大後切換高畫質並操控，「▦ 返回分割」回到總覽；全體廣播訊息、全體教學（同一份簡報推送到所有被控端並同步翻頁）；斷線 15 秒後自動重連 |

安全設計：授權碼每次連線後自動更換（也可設固定授權碼做無人值守）、錯 5 次鎖定 1 分鐘、可要求被控端按「接受」、被控端可隨時暫停操控或中斷、檔案存取限制在授權資料夾內（阻擋 ..、絕對路徑、符號連結跳出）。

線上版（免安裝）

👉 https://achir1015.github.io/xiaoke-remote/

用 Chrome、Edge（建議）或 Safari 開啟就能使用，與桌面版互通（同一個 ID 系統，可互相連線），也有主控端與被控端兩種角色，一對多最多 20 台。

功能	線上版當主控端	線上版當被控端
看對方畫面	✅	✅ 每次連線需按「接受」並選擇要分享的螢幕／視窗／分頁
操控滑鼠鍵盤	✅ 可操控桌面版被控端	❌ 瀏覽器安全限制，網頁無法控制系統滑鼠鍵盤
檔案上傳下載	✅	✅ 資料夾授權需 Chrome／Edge；每次重新開啟網頁要在「資料夾授權」按「🔓 重新允許」
文字、語音、畫面擷取聊天	✅	✅
線上教學	✅ PDF、圖片（PowerPoint 請先另存為 PDF）	✅
一對多監看（最多 20 台）	✅	—
遠端執行安裝程式	✅（對桌面版）	❌

需要被完整操控（例如遠端協助安裝軟體），被控端請使用桌面版（Windows 有免安裝版，下載後直接執行）。線上版被控端分享畫面時請選「整個螢幕」：只分享一個視窗或分頁時，對方看不到其他視窗、選單與跳出的對話框。線上版的 ID、授權碼與設定存在這個瀏覽器裡；換瀏覽器或清除網站資料會得到新的 ID。主控端全螢幕時（Chrome／Edge）會鎖定鍵盤，Ctrl+W 等快捷鍵會送到遠端而不是關閉分頁。

線上版與桌面版互通：實機測試結果（2026-10-26）

主控端	被控端	看畫面	滑鼠鍵盤操控	結果
桌面版	桌面版	✅	✅	✅ 可以（完整功能）
線上版	桌面版	✅	✅	✅ 可以（線上版主控端可完整操控桌面版）
線上版	線上版	✅	❌	⚠️ 只能檢視
桌面版	線上版	✅	❌	⚠️ 只能檢視

結論：要能操控，被控端一定要用桌面版（安裝版或 Windows 免安裝版）；主控端用桌面版或線上版都可以。

• 被控端是線上版時，畫面可以正常傳送，聊天、語音、傳檔、教學也都能用，但無法操控滑鼠鍵盤。這是瀏覽器的安全限制（任何網頁都無法控制電腦的滑鼠鍵盤），不是程式錯誤。
• 主控端連到線上版被控端時，遠端畫面上方會顯示「🌐 對方使用線上版：只能檢視」，「操控」選項會變成灰色；可按工具列的「📨 傳送免安裝版連結」，一鍵把 Windows 免安裝版的下載連結傳到對方的聊天視窗，請對方下載執行後再重新連線。
• 線上版被控端分享畫面時請選「整個螢幕」：只分享一個視窗或分頁時，對方看不到其他視窗、選單與跳出的對話框（新版會在雙方顯示提醒，並可一鍵「改分享整個螢幕」）。
• 畫面靜止時狀態列顯示 0～1 fps 是正常的（畫面沒有變化就不重複傳送，畫面一動就會恢復）。

其他已實機確認：macOS（MacBook Pro）可安裝並開啟（需依下方「macOS 安裝問題與解決方式」放行）。尚待實機測試：Windows 與 Mac 互相操控（⌘／Ctrl 對應）、一對多同時連線 10～20 台。

安裝

到 Releases 下載：

• Windows 11 免安裝版：XiaokeRemote-<版本>-win-x64-portable.exe，下載後直接執行，不用安裝（第一次啟動需解壓縮，約需數秒）。適合臨時請別人遠端協助：被控端執行它就能被完整操控。
• Windows 11：XiaokeRemote-<版本>-win-x64.exe，執行後依畫面安裝（可選安裝位置，會建立桌面與開始功能表捷徑）。未簽章，若出現 SmartScreen 請按「其他資訊 → 仍要執行」。
• macOS：Apple 晶片（M1～M4）下載 mac-arm64.dmg，Intel 下載 mac-x64.dmg（不確定時：左上角蘋果選單 › 關於這台 Mac，看「晶片」或「處理器」）。打開 dmg，把 App 拖進「應用程式」。第一次開啟會被 macOS 擋下，請見下一節。

macOS 安裝問題與解決方式

問題一：「Apple 無法驗證『小柯機器人遠端連線』是否包含可能危害 Mac 安全或洩露隱私的惡意軟體」

原因：本 App 尚未加入 Apple 付費開發者計畫做簽章與公證，macOS 的 Gatekeeper 會擋下第一次開啟。這不是程式有問題，放行一次之後就能正常使用。

解決方式 A：從系統設定放行（推薦，macOS 15 Sequoia 以後必須用這個方法）

1. 先把 App 拖進「應用程式」資料夾，在「應用程式」裡雙擊開啟一次，出現警告時按「完成」。
2. 打開「系統設定」→「隱私權與安全性」，往下捲到「安全性」區塊。
3. 會看到「已阻擋『小柯機器人遠端連線』以保護你的 Mac」，按旁邊的「仍要打開」。
4. 輸入 Mac 登入密碼（或 Touch ID）確認，再按「打開」。

之後就可以直接雙擊開啟。macOS 14 以前也可以在 App 圖示上按右鍵 →「打開」→「打開」。

解決方式 B：用終端機移除隔離標記

打開「終端機」（啟動台 › 其他 › 終端機），貼上下面這行後按 Enter，再重新開啟 App：

xattr -cr "/Applications/小柯機器人遠端連線.app"

問題二：「『小柯機器人遠端連線』已損毀，無法打開。你應該將它丟到垃圾桶」

原因：下載的檔案被加上隔離標記（quarantine），macOS 顯示的「已損毀」通常是這個原因，檔案本身沒有壞。

解決：使用上面的「解決方式 B」終端機指令；仍不行就重新下載 dmg，並確認下載的晶片版本（arm64／x64）和 Mac 相符。

問題三：系統設定裡找不到「仍要打開」按鈕

• 這個按鈕只會在剛被擋下後約一小時內出現：先雙擊 App 一次觸發警告，再立刻到「隱私權與安全性」查看。
• 確認 App 已經放在「應用程式」資料夾，不要直接從 dmg 視窗裡開啟。
• 還是沒有出現就改用「解決方式 B」。

問題四：Mac 當被控端時，主控端看到黑畫面或無法操控

App 首頁上方的黃色提示會列出缺少的權限，按「前往設定」即可跳到對應頁面：

權限	位置	沒開會怎樣
螢幕錄製	系統設定 › 隱私權與安全性 › 螢幕與系統錄音（舊版叫「螢幕錄製」）	主控端看到黑畫面或只有桌布
輔助使用	系統設定 › 隱私權與安全性 › 輔助使用	主控端滑鼠鍵盤沒反應
麥克風	第一次語音交談時會詢問	對方聽不到你的聲音

把「小柯機器人遠端連線」的開關打開後，一定要完全結束 App 再重開（Dock 圖示按右鍵 › 結束，或按 ⌘Q），權限才會生效。

如果清單裡已經有這個 App 但開了仍無效（例如更新版本之後），請先用「−」把它移除，再按「＋」重新加入 /Applications/小柯機器人遠端連線.app，然後重開 App。

Mac 只當主控端（去控制別台電腦）時，不需要「螢幕錄製」和「輔助使用」。

問題五：更新到新版後又被擋下或權限失效

未簽章的 App 每次更新後，macOS 可能會把它當成新的程式：照問題一再放行一次，並依問題四重新確認「螢幕錄製」與「輔助使用」。

若要徹底消除這些警告，需要使用 Apple Developer ID 簽章並送交 Apple 公證（Apple 開發者計畫每年 99 美元），之後可以接進 GitHub Actions 自動處理。

使用方式

1. 被控端開啟 App，把首頁的 本機 ID 與 授權碼 告訴主控端。
2. 主控端在「主控端：控制遠端電腦」輸入 ID 與授權碼 →「連線並操控」（或「僅檢視連線」）。
3. 被控端預設會跳出「接受／拒絕」確認（可在設定關閉）。
4. 連線後主控端右側有 聊天／檔案／教學 三個分頁。
5. 被控端要讓對方存取檔案，請先到「資料夾授權」新增資料夾並設定權限。

一對多監看（電腦教室、多台維護）

1. 每台被控端：「設定」把授權碼模式改為「固定授權碼」，並視需要取消「有人連入時需我按接受」（無人值守），記下 ID。
2. 主控端：「多台監看」分頁左側輸入每台的 ID、固定授權碼、名稱 →「加入」（最多 20 台，清單會保存）。
3. 按「▶ 全部連線」。點任一格放大操控；上方可廣播訊息、推送全體教學簡報。
4. 頻寬估算：縮圖每台約 0.35 Mbps，20 台約 7 Mbps；放大中的那一台另需 4～10 Mbps。

自架伺服器（選用）

公用伺服器（PeerJS Cloud）免設定即可使用。若要完全自主掌控，或兩端網路有嚴格防火牆，請使用 server/：

cd server
docker compose up -d

• xiaoke-id（port 9000）：ID／信令伺服器，相當於 RustDesk 的 hbbs。
• turn（coturn，port 3478）：中繼伺服器，相當於 RustDesk 的 hbbr，請先修改 TURN_PASSWORD 與 external-ip。

不用 Docker 也可以：cd server && npm install && npm start。

然後在兩端 App 的「設定 › 連線伺服器」選「自架伺服器」，填入主機、埠 9000、路徑 /、金鑰 peerjs；TURN 填 turn:你的主機:3478、帳號 xiaoke、密碼。兩端必須使用同一台 ID 伺服器。

開發

需要 Node.js 20。

npm install
npm start                 # 執行
npm test                  # 單元測試（資料夾授權沙箱）
npm run e2e -- <測試資料夾>  # 端對端測試：開兩個實例互連，測試全部功能（資料夾內需有 deck.pdf、big.bin，可加 deck.pptx）
npm run e2e:multi -- <測試資料夾>  # 一對多測試：1 台主控 + 3 台被控（分割、放大、廣播、全體教學、自動重連）
npm run web               # 產生線上版網站到 site/（推送到 main 後由 GitHub Pages 自動發佈）
node e2e/serve.mjs 8790   # 本機預覽線上版 http://127.0.0.1:8790/
npm run e2e:web -- <測試資料夾>  # 線上版測試：Chrome 線上版 ↔ 桌面版互連、線上版一對多
npm run dist:win          # 打包 Windows 安裝檔（dist/）
npm run dist:mac          # 打包 macOS dmg（需在 Mac 上執行）

同一台電腦可用 --profile=名稱 開多個實例測試，--dry-input 只記錄滑鼠鍵盤事件不實際操作。

推送到 main 時 GitHub Actions 會在 Windows 與 macOS（Apple 晶片、Intel）建置安裝檔，並以 package.json 的版本號建立 Release。發佈新版：修改 package.json 的 version 後推送即可。

專案結構

src/main/main.js       主程序：視窗、系統匣、IPC、檔案 I/O、簡報轉 PDF、執行安裝檔確認
src/main/input.js      被控端滑鼠鍵盤注入（nut-js），跨平台修飾鍵對應
src/main/fsguard.js    資料夾授權沙箱（可讀/可寫/可讀寫）
src/main/preload.js    提供給畫面的安全 API
src/renderer/js/net.js     ID 伺服器連線、資料通道訊息、RPC、分段傳檔
src/renderer/js/app.js     首頁、設定、被控端流程
src/renderer/js/client.js  主控端：多連線管理、放大操控、多台監看分割畫面、廣播
src/renderer/js/chat.js    文字、語音、畫面擷取、檔案互傳
src/renderer/js/files.js   主控端檔案總管、被控端檔案服務
src/renderer/js/teach.js   線上教學（pdf.js 投影片、雷射筆、畫筆、螢幕推送）
src/renderer/js/web-shim.js  線上版：用瀏覽器 API 實作與桌面版主程序相同的介面
scripts/build-web.mjs  產生線上版網站
server/                自架 ID 伺服器 + coturn
e2e/run.mjs            端對端測試

已知限制

• Windows 的 UAC 提權視窗（安全桌面）與登入畫面無法遠端操作；被控端需自行按下 UAC 的「是」。
• 被控端必須開著 App（可縮到系統匣）；目前不是 Windows 服務 / macOS 背景常駐程式。
• 安裝檔未經程式碼簽章與 Apple 公證。

授權

MIT License © 2026 吳玉柱（[email protected]）。相依套件：Electron、PeerJS、pdf.js、nut-js（各自授權）。