Anping English

取得使用權和部署

要從你的程式使用 Anping，需要一台在運作的 Anping 伺服器：它的網址、給你的程式用的秘密金鑰（API 金鑰），以及至少一組電腦設定（model）。本頁說明 Anping 目前怎麼運作。

還在開發中：給正式環境用的現成套件（桌面引擎的正式映像檔、建置範本），以及跨多個區域的單一服務。

要向管理者拿的東西

項目說明
網址例如 https://anping.example.com。
API 金鑰Oturl:ApiKeys 裡的其中一把。只放在你的伺服器上，絕不放進網頁。
model id每一組電腦設定的名稱（Targets:N:Id），大小寫也要相同。
要把 Anping 放進你的網頁把你網站的網址加進 Oturl:FrameAncestors。

接著看快速開始。

運作的元件

瀏覽器連到你的負載平衡器，它把安全連線轉給 Anping 伺服器；Anping 和它的桌面引擎（guacd）一起跑在同一份裡，共用檔案儲存，另有記錄儲存，引擎再連到 Windows。 瀏覽器 安全的網頁連線 負載平衡器 處理 https（TLS） 一份 Anping（replica：pod 或 task） 記錄儲存，只有 Anping 用: ConnectionLog:Path Anping 伺服器 連接埠 8080，使用者 1654 桌面引擎 guacd，連接埠 4822 只在內部 檔案儲存，兩邊同一個資料夾: Files:DriveRoot 健康檢查：/healthz、/readyz Windows 連接埠 3389 Hyper-V 2179 https http RDP 瀏覽器連到你的負載平衡器，它把安全連線轉給 Anping 伺服器；Anping 和它的桌面引擎（guacd）一起跑在同一份裡，共用檔案儲存，另有記錄儲存，引擎再連到 Windows。 瀏覽器 安全的網頁連線 https 負載平衡器 處理 https（TLS） http 一份 Anping（replica：pod 或 task） Anping 伺服器 連接埠 8080，使用者 1654 桌面引擎 guacd，連接埠 4822 只在內部 檔案儲存，兩邊同一個資料夾 Files:DriveRoot 記錄儲存，只有 Anping 用 ConnectionLog:Path 健康檢查：/healthz、/readyz RDP Windows 連接埠 3389 Hyper-V 2179
只有負載平衡器對外。桌面引擎（guacd）和它的連接埠都只留在內部。
元件作用
Anping 伺服器用 src/Gateway/Dockerfile 建置（.NET 10）。它提供連結頁面、API、連線記錄和桌面的即時連線。
技術細節提供 /oturl.html、/ws/oturl/get、/log.html 和 /ws/log，以及 WebSocket /tunnel。用純 http 監聽 8080 連接埠，以使用者 id 1654 執行，第一個程序是 tini，所以程式當掉時容器會結束，不會卡住。
桌面引擎（guacd）Apache Guacamole 1.6.0，負責跟 Windows 溝通（用 RDP，也就是 Microsoft 的遠端桌面協定）。它自己沒有密碼保護：絕對不要公開它的連接埠。
技術細節它以 sidecar 的方式跟 Anping 伺服器在同一個 replica（pod 或 task）裡，Anping 伺服器透過 Guacd:Host 和 Guacd:Port（localhost:4822）連到它。
檔案儲存（磁碟 volume）放使用者共用資料夾的地方，Files:DriveRoot，兩邊都要掛上。容量：Files:DriveQuotaBytes（1 GB）乘上每一份同時的連線數。
技術細節在兩個容器裡掛在同一個路徑，擁有者是使用者 id 1654。每次連線在裡面有自己的資料夾，結束時刪除。沒有它就沒有檔案傳輸。自動下載共用資料夾 Download 資料夾以外的檔案，需要 Anping 伺服器跑在 Linux 上：它用 inotify 監看這個 volume。所有連線共用核心的 inotify 上限（fs.inotify.max_user_watches）；超過時 Anping 伺服器會記錄警告，那些資料夾就不會自動下載。
記錄儲存（記錄 volume）放連線記錄的地方，ConnectionLog:Path，只有 Anping 伺服器使用。
技術細節擁有者是使用者 id 1654。沒有它的話，連線記錄只在記憶體裡，重新啟動就不見了。
負載平衡器（TLS 代理）你的負載平衡器或 ingress。它處理 https，並讓即時連線（WebSocket）通過。

步驟

步驟做法
1 建置映像檔Anping 用 docker build -f src/Gateway/Dockerfile .；桌面引擎用 guacamole/guacd:1.6.0。
技術細節在 repository 根目錄建置。開發環境以使用者 1654 和 HOME=/tmp 執行它；給正式環境用的引擎映像檔即將推出。列印預設關閉。要開啟就把 Guacd:Printing 設成 true；這需要有 Ghostscript 的 guacd 映像檔（官方的有），而 Ghostscript 是 AGPL-3 授權，或要向 Artifex 買商業授權。
2 網路Anping 要能用連接埠 3389（Hyper-V：2179）連到每台 Windows 電腦。3389 不要開放到網際網路。
技術細節guacd 的連接埠只留在 replica 裡。
3 https在前面放一台有有效憑證的負載平衡器，並允許 WebSocket。把 ForwardedHeaders:KnownNetworks 設成它的網段，AllowedHosts 設成你的公開名稱。
技術細節沒有代理伺服器（瀏覽器直接連線）時，改設 ForwardedHeaders:NoProxy=true。讓代理伺服器的記錄對 /ws/oturl/get、/ws/log 和 /oturl.html 不記查詢字串。
4 設定金鑰來自機密儲存（可用 openssl rand -hex 32 產生）、每組電腦設定一筆 Targets:N，以及兩個儲存資料夾（全部設定）。
技術細節每把金鑰至少 32 個亂數字元。Files:DriveRoot 和 ConnectionLog:Path。你的程式會送 computer 時設定 Oturl:AllowedComputers 和 Oturl:ComputerSettings；要內嵌時設定 Oturl:FrameAncestors。Dev:Pages 保持關閉（預設）。用 appsettings.json 或環境變數。
5 授權把隨 Anping 拿到的授權檔放在主機的一個資料夾，唯讀掛載到 /etc/anping/license。沒有授權時 Anping 以試用模式執行：同時 2 個連線（授權）。
6 電腦的憑證每台 Windows 電腦都必須證明自己的身分：釘選它的憑證，或給它一張引擎信任的憑證。其他的都會被拒絕（憑證）。
7 Windows要讓使用者用自己的時區，請開啟 Allow time zone redirection（下方）。
8 健康檢查給你的平台用的兩個檢查：/healthz（Anping 有沒有在跑？）和 /readyz（連得到桌面引擎嗎？）。大約每 30 秒查一次。
技術細節Anping 伺服器程序在運作時 /healthz 回 200。guacd 完成一次 RDP 交握時 /readyz 回 200，否則回 503。每次 /readyz 檢查都會讓 guacd 啟動一個程序，所以結果會快取 10 秒。
9 確認Anping 預設以正式環境模式執行，有不安全的設定時不會啟動，記錄會寫出原因。接著產生一個連結（快速開始）。
技術細節會被拒絕的：dev API 金鑰、少於 32 字元的金鑰、測試頁面、缺少代理伺服器設定或不合法的設定。
範例（環境變數） 
AllowedHosts=anping.example.com
ForwardedHeaders__KnownNetworks__0=10.0.0.0/24
Guacd__Host=localhost
Guacd__Port=4822
Files__DriveRoot=/drives
ConnectionLog__Path=/connection-log
Oturl__ApiKeys__0=<from your secret store>
Targets__0__Id=sales-desktop
Targets__0__Name=Sales
Targets__0__Host=sales-rdp.corp.example
Targets__0__CertFingerprints__0=sha256:<the computer's fingerprint>

授權

Anping 在 Anping 伺服器本身離線檢查授權：啟動時和每次建立新連線時。它從不連到外部，授權有問題也不會讓它停止。

授權的時間軸：到期日前是有效授權，之後有 14 天寬限期並提出警告，再之後拒絕新的連線，已開啟的繼續運作。沒有授權：試用，同時 2 個連線。 再 14 天 安裝 到期日（UTC） 有效授權 依授權的同時連線數 寬限期 一切照常，/log.html 警告 拒絕新的連線 已開啟的繼續運作 沒有授權或授權無效：試用，同時 2 個連線，沒有期限。 授權的時間軸：到期日前是有效授權，之後有 14 天寬限期並提出警告，再之後拒絕新的連線，已開啟的繼續運作。沒有授權：試用，同時 2 個連線。 再 14 天 安裝 到期日（UTC） 有效授權 依授權的同時連線數 寬限期 一切照常，/log.html 警告 拒絕新的連線 已開啟的繼續運作 沒有授權或授權無效： 試用，同時 2 個連線，沒有期限。
日期都是 UTC 的日子。
主題會發生什麼
安裝把 anping.license 放在主機的一個資料夾，把這個資料夾唯讀掛載到 /etc/anping/license。
技術細節例如 -v /opt/anping/license:/etc/anping/license:ro。使用者 1654 要能讀這個檔案。也可以不用檔案，把 License__Content 設成檔案的內容（一個環境變數，例如來自機密儲存）；它優先於檔案。License:Path 可以改檔案的位置。
續約用新的檔案取代舊的。從下一個新連線開始生效：不用重新啟動，已開啟的連線不受影響。
技術細節先用別的檔名把新檔案複製到資料夾，再改名蓋過舊的，這樣 Anping 不會讀到一半的檔案。用 License__Content 的話，要重新啟動 Anping。
連線數授權的數字是這台 Anping 伺服器同時的連線數，不論是誰開的。超過時新的連線會被拒絕，顯示 All 100 licensed sessions are in use.
技術細節已開啟的連結重新整理或重新連線，會取代它原本的連線，所以不用空位。Tunnel:MaxSessions 也照樣有效：取兩者中較小的。每次拒絕都會以 license_limit 記在連線記錄。
到期和寬限期有效到授權上的日期（UTC）。之後有 14 天寬限期：一切照常，/log.html 會警告。再之後新的連線會被拒絕（The remote desktop service's license has expired.）；已開啟的繼續運作。
技術細節連線記錄會寫 license_expired。寬限期過後，重新連線也算新的連線，所以會被拒絕。
沒有授權（試用）Anping 照常啟動，最多同時 2 個連線。/log.html 顯示 Unlicensed。
損壞或被改過的檔案Anping 會記錄原因，以試用模式執行（同時 2 個連線），/log.html 也會寫出原因。
技術細節檔案有兩行給人看的註解和一行簽章過的內容。那一行被改過、用 Anping 不認得的金鑰簽的授權，或讀不到的檔案，都當作沒有授權。
在哪裡看/log.html 的最上方：用文字寫出的狀態、客戶、到期日，以及使用中的連線數和授權的數量。
技術細節API：帶 API 金鑰的 GET|POST /ws/license（API 參考）。Anping 的記錄在啟動時和狀態改變時寫出狀態。

Windows 電腦

項目會發生什麼
時區Windows 原則 Allow time zone redirection 開啟時，使用者看到自己的時區；或每個 model 用一個固定的時區（TimeZone，model）。
技術細節頁面每次連線都會送出瀏覽器的時區。model 的 TimeZone 讓它所有的連線用同一個時區。這是遠端桌面連線主機的原則，在 Device and Resource Redirection 底下。沒開的話，連線維持那台電腦自己的時區。
Windows 拿到的你連線那一刻和世界標準時間（UTC）的時差（Client Local Time），沒有日光節約時間的規則。
更多跨過時間調整的連線會沿用舊的時差，直到重新連線。
Windows 看到的電腦名稱Anping- 加上連結代碼的 8 個字元，用它就能在記錄裡找到那次連線。
技術細節前 8 個字元，在 %CLIENTNAME% 和工作管理員裡看得到。model 的 ClientName 可以設成別的名稱。
登出Disconnect 和 End 之後，Windows 會讓你保持登入（已中斷連線），直到它自己的時間限制把你登出。
在 Windows 上確認過Windows Server 2025 上電腦名稱沒問題。時區有送出，但原則開著 Windows 還是停在世界標準時間（UTC），原因還沒查出來。Windows 自己的觸控支援（Touch）還沒試過。

目前的限制

限制怎麼辦
連結只記在一台伺服器的記憶體裡連結只能在產生它的那台 Anping 伺服器上打開；那台重新啟動，所有連線都會結束。
更多重新啟動會忘記所有連結，也會結束所有進行中的連線；使用者需要新的連結。
多台 Anping 伺服器每台用自己的網址，向你交給使用者的那個網址的伺服器申請。
更多例如每個區域一台。同一個網址後面放多個 replica，需要共用的連結儲存，已在規劃中。
更新或移除一份更新或移除一份（重新部署、縮減）會結束它上面的連線：請用固定的份數（replica）。
容量把 Tunnel:MaxSessions（100）設成這一份的機器撐得住的連線數：4 vCPU / 8 GiB 約 18 個，8 vCPU / 16 GiB 約 37 個。滿了的那一份會回答忙碌，不會讓大家一起變慢。
更多1920x1080、一般辦公，每個連線抓 0.15 vCPU 和 170 MiB，這是在 Mac 上用 Linux 測試桌面量的。畫面一直在變（3D、動畫）會用更多：請先用你們自己的軟體量一個連線。
你公司自己的憑證授權單位發的憑證需要 Anping 自己的引擎映像檔，即將推出；在那之前請用釘選（憑證）。

在你的電腦上試用

scripts/dev.sh up（需要 repository 和 Docker）會在 http://localhost:8080 啟動 Anping、它的桌面引擎和一台 Linux 測試桌面。金鑰 anping-dev-oturl-key，model dev-linux。

只用於開發：它以開發模式執行，信任測試桌面自己的憑證（釘選），也會開啟測試頁面。