Ubiquiti UniFi 與 Purple WiFi：整合指南

執行摘要

Ubiquiti UniFi 是全球部署最廣泛的企業 WiFi 平台之一，因其效能、可擴展性和成本效益而受到飯店、零售連鎖店、體育場館和公共部門組織的信賴。然而，其原生的訪客入口網站功能有限。Purple 的 WiFi 智慧平台透過其外部入口網站伺服器功能直接與 UniFi 網路控制器整合，解決了這一差距，提供完全品牌化、分析豐富的強制門戶體驗，無需任何額外硬體。

本指南為此整合提供了完整的技術參考。涵蓋基礎架構、目前（v7.4+）和舊版（v7.3 及以下）UniFi 版本的逐步設定流程、安全性和合規性的最佳實踐，以及結構化的疑難排解框架。完成此整合的組織將能夠存取即時訪客分析、符合 GDPR 的資料擷取、CRM 整合，以及傳遞目標行銷通訊的能力 — 將訪客 WiFi 從成本中心轉變為可衡量的商業資產。

技術深入探討

Ubiquiti UniFi 與 Purple 的整合關鍵在於 UniFi 的外部入口網站伺服器功能。此功能會將訪客使用者從本機 UniFi 控制器重新導向至指定的第三方強制門戶 — 在此案例中即為 Purple 平台。底層機制依賴一系列 HTTP 重新導向和 API 呼叫，來管理訪客授權的生命週期。

當訪客連線到指定的開放驗證 SSID 時，UniFi 控制器會將其裝置置於「待處理」狀態。在此狀態下，所有 HTTP 流量都會被攔截並重新導向至 Purple 啟動頁面 URL，並在 URL 查詢字串中附加關鍵參數：訪客的 MAC 位址、AP MAC 位址和站點識別碼。Purple 平台會擷取這些參數，呈現適當的登入體驗，並在成功驗證使用者後 — 無論是透過社群登入、電子郵件表單或代碼 — 向 UniFi 網路控制器發送安全的 HTTPS API 呼叫，以授權訪客的 MAC 位址在指定的工作階段持續時間內。此授權會將裝置從「待處理」狀態移至「已授權」狀態，授予其網際網路存取權。

此架構的一個關鍵組成部分是 Walled Garden — 一份 IP 位址和網域的白名單，允許訪客裝置在驗證前存取。這對於允許存取 Purple 自己的網域、社群登入提供者（Facebook、Google）、Apple 的 CNA 偵測端點，以及任何其他所需的外部服務至關重要。若無正確設定的 Walled Garden，強制門戶將完全無法載入。

對於更進階的部署，Purple 的 PurpleConnex 功能引入了 Passpoint (IEEE 802.11u) 支援，使用 RADIUS 伺服器為回訪使用者提供無縫、無需憑證的重新連線。這需要在 UniFi 內設定一個指向 Purple 驗證伺服器的 RADIUS 設定檔，IP 為 34.150.158.147，連接埠 1812（驗證）和 1813（帳務）。

實作指南

本節提供設定您的 UniFi 網路控制器以與 Purple 整合的逐步指南。下列說明適用於 UniFi 網路應用程式 7.4 版或更新版本。對於舊版（v7.3 及以下），設定原則相同，但導覽路徑略有不同，使用「設定檔 > 訪客熱點」而非「熱點管理員」。

步驟 1：驗證並建立控制器可存取性。 開始任何設定之前，請確認您的 UniFi 網路控制器可從公共網際網路存取。Purple 的雲端平台必須能夠與您控制器的 API 通訊，以授權訪客工作階段。對於以軟體為基礎的 UniFi 控制器，這需要在您的防火牆上設定一個連接埠轉送規則，將 TCP 連接埠 8443 對應到控制器的內部 LAN IP 位址。對於以硬體為基礎的部署 — 包括 UniFi Dream Machine Pro (UDM Pro)、UDM Special Edition、UDR 和 CloudKey Gen2+ — 相關連接埠是 TCP 443。

步驟 2：建立專用的本機管理員帳戶。 為了安全衛生，切勿將您的主要 Ubiquiti 超級管理員或雲端帳戶憑證用於 Purple API 整合。為此目的，在您的 UniFi 控制器上建立一個新的專用本機管理員帳戶。此帳戶應擁有相關站點的完整管理權限。使用專用帳戶可限制任何潛在憑證洩露的影響範圍，並確保整合不會因您主要帳戶的變更而中斷。

步驟 3：建立訪客 WiFi SSID。 在 UniFi 網路應用程式中，導覽至 設定 > WiFi，然後按一下 建立新的。指定一個公開名稱（例如「飯店訪客 WiFi」）。將 安全性通訊協定設為 開放 — 這是強制門戶重新導向機制運作的必要條件。將 SSID 指派給您指定的訪客 VLAN。啟用 熱點入口網站切換開關。

步驟 4：設定熱點入口網站和外部伺服器。 導覽至 熱點管理員 > 登陸頁面。在 驗證下，選取 外部入口網站伺服器，並輸入 Purple 提供的外部入口網站 IP 位址。在 設定下，進行如下設定：啟用 安全入口網站，啟用 使用主機名稱重新導向並輸入 Purple 提供的存取網域，並確保 HTTPS 重新導向設為 停用。工作階段 預設到期時間應設為 8 小時。

步驟 5：設定 Walled Garden。 在熱點管理員設定中，找到 預先授權存取區段。從 Purple 提供的清單中新增所有網域。此清單通常包括 Purple 自己的平台網域、社群登入提供者網域（facebook.com、google.com、accounts.google.com）、Apple 的 Captive Network Assistant (CNA) 偵測端點，以及在您的啟動頁面上使用的任何其他第三方服務。此步驟是部署失敗最常見的來源，必須精確完成。

步驟 6：在 Purple 入口網站中輸入控制器詳細資料。 登入您的 Purple 帳戶，並導覽至相關場地的設定。輸入您 UniFi 控制器的公用 IP 位址或主機名稱，以及步驟 2 中建立的專用本機管理員帳戶的憑證。儲存設定。Purple 將嘗試驗證連線。

步驟 7：測試與驗證。 使用一部先前未連線至網路的行動裝置，連線至新的訪客 SSID。您應該會自動重新導向至 Purple 強制門戶。使用其中一種已設定的方法進行驗證。成功後，您應該會獲得網際網路存取權。若重新導向失敗或驗證後未授予網際網路存取權，請參閱下方的疑難排解章節。

最佳實踐

網路分段是任何訪客 WiFi 部署的基本安全性要求。訪客 SSID 必須指派給一個專用的 VLAN，並與所有公司和管理網路進行防火牆隔離。這可防止訪客裝置存取內部資源，滿足 PCI DSS 網路隔離要求，並限制訪客網路上任何安全事件的影響。

在高密度環境中，頻寬管理同樣重要。應設定 UniFi 的每位使用者速率限制功能，為訪客使用者設定合理的上傳和下載上限。這可防止少數高頻寬使用者降低所有訪客的體驗，這在飯店和會議中心的部署中尤其重要。

Walled Garden 需要持續維護。社群登入提供者和其他第三方服務會定期更新其網域結構。每季檢查 Walled Garden 設定，並與 Purple 最新推薦的網域清單進行交叉比對，是一項良好的營運實務。未能維護此清單是部署後入口網站故障的主要原因。

對於 API 整合，始終使用專用的本機管理員帳戶，而非連結雲端的帳戶。這既是安全性最佳實踐，也是一項可靠性措施 — 雲端帳戶憑證會受到多重要素驗證流程的限制，這可能會中斷 Purple 用於授權訪客的自動化 API 呼叫。

疑難排解與風險緩解

最常見的故障模式是強制門戶無法載入。當訪客連線至 SSID 但未看到重新導向，或入口網站頁面無法呈現時，根本原因幾乎總是 Walled Garden 不完整。請開始疑難排解：連線一部測試裝置，並嘗試導覽至一個已知的 HTTP URL。若重新導向發生但頁面無法載入，請將缺少的網域新增至 Walled Garden。同時驗證訪客網路的 DNS 是否正確設定，以解析外部主機名稱。

第二常見的故障是訪客在 Purple 入口網站上成功驗證，但未獲得網際網路存取權。這表示 Purple 與 UniFi 控制器之間的 API 通訊失敗。診斷步驟為：首先，從外部網路嘗試連線至控制器，確認控制器可在正確的連接埠上公開存取；其次，驗證在 Purple 入口網站中輸入的本機管理員憑證是否正確，且帳戶未被鎖定；第三，檢查 UniFi 控制器的事件記錄中是否有任何 API 驗證錯誤。

對於生產環境部署，控制器可用性是一個關鍵風險因素。若 UniFi 控制器離線，新的訪客授權將失敗。緩解策略包括部署雲端託管的 UniFi 控制器（提供內建備援）、實作高可用性控制器配對，或設定監控和警示來追蹤控制器的可用性。Purple 的平台會將授權嘗試排入佇列並重試，但長時間的控制器停機將導致訪客體驗下降。

從合規性的角度來看，透過強制門戶收集的資料受到 GDPR 和同等資料保護法規的約束。Purple 的平台架構設計符合合規性，提供同意管理、資料主體存取請求 (DSAR) 工具，以及可設定的資料保留政策。然而，合法資料處理的法律責任仍在場地營運商身上。確保您的隱私權政策在啟動頁面上清楚地連結，您有記錄的資料收集法律依據，且您的資料保留設定與組織政策一致。

投資報酬率與商業影響

將 Purple 與 UniFi 整合不僅是技術升級；這是一項策略性商業決策，能將訪客 WiFi 從成本中心轉變為強大的資產。投資報酬率可在幾個關鍵維度上進行衡量。

商業智慧是主要的價值驅動力。Purple 會擷取豐富的匿名化訪客行為資料 — 包括客流、停留時間、造訪頻率和移動模式。對於零售連鎖店，這些資料可直接影響店面佈局決策、人員配置層級和促銷時機。對於飯店，則可揭示哪些設施最常使用以及使用的時間，從而實現更具針對性的向上銷售和營運效率。

行銷和互動能力代表了一項重要的次要效益。透過在取得同意的情況下擷取訪客聯絡詳細資料，組織可以建立第一方行銷資料庫，不受第三方 Cookie 淘汰的限制。造訪後的電子郵件活動、滿意度調查和忠誠計畫邀請可以直接從 Purple 平台自動化，推動重複造訪率和客戶終身價值的可衡量改善。

對於體育場館、會議中心和購物中心等大型場地，從即時客流分析和熱度圖中獲得的營運智慧可以帶來顯著的效率提升 — 根據實際的訪客移動資料而非假設，最佳化清潔排程、安全部署和零售攤位配置。

在某些情況下，訪客 WiFi 基礎設施本身可以透過分層存取模式、贊助啟動頁面或目標廣告來獲利，創造直接的收入流，抵銷基礎設施投資的成本。