本指南旨在为管理员提供一套系统化的排查流程，用于解决用户（员工、访客等）连接 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 不在白名单内，网络设备将拦截该请求并返回重定向报文，触发浏览器弹出认证页面。
• 手动触发测试：若页面未自动弹出，请在浏览器地址栏输入任一纯 HTTP 协议的地址（如 http://1.1.1.1）进行手动访问，观察是否发生跳转。若手动访问能弹出页面而自动不弹，说明终端的探测机制（CNA）受阻。

3. Portal 白名单配置核验 #

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

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

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

4. 环境干扰因素排除 #

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

• 网络竞争：检查终端是否同时启用了有线网口。若有线网络优先级更高，流量将不通过 Wi-Fi 传输，从而无法触发无线 Portal 认证。
• 代理与 VPN：检查终端是否开启了全局网页代理或 VPN。加密封装的流量会导致网络设备无法识别 HTTP 请求，从而无法触发重定向。
• 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 协议握手。

2. 跳转连通性探测 #

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

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

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 日志分析：若在飞连后台的 radius.event.log 中观察到以下报错，说明对接存在问题：
  • client authentic failed：表示 RADIUS 共享密钥配置错误。
  • get client err：表示飞连后台未正确录入该 AC 设备的 IP 地址。
• 在线会话冲突排查：在 AC 命令行中使用 display portal user 检查该终端 MAC 是否已有残留会话。若存在残留，AC 可能会拒绝新的认证请求，需手动清除（cut portal user）后重试。

飞连 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：建议携带。若不携带，模块将尝试使用后台配置的默认 IP。若网络环境中存在多个 AC，缺失 nasip 可能导致认证指令发错对象。
  3. 设备 ID / apmac：用于识别设备资产。如步骤二所述，这是匹配后台配置的前提。

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

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

• 观察报文流向：

  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 的 RADIUS 服务器组或地址池配置有误，未触发认证。
       • 若 RADIUS 返回了 ACCESS-REJECT，AC 随后发送的 Portal 结果必为失败。请跳转至步骤五：RADIUS 认证结果与审计日志排查查看日志中的拒绝原因（如密码错误、权限不足）。
  发起验证

  

  验证通过

  

  3. ACK_AUTH（认证响应）：AC ➔ Portal 模块。若返回的 ErrCode 不为 0，需根据 AC 的错误提示进行分析：
     

     错误码	含义	排查方向
     ErrCode=0	认证成功	流程已跑通。若仍无法上网，请跳至步骤六检查 RADIUS 的 ACL 或 VLAN 分配。
     ErrCode=1	认证被拒绝	AC 侧接收到了请求，但出于某种原因拒绝。请检查 AC 侧的 Portal 安全配置，或是否超过了最大连接数。
     ErrCode=2	链接已建立	终端已存在残留会话。请参考步骤四，在 AC 命令行清理在线用户（cut portal user）后重试。
     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 协议握手完成后，AC 会向飞连后台发起标准的 RADIUS 请求。此时，您需要通过查看飞连管理后台的日志，确认最终的准入决策。

查看认证日志 #

通过在 RADIUS 节点查看 RADIUS 认证日志和认证报文信息是否完整。在日志中找到 user conn report 记录，根据 connResult 的取值进行针对性排查：

• connResult ＝ 1（认证成功）
  飞连认证流程已结束。若此时终端仍无法上网，请按序排查：

  1. IP 地址获取：确认终端是否通过 DHCP 获取了对应 VLAN 的正确 IP 及其网关。
  2. 排查 DHCP 下发信息：若 RADIUS 下发了动态 VLAN，需确认该 VLAN 在 AC 及上行交换机中已创建，且对应的 DHCP 地址池工作正常。
  3. 检查 AC 放行状态：在 AC 命令行查看该用户是否已进入“在线列表”。若已在线但无流量，检查 AC 上关联的认证后 ACL 策略是否拦截了业务流量。
  4. 检查客户端/UI 同步：若实际已可上网但页面提示失败，排查状态同步问题。

• connResult ＝ 2（认证失败）
  流程因错误中断。请对照下表进行处理。

  报错类型 (Log Message)	日志解释与对策
  get client err xxx	RADIUS 未获取到 AC 设备。检查后台配置的设备 IP 是否正确。
  client authentic failed	共享密钥错误。检查 AC 与后台配置的 RADIUS Secret 是否一致。
  client message authentic failed	共享密钥错误导致的消息校验失败。
  parse packet err	解析包失败。报文格式异常。
  get config: json unmarshal failed	拉取配置时返回的 JSON 解析失败。系统内部配置异常。
  get user error: forbidden	权限拦截。该用户无权限或已被禁用。
  recv duplicate request	收到重复请求。通常由于 RADIUS 未能在时间内回包，需检查网络延迟。
  chap user password wrong	CHAP 认证密码错误。
  http error: xxxx	请求后台 API 接口失败。检查节点间网络通信。
  receive tls error	TLS 握手失败。多为证书错误（如 Windows 泛域名或自签证书问题）。
  Eap check: not contain...	报文非 EAP 类型。若误选了 802.1X 认证，请检查配置。
  MSCHAP Failure	802.1X 认证输入的密码错误（仅在兼容 802.1X 时出现）。

• connResult ＝ 3（认证降级）
  认证未完全成功，触发了限制性策略。请前往检查飞连管理后台动态控制 ＞ 控制策略，检查是否因命中控制策略（例如杀毒软件未开启等终端合规性检查）而导致降级。

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

• 如果您是飞连认证渠道工程师：请通过飞书搜索飞连 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 等关键报文的往返情况。