OSU-Public-Wi-Fi-Login/README.md at 94952c71362c9b675ebc2c76e5498b03ce96db58

yuanzhe1999/OSU-Public-Wi-Fi-Login

Fork 0

Files

Zhe Yuan 18cc9b6bab Rewrite as Windows Wi-Fi monitor service

2026-04-24 10:44:28 -04:00

8.6 KiB

Raw Blame History

适用于 Windows 11 的 OSU Wi-Fi 后台守护程序。它会持续监控无线网络状态，并按配置自动修复连接。

这个重写版本选择了 Python，而不是 PowerShell 或 Rust，原因是：

WiFi@OSU Captive Portal 可以直接用 HTTP 表单提交流程处理，不依赖浏览器驱动
如果 portal 页面结构比较复杂，程序会自动回退到 Playwright 驱动已安装的 Microsoft Edge
Windows 下调用 netsh、修改注册表、接 WinSW 都很直接
后续想打包成单文件 exe 也比较方便

功能

后台常驻运行，而不是一次性触发
可在 WiFi@OSU 和 eduroam 之间切换
支持 YAML 配置网络类型和检查/重试时间
WiFi@OSU 模式下：
- 启动时如果 Wi-Fi 还没连上，会主动尝试连接目标网络
- 可选启用随机 MAC
- 可按周期刷新 MAC 并重连
- 自动打开 Captive Portal 并完成条款确认/登录
eduroam 模式下：
- 启动时如果 Wi-Fi 还没连上，会主动尝试连接目标网络
- 使用系统已保存的凭据
- 可恢复为硬件 MAC
- 仅做断线检测和自动重连
支持 WinSW 包装为 Windows 服务

项目结构

main.py                     CLI 入口
osu_wifi_login/config.py    YAML 配置加载
osu_wifi_login/windows.py   netsh / 注册表 / 连通性检测
osu_wifi_login/portal.py    HTTP Portal 登录
osu_wifi_login/service.py   常驻监控与恢复逻辑
config.example.yaml         配置示例
winsw/                      WinSW 服务模板

环境要求

Windows 11 x86-64
Python 3.11+
Microsoft Edge
uv

安装

uv sync

仓库已经附带默认的 config.yaml，直接编辑即可；如果想恢复模板，也可以参考 config.example.yaml。如果 WiFi@OSU portal 页面较复杂，运行时会使用 Playwright 调用本机已安装的 Edge，所以第一次改完依赖后需要先完成一次 uv sync。

配置

默认配置文件是根目录下的 config.yaml。

最常用的项如下：

selected_network: wifi_osu

wifi_interface_name: Wi-Fi
allow_unsafe_mac_changes: false
randomize_mac_on_start: false

networks:
  wifi_osu:
    ssid: WiFi@OSU
    profile_name: WiFi@OSU
    requires_portal_login: true
    randomize_mac: false
    restore_hardware_mac: false
    auto_create_open_profile: true
    mac_refresh_hours: 6

  eduroam:
    ssid: eduroam
    profile_name: eduroam
    requires_portal_login: false
    randomize_mac: false
    restore_hardware_mac: true
    auto_create_open_profile: false

connectivity_checks:
  - url: http://example.com/
    expected_status: 200
    expected_text: Example Domain
    require_final_url_match: true
    allow_redirects: false

说明：

selected_network 设为 wifi_osu 或 eduroam
wifi_interface_name 一般是 Wi-Fi，如果你的系统接口名不同，需要改成实际值
profile_name 是 Windows 已保存的 WLAN 配置名，通常与 SSID 相同
auto_create_open_profile 适合 WiFi@OSU 这类开放网络；如果本机还没有保存过 profile，程序会先自动创建一个基础 profile 再连接
connectivity_checks 默认使用像 example.com 这样的普通页面，不再使用 Windows/Apple/Firefox 的系统探针地址，避免被 portal 白名单误判成“已联网”
allow_unsafe_mac_changes 默认关闭；关闭时不会写注册表改 NetworkAddress
randomize_mac 和 restore_hardware_mac 都只有在 allow_unsafe_mac_changes: true 时才会生效
某些无线网卡驱动在修改 MAC 时会直接蓝屏，建议默认保持关闭
connect_retry_cooldown_seconds 控制“Wi-Fi 完全没连上时”主动重连的频率
disconnect_grace_seconds 表示断线多久后开始强制恢复
connection_timeout_seconds 会用于登录后等待网络放行，默认给 captive portal 留 60 秒
mac_refresh_hours 只对 WiFi@OSU 生效

运行

前台调试运行：

.\.venv\Scripts\python.exe main.py --config config.yaml

只跑一次检查：

.\.venv\Scripts\python.exe main.py --config config.yaml --once

服务逻辑

程序每轮会做这些事：

检查当前是否连在目标 SSID 上
如果 Wi-Fi 完全没连上，先直接尝试连接目标网络
如果是 WiFi@OSU，刚连上后会主动探测 captive portal；检测到登录页就立刻登录
检查是否真的能上网
如果断线或异常持续超过阈值，则重启 Wi-Fi 网卡并重新连接
如果你显式开启了高风险 MAC 改写，才会在启动时和刷新周期到达时改 MAC 并重连

管理员权限

以下操作需要管理员权限：

修改 NetworkAddress 注册表项
为 WiFi@OSU 随机化 MAC
清除随机 MAC，恢复硬件 MAC
重启无线网卡

其中 MAC 相关操作在部分驱动上可能导致蓝屏；现在默认关闭，只有在你明确打开 allow_unsafe_mac_changes: true 后才会执行。

编译发布

推荐使用 PyInstaller 的 onedir 模式发布。这个模式会生成一个完整目录，里面包含 exe、Python 运行时、第三方依赖和 Playwright 驱动文件；目标机器仍需要安装 Microsoft Edge，但不需要安装 Python、uv 或项目依赖。

uv sync
uv run pyinstaller --noconfirm --clean --onedir --name osu-wifi-login main.py

生成结果位于：

dist\osu-wifi-login\osu-wifi-login.exe

把 config.yaml 放到同一个发布目录中：

Copy-Item config.yaml dist\osu-wifi-login\config.yaml

发布目录最终至少应包含：

dist\osu-wifi-login\
  osu-wifi-login.exe
  config.yaml
  _internal\

前台验证：

.\dist\osu-wifi-login\osu-wifi-login.exe --config .\dist\osu-wifi-login\config.yaml --once

也可以生成真正的单文件 exe：

uv run pyinstaller --noconfirm --clean --onefile --name osu-wifi-login main.py

不过不建议优先使用 onefile。Playwright 会在运行时解包和查找驱动文件，onedir 更稳定；onefile 虽然只有一个 exe，但启动更慢，也更容易遇到服务账户临时目录权限问题。无论使用哪种模式，Microsoft Edge 仍需要由系统提供，因为程序使用的是已安装 Edge 渠道。

WinSW 服务

仓库中已经提供：

使用编译后的 exe

下载 WinSW x64 可执行文件
将 WinSW 重命名为 osu-wifi-login-service.exe
将 osu-wifi-login-service.exe 放入 dist\osu-wifi-login\
在同一目录创建 osu-wifi-login-service.xml

dist\osu-wifi-login\osu-wifi-login-service.xml 示例：

<service>
  <id>osu-wifi-login</id>
  <name>OSU Wi-Fi Login Service</name>
  <description>Keeps WiFi@OSU or eduroam connected and logs into the captive portal when needed.</description>

  <executable>%BASE%\osu-wifi-login.exe</executable>
  <arguments>--config "%BASE%\config.yaml"</arguments>
  <workingdirectory>%BASE%</workingdirectory>

  <log mode="roll-by-size">
    <sizeThreshold>1048576</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>

  <onfailure action="restart" delay="10 sec" />
  <stoptimeout>30 sec</stoptimeout>
</service>

以管理员 PowerShell 安装并启动：

Set-Location .\dist\osu-wifi-login
.\osu-wifi-login-service.exe install
.\osu-wifi-login-service.exe start

查看状态、停止、卸载：

.\osu-wifi-login-service.exe status
.\osu-wifi-login-service.exe stop
.\osu-wifi-login-service.exe uninstall

服务账户建议

默认不写 <serviceaccount> 时，WinSW 通常使用 LocalSystem。这个程序需要能访问 WLAN profile、启动 Edge 自动化并执行 netsh，更推荐使用你自己的 Windows 用户运行服务。

如果要指定服务账户，在 XML 中加入：

<serviceaccount>
  <domain>.</domain>
  <user>YOUR_WINDOWS_ACCOUNT</user>
  <password>YOUR_PASSWORD</password>
  <allowservicelogon>true</allowservicelogon>
</serviceaccount>

如果你保持 allow_unsafe_mac_changes: false，通常不需要管理员权限来修改 MAC；但重启网卡和某些 netsh 操作仍可能需要提升权限。若服务日志提示权限不足，再改用管理员账户运行服务。

当前注意事项

WiFi@OSU 的 Captive Portal 表单字段仍然基于当前已知页面结构；如果学校改版，可能需要微调 YAML 或代码
现在默认不依赖 msedgedriver；复杂页面会自动回退到 Playwright + 已安装 Edge

8.6 KiB Raw Blame History Unescape Escape

OSU Public Wi-Fi Login

功能