Campus-Auth 是一个基于 Playwright、FastAPI 和 Vue 3 的校园网自动认证工具。它既可以作为终端用户直接运行的本地服务，也适合作为开发调试项目使用。项目提供 Web 控制台、自动监控、任务模板、多网络配置方案、系统托盘、自启动与日志可视化，目标是让校园网认证尽量做到"装好即用、断网即连、问题可查"。
新视频 【小刻也能学会的通用校园网自动认证教程】 https://www.bilibili.com/video/BV1d35E6mEVB/?share_source=copy_web&vd_source=db13da6ef2846b31b874687783211f99
Campus-Auth 主要解决三个场景：
- 开机后自动保持网络在线，避免手动重复登录。
- 在网络掉线、会话失效或页面失效时，自动回到认证流程并重试。
- 通过 Web 控制台统一管理配置、任务、日志和运行状态。
- Web 控制台：初始化向导、仪表盘、设置页、任务页、Python 脚本页、日志页、外观页、配置方案页、关于页。
- 多网络配置方案：为不同网络环境创建独立配置，支持按网关 IP 或 WiFi SSID 自动切换。
- 自动监控：定时探测网络可用性，异常时自动触发认证。
- 自动登录：基于 Playwright 的浏览器自动化，按任务定义执行登录流程。
- 任务系统：使用 JSON 描述认证步骤，支持导入导出、复制、安全检测。
- 实时日志：通过 WebSocket 推送运行日志，支持按级别筛选和文本搜索。
- 开机自启动：支持在 Windows、macOS 和 Linux 上配置自启动。
- 系统托盘：可在后台最小化到托盘运行。
- 防重复启动：同时检测 PID 文件和本地端口，避免重复拉起同一实例。
- 智能状态判断：识别已登录状态，减少重复提交和无效请求。
- 暂停时段：支持在夜间或指定时间段暂停自动登录。
- 失败重试：使用退避策略降低短时间内的重复冲击。
- Python 3.10 或更高版本。
- 推荐使用 uv 管理依赖。
默认 Web 控制台端口为 50721，启动后可在浏览器访问：
如果你修改了 APP_PORT，则以实际端口为准。
安装依赖：
uv sync启动服务：
uv run app.py如果你希望直接使用仓库自带环境，也可以运行：
.\environment\python\python.exe app.py建议第一次使用按下面顺序完成：
- 启动服务并打开 Web 控制台。
- 进入初始化向导，填写校园网账号、密码和认证页面地址。
- 确认运营商字段、监控开关和浏览器模式。
- 保存配置后执行一次手动登录，确认流程正常。
- 再开启自动监控，让系统在断网时自动重连。
如果校园网页面结构比较特殊，建议先用非无头模式排查，再切换回无头运行。
如果你有多个网络环境（如宿舍 WiFi 和教学楼 WiFi），可以在"配置方案"页面为每个网络创建独立配置，系统会根据当前网络自动切换。
app.py 支持若干命令行参数，用于控制服务启动、状态查询和自启动管理。
# 基础启动
python app.py
# 启动但不自动打开浏览器
python app.py --no-browser
# 启动到系统托盘
python app.py --tray
# 查看服务状态
python app.py --status
# 停止服务
python app.py --stop
# 自启动管理
python app.py --autostart
python app.py --autostart enable
python app.py --autostart disable项目支持两种配置存储：
settings.json文件：存储多网络配置方案（Profiles）和全局系统设置，由 Web 控制台管理。
首次使用时系统会通过初始化向导引导你填写配置，所有配置统一存储在 settings.json 中。
项目的所有配置现已统一通过 Web 控制台管理，配置数据存储在项目目录下的 settings.json 文件中。首次使用时，Web 控制台的初始化向导会引导你完成配置。如需高级配置（端口、代理等），可直接编辑 settings.json 或通过 Web 控制台"设置"页面操作。
以下配置仅通过 Web 控制台或直接编辑 settings.json 设置，不支持环境变量：
| 选项 | 默认值 | 说明 |
|---|---|---|
login_then_exit |
false |
登录成功后自动退出程序，适用于只需登录一次的场景。 |
proxy |
空 | 网络代理地址，用于远程任务仓库访问。留空不使用代理。 |
browser_args |
见默认值 | 自定义 Chromium 启动参数，每行一个，用于反检测或浏览器行为定制。 |
pure_mode |
false |
纯净模式，使用 Chromium 原始设置，不注入自定义参数。 |
access_log |
false |
是否输出 Uvicorn HTTP 访问日志。 |
log_retention_days |
7 |
日志与截图保留天数（1-365），过期日期目录整体删除。 |
任务系统使用 JSON 文件描述浏览器自动化认证流程，支持多种步骤类型、变量模板、网络检测兜底成功判断和帧上下文。任务文件存放在 tasks/ 目录，通过 Web 控制台管理（新建、编辑、导入导出、复制、设置活动任务）。
配置方案（Profiles）系统允许你为不同的网络环境（如宿舍 WiFi、教学楼 WiFi、有线网络）配置不同的认证参数，系统可以根据当前网络自动切换。
- 每个方案可以设置匹配条件：网关 IP 或 WiFi SSID。
- 系统检测当前网络的网关 IP 和 WiFi SSID（支持 Windows、macOS、Linux）。
- 优先按网关 IP 匹配，其次按 SSID 匹配。
- 匹配成功后自动切换到对应方案的配置。
每个方案可以独立配置：
- 凭证（用户名/密码，加密存储）
- 认证地址、运营商
- 检测间隔、暂停时段
- 浏览器参数（无头模式、超时、User-Agent 等）
- 自定义变量
也可以选择使用全局凭证或全局高级设置。
在"配置方案"页面可以：
- 查看所有方案列表及当前活动方案
- 新建、编辑、删除方案（
default不可删除） - 检测当前网络环境（网关 IP、WiFi SSID、匹配的方案）
- 开启/关闭自动切换
开启自动切换后，监控核心每 60 秒检测一次网络环境变化。当检测到当前网络匹配到不同的方案时，会自动切换配置并重新加载监控。
Campus-Auth/
├── app.py # 统一启动入口
├── launcher.py # Windows 分发入口点（PyInstaller 打包）
├── setup_env.sh # macOS/Linux 安装脚本
├── pyproject.toml # 项目元数据与依赖配置
├── requirements.txt # 依赖列表（兼容 pip）
├── settings.json # 多网络配置方案数据（gitignored）
├── Campus-Auth-Setup.spec # PyInstaller 打包配置
├── package_zip.ps1 # 发布打包脚本
├── backend/ # 后端服务
│ ├── main.py # FastAPI 主应用
│ ├── container.py # ServiceContainer 依赖注入
│ ├── config_service.py # 配置读写与初始化状态
│ ├── profile_service.py # 多网络配置方案管理
│ ├── monitor_service.py # 网络监控与认证触发（Actor 模型）
│ ├── task_service.py # 任务读写与活动任务管理
│ ├── scheduler_service.py # 定时任务调度
│ ├── login_history_service.py # 登录历史记录
│ ├── autostart_service.py # 开机自启动管理
│ ├── uninstall_service.py # 卸载功能服务
│ ├── debug_manager.py # 调试会话管理
│ ├── debug_session.py # 调试会话状态
│ ├── deps.py # FastAPI 依赖注入
│ ├── ws_manager.py # WebSocket 连接管理
│ ├── schemas.py # Pydantic 数据模型
│ ├── constants.py # 共享常量
│ └── routers/ # API 路由（13 个文件）
│ ├── monitor.py # 监控控制
│ ├── config.py # 配置管理
│ ├── tasks.py # 任务管理
│ ├── profiles.py # 配置方案
│ ├── debug.py # 调试会话
│ ├── backup.py # 配置备份
│ ├── repo.py # 仓库代理
│ ├── system.py # 系统管理
│ ├── tools.py # 工具下载
│ ├── scripts.py # 脚本管理
│ ├── scheduled_tasks.py # 定时任务
│ ├── history.py # 登录历史
│ └── logfiles.py # 日志文件管理
├── src/ # 核心逻辑与工具模块
│ ├── task_executor.py # 任务执行器（按 JSON 步骤执行）
│ ├── monitor_core.py # 监控核心（网络探测与自动切换）
│ ├── network_decision.py # 网络决策层
│ ├── network_probes.py # 网络探测（TCP/HTTP/Portal）
│ ├── network_detect.py # 网络检测工具
│ ├── network_test.py # 网络测试工具
│ ├── playwright_worker.py # Playwright Actor 模型工作线程
│ ├── playwright_bootstrap.py # Playwright 运行环境准备
│ ├── script_runner.py # 自定义脚本执行器
│ ├── system_tray.py # 系统托盘集成
│ ├── version.py # 版本号读取
│ └── utils/ # 工具模块
│ ├── browser.py # 浏览器上下文管理与反检测脚本
│ ├── login.py # 登录尝试处理
│ ├── env.py # 登录环境变量构建
│ ├── crypto.py # 密码加密（Fernet）
│ ├── logging.py # 日志系统（文件、WebSocket、控制台）
│ ├── config.py # 配置校验
│ ├── config_helpers.py # 配置辅助函数
│ ├── notify.py # 跨平台桌面通知
│ ├── time_utils.py # 时间工具
│ ├── network_helpers.py # 网络辅助函数
│ ├── file_helpers.py # 文件操作（原子写入）
│ ├── platform_utils.py # 平台检测工具
│ ├── repo_proxy.py # 远程仓库代理
│ ├── shell_policy.py # 脚本命令安全策略
│ └── exceptions.py # 自定义异常
├── frontend/ # 前端控制台（Vue 3 SPA，无构建步骤）
│ ├── index.html # 入口页面
│ ├── app.js # Vue 应用主文件
│ ├── template-loader.js # 模板加载器
│ ├── js/ # JavaScript 模块
│ │ ├── app-options.js # Vue 应用配置
│ │ ├── bootstrap.js # 应用初始化
│ │ ├── components.js # 可复用组件
│ │ ├── constants.js # 常量定义
│ │ ├── icons.js # 图标定义
│ │ ├── logger.js # 前端日志
│ │ ├── data/ # 数据模块（16 个文件）
│ │ ├── methods/ # 业务方法（17 个文件）
│ │ └── tasks/ # 任务管理模块（4 个文件）
│ ├── partials/ # HTML 模板
│ │ ├── pages/ # 页面模板（10 个页面）
│ │ │ └── settings/ # 设置子页面（5 个标签页）
│ │ ├── sidebar.html # 侧边栏
│ │ ├── topbar.html # 顶栏
│ │ ├── toast.html # 通知提示
│ │ └── wizard.html # 初始化向导
│ ├── styles/ # CSS 样式
│ │ ├── base.css # 基础样式
│ │ ├── components.css # 组件样式
│ │ ├── layout.css # 布局样式
│ │ ├── responsive.css # 响应式样式
│ │ └── pages/ # 页面样式（10 个文件）
│ ├── vendor/ # 第三方库（Vue 3, Axios）
│ └── background/ # 用户背景图片（gitignored）
├── tasks/ # 任务定义
│ ├── browser/ # 浏览器任务
│ ├── scheduled/ # 定时任务
│ └── scripts/ # 脚本任务
├── tests/ # 测试（39 个文件）
├── doc/ # 文档
│ ├── api-doc.md # API 接口文档
│ ├── task-manual.md # 任务开发参考
│ ├── task-writing-guide.md # 任务编写指南
│ ├── custom-script-guide.md # 自定义脚本指南
│ └── update_log.md # 更新日志
├── tools/ # 辅助工具
│ └── task-recorder.user.js # Tampermonkey 任务录制脚本
├── debug/ # 调试截图（按日期归档）
├── logs/ # 日志文件（按日期归档）
├── temp/ # 临时文件
└── release/ # 发布产物
入口与启动：
app.py：统一启动入口，负责服务启动、状态查询、自启动控制和浏览器打开。launcher.py：Windows 分发入口点，下载嵌入式 Python、安装依赖、启动服务。setup_env.sh：macOS/Linux 安装脚本，支持 uv 和系统 Python 两种模式。
后端服务：
backend/main.py：FastAPI 主应用，提供 HTTP API 和 WebSocket。backend/container.py：ServiceContainer 依赖注入，统一管理服务生命周期。backend/config_service.py：配置读写、初始化状态管理。backend/profile_service.py：多网络配置方案管理，网关/SSID 检测，自动切换。backend/monitor_service.py：网络监控、认证触发、WebSocket 日志广播（Actor 模型）。backend/task_service.py：任务读写、活动任务管理、危险步骤检测。backend/scheduler_service.py：定时任务调度服务。backend/login_history_service.py：登录历史记录服务。backend/autostart_service.py：跨平台开机自启动（Windows VBS / macOS LaunchAgent / Linux systemd）。backend/uninstall_service.py：卸载功能，扫描并清理程序文件、配置、日志等。
核心逻辑：
src/task_executor.py：任务执行器，负责按 JSON 步骤逐条执行浏览器操作。src/monitor_core.py：监控核心，网络探测循环与 Profile 自动切换。src/network_decision.py：网络决策层，封装暂停检查、网络状态检查、登录前置检查。src/network_probes.py：网络探测实现（TCP/HTTP/Portal），并发执行。src/playwright_worker.py：Playwright Actor 模型工作线程，所有浏览器操作统一收归。src/script_runner.py：自定义脚本执行器，支持 Python/PowerShell/cmd 等外部程序。
工具模块：
src/utils/browser.py：浏览器上下文管理与反检测脚本注入。src/utils/login.py：登录尝试处理，浏览器任务和脚本任务编排。src/utils/crypto.py：密码加密（Fernet），密钥管理。src/utils/logging.py：日志系统（文件轮转、WebSocket 推送、控制台输出）。src/utils/shell_policy.py：脚本命令安全验证。
- FastAPI：HTTP API 和 WebSocket。
- Uvicorn：ASGI 服务运行器。
- Pydantic：配置与请求数据校验。
- Playwright：浏览器自动化执行。
- socket + httpx：网络检测（TCP 探测 + HTTP 探测）。
- cryptography：密码加密。
- ddddocr：验证码 OCR 识别（任务步骤中使用）。
- Vue 3：控制台界面（单文件，无构建工具）。
- Axios：后端 API 通信。
- 原生 WebSocket：实时日志流。
- pystray / Pillow / cairosvg：系统托盘。
- pytest：测试框架。
详见 doc/api-doc.md。
uv run pytest
uv run pytest tests/test_task_executor.py -vuv run ruff check .
uv run ruff format .from src.utils.logging import get_logger
logger = get_logger("my_module")from src.task_executor import TaskExecutor, TaskConfig
config = TaskConfig(task_dict)
executor = TaskExecutor(config, env_vars)
success, message = await executor.execute(page)from backend.profile_service import ProfileService
service = ProfileService(settings_path, env_path)
gateway_ip = service.get_gateway_ip()
ssid = service.get_wifi_ssid()
matched = service.match_profile(gateway_ip, ssid)项目会自动尝试多个镜像源下载 Playwright 和 Chromium。如果下载仍然失败，可以手动设置环境变量指定下载源：
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright项目带有重复启动保护。如果你怀疑已经有实例在运行，可以先查看状态再决定是否停止：
python app.py --status
python app.py --stop建议按这个顺序排查：
- 账号和密码是否正确。
LOGIN_URL是否能正常打开。ISP是否和当前网络运营商匹配。- 在 Web 控制台查看实时日志和失败截图。
- 暂时关闭无头模式，观察浏览器具体执行了什么操作。
- 确认后端服务本身在运行。
- 检查浏览器开发者工具中的 WebSocket 连接状态。
- 刷新页面后重新订阅日志流。
使用"配置方案"页面为每个网络创建独立的 Profile，设置匹配条件（网关 IP 或 WiFi SSID），并开启自动切换。系统会在检测到网络变化时自动切换到匹配的方案。
这是因为任务中包含 eval 步骤，该步骤可以执行任意 JavaScript 代码。系统会显示代码内容要求确认。确认代码安全后点击确认即可。
Windows 自启动使用 VBS 脚本，部分杀毒软件可能会拦截。建议将程序目录添加到杀毒软件白名单，或暂时关闭杀毒软件后重试 python app.py --autostart enable。
- ddddocr — 验证码识别引擎，本项目使用它处理图形验证码。
详见 LICENSE。