Ubiquiti UniFi 的 Captive Portal：使用 Purple 访客 WiFi 进行设置

Captive Portal for Ubiquiti UniFi — A Purple 官方技术指南 [介绍与背景 — 约 1 分钟] 欢迎收看 Purple 技术指南系列。我是您的主持人，今天我们将深入探讨在 Ubiquiti UniFi 基础设施上部署外部 Captive Portal 的具体细节 — 这是全球酒店、零售和企业环境中部署最广泛的网络平台之一。 如果您是使用 UniFi 云网关、Dream Machines 或 UniFi 网络应用程序的 IT 经理、网络架构师或系统集成商，这一期内容非常适合您。我们将详细剖析外部门户机制在底层的实际工作原理、如何正确配置它、常见问题在哪里，以及为什么在 UniFi 部署之上叠加 Purple 对于需要超越基础展示页面的场所来说，是正确的架构决策。 让我们开始吧。 [技术深挖 — 约 5 分钟] 首先，让我们了解当访客连接到启用了 Captive Portal 的 UniFi SSID 时，实际上发生了什么。 当访客设备与您的访客 SSID 关联时，UniFi 接入点会像往常一样通过 DHCP 为其分配一个 IP 地址。但该设备会立即被置于 UniFi 所称的“待处理”状态。在此状态下，接入点内置的 DNSmasq 进程会拦截该设备进行的所有 DNS 查询，而不管设备认为自己使用的是什么 DNS 服务器。接入点将所有 DNS 流量重定向到自身。 同时，接入点在 80 端口上运行一个轻量级的 HTTP 重定向器。当访客的浏览器发出任何 HTTP 请求时（请注意，关键是 HTTP，而不是 HTTPS），重定向器会立即返回一个 302 重定向，将浏览器引导至 Captive Portal 的展示页面。这就是触发 iOS 和 Android 设备上显示“登录 WiFi”通知的机制。 现在，内置门户与外部门户之间的区别就变得至关重要了。使用内置的 UniFi 热点门户（UniFi Hotspot Portal），展示页面由 UniFi 网络应用程序直接提供。它可以使用，设置也很快，但局限性很大。您只能获得基本的密码验证、凭证（vouchers）和 Stripe 支付。没有电子邮件收集、没有社交媒体登录、没有 GDPR 合规同意管理、没有 CRM 集成，也没有除会话计数之外任何有意义的数据分析。 当您配置“外部门户服务器”（External Portal Server，即我们今天关注的设置）时，您是在告诉 UniFi 控制器将访客重定向到一个完全独立的 Web 应用程序。在我们的案例中，该应用程序就是 Purple。您在“外部门户服务器”字段中输入的 URL 就成为了所有这些 302 重定向的目的地。 以下是关于该重定向URL的重要技术细节。当UniFi将访客重定向到您的外部门户时，它会在URL中附加几个查询参数。这些参数包括：AP MAC地址、客户端设备MAC地址、Unix时间戳、客户端尝试访问的原始URL以及SSID名称。在当前场景中，您的外部门户Purple会捕获这些参数，利用它们来识别连接设备、展示相应的Splash Page、处理身份验证，然后向UniFi Network Application发起API调用，以授权该MAC地址。 该API调用是至关重要的握手过程。自UniFi Network Application 9.1及更高版本起，提供了一个具有完整基于密钥身份验证的官方REST API。授权端点是一个发送至第一版站点API的POST请求，针对特定的客户端ID，其JSON正文可以指定以分钟为单位的时间限制、以兆字节为单位的数据使用限制以及以千比特每秒为单位的速率限制。一旦控制器收到该授权，它就会将指令下发给AP，访客的状态随即从待处理变为已授权，并被授予互联网访问权限。 现在我们来谈谈Walled Garden，UniFi将其称为Pre-Authorization Access（预授权访问）。这是访客在通过身份验证之前可以访问的域名和IP地址的白名单。这至关重要，也是最常见的配置错误源之一。 您的Walled Garden至少需要包含您的Purple门户的完全限定域名，以及Purple基础设施所解析到的IP地址或CIDR范围。如果您正在使用社交媒体登录（例如Facebook、Google、Microsoft），您还需要添加这些提供商的OAuth端点域名。Google的登录端点跨越多个IP范围和多个域名，包括accounts.google.com和oauth2.googleapis.com。Facebook的登录基础设施同样需要多个条目。Purple的文档提供了一个持续维护的、所需确切条目的列表，并且随着这些提供商更新其基础设施，该列表会保持最新。 UniFi特有一个很容易让许多部署陷入困境的关键特性。AP上的HTTP重定向器仅拦截端口80上的明文HTTP流量。现代设备（如iOS、Android、Windows和macOS）都执行基于HTTPS的Captive Portal检测。Apple设备通过HTTPS访问captive.apple.com，Android设备则访问connectivitycheck.gstatic.com。如果这些HTTPS请求没有收到特定的响应，设备可能会判定不存在Captive Portal，从而无法显示登录提示。 解决方案是确保您的Walled Garden包含主流操作系统的Captive Portal检测域名，并且您的Purple门户可以通过HTTPS访问，且配有有效的、受信任的SSL证书。自签名证书会导致浏览器安全警告，从而阻止门户加载。这在生产环境部署中是必须遵守的原则。另一个 UniFi 专属的考虑因素是控制器可访问性。UniFi Network Application（无论运行在 Cloud Gateway、Cloud Key 还是自托管服务器上）都必须能够从 Purple 的基础设施访问，以便 API 授权调用成功。如果您的控制器处于 NAT 后面的私有网络中，您需要确保相关的 API 端口可访问。对于自托管控制器，这通常是旧版 API 的端口 8443，或者 9.1 版本中引入的新版 API 的标准 HTTPS 端口 443。Purple 的支持文档指定了需要入站访问您控制器的确切 IP 范围。 对于基于 RADIUS 的认证 - 这适用于您将 Purple 与 WPA2-Enterprise 或 WPA3-Enterprise SSID 一起部署，而不是采用开放式访客 SSID 模式的情况 - UniFi 的内置 RADIUS 服务器支持标准的 802.1X EAP 方法。您可以在 Settings、Networks、RADIUS Servers 下配置 RADIUS 配置文件，然后在 SSID 配置中引用该配置文件。UniFi 还从 8.4 版本开始支持基于 TLS 的 RADIUS（即 RADSEC），这会对 AP 与认证服务器之间的 RADIUS 流量进行加密。对于 RADIUS 流量穿过公共互联网的多站点部署，强烈推荐使用 RADSEC。 [实施建议与常见陷阱 - 约 2 分钟] 下面我为您提供一份实用的实施清单，这是我在向任何客户在 UniFi 上部署 Purple 时都会梳理的内容。 第一，网络分段。您的访客 SSID 必须处于专用的 VLAN 上，与您的企业网络和物联网网络隔离。UniFi 使这变得非常简单 - 在 Settings、Networks 中创建一个专用网络，为其分配一个 VLAN ID，然后将您的访客 SSID 与该网络关联。在访客网络上启用客户端隔离，以阻止访客之间的流量。 第二，控制器必须拥有有效的 FQDN 和可信的 SSL 证书。不要依赖 IP 地址。使用合适的域名，为其获取 Let's Encrypt 或商业证书，并配置 UniFi 使用该证书。这可以解决大部分 HTTPS 重定向问题。 第三，仔细构建您的围墙花园（Walled Garden）并进行测试。最少包含的条目有：您的 Purple Portal 域名及其 IP 范围、用于 iOS、Android 和 Windows 的 Captive Portal 检测域名，以及您正在使用的任何 OAuth 提供商域名。使用从未连接过该网络的设备进行测试 - 缓存的 DNS 和网络状态可能会在测试期间掩盖围墙花园配置的漏洞。 第四，对于 API 集成，在 UniFi Network Application 中使用具有最小所需权限的专用本地管理员账户。不要使用您的主管理员凭据。如果您使用的是 Network Application 9.1 或更高版本，请使用 Control Plane、Integrations 下的新 API 密钥机制 - 它更安全且不需要基于凭据的认证。 第五，请仔细考虑会话时长。UniFi 的默认访客会话有效期可能短至八小时。对于访客可能会入住多晚的酒店部署，请在 Purple 门户设置中配置合适的会话时长，并确保这些时长在 API 授权调用中正确传递。 我见过的最常见陷阱是部署在无法公开访问的自托管控制器上。如果 Purple 无法连接到您的控制器来授权访客，门户可以加载，但身份验证将静默失败。在正式上线前，务必验证来自 Purple 基础设施的 API 连接性。 [快速问答 - 约 1 分钟] 这适用于 UniFi Dream Machine Pro 吗？是的。所有 UniFi OS 控制台（UDM、UDM Pro、UDM SE、UCG Ultra、UCG-Max）都支持 External Portal Server 配置。网络应用程序在设备上运行。 我可以在单个 Purple 账户中对多个 UniFi 站点使用 Purple 吗？是的。Purple 的多站点架构正是为此而设计的。每个场所都在 Purple 中配置为一个独立的站点，并映射到相应的 UniFi 站点。 我需要在 UniFi 网关上打开防火墙端口吗？您需要确保访客 VLAN 流量可以通过 443 端口到达 Purple 门户域名。控制器 API 端口也需要能够从 Purple 的服务器进行访问。Purple 的文档提供了特定的 IP 范围。 WPA3 呢？UniFi 支持 WPA3 Personal 和 WPA3 Enterprise。Captive Portal 机制在访客网络上可与 WPA3 Personal 配合工作。WPA3 Enterprise 使用 802.1X 和 RADIUS，这是不同的身份验证流程。 [总结与后续步骤 - 约 1 分钟] 总结一下：将 Purple 作为外部 Captive Portal 部署在 UniFi 上是一个支持良好、架构合理的集成。关键步骤是：配置您的访客 SSID，将其中的 External Portal Server 选项指向您的 Purple 门户 URL，构建一个涵盖 Purple 基础设施和您正在使用的任何 OAuth 提供商的完整围墙花园，确保您的 UniFi 控制器拥有有效的 SSL 证书且可从 Purple 的 API 服务器访问，并根据您的场所类型配置适当的会话时长。 商业价值显而易见。内置的 UniFi 门户仅为您提供一个欢迎页面。而 Purple 则为您提供一个符合合规要求、数据分析驱动的访客体验平台，它能与您的 CRM 集成，在符合 GDPR 同意的情况下获取第一方数据，并提供场所运营商和营销团队实际所需的人流量和停留时间分析。 如果您是进行大规模 UniFi 部署的 MSP 或系统集成商，Purple 的多站点管理和白标功能使其成为最适合您客户的叠加方案。 有关详细的配置文档、围墙花园 IP 列表和 API 集成指南，请访问 purple.ai。感谢您的收听。