故障排查与认证页采集
| 现象 | 优先检查 |
|---|---|
| 安装后没有菜单或页面报模块缺失 | 包型、依赖、Lua CBI 兼容性；重新登录 LuCI |
| 无法加载可编辑配置、账号列表异常为空或保存提示版本失效 | 查看下方配置读取与保存，先确认服务与读取结果再修改 |
| newifi3 d2 从 rc1 覆盖升级时 opkg 段错误 | 查看下方覆盖安装失败，先导出备份并保留旧包 |
| 无法连接 Wi-Fi | SSID、无线密码、信号、无线电占用、企业认证及未应用的 UCI 修改 |
| 已连接 Wi-Fi，但无 IPv4 | DHCP、出口接口、防火墙与校园接入限制 |
| 已能上网，未发现认证地址 | 指定登录页或选择学校预设后继续探测；互联网连通性不提供网关地址本身 |
| 认证后缀为空或未读取到 | 认证页是否公开选项、预设是否记录；使用手动输入或网页采集 |
| 账号归属未能判断 | 该账号是否在线、网关是否返回账号/域信息、是否在相同线路；这不是后缀枚举结果 |
| 密码错误或认证拒绝 | 实际完整登录名、账号状态、密码与 AC_ID，不要将错误视为验证成功 |
| 网关可达，互联网不可达 | 网页认证结果、探测目标、当前线路和路由，结合具体错误排查 |
| 手动登出后再次上线 | Go 会暂停该账号的自动认证；检查是否有其他客户端维持登录，或之后是否保存了新配置。1.x 版本检查自动认证是否仍开启 |
| 多 WAN 某条线路失败 | 该账号的接口、IPv4、设备和认证参数，不以其他 WAN 在线代替判断 |
| 开启 UA-Mask 本机代理后认证超时 | 检查认证网关是否被重定向；Go 开发版的验证范围和处理方式见下文 |
| 无线任务未完成回滚 | 是否有并发网络修改；依据提示检查 network / wireless / firewall |
提供问题信息时包含插件版本、固件与包管理器、接入方式、失败步骤、经过脱敏的相关日志。Wi-Fi 与校园认证使用不同密码；同一账号被其他客户端维护时可能相互抢占会话。
配置读取与保存
2.0.1 修复了读取失败时误显示默认设置和空账号、热点列表的问题。看到「无法加载可编辑配置」时，先检查认证服务状态，再点击「重新读取配置」完整重载；不要把读取失败理解为配置已被清空。旧版本出现类似空列表时，先保留配置并更新到修复版本。
表单、账号、热点和向导保存绑定读取时的配置版本。页面打开后，如果另一个标签页、向导或 CLI 已修改配置，旧页面保存会被拒绝。重新读取配置、核对最新内容后再编辑，不要反复提交旧页面。保存或导入没有明确成功反馈时，先重新读取确认结果；「未知」服务状态也不等于服务已停止。
覆盖安装失败
当前正式版发布说明仍列出 newifi3 d2 从 rc1 覆盖升级时 opkg 段错误（#68），尚未复现和确认根因。遇到时先导出配置、保留原版本安装包及脱敏错误输出，再按发布说明尝试卸载旧包后安装匹配的新包。安装完成后核对配置，必要时预览并导入备份，再恢复自动认证。
Go 开发版与 UA-Mask
2026-09-20 在 OpenWrt 25.12.2 x86_64 虚拟机中，使用实际 UA-Mask 0.4.3 安装包（固定源码版本）、fw4 / nftables 和两个隔离的模拟认证网关验证了以下组合。结果对应当时的 Go 开发版，不是当前正式版的重新测量，也不代表 1.x 发布版或校园检测效果。
| UA-Mask 设置或操作 | 已观察结果 |
|---|---|
不代理本机流量，proxy_host=0 | 两条独立 WAN 的本机认证正常；LAN 客户端的 HTTP 对照请求仍按设置改写 |
| 代理本机流量，仅绕过各认证网关的精确 IPv4 地址 | 两条 WAN 认证正常；本机和 LAN 的其他 HTTP 对照请求仍被 UA-Mask 改写 |
| 代理本机流量，认证网关也被重定向 | 两条 WAN 均在获取 challenge 时超时，没有继续发送登录凭据 |
| UA-Mask 重启、崩溃后由自身服务恢复、fw4 重载 | 配置精确网关绕过时，两条 WAN 可恢复认证，未观察到反复登录风暴 |
| smart-srun 停止、启动，或通过 apk 卸载后重新安装 | UA-Mask 的配置、规则和运行进程保持不变，LAN 对照请求仍被改写 |
| 两条 WAN 使用相同网关地址和相同本机 IPv4 | 关闭本机代理或精确绕过网关时，各账号只到达所属网关；断开 A 后不会借 B 登录，B 仍可认证 |
| 精确网关绕过开启，断开 WAN A | A 的认证失败且未向任一网关提交登录凭据；B 仍可认证，LAN 对照请求继续改写；恢复 A 后可重新认证 |
| 获取 challenge 期间更换 WAN A 的 IPv4 | 旧请求中断且未提交登录凭据；新地址可重新认证，B 和 LAN 对照请求仍正常，无需重启 smart-srun |
| HTTPS 认证网关 | 有效证书和对应域名可认证；不受信或域名不匹配的证书在发送认证请求前被拒绝 |
| DNS 响应截断或超时 | 截断后使用 TCP 查询；A 线 DNS 超时会有界失败，B 仍可认证，A 的 DNS 恢复后可重试 |
| DNS 被透明 DNAT 到本机 dnsmasq 代理 | 代理可能从 B 线重新发起 A 线查询；本次实验随后认证失败且未提交登录凭据。精确排除 A 线 DNS 的重定向后，查询和认证恢复到 A |
| 连通性探测返回重定向、HTML 或慢响应 | 已认证与互联网可用分别显示；不会跟随重定向发送凭据，探测恢复 204 后可确认连通 |
另外，在同版本固件的独立虚拟机上，以官方 fw3 和 iptables 1.8.10 legacy 后端验证了 LAN 改写、两条不同子网 WAN 的认证与精确网关绕过、断线和地址变更恢复。fw3 重载、UA-Mask 重启或崩溃恢复，以及 smart-srun 停止和启动后，上述流程仍正常；未绕过认证网关时，会有界失败且不继续提交登录凭据。iptables 下的相同网关地址、DNS 代理、HTTPS 和卸载流程尚未分别验证。
若只有开启本机代理后认证失败，可在 UA-Mask 自身的绕过 IP 设置中添加实际认证网关的单个 IPv4 地址（/32）；多 WAN 分别填写各自网关。另一种方式是关闭 UA-Mask 的本机代理，保留其 LAN 代理设置。修改后分别测试认证和原本需要 UA 改写的业务。smart-srun 不会自动改写 UA-Mask 的规则。
如果使用透明 DNS 代理，多 WAN 还需在该代理的设置中，为所选线路的实际 DNS 地址精确排除 UDP/TCP 53 端口的重定向；只绕过 HTTP 认证网关不足以保证 DNS 出口。Go 开发版只获得本机回环 DNS 时会明确拒绝域名解析，要求配置该线路上可达的 DNS。smart-srun 不会自动修改用户的 DNS 或代理规则。
不要为此放行所有 80 端口、清空防火墙或取消 smart-srun 的出口绑定。fw4 实验分别覆盖了不同 WAN 子网，以及网关和本机 IPv4 都相同的隔离线路；本地 DNS 代理实验使用 dnsmasq 2.91，其他代理、未列出的防火墙组合与真实校园环境仍需分别验证。这些实验不证明 Wi-Fi 切换时游戏连接能够保持。
当前 Go 发布版的手动登出、暂停与恢复规则见认证说明。网关会话是否真正退出仍应以登出结果为准。
参数收集与问题反馈
优先使用插件的一键配置：先选择接入线路，探测认证地址和后缀，再填写账号。保存成功后可生成预设 Issue 草稿，操作说明见 贡献学校预设。
插件不能执行任意门户 JavaScript。对于动态选项、特殊编码或未公开后缀的页面，可手动填写已知值；若浏览器能登录而插件不能，请通过 学校不适配反馈 提供页面地址、出错步骤与脱敏日志。
需要进一步诊断时，可在浏览器开发者工具中核对正常登录请求的 ac_id、用户名后缀和登录参数。不要公开完整 HAR、Cookie、密码、challenge、token、info、chksum 或未经检查的原始响应。浏览器登录成功不代表插件已经适配，应分别说明结果。