Ruckus Captive Portal 故障排除：WISPr 重定向、热点和 Walled Garden 检查清单

大多数 Ruckus Captive Portal 故障可追溯到五个方面：热点 (WISPr) 登录 URL 和起始页、Portal 及其资源缺失的 Walled Garden 条目、北向接口密码不匹配、RADIUS 身份验证或计费失败，以及 HTTPS 重定向证书警告。请按照该顺序，使用 SmartZone、Ruckus One 或 Unleashed 上的客户端事件历史记录进行检查。

故障的 Ruckus Captive Portal 是什么样子的？

Ruckus 热点服务使用 WISPr（无线因特网服务提供商漫游）。这是一种控制器将未通过身份验证的访客拦截在 Captive Portal 后，直至外部系统批准其访问的框架。Captive Portal 是访客在连接到互联网之前完成填写的 Splash 页面。当该链路断开时，访客会看到以下六种症状之一：

• 完全没有重定向。 设备加入 SSID 并获取 IP 地址，但未出现登录提示，且浏览器超时。
• 空白或只加载了一半的 Splash 页面。 提示已打开，但徽标、字体、脚本或社交登录按钮无法加载。
• 在进入 Portal 前出现证书警告。 浏览器显示“您的连接不是私密连接”或类似信息，访客必须点击忽略方可继续。
• 登录循环。 访客填写完表单后又返回到 Splash 页面，但仍然处于离线状态。
• 没有提示，但无法上网。 设备报告已在线，因此 Captive Network Assistant 永远不会打开。
• 在线但无会话数据。 访客可以正常浏览网页，但登录和会话时长从未记录到您的报表中。

最后两种症状很容易被忽视，因为没有人会致电服务台。您通常是在稍后发现访客数据停止增长时才会注意到它们。

通常是什么原因导致 Ruckus Captive Portal 失败？

首先了解交互流程会有所帮助。Purple 的 Captive Portal 支持文章 对此进行了详细阐述。控制器管理 WiFi 与 Purple 的 Splash 页面服务器之间的交互。这些服务器收集访客信息并发出一次性登录凭证。然后，控制器将该登录凭证传递给 Purple 的 RADIUS 服务器以完成访问。RADIUS (远程用户拨号认证服务，RFC 2865) 是用于对会话进行身份验证的协议。RADIUS 计费 (RFC 2866) 则在随后报告该会话。

每个步骤都有其特定的失效模式。

热点服务重定向和起始页设置

热点服务中保存着外部登录 URL 和起始页。登录 URL 是未通过身份验证的访客被定向到的地方。起始页是他们登录后到达的地方。拼写错误、Portal 变更后未更新的过期 URL，或者 WLAN 绑定了错误的热点服务，都会导致重定向失败。而指向已拦截或已弃用 URL 的起始页，会让一次成功的登录看起来像是一次失败。

Walled Garden 遗漏

围墙花园（walled garden）是未经身份验证的访客在登录前可以访问的目的地列表。它必须包含 portal 主机名以及展示页面加载资源的所有主机。它还必须包含您提供的任何社交或单点登录身份验证提供商的域名。如果您添加了登录选项，请阅读 如何启用单点登录 并添加该提供商的域名。缺少一个资源主机就会导致页面加载不完整。

相反的错误也会导致问题。根据 Purple 的支持文章，设备通过检查预定义的域名来测试连接性。如果该探测域名位于围墙花园中，设备就会认为自己已在线。提示永远不会出现，访客就会处于无法上网的状态。

北向 portal 接口凭据

在 SmartZone 上，北向 portal 接口是外部 portal 通知控制器访客已登录的方式。portal 使用控制器上设置的密码向该接口进行身份验证。如果该密码仅在单侧更改，则 portal 无法授权任何人。访客填写完表单后会循环返回到展示页面。

RADIUS 身份验证和计费

控制器将一次性登录转发给 RADIUS。如果共享密钥不同、RADIUS 服务器不可达或请求来自服务器无法识别的地址，则身份验证将失败。计费失败则较为隐蔽。访客可以上网，但会话开始和结束记录永远不会送达。

HTTPS 重定向行为

现代浏览器期望通过 HTTPS 访问登录页面。Purple 的 Cisco WLC 证书文章 描述了对 Cisco 控制器的影响。向控制器地址的 HTTP 重定向会触发安全警告，访客必须点击跳过。这里的解决方法是使用一个其公用名（Common Name）与控制器的 Web 身份验证主机名相匹配的公共信任证书。当您在 Ruckus 控制器上启用 HTTPS 重定向时，也适用相同的原理。证书过期或名称不匹配会导致警告再次出现。

如何找出具体原因？

从症状开始分析，而不是从配置开始。下表将每种症状映射到其最可能的原因以及您应该首先检查的地方。

症状	最可能的原因	首先查看哪里	首次检查项目
无登录提示，浏览器超时	热点登录 URL 错误，或 WLAN 上的热点服务错误	热点 (WISPr) 服务和 WLAN 设置	在测试设备上打开 neverssl.com，看看其指向何处
展示页面加载，但没有图像或按钮	围墙花园中缺少资源或身份验证提供商主机	围墙花园列表	在笔记本电脑上加载 portal，并在浏览器开发者工具中列出所有被拦截的主机
设备显示已在线，无提示，无网络	连接探测域名在围墙花园中	围墙花园列表	移除宽泛的通配符条目并重新测试
门户页面弹出前出现证书警告	HTTPS 重定向缺少受信任且匹配的证书	控制器证书设置	对比证书名称和过期日期与重定向主机名
表单提交后，访客重新循环返回	北向门户接口密码不匹配	北向接口设置与门户集成	确认两端的密码相匹配
提交表单后登录被拒绝	RADIUS 共享密钥或源地址不匹配	RADIUS 认证服务和客户端事件	查找认证超时或拒绝信息
访客已在线，但无会话数据	RADIUS 计费配置错误或未挂载	WLAN 上的 RADIUS 计费服务	确认已启用计费并指向正确的服务器

在干净的设备上进行重现

在测试手机和测试笔记本电脑上忽略该 SSID，然后重新连接。如果未弹出提示，Purple 的支持文章建议访问 neverssl.com。该网站可以规避 SSL 重定向问题，从而能够显示重定向本身是否正常工作。

查看客户端事件

每个 Ruckus 平台都会保留客户端事件历史记录。在 SmartZone 上，请使用事件与告警日志以及客户端的连接历史记录。在 Ruckus One 上，打开客户端并查看其事件。在 Unleashed 上，检查客户端 MAC 地址的事件日志。重点查看三点：客户端是否已关联、是否已重定向、以及 RADIUS 是否接受或拒绝了它。这一顺序可以告诉您链条中的哪个环节出现了问题。

如何在 SmartZone、Ruckus One 和 Unleashed 上解决此问题？

这三个平台上的修复步骤遵循相同的顺序。由于菜单有所不同，请参考适用于您版本的 Ruckus 文档以及 Captive Portal 支持文章 以获取 Purple 的对应参数值。

SmartZone

确认 WLAN 使用了您预期的热点 (WISPr) 服务，且其登录 URL 与集成配置匹配。根据当前列表重新构建 Walled Garden (围墙花园)，而不是凭记忆配置。检查北向门户接口密码是否与门户中配置的密码一致。然后确认 RADIUS 认证和计费服务均指向正确的服务器且共享密钥正确。

Ruckus One

Ruckus One 在云端集中管理相同的 WISPr 元素。检查访客网络门户提供商的设置、Walled Garden (围墙花园) 和 RADIUS 服务。场馆级 (Venue-level) 的覆写设置需要特别注意，因为某个特定场馆的配置可能会与应用到其他所有地方的模板产生偏差。

Unleashed

Unleashed 在 AP (接入点) 上运行控制器功能，因此请检查该主 AP 上的热点服务。注意 Walled Garden (围墙花园) 和 RADIUS 设置，并确认热点服务已绑定到访客 WLAN。

排除相似的故障

有些投诉看起来像是门户故障，但实际并非如此。如果访客在接入点之间移动时被再次提示，请参阅 解决企业 WLAN 中的漫游问题。如果 5GHz 信道上的会话随机掉线，DFS 雷达事件诊断清单 是更好的起点。

在真实场馆中这是什么样的？

以下两个场景仅用于说明。它们展示的是方法，而非报告具体的命名部署。

场景 1：品牌形象重新设计后的拥有 200 间客房的酒店

情况。 营销团队重新发布了酒店的展示页面。第二天早上，前台报告称访客只看到一个带有单个表单字段的空白页面。

采取的措施。 工程师在笔记本电脑上加载了门户，并在浏览器的开发者工具中列出了被阻止的请求。新设计从一个未包含在 SmartZone 围墙花园（Walled Garden）中的主机拉取字体和图像。工程师添加了该主机，重新连接了一部测试手机和一台测试笔记本电脑，并确认两者都能渲染完整页面。

结果。 在第一次重新测试时，两台测试设备上都渲染出了完整的展示页面。该修复仅需添加一个围墙花园条目，客户端事件显示访客再次通过重定向和 RADIUS 接受。有关该行业访客体验的更多信息，请参阅适用于 酒店 的 Purple。

场景 2：控制器迁移后的拥有 40 家门店的零售连锁店

情况。 一家零售商将其门店迁移到了一个新的 SmartZone 集群。顾客仍可上网，但访客报告显示所有 40 家门店的新会话均为零。

采取的措施。 客户端事件显示 RADIUS 认证接受，但没有计费记录。新集群上的访客 WLAN 未启用计费服务。工程师启用了该服务并确认共享密钥匹配。

结果。 所有 40 家门店的会话记录重新出现。顾客未受到任何干扰，因为只有报告受到了影响。请参阅适用于 零售 的 Purple，了解这些会话数据如何转化为顾客洞察。

如何防止 Ruckus Captive Portal 故障再次发生？

大多数重复发生的故障源于变更，而非硬件失效。以下五个习惯可以预防这些故障：

1. 将围墙花园视为受控文件。 记录每一个条目、其所有者以及存在的原因。每当展示页面发生变化时，都要对其进行审查。
2. 同时轮换两端的密钥。 在单个变更窗口内同时更改北部门户接口密码和 RADIUS 共享密钥，绝不要仅更改单侧。
3. 跟踪证书过期。 在 HTTPS 重定向证书过期之前做好更新日程规划，并在之后重新检查名称是否匹配。
4. 在每次变更后进行测试。 在 iPhone、Android 手机、Windows 笔记本电脑和 macOS 笔记本电脑上运行相同的检查。不同的操作系统处理 Captive Network Assistant 的方式不同。
5. 每日监测会话数量。 WiFi 分析中突然归零通常指向计费问题，这能让您在任何访客投诉前发现异常。

如 Purple 的支持文章所建议，请保持访客网络开放。开放网络是标准惯例，熟悉的连接行为可以减少登录时的阻碍。对于在移动中连接的乘客，交通运营商也适用同样的检查步骤；请参阅面向 Trains 的 Purple 解决方案。

常见问题解答

Purple 是否支持 Ruckus SmartZone、Ruckus One 和 Unleashed？

是的，Purple 访客 WiFi 作为外部 Captive Portal 运行在 Ruckus 热点 (WISPr) 服务上。Purple 兼容各种硬件，还支持 Cisco Meraki、HPE Aruba、Juniper Mist、Ubiquiti UniFi、Cambium、Extreme 和 Fortinet。控制器负责处理重定向和 RADIUS，而 Purple 托管登录页面并对访客进行认证。配置参数和步骤可在 Purple 的 Captive Portal 支持文章中找到。

我们是否需要新的接入点才能在现有的 Ruckus 网络中添加 Purple？

不需要，Purple 作为云端叠加层运行在您现有的 Ruckus 接入点和控制器上。您只需在控制器上配置热点服务、围墙花园（walled garden）和 RADIUS 设置，然后将访客 WLAN 指向 Purple 即可。现场无需更换任何设备。大部分工作在于上线前在 iOS、Android、Windows 和 macOS 设备上测试重定向。

我们能否在不中断访客服务的情况下，从内置的 Ruckus 访客门户迁移到 Purple？

可以，只要您先在独立的测试 WLAN 上构建 Purple 配置。在现有在线访客网络旁设置热点服务、围墙花园和 RADIUS 服务，并在测试设备上验证完整的登录流程。确认无误后，在业务低谷期将新的热点服务应用到在线 WLAN 上。访客只会看到新的登录页面，而不会遇到网络中断。

Purple 如何处理通过 Ruckus Captive Portal 收集的访客数据？

Purple 通过登录页面上用户主动选择的同意项来收集第一方数据。Purple 已通过 ISO 27001 和 Cyber Essentials 认证，其运营符合 GDPR 和 CCPA。Ruckus 控制器不保存任何营销数据，它仅向 Purple 的 RADIUS 服务器传递一次性登录信息，因此访客信息会保留在 Purple 的认证平台内，而不会散落到各个网点控制器中。

使用 Purple 部署 Ruckus Captive Portal 需要多长时间？

由于不需要更改硬件，单个网点通常在一个工作时段内即可配置完毕。控制器需要配置热点服务、围墙花园以及 RADIUS 认证与计费。多网点的大型项目需要更长时间，但这主要是由于测试和变更控制，而非配置本身。在 Ruckus One 或 SmartZone 上，集中应用模板可确保每个场所的一致性，降低不同网点间配置出现偏差的风险。

Purple 的访客 WiFi 平台在何种应用规模下得到了验证？

根据 Purple 公司的自有数据显示，Purple 已在超过 80,000 个活跃场所运行，并在 2024 年记录了 4.4 亿次登录。这些场所涵盖酒店、零售、交通、教育和公共部门。Purple 自 2012 年起开始运营，无论底层网络由哪家受支持的硬件厂商运行，每一次部署都使用本指南中描述的相同引流页面和 RADIUS 流程。