Anping從 Thinfinity 移轉
你的程式照樣送同一個請求（/ws/oturl/get），也拿到同樣的回應。只有伺服器網址要改；其他都在 Anping 伺服器上設定。
不變的部分
| 不變 | 說明 |
|---|---|
| 路徑 | /ws/oturl/get，值放在網址裡（GET）。 |
| 選項 | 每個選項的名稱、型別和預設值（差異）。 |
| 回應 | /oturl.html?key=..&pass=..，由你的程式接在伺服器網址後面。 |
| 模式 | 指定 model；model 加上你自己的選項（overrideDefaults=true）；或不用 model。 |
要改的部分
| 項目 | 改用 Anping |
|---|---|
| 伺服器網址 | Anping 的網址，例如 https://anping.example.com。 |
| API 金鑰 | Oturl:ApiKeys 其中一把：新的金鑰，或者只想改網址時，用你現在送的那個值。 |
| model | 你的程式指定的每個 Access Profile，都變成 Anping 裡的一組電腦設定。它的 Id 就是那個 model 值，設定放在 Targets:N:Oturl:<參數>。 |
請求裡的 computer | 你的程式只能指定 Oturl:AllowedComputers 列出的電腦。 |
| 放進你的網頁 | 把你網站的網址加進 Oturl:FrameAncestors。 |
| 公開名稱檢查 | 把你的公開名稱加進 AllowedHosts。 |
| 電腦的憑證 | 會先檢查你的登入（NLA），每台電腦也必須用受信任或已釘選的憑證證明自己的身分。Windows 自己產生的憑證需要釘選（下方）。 |
| 正式環境檢查 | 用開發用的金鑰、少於 32 字元的金鑰、測試頁面，或缺少負載平衡器的設定時，Anping 不會啟動（設定）。 |
設定一個 model
假設你的程式送 model=sales-desktop，那個設定檔用固定大小開啟一個單一程式視窗（RemoteApp）。在 Anping 伺服器上這樣寫：
Targets__0__Id=sales-desktop
Targets__0__Name=Sales
Targets__0__Host=sales-rdp.corp.example
Targets__0__Port=3389
Targets__0__Domain=CORP
Targets__0__Username=sales-app
Targets__0__Password=<from your secret store>
Targets__0__Oturl__startprg=2
Targets__0__Oturl__command=||SalesApp
Targets__0__Oturl__resolution=fixed
Targets__0__Oturl__width=1280
Targets__0__Oturl__height=800
Targets__0__Oturl__clipboard=false不設 Username 和 Password，連結頁面就會請每位使用者輸入；也可以由你的程式送出。設定值有錯時，Anping 啟動時會寫在記錄裡。
不是參數的設定，以及 Thinfinity 的名稱
Name（顯示在工具列）、Security、CertFingerprints（憑證）、KeyboardLayout、AllowCopy/AllowPaste（只開剪貼簿的一個方向）、ClipboardLineEndings、AllowUpload/AllowDownload、AllowAudio/AllowPrinting、AllowProgramOverride、TimeZone、ClientName、Touch、WindowsIme（全部設定）。Allow設定是請求不能超過的上限。- 如果遠端連線裡的程式會找 Thinfinity 的名稱，請把
Oturl:DefaultDiskName設成ThinDisk，Oturl:DefaultPrinterName設成它們預期的印表機名稱。
Access Profile 對應到 model
| 你的 Access Profile 裡的 | 在 Anping 放在哪裡（名稱跟連結的選項一樣） |
|---|---|
設定檔金鑰（model） | Targets:N:Id，同一個值，大小寫也要相同。 |
| 名稱 | Targets:N:Name，顯示在工具列。 |
| 電腦、連接埠 | Targets:N:Host、Targets:N:Port。 |
| 儲存的使用者名稱和密碼 | Targets:N:Username、Password、Domain；不設的話，連結頁面會詢問。 |
| 安全性、提早檢查登入（NLA）、憑證 | Targets:N:Security（預設 nla）、Targets:N:CertFingerprints；Targets:N:Oturl:disablenla。 |
| 顯示 | Targets:N:Oturl:resolution、width、height、bpp、imagequality。 |
| 體驗 | Targets:N:Oturl:desktopbackground、visualstyles、menuwindowanimation、fontsmoothing、showwindowcontent、desktopcomposition。 |
| 程式 | Targets:N:Oturl:startprg、command、cmdargs、directory。更多會啟動程式的 model 會保留它的程式，即使overrideDefaults=true 也一樣；要 Thinfinity 的行為，請設定 Targets:N:AllowProgramOverride。 |
| 鍵盤 | Targets:N:Oturl:unicodekeyboard、keyboardlayout；這次連線用的配置：Targets:N:KeyboardLayout。 |
| 主控台、壓縮 | Targets:N:Oturl:console、wscompression。 |
| 虛擬機器（Hyper-V）、伺服器群（RD 連線代理） | Targets:N:Oturl:desttype、destinfo。 |
| 共用資料夾、剪貼簿、聲音、印表機 | Targets:N:Oturl:diskenabled、diskname、diskautodownload、clipboard、soundenabled、soundquality、printer*。更多要只開一個方向或禁止某個功能：AllowUpload、AllowDownload、AllowCopy、AllowPaste、AllowAudio、AllowPrinting。列印預設關閉（Guacd:Printing，見下方）。 |
| 影像壓縮（H.264）、錄影、集區、負載平衡、權限 | 沒有對應：移轉時直接丟掉，不會出現錯誤。誰能拿到連結由你的程式決定。更多連線錄影、多台電腦的集區或負載平衡，以及權限（哪些使用者或群組可以用這個設定檔）。連線就是在沒有它們的情況下執行。 |
Targets:N:Oturl 底下不是連結選項的名稱，Anping 會忽略，並在啟動時發出警告。
參數對應
每個選項在請求和 model 的 Oturl 設定裡都用同樣的名稱。每個選項做什麼、支援到什麼程度：參數表。Anping 另外支援 format=json 和 POST。
已知差異
| 主題 | Anping 哪裡不一樣 |
|---|---|
| 色彩深度 | 預設 32 位元色彩（Thinfinity：16）。要 16 就設 Targets__N__Oturl__bpp=16。技術細節沒給bpp 時是 32 位元色彩，搭配 RDP 圖形管線。在 model 設 16，或送 bpp=16 並加上 overrideDefaults=true：只給 model 時，請求裡的連線參數會被忽略。 |
model | 必須跟 model 的 Id 完全一樣，大小寫也要相同。選項名稱不分大小寫。 |
imagequality | 2 和 3 的效果跟 1 一樣。 |
directory | 只用在單一程式視窗（RemoteApp，startprg=2）。 |
unicodekeyboard | 遠端用 model 的鍵盤配置時，打出來的字才會正確。 |
diskname、diskautodownload | 共用資料夾預設叫 Anping。存好的檔案關閉後會自己下載到瀏覽器；還沒在 Windows 上確認過。技術細節Anping 伺服器跑在 Linux 上時是共用資料夾任何地方的檔案，否則只有共用資料夾的Download 資料夾。超過 Files:MaxUploadBytes 的檔案留在共用資料夾裡。 |
printerenabled | 列印預設關閉：連結照樣能開，只是沒有印表機，試跑會說明原因。要開啟（Guacd:Printing）需要有 Ghostscript 的桌面引擎，而 Ghostscript 是 AGPL-3 授權，或要向 Artifex 買商業授權。 |
printersetasdefault=false、printerdriver | 桌面引擎（Apache Guacamole 1.6.0 的 guacd）做不到。 |
| 聲音 | 任何能從網頁播放聲音（Web Audio）的瀏覽器都可以，從第一次點擊或按鍵後開始。 |
| 重新整理、斷線 | 同一個瀏覽器：斷線後 10 分鐘內，網路斷掉時自動重試 60 秒。其他瀏覽器：已使用的訊息。 |
| 連線數 | 每個連結一條連線；同一個瀏覽器的新連線會立刻接手。 |
| 錯誤 | 純文字回應：一個錯誤代碼（HTTP 狀態碼）和簡短原因（錯誤）。 |
| 時區、電腦名稱、觸控 | 連結沒有這些選項；請在每個 model 設定（TimeZone、ClientName、Touch）。 |
| 連線時間限制 | 沒有輸入 60 分鐘、開始後 720 分鐘；End 讓連結永久失效（效期）。更多Sessions:IdleTimeoutMinutes 和 Sessions:MaxDurationMinutes；設成 0 就關閉該項限制。 |
| 重新啟動 | 忘記所有連結並結束所有連線；使用者需要新的連結。更多不論用過與否。頁面會說服務重新啟動了，需要新的連結。 |
| model 的上限 | model 的上限（Allow 設定）和它的程式，就算 overrideDefaults=true 也改不了。技術細節Allow 設定是請求不能超過的上限；會啟動程式的 model 會保留它的程式，除非設了 AllowProgramOverride（Thinfinity 讓請求可以改）。 |
| 密碼錯誤 | 每個連結和每個網路都有次數限制（登入次數限制）。 |
| 憑證 | 會先檢查你的登入（NLA），電腦也需要受信任或已釘選的憑證（下方）。 |
| 多台 Anping 伺服器 | 連結只能在產生它的 Anping 伺服器上開啟（部署）。 |
| 還沒測過 | 虛擬機器（Hyper-V）、伺服器群（RD 連線代理、RD 工作階段主機）、實際伺服器上的單一程式視窗（RemoteApp），以及 Server 2025 以外的 Windows。技術細節Hyper-V 是desttype=VMID，RD 連線代理是 desttype=RDS。還有：美式英文以外的鍵盤配置；Windows 上的時區、用戶端名稱和原生觸控；正式發行的 Safari 和 Firefox（自動測試用的是它們的引擎），以及在 Firefox 和 Safari 裡重新整理內嵌的頁面。 |
電腦的憑證
憑證是 Windows 電腦證明自己身分的方式。沒有這個檢查，中間的人就能假冒那台電腦，拿走使用者輸入的密碼。所以 Windows 自己產生的憑證會被拒絕，直到你對每台電腦做下面其中一件事：
| 做法 | 怎麼做 |
|---|---|
| 1 釘選 | 在 Anping 伺服器執行的地方讀出它的指紋（SHA-256）：dotnet Gateway.dll rdp-fingerprint host[:port]。到那台電腦上核對，再設定 Targets__N__CertFingerprints__0=sha256:..。技術細節開發環境用scripts/rdp-fingerprint.sh host[:port]。連結指定的電腦：Oturl__ComputerSettings__N__Computer=<host> 和 Oturl__ComputerSettings__N__CertFingerprints__0=sha256:..。Windows 的自簽憑證到期時會自己換新（工具會印出日期）：在那之前加上新的指紋，舊的留到沒有電腦再出示它為止。 |
| 2 或給它一張憑證 | 名稱跟 Host（或 computer）一致，由桌面引擎信任的憑證授權單位（CA）簽發。技術細節企業（Active Directory）的憑證授權單位要加進那個映像檔，這會隨 Anping 自己的引擎映像檔推出；在那之前請用釘選。 |
- 沒有提早檢查登入（NLA）的電腦（某些非 Microsoft 的伺服器）：
Security設成tls，或在連結加上disablenla=true。憑證照樣檢查。 - 被拒絕時，使用者看到 The remote desktop service could not verify the remote computer's certificate, so it did not connect.；Anping 的記錄會寫出那台電腦、它預期的憑證，以及實際拿到的指紋。
IgnoreCert會關掉檢查。只能用在開發和實驗用的伺服器；其他地方 Anping 不會啟動。
用真實的請求試跑
切換之前，把你的程式送給 Thinfinity 的請求重播一次。/ws/oturl/check 會告訴你 /ws/oturl/get 會怎麼處理，但不產生連結（試跑）。
ANPING_API_KEY=... node scripts/oturl-replay.mjs --gateway https://anping.example.com requests.txt| 步驟 | 重播工具做什麼 |
|---|---|
| 讀取 | 一行一個請求：含 /ws/oturl/get?... 的網址或路徑、含這種網址的記錄行、? 後面那一段，或 POST <form body>。更多空行和# 註解會略過。 |
| 保護機密 | 拿掉檔案裡的 API 金鑰，遮住密碼和使用者名稱，把你的金鑰（ANPING_API_KEY）放在請求內容裡送出（POST），而且從不印出它讀到的內容。 |
| 印出 | 每個請求一列，最後是整個檔案的統計。更多每一列：接受或拒絕、模式、model、第一個問題。再統計整個檔案的所有問題、沒有作用的參數，以及和 Thinfinity 不一樣的地方。--json 會印出每個回應。 |
| 接著 | 修好被拒絕的部分（在你的程式或 model 裡），看過其他提醒，再切換網址。 |
並行和回退
要退回，就把網址改回 Thinfinity。已經發出的連結只能在產生它的伺服器上打開，並在 expires 分鐘後失效；進行中的 Anping 連線會持續到使用者斷線。
逐步說明
- 在旁邊架設 Anping 時，讓 Thinfinity 照常運作、不做任何變更。
- 把主機名稱和 API 金鑰放進你程式的設定。
- 用試跑重播幾天份的請求，修好它回報的問題。
- 只要 Thinfinity 還是退路，就繼續用 GET（值放在網址裡）：兩邊接受同樣的請求。
- 先移一個試用群組（一個 model，或少數使用者），用下面的測試跟他們一起驗證。
- 切換完成後改用 POST（只有 Anping 支援）：API 金鑰不會出現在網址和記錄裡。
檢查清單
部署 7
- Anping 和它的桌面引擎（guacd）一起跑在同一份裡，檔案儲存設定成
Files:DriveRoot（部署）。 - 用 https 和有效憑證連到 Anping，經由讓即時連線（WebSocket）通過的負載平衡器。
AllowedHosts有公開名稱；ForwardedHeaders:KnownNetworks有負載平衡器的網段（或ForwardedHeaders:NoProxy=true）。- 以正式環境模式執行（預設）而且能啟動：沒有開發用的金鑰、測試頁面或不合法的設定。
ConnectionLog:Path是只有 Anping 使用的儲存；/readyz回 200。- 如果使用者應該看到自己的時區，Windows 電腦已開啟 Allow time zone redirection（Windows 電腦）。
- 每個網址一台 Anping 伺服器（連結只能在產生它的地方開啟）：每個區域用自己的網址，你的程式向它交給使用者的那個網址的 Anping 伺服器申請。同一個網址後面放好幾份，需要共用的連結儲存，即將推出。
Anping 伺服器設定 5
Oturl:ApiKeys來自機密儲存，每把至少 32 個亂數字元（openssl rand -hex 32）。- 每個 model 一台電腦，
Id和大小寫相同，帶它的Oturl設定；啟動記錄沒有警告。 Oturl:AllowedComputers列出你的程式會送的每個computer；Oturl:FrameAncestors列出每個內嵌的來源（如果有）。- 每台電腦的憑證都受信任或已釘選（上方）；沒有
IgnoreCert。 - 負載平衡器的記錄不記
/ws/oturl/get、/ws/log、/oturl.html網址?後面那一段。