Ubiquiti UniFi captive portal 疑難排解：外部入口網站、熱點與 walled garden 檢查表

UniFi Captive Portal 發生故障通常有五個原因。外部門戶伺服器地址錯誤，或者預先授權存取中遺漏了門戶與登入網域。訪客隔離可能會封鎖門戶主機。重新導向可能使用 HTTP 導向 IP 地址。或者主控台無法連線。請依序檢查每一項，然後從用戶端進行測試。

無法正常運作的 UniFi Captive Portal 看起來像怎樣？

大多數故障會呈現為四種症狀之一。先確定症狀名稱，即可在開啟 UniFi Network 應用程式之前縮小原因範圍。

• 完全沒有門戶。 裝置加入訪客 SSID 並取得 IP 地址，但沒有出現登入提示。手機可能會報告「無網際網路連線」或顯示已連線但無流量。
• 空白或無限載入的頁面。 Captive Network Assistant (CNA) 開啟，但登入頁面（splash page）從未渲染。CNA 是您的作業系統在 Captive Portal 網路上啟動的小型瀏覽器。
• 憑證警告。 筆記型電腦在登入頁面出現前顯示「您的連線不是私密連線」。訪客必須點擊忽略警告才能繼續。
• 不完整的門戶。 登入頁面（splash page）已載入，但社群登入或付款按鈕一直旋轉、失敗或陷入迴圈。

Purple 的 Captive Portal 支援文章 更詳細地解釋了 CNA。CNA 會檢查預定義的網域以測試是否可以連線到網際網路。然後它會通知裝置、啟動瀏覽器並確認「線上」狀態。當該鏈條中的任何部分中斷時，您的訪客就會看到上述症狀之一。

本指南假設您的 UniFi 熱點門戶或外部門戶已經配置完畢。這是一份故障排除清單，而非安裝指南。

通常是什麼原因導致 UniFi Captive Portal 失敗？

六個原因佔了大多數 UniFi 訪客門戶疑難排解案例的大部分。

1. 外部門戶伺服器設定錯誤。 地址指向舊的主機、拼寫錯誤或閘道器無法連線的伺服器。
2. 預先授權存取不完整。 UniFi 將此設定標記為 "Pre-Authorization Access"。這是 UniFi 的圍牆花園：訪客在登入前可以存取的主機和子網路。如果遺漏了門戶、其資產或社群登入提供商，頁面就會保持空白或顯示不完整。
3. 訪客網路限制。 UniFi 訪客網路會封鎖私有地址範圍。內部子網路上的門戶伺服器或 DNS 伺服器會變得無法連線。
4. HTTPS 與主機名稱重新導向不符。 HTTPS 重新導向至 IP 地址，或重新導向至沒有相符憑證的主機名稱，會觸發瀏覽器警告。
5. 控制器或主控台的可連線性。 自行代管的 UniFi Network Server 和雲端主控台必須保持可連線狀態。使用外部門戶時，控制器還必須連線到完成登入的 RADIUS 伺服器。
6. 用戶端干擾。 VPN、自訂 DNS 設定或被關閉的 CNA 通知會阻止該裝置上的重新導向。

您如何找出自己遇到了哪種 UniFi Captive Portal 故障？

請先從症狀開始，並在更改任何設定之前執行表中的第一項檢查。

症狀	最可能的可能原因	第一步檢查	修正方法
沒有出現門戶頁面（Portal），也沒有任何提示	無法連線至 DNS 或 CNA 探測被阻擋	用戶端在登入前是否能解析公開主機名稱？	分配一個位於阻擋私有範圍之外的 DNS 伺服器，或在預先授權存取（pre-authorisation access）中允許它
網頁一片空白或無限載入	預先授權存取中缺少門戶主機或資源	門戶主機名稱是否能從訪客裝置解析並載入？	將門戶主機、其資源網域及其子網路新增至預先授權存取中
筆記型電腦上出現憑證警告	HTTPS 重新導向至 IP 位址或主機名稱不符	出現警告時，網址列中顯示什麼 URL？	停用 HTTPS 重新導向，或使用與該主機名稱相符且受公開信任的憑證，按主機名稱進行重新導向
社群登入按鈕旋轉或失敗	缺少身分驗證提供商網域	瀏覽器的網路檢視中，哪一個網域失敗？	新增該提供商登入頁面載入的所有網域
付款步驟失敗	缺少付款閘道網域	付款頁面是否能完全載入？	將付款提供商的主機新增至預先授權存取中
門戶頁面已載入，但無法完成登入	無法連線至 RADIUS 或控制器	控制器事件中是否有出現驗證嘗試？	恢復控制器的連線能力，並確認 RADIUS 詳細資料與您的門戶提供商相符
單一裝置失敗，其他裝置正常	用戶端 VPN、自訂 DNS 或已關閉的 CNA	該裝置上是否會重新導向至 neverssl.com？	停用 VPN 或自訂 DNS，清除該網路並重新連線

兩個快速測試可以區分大多數故障。首先，在已連線但未經驗證的裝置上瀏覽至 neverssl.com。Purple 的支援團隊推薦這個網站，因為它能避免 SSL 重新導向的問題。如果 neverssl.com 重新導向到您的門戶頁面，說明重新導向正常工作，故障出在預先授權存取或門戶本身。如果它沒有重新導向，請檢查 DNS、外部門戶伺服器設定或控制器。

其次，檢查 UniFi Network 應用程式中的用戶端項目。用戶端列表和事件會顯示裝置是否在訪客網路中以及是否已授權。如果裝置標記為已授權但仍顯示門戶頁面，則指向用戶端快取或 CNA 問題。

您該如何解決每個 UniFi Captive Portal 的原因？

Purple 在此不重複列出 UniFi 選單路徑，因為它們在不同的 UniFi Network 版本之間會有所變更。請參閱 Ubiquiti 的最新文件以獲取每個設定的確切位置。

外部門戶伺服器

確認外部門戶伺服器值與您的門戶提供商指定的值相符。只要一個字元錯誤，就會將所有訪客引導至失效的主機。如果您更換了門戶提供商，請刪除舊地址，而不要將其與新地址留在在一起。 當您使用 Purple 時，快顯頁面伺服器會收集訪客詳細資訊並發行一次性登入。控制器會將該登入傳遞至 Purple 的 RADIUS 伺服器以完成驗證。RADIUS 是網路設備用於對照中央伺服器檢查認證的協定。如果入口網站可以載入但登入失敗，請接著檢查 RADIUS 設定檔。

入口網站、社群登入和付款網域的授權前存取

這是最常見的修正方法。請將這些項目新增至授權前存取：

• 入口網站伺服器主機及其所在的任何子網路。
• 快顯頁面載入的每個網域，包括來自內容傳遞網路的字型、圖片和指令碼。
• 每個社群登入提供者的驗證網域（如果您提供 Facebook、Google 或 Apple 登入）。
• 您的付款閘道主機（如果您對進階存取進行收費）。

從不受限制網路上的筆記型電腦開啟快顯頁面，並讓瀏覽器的開發者工具顯示網路請求。在登入之前，此處列出的每個網域都必須是可連通的。如果您的 UniFi 網路版本僅接受 IP 輸入，請在提供者變更其地址時重新檢查它們。

訪客網路隔離與封鎖的子網路

訪客隔離本身並不會封鎖 Captive Portal。用戶端裝置隔離會阻止訪客裝置彼此通訊。訪客網路的子網路限制會封鎖私人地址範圍，而這些限制會攔截內部入口網站或 DNS 伺服器。

如果您的入口網站伺服器或 DNS 解析程式位於內部子網路，請將該特定主機新增至授權前存取。更乾淨的做法是為訪客提供公共 DNS 解析程式，並將入口網站託管在公共地址上。

HTTPS 與主機名稱重新導向選項

現代瀏覽器期望登入頁面使用 HTTPS。Purple 的 Cisco WLC 憑證文章 說明了 Cisco 硬體上的相同模式。重新導向至 HTTP 地址（例如純 IP）會觸發安全性警告，訪客必須點擊通過它。

在 UniFi 上的修正也遵循相同的原則。您可以關閉 HTTPS 重新導向並讓 CNA 使用 HTTP，或者依主機名稱重新導向。主機名稱重新導向需要受公開信任的 SSL/TLS 憑證，且主機名稱必須與憑證的通用名稱 (Common Name) 相符。自我簽署的憑證或不相符的名稱會直接使警告再次出現。

自行託管與雲端主控台的控制器可連通性

對於自行託管的 UniFi 網路伺服器，請確認伺服器正在執行且可從您的閘道和存取點連通。如果伺服器位於總部或資料中心，請檢查站點之間的防火牆規則。對於雲端主控台，請確認主控台顯示在線且閘道已採用。然後確認允許向您的 RADIUS 伺服器發送輸出流量。

用戶端檢查

請訪客在裝置上忽略此網路並重新加入。停用任何可能完全繞過重導向的 VPN 或自訂 DNS 設定。如果漏掉了 CNA 通知，請開啟瀏覽器並前往 neverssl.com。在 Android 裝置上，點擊「您可能需要登入」通知即可啟動 CNA 瀏覽器工作階段。

來自旅宿業、零售業與活動場地的實際案例

這些實際案例展示了核對清單在場域層級的運作方式。

一間擁有 200 間客房但出現空白快顯頁面的飯店

情況。 一間 飯店 運作了自行託管的 UniFi Network Server 和外部入口網站。在進行網路變更後，連線到訪客 SSID 的訪客看到了空白頁面。櫃檯人員每晚記錄了約十幾起投訴。

處理方式。 neverssl.com 沒有重導向，因此團隊首先檢查了 DNS。訪客 VLAN 的 DHCP 範圍發放了私有子網路上的內部 DNS 伺服器，而訪客限制阻擋了該子網路。團隊隨後將訪客範圍切換到公共解析程式。

結果。 下一次連線時，入口網站重導向便正常運作。櫃檯在該週內沒有再接到任何 WiFi 投訴。

一間因社群登入停滯的 40 家門市連鎖零售商

情況。 一家 零售 連鎖店在其快顯頁面上新增了社群登入功能。電子郵件表單可以正常運作，但社群按鈕在每家門市中都無限旋轉。

處理方式。 團隊使用開發人員工具開啟快顯頁面，並列出該提供商登入時載入的所有網域。他們將這些網域新增至一家試點門市的預先授權存取清單中，並在 Android 和 iOS 上進行測試，然後將此變更推廣到所有 40 家門市。

結果。 所有 40 家門市的社群登入皆順利完成。該團隊現在會在每次提供商更新後，重新測試該試點門市。

一間出現憑證警告的會議中心

情況。 使用筆記型電腦的與會者在進入入口網站前看到了「您的連線不是私密連線」的訊息。手機透過 CNA 可以正常運作，因此故障看起來是斷斷續續的。

處理方式。 網址列顯示了指向 IP 位址的 HTTPS 重導向。團隊停用了 HTTPS 重導向，直到與重導向主機名稱相符且受公開信任的憑證就位。

結果。 筆記型電腦上的警告消失了。在會議接下來的期間，活動服務台沒有再收到任何入口網站的支援需求單。

您該如何防止 UniFi Captive Portal 再次失敗？

• 維護預先授權註冊表。 列出所有主機和子網路、存在原因以及擁有者。在新增登入方法或付款提供商時，請重新檢視此清單。
• 每次變更後進行測試。 使用一支 Android 手機、一支 iPhone 和一台筆記型電腦進行測試。確認 neverssl.com 可以重導向且能完成登入。
• 追蹤憑證過期時間。 主機名稱重導向上的憑證過期，會產生與沒有憑證相同的警告。
• 監控控制器。 在訪客發現之前，針對自行託管伺服器離線的情況發出警報。
• 運行開放式訪客網路。 Purple 建議使用開放式訪客網路，因為熟悉度可以減少登入時的阻力。

同樣的原則也適用於其他廠商。Purple 的 HPE Aruba captive portal troubleshooting guide 和 Cisco Meraki captive portal troubleshooting guide 也為這些平台遵循相同的檢查清單。

常見問題

Purple 是否支援我們現有的 Ubiquiti UniFi 無線基地台？

是的，Purple 可以作為外部傳送門與 RADIUS 服務在 Ubiquiti UniFi 上運行，因此您可以保留現有的無線基地台。Purple 與硬體無關，同時也支援 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Cambium、Extreme 和 Fortinet。這對於擁有多種混合硬體的多站點物業非常重要，因為單一的 Guest WiFi 設定即可覆蓋所有廠商。根據 Purple 的自家數據，Purple 的平台已在超過 80,000 個實體場域中運行。

我們可以將自託管的 UniFi Network Server 與外部傳送門一起保留嗎？

是的，自託管的 UniFi Network Server 可以與外部傳送門搭配使用，前提是該伺服器必須保持可連線狀態。閘道器和無線基地台必須能夠連線到伺服器，且伺服器必須能夠連線到您傳送門提供商的 RADIUS 服務。如果伺服器位於總部，請檢查站點之間的防火牆規則。雲端主控台雖然免去了託管工作，但仍需要對 RADIUS 的輸出存取權限。

我們的 UniFi 訪客網路應該是開放的還是有密碼保護的？

對於訪客存取，建議選擇開放式網路。Purple 建議透過開放式網路提供 Guest WiFi，因為這已成為目前的標準慣例，且能減少登入時的阻礙。Captive Portal 仍會控制存取、收集自願選擇的同意聲明，並為每位訪客提供一次性登入。受密碼保護的訪客網路會增加一個步驟，並導致更多前台諮詢。

我們需要為 Captive Portal 購買 SSL 憑證嗎？

是的，如果您透過 HTTPS 或主機名稱重新導向訪客。瀏覽器要求使用受大眾信任的憑證，且重新導向的主機名稱必須與憑證的通用名稱 (Common Name) 一致。如果沒有憑證，筆記型電腦在載入傳送門之前會顯示安全性警告。如果您無法維護憑證，請關閉 HTTPS 重新導向，並讓裝置的 CNA 改用 HTTP 重新導向。

轉移到 Purple 對我們的 GDPR 合規狀況有何影響？

Purple 能協助您符合 GDPR，而不是增加風險。Purple 擁有 ISO 27001、GDPR、CCPA 以及 Cyber Essentials 認證，且歡迎頁面會記錄行銷同意的自願選擇。您收集的第一方數據將與每位訪客所給予的同意保持關聯。您自己的隱私權聲明和保留政策仍適用，因此請在發布前檢視這兩項內容。

從內建的 UniFi 熱點遷移到 Purple 需要花費多少心力？

轉換至 Purple 僅是設定變更，而非硬體專案。您只需將外部入口網站伺服器與 RADIUS 設定指向 Purple，接著更新 Splash Page 網域的預先授權存取。Purple 層疊於您現有的 UniFi 基礎架構之上，因此無需拆除與汰換。您可以先在一處站點進行測試，隨後將該設定複製到您的整個場域中。

Purple 能處理高流量場地的訪客登入嗎？

是的，根據 Purple 的官方數據，Purple 在 2024 年處理了 4.4 億次登入。此流量涵蓋了 飯店、零售、火車 以及面臨極高尖峰流量的 醫療保健 站點。在 UniFi 上，入口網站的容量極少成為瓶頸。DNS 的可達性與完整的預先授權存取更為重要，因此在大規模活動前，請務必套用此檢查清單。