OpenWrt 自定义固件与 Purple WiFi 的集成

执行摘要

OpenWrt 是需要硬件独立性且不牺牲企业级控制力的 IT 团队的首选固件。它部署于酒店、零售和公共场所，提供完全可配置的基于 Linux 的网络协议栈。但开箱即用的 OpenWrt 就像一张白纸。如果没有结构化的身份层，访客网络将变得无法管理，员工网络依然不安全，多租户环境则会退化为单一的扁平网络。

本指南提供了将 OpenWrt 连接到 Purple 云端 RADIUS 和 Captive Portal 平台的终极集成手册。我们涵盖了四种不同的部署场景：使用 CoovaChilli 的访客 Captive Portal 重定向、iptables 围墙花园（walled garden）配置、使用 hostapd 与 IEEE 802.1X 的安全员工 WiFi，以及使用个人预共享密钥（PPSK）和动态 VLAN 分配的多租户隔离。阅读完成后，您将获得在任何支持 OpenWrt 的硬件上部署生产就绪、符合 GDPR 规范、身份驱动型网络所需的精确配置参数、常见故障模式和决策框架。

Purple 业务遍及 80,000 多个活跃场所，并在 2024 年处理了 4.4 亿次登录（Purple 内部数据，2024 年）。此处描述的架构与在酒店连锁、零售物业和交通枢纽中大规模部署的架构完全相同。

技术深挖

CoovaChilli Captive Portal 架构

在 OpenWrt 上部署 访客 WiFi 时，CoovaChilli 是行业标准的接入控制器。它作为一个 Captive Portal 守护进程运行，拦截未授权的客户端流量，通过其在 tun0 虚拟接口上的内部 DHCP 服务器分配 IP 地址，并使用其直接管理的 iptables 规则来执行围墙花园策略。

认证流程如下。访客设备关联到开放的 SSID。CoovaChilli 从其内部地址池（通常为 10.1.0.0/24）为设备分配一个 IP 地址。当设备发送其第一个 HTTP 请求时，CoovaChilli 会拦截该请求并向 Purple 欢迎页面（splash page）URL 发出 HTTP 302 重定向。在预认证阶段，该设备是隔离的——它只能访问围墙花园中明确列出的域名。 一旦访客在 Purple 门户上完成认证，Purple 的云端 RADIUS 服务器就会向 UDP 端口 1812 上的 CoovaChilli 发送一个 Access-Accept 消息。随后，CoovaChilli 会更新其 iptables 规则，以允许该特定 MAC 地址访问互联网，并开始将计费数据（会话时长、已传输字节数）传输到 UDP 端口 1813 上的 Purple RADIUS 计费服务器。计费不是可选的——它是 Purple 用于将会话数据填充到您的 WiFi Analytics 仪表板的机制。

围墙花园：iptables 和域名白名单

在任何 Captive Portal 部署中，围墙花园都是运营上最关键的配置元素。CoovaChilli 通过两种机制管理围墙花园：针对单个 IP 地址的 uamallowed 参数，以及用于进行 DNS 检查的基于域名的白名单的 uamdomains 参数。

对于 Purple 集成，最少所需的围墙花园条目为：

关于 Apple CNA 管理的说明： 如果您在围墙花园中包含 captive.apple.com，iOS 设备将在认证前检测到互联网连接，并抑制 Captive Network Assistant 弹窗。大多数酒店部署都会特意排除此域名，以触发自动门户提示。正确的选择取决于您的访客体验设计。

安全的员工 WiFi：hostapd 和 IEEE 802.1X

访客网络需要无摩擦的接入体验。员工网络则需要绝对的安全。对于内部用户，OpenWrt 使用 hostapd 来促进 IEEE 802.1X 认证。在这种架构中，OpenWrt 接入点充当认证者（Authenticator），在客户端设备（客户端 Supplicant）和 Purple RADIUS 服务器之间转发可扩展身份验证协议（EAP）消息。

对于企业设备，EAP-TLS 是强制性标准。它依赖于双向证书认证——服务器和客户端设备都出示数字证书——完全消除了密码以及相关的凭据窃取或钓鱼风险。对于尚未准备好部署完整公钥基础设施（PKI）的环境，PEAP-MSCHAPv2 提供了一个合理的过渡选项，使用加密隧道来保护用户名和密码凭据。

当员工成功通过身份验证时，RADIUS 服务器会返回授权属性。网络分段的关键属性是 Tunnel-Private-Group-ID，它指示 OpenWrt 动态地将用户分配到正确的 VLAN。这就是基于身份的网络（Identity-Based Networks）背后的机制：决定用户网络访问权限的是用户的身份，而不是其物理位置。

多租户分段：OpenWrt PPSK 配置

在多租户环境中（如联合办公空间、建设出租（BTR）物业、拥有多个商户的零售中心或设有独立赞助商区域的体育场），广播多个 SSID 的运营成本高昂且射频效率低下。每增加一个 SSID 都会增加管理帧开销，从而减少数据流量的可用空口时间。

私有预共享密钥（PPSK，有时也称为动态 PSK）解决了这个问题。您只需广播单个 SSID。当设备尝试连接时，hostapd 会通过标准的 Access-Request 将设备的 MAC 地址发送到 RADIUS 服务器。RADIUS 服务器根据其数据库验证 MAC 地址，并返回包含两个关键属性的 Access-Accept：Tunnel-Password 属性（该设备的唯一密码）和 Tunnel-Private-Group-ID 属性（VLAN 分配）。设备使用其唯一的密码进行连接，并直接置于其分配的 VLAN 中。

这意味着零售经理和活动参与者可以连接到完全相同的 SSID，但根据其独特的身份被路由到完全独立、隔离的网络。

实施指南

第 1 步：获取 Purple RADIUS 凭据

在修改 OpenWrt 配置之前，请从 Purple 门户管理控制台获取以下信息：

• 主 RADIUS 服务器 IP 地址
• 备 RADIUS 服务器 IP 地址（用于故障转移）
• RADIUS 共享密钥（Shared Secret）
• Captive Portal 登录页面 URL
• 验证后重定向 URL

第 2 步：安装并配置 CoovaChilli 以提供访客 WiFi

通过 opkg 安装 coova-chilli 软件包：

opkg update && opkg install coova-chilli

主配置文件为 /etc/chilli/defaults。定义核心网络参数：

# 核心网络接口
HS_WANIF=eth0           # 上行互联网接口
HS_LANIF=wlan0          # 访客 WiFi 接口（或 VLAN 子接口）

# 访客子网
HS_NETWORK=10.10.20.0
HS_NETMASK=255.255.255.0
HS_UAMLISTEN=10.10.20.1 # CoovaChilli 在访客网络上的 IP
HS_UAMPORT=3990

# Purple RADIUS 集成
HS_RADIUS=
HS_RADIUS2=
HS_RADSECRET=
HS_NASID=venue-openwrt-01

# Purple 登录页面
HS_UAMSERVER=

# 围墙花园（Walled garden） - 基于域名的白名单
HS_UAMDOMAINS=".purple.ai,.googleapis.com,.gstatic.com,.facebook.com,.fbcdn.net"

启用并启动服务：

/etc/init.d/chilli enable
/etc/init.d/chilli start

步骤 3：为访客 SSID 配置 OpenWrt 无线接口

在 /etc/config/wireless 中，将访客 SSID 定义为一个绑定到 CoovaChilli 将管理的接口的开放网络：

config wifi-iface 'guest_wifi'
    option device 'radio0'
    option network 'guest'
    option mode 'ap'
    option ssid 'Venue_Guest'
    option encryption 'none'
    option isolate '1'

客户端隔离（isolate '1'）可防止访客设备之间相互通信 - 这是任何共享网络强制性的安全控制。

步骤 4：为 802.1X 员工 WiFi 配置 hostapd

对于员工 SSID，在 /etc/config/wireless 中配置 WPA2-Enterprise：

config wifi-iface 'staff_wifi'
    option device 'radio0'
    option network 'staff_vlan10'
    option mode 'ap'
    option ssid 'Venue_Staff'
    option encryption 'wpa2'
    option server ''
    option port '1812'
    option key ''
    option dynamic_vlan '2'
    option vlan_tagged_interface 'eth0'
    option vlan_bridge 'br-vlan'
    option vlan_naming '0'

设置 dynamic_vlan '2' 指示 hostapd 强制执行 RADIUS 服务器返回的 VLAN 分配，并在没有返回 VLAN 时拒绝身份验证。

软件包要求： 标准的 wpad-mini 软件包不支持 WPA2-Enterprise。您必须安装 wpad 或 wpad-openssl：

opkg remove wpad-mini && opkg install wpad-openssl

步骤 5：为多租户隔离配置 PPSK

PPSK 需要 hostapd 针对 RADIUS 服务器执行 MAC 地址身份验证，然后该服务器返回每个设备的密码。在 /etc/config/wireless 中：

config wifi-iface 'ppsk_ssid'
    option device 'radio0'
    option mode 'ap'
    option ssid 'Venue_Connect'
    option encryption 'psk2'
    option key 'default_fallback_key'
    option macfilter 'radius'
    option server ''
    option port '1812'
    option key ''
    option dynamic_vlan '2'
    option vlan_tagged_interface 'eth0'
    option wpa_psk_radius '2'

wpa_psk_radius '2' 参数指示 hostapd 要求来自 RADIUS 响应的 Tunnel-Password 属性。如果 RADIUS 服务器未返回密码，则身份验证将被拒绝。

在 Purple RADIUS 端，FreeRADIUS 配置（或等效配置）的 authorize 部分会将 MAC 地址映射到密码和 VLAN ID：

# PPSK 的 RADIUS 授权条目示例
AA:BB:CC:DD:EE:FF   Auth-Type := Accept
    Tunnel-Password = "GuestPass2024",
    Tunnel-Type = VLAN,
    Tunnel-Medium-Type = IEEE-802,
    Tunnel-Private-Group-ID = "20"

步骤 6：配置动态 VLAN 分配

要使动态 VLAN 分配正常工作，您的 OpenWrt 交换机必须配置为在连接到核心交换机的 Trunk 端口上将相关 VLAN 作为 Tagged 流量进行传输。在 /etc/config/network 中：

config interface 'vlan10'
    option ifname 'eth0.10'
    option proto 'dhcp'

config interface 'vlan20'
    option ifname 'eth0.20'
    option proto 'dhcp'

config interface 'vlan30'
    option ifname 'eth0.30'
    option proto 'dhcp'

确保您的核心交换机端口已配置为 Trunk，并允许 VLAN 10、20 和 30 以 Tagged 方式通过。

最佳实践

绝对的网络隔离。 切勿将访客接口与内部网络桥接。访客流量必须隔离在专用的 VLAN 上，并直接路由到互联网防火墙。这是满足 PCI DSS 4.0 合规性的硬性要求，该合规性强制要求访客 WiFi 网络必须与处理持卡人数据的任何网络段完全隔离。

精准配置围墙花园（Walled garden）。 围墙花园配置不完整是导致 Captive Portal 故障的主要原因。在连接到访客 SSID 的测试设备上使用浏览器的开发者工具，识别哪些请求在认证前被拦截。每一个被拦截的域名都是潜在的 Portal 故障点。

RADIUS 计费间隔。 将 CoovaChilli 的计费中期时间间隔（interim interval）配置为 120 秒。这可以在不产生过多元数据流量的情况下，在 Purple 分析仪表板中提供近乎实时的会话数据。

备用 RADIUS 服务器。 务必在 CoovaChilli 配置中配置 HS_RADIUS2。如果主要的 Purple RADIUS 服务器无法访问，CoovaChilli 将无法对新会话进行身份验证。备用服务器可提供自动故障转移，且无需在接入点进行任何配置更改。

软件包选择。 许多 OpenWrt 构建版本中自带的 wpad-mini 软件包不支持 WPA2-Enterprise 或动态 VLAN 分配。对于任何需要 802.1X 或 PPSK 的部署，请务必安装 wpad-openssl。

有关企业级 WiFi 安全架构的更多指导，请参阅我们的 Enterprise WiFi Security: A Complete Guide for 2026 。

问题排查与风险缓解

GDPR 合规性说明： CoovaChilli 本身不捕获或存储个人数据。所有同意捕获、数据处理和 GDPR 合规机制均由 Purple 平台在门户层处理。在上线前，请确保您的 Purple 门户已配置您场所的服务条款和数据处理通知。

有关相关硬件集成模式，请参阅我们的指南： EnGenius Cloud 接入点与 Purple WiFi 集成 和 DrayTek Vigor 路由器和接入点与 Purple WiFi 集成 。

投资回报率 (ROI) 与业务影响

从基础 PSK 网络过渡到由 Purple 管理的 OpenWrt 架构，可在三个维度上带来可衡量的影响。

数据捕获与营销。 通过强制执行 Captive Portal 认证，场所可在连接 WiFi 的那一刻捕获合规的第一方人口统计数据（姓名、电子邮件地址、社交媒体资料）。这些数据可直接接入 CRM 和电子邮件营销平台，从而推动忠诚度计划的注册并实现精准营销。Purple 在 2024 年处理了 4.4 亿次登录（Purple 内部数据），这展示了在网络边缘进行第一方数据捕获的巨大规模。

运营效率。 实施 PPSK 可减少 SSID 开销，从而提高密集环境中的 WiFi 性能。对于拥有 200 个分店的零售连锁店，通过 Purple 的云 RADIUS 进行集中身份管理，而不是在每个站点更新本地路由器配置，每年可节省数百个工程小时。单个 RADIUS 策略的更改会立即传播到所有 200 个位置。

安全与合规。 动态 VLAN 分配在边缘强制执行最小特权访问。员工与访客隔离。IoT 设备与员工隔离。POS 终端与所有其他流量隔离。这种隔离满足了 PCI DSS 4.0 网络隔离要求，并为 GDPR 合规性审查提供了清晰、可审计的网络拓扑结构。

有关特定垂直行业的部署模式，请参阅我们针对 零售 、 酒店 、 医疗保健 以及 交通 环境的指南。您可能还会发现我们的指南 什么是无线显示：协议与 2026 年最佳实践 对于了解场所部署中互补的无线技术非常有用。