适用于 Ubiquiti UniFi 的 Captive Portal

Executive Summary

随着企业实体场所——从大型连锁零售 [1]、多场所酒店集团 [2] 到大型交通枢纽 [3] 和教育机构 [4]——旨在最大化其无线基础设施的价值，内置热点控制器的局限性已成为一个重大的运营瓶颈。Ubiquiti UniFi 生态系统提供了高度可靠、高性价比且可扩展的硬件。然而，其原生访客门户缺乏现代企业运营所需的高级数据捕获、多场所分析、CRM 集成、全球隐私合规性（GDPR、CCPA、PCI DSS）以及变现能力。

本技术参考指南提供了将 Purple 的企业 WiFi 智能平台 [5] 叠加到 Ubiquiti UniFi 网络架构上的全面架构演练。通过利用 UniFi 的 External Portal Server 功能，网络架构师和系统集成商可以绕过本地控制器的限制。此集成通过 Purple 安全的云托管身份与分析引擎路由访客认证，将一项基础工具转变为企业级的营销和运营资产。

Technical Deep-Dive

要部署安全且稳定的外部 Captive Portal，网络工程师必须了解未认证客户端连接到无线网络时发生的底层通信和状态转换。

The Guest Connection and Redirection Lifecycle

UniFi Captive Portal 工作流基于严格的状态模型运行。当客户端关联到启用了访客功能的 SSID 时，会启动以下顺序过程：

重定向查询参数

当 UniFi AP 发起 HTTP 302 重定向时，它会在外部 Portal URL 中附加一组标准化的查询参数。外部 Portal 必须捕获这些参数，以识别客户端并执行后续的 API 授权：

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://connectivitycheck.gstatic.com%2F&ssid=purple-guest

• ap：客户端关联的特定 UniFi 接入点的 MAC 地址。
• id：请求网络访问的客户端设备的 MAC 地址。
• t：代表重定向发起时间的 Unix 时间戳，用于安全验证。
• url：客户端尝试访问的原始 URL（通常是操作系统 Captive Portal 检测端点）。
• ssid：客户端连接的 SSID 名称，允许 Portal 展示特定站点的品牌定制。

Walled Garden（授权前访问控制）

在客户端获得授权之前，除授权前访问列表（通常称为 Walled Garden）中明确定义的目标地址外，所有流量都将被阻断。由于现代客户端设备会运行自动化的 Captive Portal 助手 (CPA) 来通过 HTTPS 测试连接性，且外部认证通常依赖第三方身份提供商 (IdP)，因此配置一个健壮且准确的 Walled Garden 至关重要。

如果 Walled Garden 中遗漏了所需的域名或 IP 范围，欢迎页面将无法加载，社交登录按钮将无响应，或者客户端设备会认为网络故障而完全断开 WiFi 连接。

实施指南本节概述了将 Purple 的外部 Captive Portal 与 Ubiquiti UniFi 网络应用程序（控制器）进行集成所需的逐步配置。

步骤 1：网络分段与 VLAN 配置

为确保企业级安全性和合规性（例如 PCI DSS 和 GDPR），访客流量必须与企业资源、POS 系统和 IoT 网络完全隔离。

1. 导航至 UniFi 网络应用程序中的 Settings > Networks（设置 > 网络）。
2. 单击 Create New Network（创建新网络）。
3. 按如下方式配置网络设置：
   • Name（名称）：Purple Guest Network
   • VLAN ID：90（或任何专用的访客 VLAN 标签）
   • Network Type（网络类型）：Guest（这会自动应用客户端隔离，防止访客之间的通信）。
   • Gateway IP/Subnet（网关 IP/子网）：配置合适的子网（例如 10.90.0.1/22，以支持最多 1022 个并发访客租约）。
   • DHCP Range（DHCP 范围）：启用 DHCP 并定义范围（例如 10.90.0.10 至 10.90.3.254）。
   • DNS Server（DNS 服务器）：设置为可靠的公共解析器（例如 Cloudflare 1.1.1.1 和 Google 8.8.8.8），以确保快速的 DNS 解析。

步骤 2：访客 SSID 配置

1. 导航至 Settings > WiFi（设置 > WiFi），然后单击 Create New WiFi Network（创建新 WiFi 网络）。
2. 配置 SSID 参数：
   • Name (SSID)（名称 (SSID)）：Purple Guest WiFi
   • Security Protocol（安全协议）：Open（将由 Captive Portal 处理身份验证）。
   • Network（网络）：选择在步骤 1 中创建的 Purple Guest Network (VLAN 90)。
   • Client Device Isolation（客户端设备隔离）：确保此项已切换为 ON（开启）。
3. 向下滚动至 Hotspot Portal（热点门户），并勾选 Enable Captive Portal（启用 Captive Portal）复选框。

步骤 3：配置外部门户服务器

启用 Hotspot Portal 后，您必须将身份验证重定向到 Purple 的安全云服务器。

1. 导航至 Settings > Profiles > Guest Hotspot（设置 > 配置文件 > 访客热点）（或在较旧的控制器版本中导航至 Settings > Guest Control）。
2. 在 Authentication（身份验证）下，选择 External Portal Server（外部门户服务器）。
3. 配置以下字段：
   • IP / FQDN：输入 Purple 提供的 FQDN（例如 portal.purplehotspot.com）。
   • Use Secure Portal (HTTPS)：切换为 ON（开启）（为了安全性和现代浏览器的兼容性，此项为必选项）。
   • Redirect Using Hostname：切换为 ON（开启）并输入 FQDN portal.purplehotspot.com。
   • Port（端口）：443（标准 HTTPS）。
   • HTTPS Redirection：切换为 ON（开启）（这允许 AP 拦截初始 HTTPS 请求并进行重定向，但这需要仔细的 DNS 管理）。

步骤 4：配置预授权访问（Walled Garden）

要允许未通过身份验证的访客加载 Purple 引导页面并通过第三方 IdP 进行身份验证，请将以下域名和 IP 范围添加到 Settings > Profiles > Guest Hotspot > Pre-Authorization Access 下的 Pre-Authorization Access（预授权访问）列表中：

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
```"ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

注意：对于使用 Stripe 支付处理的部署，请将 *.stripe.com 和 *.stripe.network 添加到预授权列表中。

步骤 5：建立 API 握手

为了让 Purple 授权访客，其云端服务器必须与您的 UniFi Network Application 进行通信。

适用于 UniFi Network Application 9.1 及更高版本（推荐使用 REST API）

1. 在 UniFi 控制器中，导航至 Settings > Control Plane > Integrations。
2. 在 API Keys 区域，点击 Generate New API Key。
3. 分配一个名称（例如 Purple Integration Key），并将权限设置为 Administrator。
4. 复制生成的 API Key。
5. 登录您的 Purple Portal，导航至 Venue Settings > Integration > Ubiquiti UniFi，然后粘贴该 API Key 以及您的 UniFi 控制器的公网 FQDN（例如 unifi.yourdomain.com:443）。

适用于旧版控制器（基于凭据的 API）

1. 导航至 Settings > System > Admins。
2. 创建一个专用的本地管理员账户（例如 purple_api）。
3. 分配 Administrator 或 Hotspot Operator 权限。
4. 配置一个强且唯一的密码。
5. 在 Purple Portal 中，在 UniFi Integration 选项卡下输入这些凭据。

最佳实践

1. SSL 证书要求

切勿在生产环境的 UniFi 控制器或外部 Portal 服务器上使用自签名 SSL 证书。现代 Web 浏览器和操作系统 Captive Portal 助手 (CPA) 会执行严格的 SSL/TLS 验证。自签名证书会触发非常显眼的安全警告（例如“您的连接不是私密连接”），从而导致极高的流失率并损害品牌形象。

• 在 UniFi 控制器的 FQDN 上部署有效的、受公众信任的 SSL 证书（例如 Let's Encrypt 或商业 CA 证书）。
• 确保控制器的 FQDN 能够从内部访客 VLAN 和公网正确解析。

2. DNS 配置

DNS 解析缓慢是 Captive Portal 重定向缓慢的主要原因。

• 除非网关配置了高性能的 DNS 转发，否则请勿将访客 DNS 指向 UniFi 网关的本地 IP。
• 相反，应配置访客 DHCP 范围，以直接向客户端分配快速、弹性的公共 DNS 服务器（例如，主 DNS：1.1.1.1，备 DNS：8.8.8.8）。

3. RADIUS 访客 WiFi 配置（企业级替代方案）

对于需要基于证书或凭据的 802.1X 安全性，而不是带有 Web 门户的开放式 SSID 的场所，UniFi 支持外部云 RADIUS 集成 [6]。

• 在 Settings > Profiles > RADIUS 下配置 RADIUS Profile。
• 输入 Purple 提供的首选和备用 RADIUS 服务器 IP 以及共享密钥。* 启用 RADIUS Accounting 并将 Interim Update Interval 设置为 300 秒，以确保实时会话跟踪。
• 在 SSID 设置下，将安全协议设置为 WPA2 Enterprise 或 WPA3 Enterprise [7]，然后选择 RADIUS Profile。

故障排除与风险规避

在部署外部 Captive Portal 时，网络管理员经常会遇到几种常见的故障模式。下表详细列出了这些问题、其根本原因以及具体的规避步骤：

ROI 与业务影响

虽然部署外部 Captive Portal 需要精细的网络工程设计，但其带来的业务成果和投资回报率（ROI）远超初始实施的复杂性。

企业级数据采集与 CRM 数据富集

原生 UniFi 访客门户是一个“盲目”的工具；它仅授予互联网访问权限，而不捕获用户身份。通过叠加 Purple，场所可以完全符合 GDPR 和 CCPA 合规要求的方式捕获宝贵的第一方数据（电子邮件、电话号码、社交账号个人资料）。这些数据会自动实时同步到 CRM 系统、营销平台（例如 Salesforce、HubSpot、Mailchimp）和会员忠诚度计划中，从而实现高度精准的营销活动，提高复访率和客户生命周期价值。

多站点管理与白标定制

对于托管服务提供商（MSP）和多站点企业运营商而言，通过独立的 UniFi 控制器管理数百个场所的访客 WiFi 效率极低。Purple 提供了一个统一的、中心化的云端仪表板，无论底层的 UniFi 控制器如何分布，都可以管理全球所有场所的展示页面、合规条款和分析数据。

实时分析与空间智能

Purple 将 UniFi 无线网络转化为强大的传感器阵列。通过分析探测请求和连接元数据， Purple 提供了深度的空间智能，包括：

• 客流量分析：总访客量、路过客流量以及转化率（路过并进入）。
• 停留时间：平均访问时长，按客户类型（新客户与回头客）进行细分。
• 新近度与频次：客户返回的频率以及两次访问之间间隔的时间。
• 场所热力图：访客流量和密度的可视化呈现，使零售和场所运营商能够优化布局和人员配置。

通过零售媒体网络变现

对于体育场馆、购物中心和机场等大型场所，Captive Portal 展示页面代表着极具价值的数字资产。Purple 允许场所通过与零售媒体网络集成来将该空间变现，在连接的瞬间直接向访客投放精准的程序化广告、赞助登录体验和本地化促销活动。

参考资料

• [1] 零售业 Purple： 零售场所 WiFi 营销与分析
• [2] 酒店餐饮业 Purple： 酒店与餐厅企业级访客 WiFi 解决方案 * [3] Purple 交通运输： 交通枢纽公共 WiFi 与分析服务
• [4] Purple 医疗保健： 医疗机构患者与访客 WiFi 解决方案
• [5] Purple 核心产品： 企业级访客 WiFi 平台
• [6] Cloud RADIUS 集成指南： 如何使用 Cloud RADIUS 实现 802.1X 认证
• [7] 网络准入控制最佳实践： 2026年10大最佳网络准入控制 (NAC) 解决方案
• [8] 思科无线参考（架构对比）： 思科无线 AP：2026年产品与部署指南
• [9] 教育行业 WiFi 参考： 学校 WiFi：2026年管理员与 IT 指南
• [10] Purple 分析平台： WiFi 分析与营销平台