Ubiquiti UniFi captive portal故障排除：外部门户、热点与walled garden检查清单

UniFi Captive Portal 故障通常由以下五个原因之一引起：外部门户服务器地址错误；预授权访问中缺失门户和登录域名；访客隔离阻挡了门户主机；重定向使用了指向 IP 地址的 HTTP 协议；或者控制台无法访问。请依次排查每一项，然后使用客户端进行测试。

无法正常工作的 UniFi Captive Portal 表现为什么样？

大多数故障会表现为以下四种症状之一。在打开 UniFi Network 应用程序之前，先确定症状可以缩小排查范围。

• 完全没有门户。 设备加入了访客 SSID 并获取了 IP 地址，但没有弹出登录提示。手机可能会报告“无互联网连接”或显示已连接但无流量。
• 页面空白或无限加载。 Captive Network Assistant (CNA) 已打开，但 Splash 页面始终无法渲染。CNA 是您的操作系统在 Captive Portal 网络上启动的微型浏览器。
• 证书警告。 在加载登录页面之前，笔记本电脑显示“您的连接不是私密连接”。访客必须点击忽略警告才能继续。
• 门户显示不完整。 Splash 页面可以加载，但社交登录或支付按钮一直旋转、失败或陷入循环。

Purple 的 Captive Portal 支持文章 更详细地解释了 CNA。CNA 会检查一个预定义的域名以测试互联网是否可达。然后它会通知设备、启动浏览器并确认“在线”状态。当该链路的任何部分中断时，您的访客就会看到上述症状之一。

本指南假设您的 UniFi 热点门户或外部门户已经配置完毕。这是一个故障排查清单，而非安装指南。

通常是什么原因导致 UniFi Captive Portal 发生故障？

以下六个原因涵盖了绝大多数 UniFi 访客门户故障排查案例。

1. 外部门户服务器设置错误。 地址指向了旧的主机、存在拼写错误，或者网关无法访问该服务器。
2. 预授权访问设置不完整。 UniFi 将此设置标记为 "Pre-Authorization Access"。这是 UniFi 的围墙花园：访客在登录前可以访问的主机和子网。如果缺失了门户、其资源或社交登录提供商，页面就会保持空白或显示不全。
3. 访客网络限制。 UniFi 访客网络会阻断私有地址范围。这会导致内部子网上的门户服务器或 DNS 服务器变得无法访问。
4. HTTPS 与主机名重定向不匹配。 针对 IP 地址的 HTTPS 重定向，或针对没有匹配证书的主机名的重定向，都会触发浏览器警告。
5. 控制器或控制台的可达性。 自托管的 UniFi Network Server 和云控制台必须保持可访问。使用外部门户时，控制器还必须能够访问完成登录所需的 RADIUS 服务器。
6. 客户端干扰。 VPN、自定义 DNS 设置或被忽略的 CNA 通知都会阻止该设备上的重定向。

如何确定您遇到了哪种 UniFi Captive Portal 故障？

首先确定故障现象，然后按照表格运行第一步检查，不要在检查前更改任何设置。

故障现象	最可能的原因	第一步检查	解决方法
没有弹出 Portal 页面，没有提示	DNS 无法解析或 CNA 探测被拦截	客户端在登录前能否解析公网主机名？	分配一个不在拦截的私有 IP 范围内的 DNS 服务器，或在预授权访问中允许该 DNS
页面空白或加载无限循环	预授权访问中缺失 Portal 主机或资源	Portal 主机名能否在访客设备上解析并加载？	将 Portal 主机、其资源域名及子网添加到预授权访问中
笔记本电脑出现证书警告	HTTPS 重定向到 IP 地址或主机名不匹配	警告出现时，地址栏中显示什么 URL？	禁用 HTTPS 重定向，或使用与该主机名匹配且受公认信任的证书按主机名进行重定向
社交媒体登录按钮一直旋转或失败	身份验证提供商的域名缺失	浏览器网络视图中哪个域名加载失败？	添加该提供商登录页面加载的所有域名
支付步骤失败	支付网关域名缺失	支付页面是否能加载？	将支付提供商的主机添加到预授权访问中
Portal 页面已加载，但登录永远无法完成	RADIUS 或控制器无法访问	控制器事件中是否出现了身份验证尝试？	恢复控制器可访问性，并确认 RADIUS 详细信息与您的 Portal 提供商匹配
单个设备失败，其他设备正常	客户端 VPN、自定义 DNS 或已关闭 CNA	该设备上访问 neverssl.com 会重定向吗？	禁用 VPN 或自定义 DNS，忽略该 WiFi 网络并重新加入

两个快速测试可以区分大部分故障。首先，在已连接但未经过身份验证的设备上浏览 neverssl.com。Purple 的支持团队推荐此网站，因为它避免了 SSL 重定向的问题。如果 neverssl.com 重定向到您的 Portal 页面，说明重定向工作正常，故障出在预授权访问或 Portal 本身。如果它没有重定向，请检查 DNS、外部 Portal 服务器设置或控制器。

第二，检查 UniFi Network 应用程序中的客户端条目。客户端列表和事件会显示该设备是否在访客网络上，以及它是否已授权。被标记为已授权但仍显示 Portal 的设备通常指向客户端缓存或 CNA 问题。

如何解决每个 UniFi Captive Portal 原因？

Purple 在此不列出 UniFi 的具体菜单路径，因为它们在不同的 UniFi Network 版本之间会发生变化。请使用 Ubiquiti 的最新文档来查找每个设置的准确位置。

外部 Portal 服务器

确认外部 Portal 服务器的值与您的 Portal 提供商指定的值匹配。一个字符的错误就会将所有访客发送到失效的主机。如果您更换了 Portal 提供商，请删除旧地址，而不要将其与新地址留在在一起。 当您使用 Purple 时，微页面（splash page）服务器会收集访客详细信息并分发一次性登录凭据。控制器将该登录凭据传递给 Purple 的 RADIUS 服务器以完成身份验证。RADIUS 是网络设备用于向中央服务器验证凭据的协议。如果门户页面可以加载但登录失败，请下一步检查 RADIUS 配置。

门户、社交登录和支付域名的预授权访问

这是最常见的解决方法。将以下条目添加到预授权访问中：

• 门户服务器主机及其所在的任何子网。
• 微页面加载的每一个域名，包括来自内容分发网络（CDN）的字体、图像和脚本。
• 每个社交登录提供商的身份验证域名，如果您提供 Facebook、Google 或 Apple 登录。
• 您的支付网关主机，如果您对高级访问收费。

在不受限制的网络上使用笔记本电脑打开微页面，并通过浏览器的开发者工具查看网络请求。其中列出的每个域名在登录前都必须是可达的。如果您的 UniFi Network 版本仅接受 IP 条目，请在提供商更改其地址时随时重新检查这些条目。

访客网络隔离和受阻子网

访客隔离本身并不会阻拦 Captive Portal。客户端设备隔离只是阻止访客设备之间互相通信。访客网络的子网限制会阻止私有地址范围，而这些限制会拦截内部门户或 DNS 服务器。

如果您的门户服务器或 DNS 解析器位于内部子网中，请将该特定主机添加到预授权访问中。更规范的做法是向访客分配公共 DNS 解析器，并在公共地址上托管门户。

HTTPS 和主机名重定向选项

现代浏览器要求登录页面使用 HTTPS。Purple 的 Cisco WLC 证书文章 描述了 Cisco 硬件上的相同模式。重定向到裸 IP 等 HTTP 地址会触发安全警告，访客必须点击确认才能继续。

在 UniFi 上的解决方法遵循相同的原理。要么关闭 HTTPS 重定向并允许 CNA 使用 HTTP，要么按主机名重定向。主机名重定向需要受公共信任的 SSL/TLS 证书，且主机名必须与证书的通用名称（Common Name）匹配。自签名证书或不匹配的名称会直接再次触发警告。

自托管和云端控制台的控制器可达性

对于自托管的 UniFi Network 服务器，请确认该服务器正在运行，并且可从您的网关和接入点访问。如果服务器位于总部或数据中心，请检查分支机构之间的防火墙规则。对于云端控制台，请确认控制台显示在线且网关已被采用（adopted）。然后确认允许向您的 RADIUS 服务器发送出站流量。

客户端检查

要求访客忽略该网络并重新加入。禁用任何可能完全绕过重定向的 VPN 或自定义 DNS 设置。如果错过了 CNA 通知，请打开浏览器并访问 neverssl.com。在 Android 设备上，点击“您可能需要登录”通知将启动 CNA 浏览器会话。

来自酒店、零售和活动行业的成功案例

这些实际案例展示了该检查清单在场馆层面的应用效果。

一家拥有 200 间客房且展示空白展示页面的酒店

**情况：**一家 酒店 运行了自托管的 UniFi 网络服务器和外部门户。在一次网络变更后，连接访客 SSID 的访客看到了空白页面。前台每晚记录约十几次投诉。

**处理过程：**neverssl.com 未能重定向，因此团队首先检查了 DNS。访客 VLAN 的 DHCP 作用域正在分发私有子网上的内部 DNS 服务器。而访客限制阻止了该子网。团队将访客作用域切换为公共解析器。

**结果：**在下一次连接时，门户重定向正常工作。前台当周未再记录任何 WiFi 投诉。

一家社交登录陷入停滞的 40 店零售连锁企业

**情况：**一家 零售 连锁企业在其展示页面中添加了社交媒体登录功能。邮箱表单可以正常工作，但每家门店的社交登录按钮都会无限期转圈。

**处理过程：**团队使用开发者工具打开了展示页面，并列出了该提供商登录时加载的所有域名。他们在一间试点门店中将这些域名添加到预授权访问中，并在 Android 和 iOS 上进行了测试，然后将此更改推广到了所有 40 家门店。

**结果：**所有 40 家门店的社交登录均顺利完成。该团队现在会在每次提供商更新后重新测试试点门店。

一家出现证书警告的会议中心

**情况：**使用笔记本电脑的参会代表在进入门户之前看到了“您的连接不是私密连接”的提示。手机通过 CNA 可以正常工作，因此该故障看起来是断断续续的。

**处理过程：**地址栏显示了指向 IP 地址的 HTTPS 重定向。团队禁用了 HTTPS 重定向，直到配置了与重定向主机名匹配的受信任公开证书。

**结果：**笔记本电脑上的警告消失了。在会议余下的时间里，活动服务台没有再收到任何关于门户的工单。

如何防止 UniFi Captive Portal 再次失效？

• 保留预授权登记册。 列出每个主机和子网、存在的原因以及所有权归属。在添加登录方式或支付提供商时进行审查。
• 每次变更后进行测试。 使用一部 Android 手机、一部 iPhone 和一台笔记本电脑进行测试。确认 neverssl.com 可以重定向且登录能够顺利完成。
• 跟踪证书过期情况。 主机名重定向上的证书过期会产生与无证书相同的警告。
• 监控控制器。 在访客发现之前，对自托管服务器离线进行告警。
• 运行开放的访客网络。 Purple 推荐使用开放的访客网络，因为熟悉度可以减少登录时的摩擦。同样的原则也适用于其他厂商。Purple 的 HPE Aruba captive portal 故障排除指南 和 Cisco Meraki captive portal 故障排除指南 针对这些平台也遵循相同的检查清单。

常见问题解答

Purple 是否可以与我们现有的 Ubiquiti UniFi 接入点兼容？

是的，Purple 作为外部门户和 RADIUS 服务运行在 Ubiquiti UniFi 上，因此您可以保留现有的接入点。Purple 与硬件无关，还支持 Cisco Meraki、HPE Aruba、Ruckus、Juniper Mist、Cambium、Extreme 和 Fortinet。这对于拥有混合硬件的多场所物业至关重要，因为一个访客 WiFi 配置即可覆盖所有厂商。根据 Purple 的自身数据，Purple 的平台已在 80,000 多个活跃场所运行。

我们可以将自托管的 UniFi 网络服务器与外部门户结合使用吗？

是的，自托管的 UniFi 网络服务器可以与外部门户结合使用，前提是它保持可达。网关和接入点必须能够连接到服务器，且服务器必须能够连接到您的门户提供商的 RADIUS 服务。如果服务器位于总部，请检查各场所之间的防火墙规则。云控制台免去了托管任务，但仍需要向外的 RADIUS 访问权限。

我们的 UniFi 访客网络应该是开放的还是有密码保护的？

对于访客访问，建议选择开放网络。Purple 建议通过开放网络提供访客 WiFi，因为这已成为行业标准惯例，并且可以减少登录时的阻碍。Captive Portal 仍然控制着访问权限，收集用户的知情同意，并为每位访客发放一次性登录凭证。受密码保护的访客网络会增加步骤，并导致前台收到更多咨询。

我们需要为我们的 captive portal 购买 SSL 证书吗？

是的，如果您通过 HTTPS 或主机名重定向访客。浏览器需要公共受信任的证书，且重定向主机名必须与证书的通用名称（Common Name）相匹配。如果没有证书，笔记本电脑将在门户加载前显示安全警告。如果您无法维护证书，请关闭 HTTPS 重定向，让设备的 CNA 改用 HTTP 重定向。

迁移到 Purple 对我们的 GDPR 合规地位有何影响？

Purple 能够帮助您满足 GDPR 要求，而不是增加风险。Purple 拥有 ISO 27001、GDPR、CCPA 和 Cyber Essentials 认证，且欢迎页面会记录营销同意的知情选择。您收集的第一方数据将与每位访客给予的同意保持一致。您自己的隐私声明和保留政策仍然适用，因此请在上线前对两者进行审查。

从内置的 UniFi 热点迁移到 Purple 需要花费多少精力？

迁移至 Purple 是一项配置更改，而非硬件工程。您只需将外部门户服务器和 RADIUS 设置指向 Purple，然后更新 Splash 页面域名的预授权访问。Purple 覆盖在您现有的 UniFi 基础设施之上，因此无需推倒重来。先测试一个站点，然后在您的整个业务中复制这些设置。

Purple 能否处理高流量场馆的访客登录？

是的，根据 Purple 自身的数据，Purple 在 2024 年处理了 4.4 亿次登录。该业务量覆盖了高峰流量极大的 酒店、零售、火车 和 医疗保健 站点。在 UniFi 上，门户的容量极少成为瓶颈。DNS 可达性和完整的预授权访问更为重要，因此在大规模活动之前请务必应用此检查清单。