本指南旨在为管理员提供一套系统化的排查流程，用于解决用户（员工、访客等）连接 Portal Wi-Fi 后，无法自动弹出认证页面、登录页面加载报错、或完成身份核验（账号登录/短信验证/扫码）后依然无法上网等问题。

1. 已参阅Portal 认证文档说明，充分了解 PortalServer 两种认证方式的应用场景及流程差异。
2. 请先阅读网络准入常见问题，确认您遇到的问题是否已有对应的快速解决方案。若上述文档未能解决您的问题，请遵循本文提供的排查步骤进行深度诊断。

Portal 认证的排查路径由以下四个逻辑阶段组成：

1. 【共性】页面弹出阶段：终端能否成功加载重定向的 Portal 页面，即用户是否能看到登录页。
2. 【共性】身份提交阶段：用户提交凭据（账密/短信码/扫码）时，后台能否正常识别。
3. 【分流】数据交互阶段：根据认证实施方案（AC 内置 Portal Server 或飞连 Portal Server）排查凭据流转。
4. 【共性】准入决策阶段：RADIUS 节点最终是否下发放行指令。

步骤一：接入网络与认证页面弹出异常排查 #

Portal 页面弹出的前提是终端与网络设备之间已建立基础的 IP 通信。在调整认证配置前，必须首先确认终端已完成预连接。

1. 接入层状态检查 #

在开始 Portal 排查前，请确保终端已成功连接网络并获取合法身份，避免将底层网络问题误判为认证故障：

• SSID 关联检查：若无法连接或连接后立即掉线，则属于无线链路层故障（如信号干扰、AP 负载过高、加密模式不匹配），需优先排查无线侧配置。
• IP 地址获取检查：终端必须通过 DHCP 成功获取有效 IP。若 IP 地址为空或为自动配置地址（169.254.x.x），说明网络链路不通，Portal 认证流程将无法触发。

2. 重定向逻辑检查 #

Portal 弹窗的原理是：网络设备（AC）拦截终端发起的 HTTP 请求，并强制将其重定向至认证页面 URL。

• 拦截逻辑说明：
  • 若终端访问的目标 IP 在 Portal 白名单（免认证规则） 内，网络设备将直接放行流量，不触发弹窗。
  • 若终端访问的目标 IP 不在白名单内，网络设备将拦截该请求并返回重定向报文，触发浏览器弹出认证页面。
• 手动触发测试：若页面未自动弹出，请在浏览器地址栏输入未列入 Portal 白名单的 HTTP 地址（如 http://www.baidu.com）进行手动访问，观察是否发生跳转。若手动访问能弹出页面而自动不弹，说明终端的探测机制（CNA）受阻。

3. Portal 白名单配置核验 #

请确认网络设备（AC）的 Portal 白名单内已包含以下关键地址。若缺失，将导致重定向流程中断或页面加载失败：

• DNS 服务器地址：必须放行。否则终端无法解析认证页面域名及后续的认证信息接收地址。
• Portal 认证页面地址：即飞连后台域名或 IP。若不放行，终端加载登录页的流量会被 AC 再次拦截，导致页面无法打开。

在网络设备详情中，分别查看员工 Wi-Fi 和访客 Wi-Fi 的认证页面地址。以下两图标出了浏览器加载登录页面时访问的地址，请核对该地址是否已加入 Portal 白名单。

员工 Wi-Fi：认证页面地址

访客 Wi-Fi：认证页面地址

• 认证信息接收地址：
  • 方案一（AC 内置）：需放行 AC 自身的 Portal 监听地址，一般为 AC 的接口 IP。
  • 方案二（飞连托管）：需放行飞连后台对应的 Portal 监听地址，即开启 Portal Server 功能的 Radius 节点 IP。

在同一设备详情中，分别查看员工 Wi-Fi 和访客 Wi-Fi 的认证信息接收地址。以下两图标出了用户提交认证信息的目标地址，请结合上面的 Portal Server 方案核对需要放行的地址。

员工 Wi-Fi：认证信息接收地址

访客 Wi-Fi：认证信息接收地址

4. 环境干扰因素排除 #

若以上配置均正确但仍不弹窗，请检查是否存在以下环境干扰：

• 网络竞争：检查终端是否同时启用了有线网口。若有线网络优先级更高，流量将不通过 Wi-Fi 传输，从而无法触发无线 Portal 认证。
• 代理与 VPN：检查终端是否开启了全局网页代理或 VPN。加密封装的流量会导致网络设备无法识别 HTTP/HTTPS 请求，从而无法触发重定向。
• HTTPS 与 HSTS 限制：部分浏览器会对特定域名强制使用 HTTPS 访问。由于部分网络设备通常仅能重定向 HTTP 请求，建议使用纯 HTTP 地址进行初次触发测试。

步骤二：认证页面显示与账号登录排查 #

当终端成功触发重定向并打开 Portal 页面后，需重点排查“页面加载状态”与“身份凭证校验”两个环节。

1. 页面加载报错排查：网络设备匹配机制 #

若页面显示“获取配置失败，请刷新重试”，或后台返回代码 {"code":174003, "message":"无法匹配到当前AP"}，说明飞连后台无法识别当前发起认证请求的网络设备。

• 匹配逻辑原理：终端打开认证页面时，飞连后台需要解析 URL 携带的参数，将其关联至管理后台预设的“网络设备”配置中。只有匹配成功，系统才能下发正确的“认证信息接收地址”。
• 不同版本的匹配方式排查：
  1. 飞连 3.1.5 及以上版本（新机制）：
     系统通过 URL 末尾挂载的唯一数字串（设备 ID）进行识别。
     • 排查点：检查 AC 配置的重定向 URL，确认其末尾是否完整携带了飞连管理后台生成的设备 ID。
  2. 飞连 3.1.5 以前版本（旧机制）：
     系统依赖 URL 中的 apmac 参数与后台配置的设备 MAC 地址进行比对。
     • 排查点：检查 URL 中是否包含 apmac 参数，且该参数的值是否与管理后台【网络设备】列表中录入的 MAC 地址完全一致。
• 新旧版本兼容说明：
  新版本（3.1.5+）依然兼容旧的 apmac 匹配逻辑。若 URL 中既有 ID 也有 apmac，系统将优先根据设备 ID 进行关联。

2. 账号登录校验排查 #

用户在 Portal 页面输入的账号密码，需通过飞连后台的身份源校验。

• 账号一致性说明：
  Portal 认证使用的账号及其密码，与员工访问飞连门户（或登录飞连客户端）的凭据完全一致。
• 常见报错处理：
  • 错误码 10110001：提示“用户名或密码错误”。
    • 排查动作：重点核实账号状态以及输入的密码是否准确。
  • 认证通过后无法跳转：
    • 排查动作：检查账号是否拥有该网络的入网权限。若账号无权限，虽然密码正确，系统也无法为其获取入网凭证并进行后续重定向。

步骤三：认证信息提交路径核验 #

当用户在 Portal 页面输入账号密码并单击“登录”后，浏览器会重定向至一个用于处理认证请求的地址（即“认证信息接收地址”）。通过识别这个地址的归属，您可以确定当前系统运行的模式，并选择后续的排查分支。

1. 观察跳转动作与提交地址 #

单击登录时，请密切观察浏览器地址栏变化，或通过浏览器的开发者工具（F12 - Network 标签页）查看请求的目标 URL。

• 若跳转地址形如 http://[AC-IP]:8000/login 或 http://[AC-IP]/portal/logon.cgi，表示您的环境正在使用 AC 内置 Portal Server 认证方案，浏览器尝试将账密直接发往 AC。请直接进入 AC 内置 Portal 认证深度排查，重点核对各厂商特定的字段名称格式及 RADIUS 对接密钥。
• 若跳转地址形如 http://[飞连节点IP]:9100/login，表示您的环境正在使用飞连 Portal Server 认证方案，浏览器尝试将账密发往飞连服务器处理。请直接进入飞连 Portal Server 认证深度排查，重点检查 9100 端口存活状态、URL 中的 userip/nasip 参数以及 Portal 协议握手。

飞连 Portal Server 加载 HTTPS 证书后，认证信息接收地址应使用 https://portal-server-ip:9100/login，并确认所配置的证书路径和内容正确。若地址使用域名，请确认域名解析到对应的 RADIUS 节点 IP。端口以实际配置为准。

2. 跳转连通性探测 #

无论属于哪种模式，如果单击登录后页面长时间无响应或显示“连接超时”，请执行以下排查：

• 网络探测：在终端侧（或处于同一网段的测试机上），使用 telnet 或 tcping 工具探测目标地址的端口（AC 的 80/8000 端口或飞连的 9100 端口）是否处于开放状态。
• 路径排查：说明终端与接收地址之间的网络路径存在防火墙拦截、ACL 限制或物理路由不通，需先修复网络层连通性；若端口已通但仍然报错，请根据上述分流判断，进入对应的步骤四或步骤五进行深层协议排查。

当 RADIUS 使用飞连 Server 内置服务时，若 Portal 服务已监听，但终端仍无法访问且抓包显示 TCP SYN 持续重传，请检查服务器入站防火墙规则是否拦截了 Portal 监听端口（例如 TCP 9100）。按实际配置放通端口后，保存防火墙规则，避免服务器重启后失效。

3. 浏览器安全警告处理 #

• 现象说明：跳转过程中，浏览器可能弹出“连接不安全”或“您的连接不是私密连接”的警告。
• 原因分析：这是因为当前配置使用的是不加密的 HTTP 协议，或者使用了自签名证书的 HTTPS。
• 处理建议：在排查阶段，可单击网页上的“高级”并选择“继续访问”。若需从根本上消除此提示，需在飞连后台或网络设备上加载合规的 SSL 证书并启用 HTTPS 协议。

步骤四：分支路径排查 #

AC 内置 Portal 认证深度排查 #

如果您在步骤三中确认浏览器跳转的地址是 AC 自身的 IP（如 8000 端口），请按照本路径进行深度排查。

1. 核对字段名称格式

AC 内置服务对表单提交的字段名（username/password）有严格固定要求。请检查飞连管理后台网络设备配置中的“认证用户名字段”和“认证密码字段”。必须与厂商要求（见下表）完全一致，大小写敏感。

2. 检查 AC 与 RADIUS 的通信对接

AC 成功接收凭据后，会作为 RADIUS 客户端向飞连发起认证请求。若此时失败，通常体现为 RADIUS 端的拒绝。

• 共享密钥核对：请检查 AC 侧配置的 RADIUS 共享密钥（Shared Secret）是否与飞连后台网络设备中配置的共享密钥完全一致。
  
• RADIUS 日志分析：若在飞连后台的 /var/log/feilian/radius.event.log 中观察到以下报错，说明对接存在问题：
  • client authentic failed：表示 RADIUS 共享密钥配置错误。
  • get client err：表示飞连后台未正确录入该 AC 设备的 IP 地址。

飞连 Portal Server 认证深度排查 #

如果您在步骤三中确认浏览器跳转的地址是飞连节点的 9100 端口，请按照本路径进行深度排查。

1. Portal 模块状态与 URL 参数校验

在此方案中，飞连 Portal 模块充当转发中间人，对 URL 参数有极高要求。

• 检查 9100 端口存活：在 RADIUS 节点后台执行 lsof -i:9100，核验 Portal 服务是否正常监听 9100 端口。
  • 预期结果示例如下：

    # 执行命令
    root@radius-node:~# lsof -i:9100
    
    # 预期输出示例
    COMMAND     PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
    feilian-r  [PID]  root   25u  IPv6   1234567      0t0  TCP *:9100 (LISTEN)
    

  • 若无结果，说明 Portal 模块未启动。请在管理后台检查该节点的 Portal Server 实例是否已开启。
• 检查 URL 必备参数：
  1. userip：AC 重定向时必须携带此参数。若缺失，Portal 模块无法定位发起请求的终端 IP，会返回错误 {"error":"portal http request do not contain arg userip"}。
  2. nasip：未携带该参数时，飞连 Portal Server 默认使用管理后台配置的无线控制器对接地址作为目标 AC 地址。若需从 Portal 认证 URL 提取其他控制器地址，可通过控制器 IP 地址字段名指定参数；该参数的取值优先于默认对接地址。请核对实际目标地址是否正确，并确认其 UDP 2000 端口可达。
  3. 设备 ID / apmac：用于识别设备资产。如步骤二所述，这是匹配后台配置的前提。

未携带 nasip 时，日志可能出现以下提示，表示服务正在使用默认对接地址。该提示本身不代表认证失败，应核对日志中的目标地址是否符合预期。

portal http request do not contain argument nasip using default bas address 192.168.1.1:2000

2. Portal 模块与 AC 间的协议握手排查（抓包分析）

Portal 模块收到凭据后，会通过 UDP 2000 端口与 AC 进行“Portal 协议”握手。

在飞连 RADIUS 节点按认证对象执行以下抓包命令，复现问题并保存报文。TCP 9100 对应终端提交认证信息，UDP 2000 对应 Portal 协议，UDP 1812 和 3812 分别对应员工、访客 RADIUS 认证；如已修改端口，请替换为实际值。

# 员工 Portal 认证
sudo tcpdump -i any '((tcp port 9100) or (udp port 2000) or (udp port 1812))' -v -w 1.pcap

# 访客 Portal 认证
sudo tcpdump -i any '((tcp port 9100) or (udp port 2000) or (udp port 3812))' -v -w 2.pcap

• 观察报文流向：

  1. REQ_AUTH（认证请求）：Portal 模块 ➔ AC。若 AC 没收到或没反应，检查 AC 的 Portal 协议监听是否开启。
     
  2. RADIUS 交互联动排查 (ACCESS-REQUEST / ACCEPT)：
     AC 在收到上述请求后，会立即向 RADIUS 节点发起验证。
     • 正常情况：AC 发出 ACCESS-REQUEST，RADIUS 节点校验通过后返回 ACCESS-ACCEPT。只有收到此返回，AC 才会进行下一步。
     • 异常情况：
       • 若只观察到 REQ_AUTH，未观察到 ACCESS-REQUEST，请检查 AC 是否收到并处理 Portal 请求，以及是否向正确的 RADIUS 地址和端口发起认证。结合 AC 侧配置和抓包结果定位原因。
       • 若 RADIUS 返回了 ACCESS-REJECT，AC 随后发送的 Portal 结果必为失败。请跳转至步骤五：RADIUS 认证结果与审计日志排查查看日志中的拒绝原因（如密码错误、权限不足）。

  

  
  3. ACK_AUTH（认证响应）：AC ➔ Portal 模块。若返回的 ErrCode 不为 0，需根据 AC 的错误提示进行分析：
  
  
  | 错误码 | 含义 | 排查方向 |
  | --- | --- | --- |
  | ErrCode=0 | 认证成功 | 认证成功。若仍无法上网，请参见认证结果报告分析，检查认证后的网络访问。 |
  | ErrCode=1 | 认证被拒绝 | AC 侧接收到了请求，但出于某种原因拒绝。请检查 AC 侧的 Portal 安全配置，或是否超过了最大连接数。 |
  | ErrCode=2 | 链接已建立 | 用户已在线。请核对 AC 上该用户的在线状态；需要处理已有会话时，按对应厂商的操作说明执行。 |
  | ErrCode=3 | 正在认证中 | AC 正在处理该终端的并发请求。建议用户稍等片刻，避免连续频繁单击登录。 |
  | ErrCode=4 | 发生错误 | AC 系统内部错误或协议解析异常。请检查 AC 与飞连间的协议版本（Portal 1.0/2.0）是否匹配。 |
  4. AFF_ACK_AUTH（确认应答）：Portal 模块 ➔ AC。完成最后的三次握手确认。
  

3. Portal 模块与 AC 的通信链路排查

若模块发出了请求但长时间未收到 AC 的回包：

• UDP 2000 端口放通：Portal 1.0/2.0 协议默认使用 UDP 2000 端口通信。必须确保飞连节点与 AC 之间的此端口双向互通。
• AC 协议开关：部分 AC 需要手动开启“外置 Portal 服务器支持”或“Portal 协议监听功能”。
• 抓包定位：在飞连 RADIUS 节点使用 tcpdump -i any port 2000 -v 观察。若只看到 REQ_AUTH 发出而无回包，说明报文在传输路径中被阻断，或 AC 未响应。

步骤五：RADIUS 认证结果与审计日志排查 #

使用飞连 Portal Server 时，AC 收到 Portal 认证请求后，向 RADIUS 节点发起认证，再将认证结果返回给 Portal Server。使用 AC 内置 Portal Server 时，由 AC 接收认证信息并发起 RADIUS 认证。请结合 RADIUS 报文和事件日志确认认证结果。

1. 快速识别日志报错信息 #

请登录 RADIUS 节点，查看 /var/log/feilian/radius.event.log。在寻找具体的认证结果前，请先观察是否存在以下高频报错。 这些报错通常意味着 RADIUS 通信阶段就已出现异常：

2. 通过认证结果报告（user conn report）深度定位 #

若上述底层通信日志正常，请在日志中搜索关键词 user conn report。该记录反映了业务层面的最终处理结果，请根据 connResult 的取值进行排查：

• connResult ＝ 1（认证成功）
  飞连认证流程已结束。若此时终端仍无法上网，请按序排查：
  1. IP 地址获取：确认终端是否通过 DHCP 获取了对应 VLAN 的正确 IP 及其网关。
  2. 排查 DHCP 下发信息：若 RADIUS 下发了动态 VLAN，需确认该 VLAN 在 AC 及上行交换机中已创建，且对应的 DHCP 地址池工作正常。
  3. 检查 AC 放行状态：在 AC 命令行查看该用户是否已进入“在线列表”。若已在线但无流量，检查 AC 上关联的认证后 ACL 策略是否拦截了业务流量。
• connResult ＝ 2（认证失败）
  认证流程因特定错误（如因为认证用户权限或者认证超时等原因）而中断，请结合日志中的具体错误信息进行排查。
• connResult ＝ 3（认证降级）
  认证未完全成功，触发了限制性策略。请前往检查飞连管理后台动态控制 ＞ 控制策略，检查是否因命中控制策略（例如杀毒软件未开启等终端合规性检查）而导致降级。

3. 解析访客 RADIUS 报文 #

访客 RADIUS 认证默认使用 UDP 3812。若 Wireshark 未将该端口的报文识别为 RADIUS，可手动指定解析协议。

1. 在 Wireshark 中找到 UDP 3812 端口的报文，右键选择 Decode As…。

   

2. 在弹出的窗口中，将 UDP port 3812 对应的 Current（当前） 列设为 RADIUS，单击 OK（确定）。

   

配置后，可查看 RADIUS 报文的属性、Code 和 Identifier 等字段。若访客认证使用了其他端口，请对实际端口设置解析协议。

如果已完成上述所有排查步骤但问题仍未解决，请准备以下信息并联系飞连技术支持团队，以便我们高效地为您定位问题。

• 如果您是飞连认证渠道工程师：请通过飞书搜索飞连 FOC，提交工单处理。
• 如果您是企业用户：请通过火山引擎官网提交工单处理。

信息收集清单 #

1. 基础概况：故障账号、故障时间点（精确到分钟）、受影响的范围（个别用户还是全员）。
2. 配置核验截图：
   • AC 侧：Portal 配置页、RADIUS 方案配置页。
   • 飞连后台：网络设备的配置详情页。
3. 核心日志文件：
   • RADIUS 节点的 /var/log/feilian/radius.event.log。
   • 故障发生时的 pcap 格式抓包文件。
4. 报错全屏截图：包含浏览器地址栏（URL 参数）的完整报错画面。

为了规避潜在的认证故障，建议在部署及维护阶段重点落实以下预防工作：

1. 科学规划部署架构：明确 AC、飞连后台、RADIUS 节点及终端之间的网络位置与交互路径。
2. 预放通访问策略：在防火墙或 ACL 中预先放通所有必需的 IP 与端口（DNS 53, RADIUS 1812/1813, Portal 2000/9100, HTTP/HTTPS 等）。
3. 熟练运用分析工具：理解认证机制，熟练使用 Wireshark 进行报文级分析，重点观察 REQ_AUTH、ACCESS-REQUEST 等关键报文的往返情况。