Ubiquiti UniFi 与 Purple WiFi：集成指南

执行摘要

Ubiquiti UniFi 是全球部署最广泛的企业 WiFi 平台之一，因其性能、可扩展性和成本效益而受到酒店、零售连锁店、体育场馆和公共部门组织的信赖。然而，其原生访客门户功能有限。Purple 的 WiFi 智能平台通过其外部门户服务器功能直接与 UniFi 网络控制器集成，从而弥补了这一差距，无需任何额外硬件即可提供完全品牌化、富含分析功能的 Captive Portal 体验。

本指南为该集成提供完整的技术参考。它涵盖了底层架构、当前版本（v7.4+）和旧版本（v7.3 及以下）UniFi 版本的逐步配置过程、安全与合规的最佳实践，以及结构化的故障排除框架。完成这一集成的组织可以访问实时访客分析、符合 GDPR 要求的数据采集、CRM 集成，并能够投放有针对性的营销传播——将访客 WiFi 从成本中心转变为可衡量的商业资产。

技术深度解析

Ubiquiti UniFi 与 Purple 之间的集成依赖于 UniFi 的外部门户服务器功能。此功能将访客用户从本地 UniFi 控制器重定向到指定的第三方 Captive Portal——在本例中即为 Purple 平台。底层机制依赖于一系列 HTTP 重定向和 API 调用，这些调用管理着访客授权生命周期。

当访客连接到指定的开放式认证 SSID 时，UniFi 控制器会将其设备置于“待处理”状态。在此状态下，所有 HTTP 流量都会被拦截并重定向到 Purple 的启动页面 URL，同时将关键参数附加到 URL 查询字符串中：访客的 MAC 地址、AP 的 MAC 地址以及站点标识符。Purple 平台捕获这些参数，呈现适当的登录体验，并在用户成功认证后——无论是通过社交登录、电子邮件表单还是代金券——向 UniFi 网络控制器发起安全的 HTTPS API 调用，以授权该访客的 MAC 地址在指定的会话时长内获得访问权限。这一授权将设备从“待处理”状态移至“已授权”状态，从而授予其互联网访问权限。

该架构的一个关键组成部分是围墙花园——在认证之前允许访客设备访问的 IP 地址和域名白名单。这对于允许访问 Purple 自己的域名、社交登录提供商（Facebook、Google）、Apple 的 CNA 检测端点以及任何其他所需的外部服务至关重要。如果没有正确配置围墙花园，Captive Portal 将完全无法加载。

对于更高级的部署，Purple 的 PurpleConnex 功能引入了 Passpoint (IEEE 802.11u) 支持，使用 RADIUS 服务器为回头客提供无缝、无需凭据的重新连接。这需要在 UniFi 中配置一个 RADIUS 配置文件，指向 Purple 的认证服务器 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 特别版、UDR 和 CloudKey Gen2+——相关端口为 TCP 443。

步骤 2：创建专用本地管理员账户。 出于安全卫生考虑，切勿在 Purple API 集成中使用您的主要 Ubiquiti 超级管理员或云账户凭据。在 UniFi 控制器上专门为此目的创建一个新的专用本地管理员账户。该账户应具有相关站点的完全管理权限。使用专用账户可以限制任何潜在凭据泄露的影响范围，并确保集成不会因您的主账户变更而中断。

步骤 3：创建访客 WiFi SSID。 在 UniFi 网络应用程序中，导航至 设置 > WiFi，然后点击 新建。分配一个面向公众的名称（例如，“酒店访客 WiFi”）。将 安全协议 设置为 开放式——这是 Captive Portal 重定向机制正常工作的必要条件。将该 SSID 分配给您指定的访客 VLAN。启用 热点门户 开关。

步骤 4：配置热点门户和外部服务器。 导航至 热点管理器 > 登录页面。在 认证 下，选择 外部门户服务器，并输入 Purple 提供的外部门户 IP 地址。在 设置 下，进行如下配置：启用 安全门户，启用 使用主机名重定向 并输入 Purple 提供的访问域名，并确保 HTTPS 重定向 设置为 禁用。会话的 默认过期时间 应设置为 8 小时。

步骤 5：配置围墙花园。 在热点管理器设置中，找到 预授权访问 部分。添加 Purple 提供的列表中的所有域名。此列表通常包括 Purple 自己的平台域名、社交登录提供商域名（facebook.com、google.com、accounts.google.com）、Apple 的 Captive Network Assistant (CNA) 检测端点，以及您在启动页面上使用的任何其他第三方服务。此步骤是部署失败的最常见原因，必须精确完成。

步骤 6：在 Purple 门户中输入控制器详细信息。 登录您的 Purple 账户，并导航至相关场所的设置。输入 UniFi 控制器的公共 IP 地址或主机名，以及步骤 2 中创建的专用本地管理员账户的凭据。保存配置。Purple 将尝试验证连接。

步骤 7：测试与验证。 使用先前未连接过该网络的移动设备，连接到新的访客 SSID。您应自动重定向到 Purple 的 Captive Portal。使用配置的认证方式之一进行认证。成功后，您应获得互联网访问权限。如果重定向失败或认证后未获得互联网访问权限，请参考下面的故障排除部分。

最佳实践

网络隔离是任何访客 WiFi 部署的基本安全要求。访客 SSID 必须分配给一个专用 VLAN，该 VLAN 需与所有公司网络和管理网络进行防火墙隔离。这可以防止访客设备访问内部资源，满足 PCI DSS 网络隔离要求，并限制任何安全事件对访客网络的影响。

在高密度环境中，带宽管理同样重要。应配置 UniFi 的每用户速率限制功能，为访客用户设置合理的上传和下载上限。这可以防止少数高带宽用户降低所有访客的体验，这在酒店和会议中心部署中尤为重要。

围墙花园需要持续维护。社交登录提供商和其他第三方服务会定期更新其域名结构。每季度对照 Purple 最新的推荐域名列表审查围墙花园配置，是一种良好的运维实践。未能维护此列表是部署后门户失败的主要原因。

对于 API 集成，始终使用专用本地管理员账户，而不是关联云账户。这既是最佳安全实践，也是一项可靠性措施——云账户凭据会受到多因素认证流程的影响，可能会中断 Purple 为授权访客而进行的自动 API 调用。

故障排除与风险缓解

最常见的故障模式是 Captive Portal 无法加载。当访客连接到 SSID 但未看到重定向，或门户页面无法呈现时，根本原因几乎总是围墙花园不完整。开始故障排除时，连接一个测试设备并尝试导航到一个已知的 HTTP URL。如果发生了重定向但页面无法加载，则将缺失的域名添加到围墙花园中。同时验证访客网络的 DNS 是否正确配置以解析外部主机名。

第二常见的故障是访客在 Purple 门户上成功认证，但未获得互联网访问权限。这表明 Purple 与 UniFi 控制器之间的 API 通信失败。诊断步骤如下：首先，通过从外部网络尝试访问来确认控制器在正确的端口上可公开访问；其次，验证在 Purple 门户中输入的本地管理员凭据是否正确，并且账户未被锁定；第三，检查 UniFi 控制器的事件日志，查看是否有任何 API 认证错误。

对于生产环境部署，控制器可用性是一个关键风险因素。如果 UniFi 控制器离线，新的访客授权将失败。缓解策略包括部署云托管 UniFi 控制器（提供固有冗余），实施高可用性控制器配对，或配置控制器可用性的监控和警报。Purple 平台将对授权尝试进行排队并重试，但长时间控制器停机将导致访客体验下降。

从合规性的角度来看，通过 Captive Portal 收集的数据受 GDPR 及同等数据保护法规的约束。Purple 的平台架构专为合规性而设计，提供同意管理、数据主体访问请求 (DSAR) 工具以及可配置的数据保留策略。但是，合法数据处理的法定责任仍由场所运营方承担。确保您的隐私政策在启动页面上有明确的链接，您有数据收集的书面法律依据，并且您的数据保留设置与您的组织政策一致。

投资回报率与业务影响

将 Purple 与 UniFi 集成不仅仅是一次技术升级；它是一项战略性的业务决策，将访客 WiFi 从成本中心转变为强大的资产。投资回报率可在多个关键维度上衡量。

商业智能是主要的驱动力。Purple 捕获访客行为的丰富匿名数据——包括客流量、停留时间、访问频率和移动模式。对于零售连锁店，这些数据可以直接为店铺布局决策、人员配备水平和促销时机提供信息。对于酒店，它可以揭示哪些设施在什么时间使用最多，从而实现更有针对性的追加销售和运营效率。

营销和互动能力是显著的次要效益。通过征得同意后捕获访客联系方式，组织可以建立第一方营销数据库，不受第三方 cookie 弃用的限制。访问后的电子邮件活动、满意度调查和忠诚度计划邀请可以直接从 Purple 平台自动化，从而推动重复访问率和客户终身价值的可衡量改进。

对于体育场馆、会议中心和购物中心等大型场所，通过实时客流量分析和热力图获得的运营情报可以带来显著的效率提升——根据实际的访客移动数据而非假设来优化清洁时间表、安保部署和零售摊位布局。

在某些情况下，访客 WiFi 基础设施本身可以通过分级访问模式、赞助启动页面或定向广告实现货币化，从而创造直接的收入来源，抵消基础设施投资的成本。