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

Captive Portal for Ubiquiti UniFi — A Purple Technical Briefing [INTRODUCTION & CONTEXT — approximately 1 minute] 欢迎收看 Purple 技术简报系列。我是主持。今天我们将深入探讨在 Ubiquiti UniFi 基础设施上部署外部 Captive Portal 的具体细节。Ubiquiti UniFi 是全球酒店业、零售业和企业环境中部署最广泛的网络平台之一。 如果您是处理 UniFi Cloud Gateways、Dream Machines 或 UniFi Network Application 的 IT 经理、网络架构师或系统集成商，那么本期节目非常适合您。我们将详细剖析外部门户机制背后的运行原理、如何正确配置它、常见的误区在哪里，以及为什么对于需要更高级展示页面（Splash Page）的场所来说，在 UniFi 部署之上叠加 Purple 才是正确的架构决策。 让我们开始吧。 [TECHNICAL DEEP-DIVE — approximately 5 minutes] 首先，我们来了解一下当访客设备连接到启用了 Captive Portal 的 UniFi SSID 时，实际上发生了什么。 当访客设备与您的访客 SSID 关联时，UniFi 接入点（AP）会照常通过 DHCP 为其分配 IP 地址。但该设备会立即被置于 UniFi 所称的“待处理（pending）”状态。在这种状态下，AP 内置的 DNSmasq 进程会拦截该设备发出的每个 DNS 查询，无论该设备以为自己使用的是什么 DNS 服务器。AP 会将所有 DNS 流量重定向到自身。 同时，AP 会在 80 端口上运行一个轻量级的 HTTP 重定向器。一旦访客的浏览器发出任何 HTTP 请求 - 请注意，是 HTTP，而不是 HTTPS - 重定向器就会立即触发并返回 302 重定向，将浏览器发送到 Captive Portal 展示页面。这就是在 iOS 和 Android 设备上触发“登录 WiFi”通知的机制。 现在，内置门户与外部门户之间的区别就变得至关重要了。使用内置的 UniFi Hotspot Portal，展示页面直接由 UniFi Network Application 提供。它功能尚可，设置也很快，但局限性很大。您只能获得基本的密码认证、凭证（vouchers）和 Stripe 支付。没有电子邮件捕获、没有社交媒体登录、没有符合 GDPR 的同意管理、没有 CRM 集成，也没有除会话计数之外任何有价值的数据分析。 当您配置“外部门户服务器（External Portal Server）”时 - 这正是我们今天关注的设置 - 您是在指示 UniFi 控制器将访客重定向到一个完全独立的 Web 应用程序。在我们的场景中，那就是 Purple。您在“外部门户服务器”字段中输入的 URL 就会成为所有这些 302 重定向的目的地。 这里是关于该重定向 URL 的重要技术细节。当 UniFi 将访客重定向到您的外部门户时，它会在 URL 中附加多个查询参数。这些参数包括：AP MAC 地址、客户端设备 MAC 地址、Unix 时间戳、客户端原本尝试访问的原始 URL 以及 SSID 名称。在这一场景下，您的外部门户（即 Purple）会捕获这些参数，利用它们识别连接设备，显示相应的 splash page，处理身份验证，然后通过 API 回调 UniFi Network Application 以授权该 MAC 地址。 该 API 调用是至关重要的握手。在 UniFi Network Application 9.1 及更高版本中，提供了一个带有规范密钥身份验证的官方 REST API。授权端点是对 sites API 第一版发起的一个 POST 请求，针对特定的客户端 ID，其 JSON 主体可以指定以分钟为单位的时间限制、以兆字节（MB）为单位的数据流量限制以及以千字节每秒（kbps）为单位的速率限制。一旦控制器收到该授权，它就会将指令下发给 AP，访客的状态就会从“待处理”变为“已授权”。互联网访问权限随即开通。 现在我们来谈谈 Walled Garden（围墙花园），UniFi 将其称为“预授权访问”。这是访客在通过身份验证之前可以访问的域名和 IP 地址白名单。它至关重要，也是最容易配置错误的环节之一。 您的 walled garden 至少需要包含 Purple 门户的完全限定域名（FQDN），以及 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 门户可以通过带有有效、受信任 SSL 证书的 HTTPS 进行访问。自签名证书会导致浏览器安全警告，从而阻止门户加载。对于生产部署而言，这是不容妥协的要求。 另一个针对 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 方法。您可以在“设置”、“网络”、“RADIUS 服务器”下配置 RADIUS 配置文件，然后在您的 SSID 配置中引用该配置文件。从 8.4 版本开始，UniFi 还支持基于 TLS 的 RADIUS（即 RADSEC），这会加密 AP 与身份验证服务器之间的 RADIUS 流量。对于 RADIUS 流量需要跨越公共互联网的多站点部署，强烈建议使用 RADSEC。 [实施建议与常见陷阱 - 约 2 分钟] 让我为您提供在 UniFi 上部署 Purple 时我会与任何客户共同检查的实际实施清单。 第一，网络分段。您的访客 SSID 必须位于专用 VLAN 上，与您的企业和物联网网络隔离。UniFi 使这变得非常简单 - 在“设置”、“网络”中创建一个专用网络，为其分配一个 VLAN ID，然后将您的访客 SSID 与该网络关联。在访客网络上启用客户端隔离，以防止访客之间的流量互通。 第二，控制器必须具有有效的 FQDN 和受信任的 SSL 证书。不要依赖 IP 地址。使用合规的域名，为其获取 Let's Encrypt 或商业证书，并配置 UniFi 使用该证书。这可以解决绝大多数 HTTPS 重定向问题。 第三，仔细构建您的围墙花园并进行测试。最少条目包括：您的 Purple 门户域名及其 IP 范围、用于 iOS、Android 和 Windows 的 Captive Portal 检测域名，以及您正在使用的任何 OAuth 提供商域名。使用从未连接过该网络的设备进行测试 - 缓存的 DNS 和网络状态可能会在测试期间掩盖围墙花园的漏洞。 第四，对于 API 集成，请在 UniFi Network Application 中使用具有最小所需权限的专用本地管理员帐户。不要使用您的主管理员凭据。如果您使用的是 Network Application 9.1 或更高版本，请使用“控制平面”、“集成”下的新 API 密钥机制 - 它更安全，且不需要基于凭据的身份验证。 第五，请仔细考虑会话时长。UniFi 默认的访客会话过期时间可能短至 8 小时。对于访客可能入住多晚的酒店部署，请在 Purple 门户设置中配置合适的会话时长，并确保在 API 授权调用中正确传递这些时长。 我见过的最常见问题是在无法公开访问的自托管控制器上进行部署。如果 Purple 无法连接到您的控制器来授权访客，门户页面虽然能加载，但身份验证会默默失败。在上线前，请务必从 Purple 的基础设施验证 API 连接性。 [快速问答 — 约 1 分钟] 这适用于 UniFi Dream Machine Pro 吗？是的。所有 UniFi OS 控制台（UDM、UDM Pro、UDM SE、UCG Ultra、UCG-Max）都支持 External Portal Server 配置。Network Application 在设备上运行。 我可以在一个 Purple 帐户下将 Purple 用于多个 UniFi 站点吗？是的。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 分钟] 总结一下：在 UniFi 上将 Purple 部署为外部 Captive Portal 是一种受良好支持、架构合理的集成方案。关键步骤包括：将您的访客 SSID 配置为 External Portal Server 选项，并指向您的 Purple 门户 URL；构建一个涵盖 Purple 基础设施及您所使用的任何 OAuth 提供商的完整围墙花园 (walled garden)；确保您的 UniFi 控制器拥有有效的 SSL 证书且可从 Purple 的 API 服务器访问；并根据您的场所类型配置合适的会话时长。 商业价值显而易见。内置的 UniFi 门户只为您提供一个欢迎页面。而 Purple 则为您提供一个符合合规要求、数据分析驱动的访客体验平台，该平台可与您的 CRM 集成，在满足 GDPR 同意的前提下获取第一手数据，并提供场所运营商和营销团队实际需要的客流量和停留时间分析。 如果您是部署大规模 UniFi 的 MSP 或系统集成商，Purple 的多站点管理和白标能力使其成为您客户的理想叠加方案。 有关详细的配置文档、围墙花园 IP 列表和 API 集成指南，请访问 purple.ai。感谢您的收听。