Portal 认证配置与参数对接指南

本文档详细说明 YunyiRADIUS 与各厂商 NAS/BAS 设备对接时的 Portal 参数传递方式、字段映射关系、配置方法，以及 Portal 模板管理。

概述

Portal 认证流程中，NAS/BAS 设备将用户重定向到 Portal 服务器时，通过 URL 参数或 HTTP 请求体传递用户标识信息。不同厂商使用的参数名称和传递方式不同，YunyiRADIUS 已做好兼容层，只需在添加设备时选择正确的厂商类型即可。

支持的厂商及参数格式

华为 (Huawei) — Vendor 2011

Portal 1.0 重定向 URL

华为 AC 将用户重定向到 Portal 服务器时携带以下参数：

http://portal-server:1816/portal/login?
  wlanuserip=10.0.0.100           # 用户 IP 地址
  wlanacname=AC-01                 # AC 名称（对应 NAS-Identifier）
  wlanacip=192.168.1.1             # AC IP 地址
  wlanusermac=00-11-22-33-44-55   # 用户 MAC 地址
  wlanapmac=AA-BB-CC-DD-EE-FF     # AP MAC 地址
  wlanssid=Hotel-WiFi              # WiFi SSID
  wlanuserfirsturl=http://...      # 认证成功后跳转地址

Portal 2.0 (JSON)

json

{
  "username": "user001",
  "password": "password",
  "ip_addr": "10.0.0.100",
  "mac_addr": "00:11:22:33:44:55",
  "nas_ip": "192.168.1.1",
  "nas_id": "AC-01"
}

RADIUS 认证属性

RADIUS 属性	说明
Calling-Station-Id (31)	MAC 地址（`-` 自动转 `:`）
NAS-Identifier (32)	AC 名称
NAS-IP-Address (4)	AC IP
NAS-Port-Id (87)	VLAN 信息（如 `eth0.100` → vlan=100）

CoA / 强制下线

华为设备必须使用私有 VSA 才能正确执行 CoA：

CoA Request:
  User-Name = "user001"
  NAS-IP-Address = 192.168.1.1
  HW-IP-Host-Address (26-61) = 10.0.0.100   ← 华为私有
  HW-MAC-Addr (26-62) = 00:11:22:33:44:55   ← 华为私有

速率控制 VSA

VSA 子属性	说明
HW-Input-Average-Rate (26-1)	上行平均速率 (bps)
HW-Input-Peak-Rate (26-2)	上行峰值速率 (bps)
HW-Output-Average-Rate (26-3)	下行平均速率 (bps)
HW-Output-Peak-Rate (26-4)	下行峰值速率 (bps)

H3C — Vendor 25506

Portal 重定向 URL

http://portal-server:1816/portal/login?
  userip=10.0.0.100               # 用户 IP
  usermac=00:11:22:33:44:55       # 用户 MAC
  nasip=192.168.1.1                # NAS IP
  nasid=AC-01                      # NAS 标识
  apmac=AA:BB:CC:DD:EE:FF         # AP MAC
  ssid=Office-WiFi                 # SSID
  vlan=100                         # VLAN ID

RADIUS 认证属性

RADIUS 属性	说明
H3C-IP-Host-Addr (VSA 60)	IP+MAC 组合字段（优先使用）
Calling-Station-Id (31)	MAC 地址（回退）
NAS-Port-Id (87)	VLAN 信息

CoA / 强制下线

H3C 支持标准 Acct-Session-Id 方式，也支持私有 VSA：

方式一（推荐）:
  Acct-Session-Id = "abc123456"
  NAS-IP-Address = 192.168.1.1

方式二（私有 VSA）:
  H3C-User-IP-Address (26-210) = 10.0.0.100
  H3C-User-MAC-Address (26-211) = 00:11:22:33:44:55

锐捷 (Ruijie) — Vendor 4881

Portal 重定向参数

锐捷通常使用标准 HTTP 参数或 JSON POST：

http://portal-server:1816/portal/login?
  wlanuserip=10.0.0.100
  wlanusermac=00:11:22:33:44:55
  wlanacname=AC-RJ-01
  wlanacip=192.168.2.1

或 JSON:

json

{
  "username": "user001",
  "password": "password",
  "ip_addr": "10.0.0.100",
  "mac_addr": "00:11:22:33:44:55",
  "nas_ip": "192.168.2.1",
  "nas_id": "AC-RJ-01"
}

RADIUS 认证属性

锐捷使用标准 RADIUS 属性，无需特殊处理：

属性	说明
Calling-Station-Id (31)	MAC 地址
NAS-IP-Address (4)	设备 IP
NAS-Port-Id (87)	VLAN 信息

CoA 速率控制

锐捷使用私有 VSA 控制带宽：

Ruijie-Input-Rate (26-1)：上行 (bps)
Ruijie-Output-Rate (26-2)：下行 (bps)
Ruijie-Input-Peak-Rate (26-3)：上行峰值 (bps)
Ruijie-Output-Peak-Rate (26-4)：下行峰值 (bps)

TP-Link / 水星 (Mercury) — Vendor 11863

水星是 TP-Link 子品牌，使用标准 RADIUS 协议，无私有 VSA。

Portal 重定向

http://portal-server:1816/portal/login?
  wlanuserip=10.0.0.100
  wlanusermac=00:11:22:33:44:55
  ssid=Guest-Network

RADIUS 认证属性

完全标准：

属性	说明
Calling-Station-Id (31)	MAC 地址
NAS-IP-Address (4)	设备 IP
NAS-Port-Id (87)	端口标识

CoA

使用标准 Filter-Id + Session-Timeout 属性，无需私有 VSA。

ZTE (中兴) — Vendor 3902

速率控制 VSA

VSA	说明
ZTE-Rate-Ctrl-SCR-Up	上行速率 (bps)
ZTE-Rate-Ctrl-SCR-Down	下行速率 (bps)

Ikuai (爱快) — Vendor 10055

Portal JSON 格式

json

{
  "username": "user001",
  "password": "password",
  "mac": "00:11:22:33:44:55",
  "terminal_type": "pc",
  "ap_mac": "AA:BB:CC:DD:EE:FF",
  "ssid": "WiFi-Name"
}

速率控制 VSA

RP-Upstream-Speed-Limit (单位: bps×8)
RP-Downstream-Speed-Limit (单位: bps×8)

MikroTik — Vendor 14988

速率控制

MikroTik 使用字符串格式的速率属性：

Mikrotik-Rate-Limit = "10M/20M"
// 格式: "{上行}k/{下行}k"

设备配置对照表

NAS 设备添加时选型

实际设备	厂商代码	说明
华为 AC6003/AC6005/AC6800V	2011 (Huawei)	Portal 1.0/2.0 均支持
华为 ME60/NE40E (BAS)	2011 (Huawei)	PPPoE 场景
H3C WX3540H/WX5500H	25506 (H3C)	Portal URL + RADIUS VSA
新华三 (New H3C)	25506 (H3C)	同 H3C
锐捷 RG-WS6000/RG-AC 系列	4881 (Ruijie)	标准属性为主
TP-Link AC 控制器	11863 (TP-Link)	完全标准协议
水星 AC/AP	11863 (TP-Link)	同 TP-Link
中兴 ZXR10 系列	3902 (ZTE)	私有速率 VSA
爱快 IK-G 系列	10055 (Ikuai)	JSON Portal
MikroTik RouterOS	14988 (Mikrotik)	字符串速率
Cisco WLC	9 (Cisco)	标准属性
Aruba 控制器	14823 (Aruba)	标准属性
Juniper/Mist	2636 (Juniper)	标准属性

配置步骤

1. 添加 NAS 设备

进入「网络管理 → NAS 设备」，点击「添加 NAS」：

参数	示例值	说明
名称	AC-01-办公楼	自定义标识
IP 地址	192.168.1.1	设备管理 IP
厂商代码	Huawei/H3C/Ruijie...	关键：影响 VSA 处理
RADIUS 密钥	`MySecret@2024`	与设备配置一致
CoA 端口	3799	默认值
接入策略	选择公共模式策略	关联认证规则

2. 配置设备端 RADIUS

以华为 AC 为例：

text

radius-server template yunyi
 radius-server shared-key cipher MySecret@2024
 radius-server authentication 10.0.0.1 1812 weight 80
 radius-server accounting 10.0.0.1 1813 weight 80

以 H3C AC 为例：

text

radius scheme yunyi
 primary authentication 10.0.0.1 1812
 primary accounting 10.0.0.1 1813
 key authentication cipher MySecret@2024
 key accounting cipher MySecret@2024
 user-name-format without-domain

3. 配置 Portal URL

设备端的 Portal URL 配置为：

http://{YunyiRADIUS_IP}:1816/portal/login?nas_id={设备标识}&nas_ip={设备IP}

或配置为 JSON Portal API：

POST http://{YunyiRADIUS_IP}:1816/api/user/public/login
Content-Type: application/json

{
  "phone": "{手机号}",
  "sms_code": "{验证码}",
  "nas_id": "{设备标识}",
  "nas_ip": "{设备IP}",
  "ip_addr": "{用户IP}",
  "mac_addr": "{用户MAC}"
}

4. 验证对接

用户连接 WiFi → 应被重定向到 Portal 页面
在「会话管理」中查看在线用户
执行 CoA 调速率测试
执行强制下线测试

常见问题

Portal 页面不弹出

检查 NAS 设备 Portal URL 配置是否正确
检查 DNS 劫持是否配置（设备需拦截用户 DNS 请求）
检查防火墙是否放行 1816 端口

认证失败

检查 RADIUS 密钥是否一致
查看服务日志 tail -f logs/yunyiradius.log
抓包验证：tcpdump -i eth0 port 1812 -w radius.pcap

带宽限制不生效

检查设备厂商代码是否正确
确认 CoA 端口可达：nc -uz 192.168.1.1 3799
华为设备需确认 CoA 功能已开启

强制下线失败

厂商	检查项
华为	必须使用 `HW-IP-Host-Address` + `HW-MAC-Addr` VSA
H3C	优先使用 `Acct-Session-Id`
锐捷	检查 CoA 端口 3799 是否开放
其他	使用标准 `Framed-IP-Address` + `Calling-Station-Id`

Portal 模板管理

Portal管理

Portal 模板是用户看到的认证页面样式，支持自定义品牌 Logo、背景、色调等。

Portal模板

进入「Portal 管理 → 模板管理」可以创建和管理模板。

创建模板

参数	说明
模板名称	标识名称
模式	public（公共模式）/ tenant（租户模式）/ both（通用）
Logo	上传品牌 Logo
背景图	自定义背景
主色调	品牌色
CSS	自定义样式（高级）
底部信息	版权/联系信息

模板绑定优先级

网络节点（Node）是公共/租户模式的统一承载入口，节点上的 mode 决定认证模式，节点默认模板与默认策略作为中间优先级生效。Portal 模板的具体指定方式，优先级从高到低：

接入策略级：策略中指定 portal_template_id（最高优先级）
节点级：节点默认模板
系统默认：全局 Portal 模板

模板推断流程

HTTP 请求（?nas_id=X 或 ?nas_ip=Y）
  → lookupDevice() 查找 bas_device / net_nas
    → resolveEffectivePolicy()
      → 设备级 policy_id（最高）
      → 节点级 default_policy_id
      → 系统默认 (node_id=0)
        → ProductMode → "tenant" 或 "public"
        → PortalTemplateID → 指定模板或默认

用户门户

用户门户 (User Portal) 是租户模式下终端用户的自助管理页面：

注册/登录
账号信息管理（密码修改、手机绑定）
TOTP 两步验证
套餐查看与在线购买
在线设备管理
使用记录与账单查询
支付宝在线充值

用户门户是独立 Vue 3 SPA，部署在 /user/ 路径下。

访问地址汇总

地址	说明
`http://server:1816/admin`	管理后台
`http://server:1816/user`	用户自助门户
`http://server:1816/portal`	Portal 认证页（由 NAS 重定向）
`http://server:1816/portal/api/login`	Portal 登录 API (POST)
`http://server:1816/api/user/public/login`	公共模式登录 API (POST)
`http://server:1816/api/user/public/sms-code`	短信验证码发送 (POST)

Portal 认证配置与参数对接指南 ​

概述 ​

支持的厂商及参数格式 ​

华为 (Huawei) — Vendor 2011 ​

Portal 1.0 重定向 URL ​

Portal 2.0 (JSON) ​

RADIUS 认证属性 ​

CoA / 强制下线 ​

速率控制 VSA ​

H3C — Vendor 25506 ​

Portal 重定向 URL ​

RADIUS 认证属性 ​

CoA / 强制下线 ​

锐捷 (Ruijie) — Vendor 4881 ​

Portal 重定向参数 ​

RADIUS 认证属性 ​

CoA 速率控制 ​

TP-Link / 水星 (Mercury) — Vendor 11863 ​

Portal 重定向 ​

RADIUS 认证属性 ​

CoA ​

ZTE (中兴) — Vendor 3902 ​

速率控制 VSA ​

Ikuai (爱快) — Vendor 10055 ​

Portal JSON 格式 ​

速率控制 VSA ​

MikroTik — Vendor 14988 ​

速率控制 ​

设备配置对照表 ​

NAS 设备添加时选型 ​

配置步骤 ​

1. 添加 NAS 设备 ​

2. 配置设备端 RADIUS ​

3. 配置 Portal URL ​

4. 验证对接 ​

常见问题 ​

Portal 页面不弹出 ​

认证失败 ​

带宽限制不生效 ​

强制下线失败 ​

Portal 模板管理 ​

创建模板 ​

模板绑定优先级 ​

模板推断流程 ​

用户门户 ​

访问地址汇总 ​

Portal 认证配置与参数对接指南

概述

支持的厂商及参数格式

华为 (Huawei) — Vendor 2011

Portal 1.0 重定向 URL

Portal 2.0 (JSON)

RADIUS 认证属性

CoA / 强制下线

速率控制 VSA

H3C — Vendor 25506

Portal 重定向 URL

RADIUS 认证属性

CoA / 强制下线

锐捷 (Ruijie) — Vendor 4881

Portal 重定向参数

RADIUS 认证属性

CoA 速率控制

TP-Link / 水星 (Mercury) — Vendor 11863

Portal 重定向

RADIUS 认证属性

CoA

ZTE (中兴) — Vendor 3902

速率控制 VSA

Ikuai (爱快) — Vendor 10055

Portal JSON 格式

速率控制 VSA

MikroTik — Vendor 14988

速率控制

设备配置对照表

NAS 设备添加时选型

配置步骤

1. 添加 NAS 设备

2. 配置设备端 RADIUS

3. 配置 Portal URL

4. 验证对接

常见问题

Portal 页面不弹出

认证失败

带宽限制不生效

强制下线失败

Portal 模板管理

创建模板

模板绑定优先级

模板推断流程

用户门户

访问地址汇总