README.md

---

title: Advanced SCU Course Catcher
emoji: 🐳
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---


# Advanced SCU Course Catcher

这是一个面向 Hugging Face Space 的四川大学选课系统 Web 版抢课面板。当前版本已经从单机脚本改造成了可部署、可并行、可多用户管理的 Flask + Selenium 服务，支持普通用户端和管理员端分离运行。

## 当前能力

- 普通用户入口：`/login`
  用户使用 `学号 + 密码` 登录，只能看到自己的课程、任务状态和实时日志。
- 管理员入口：`/admin`
  管理员使用 `账号 + 密码` 登录。此入口不会在用户登录页展示。
- 多管理员体系
  支持多位普通管理员，支持 1 位超级管理员。超级管理员账号和密码由环境变量 `ADMIN`、`PASSWORD` 提供。
- 多用户管理
  管理员可以手动录入用户账号、重置密码、启用/禁用用户、查看所有课程目标。
- 课程录入
  用户自己填写 `课程号` 和 `课序号`，管理员可见全部内容，也可以代为录入和修改。
- 实时日志
  用户和管理员都可以实时看到程序日志，前端通过 SSE 持续推送。
- 并行调度
  多用户任务由后台任务调度器并行执行，管理员可以在后台动态设置并行数。
- Hugging Face Space 适配
  使用 Docker Space 运行，内置 Chromium、chromedriver、中文字体和无头浏览器配置。
- 登录验证码与提交验证码 OCR
  登录阶段和提交选课阶段都支持验证码 OCR 自动识别。
- Selenium 自恢复
  单个 Selenium 会话连续错误达到 5 次时，会自动重建浏览器；连续重建 5 个会话仍失败时，任务才会终止。

## 运行结构

当前实际运行入口和核心模块如下：

- `app.py`
  Hugging Face / gunicorn 使用的 WSGI 入口。
- `space_app.py`
  Flask 路由、页面渲染、登录鉴权、SSE 日志流。
- `core/config.py`
  运行配置与内部密钥管理。
- `core/db.py`
  SQLite 数据层。
- `core/task_manager.py`
  并行调度、任务生命周期管理。
- `core/course_bot.py`
  Selenium 抢课核心逻辑、验证码识别、重试与重建策略。
- `webdriver_utils.py`
  Chromium / chromedriver 初始化。
- `templates/` + `static/`
  用户端、管理员端和响应式前端页面。

## 环境变量

为了减少 Space 配置复杂度，当前只保留少量必要环境变量。

### 必填

- `ADMIN`
  超级管理员账号。
- `PASSWORD`
  超级管理员密码。

### 可选

- `DATA_DIR`
  数据目录，默认会使用仓库下的 `data/`。在 Hugging Face Space 中建议保持为 `/data`。
- `CHROME_BIN`
  自定义 Chromium 路径。默认会自动尝试 `/usr/bin/chromium`。
- `CHROMEDRIVER_PATH`
  自定义 chromedriver 路径。默认会自动尝试 `/usr/bin/chromedriver`。

### 不需要再手动配置的内容

以下内容已经改为自动生成或写入程序默认值，不需要再手工配置环境变量：

- Flask session secret
- 用户密码加密密钥
- 默认并行数
- 登录重试次数
- Selenium 会话错误阈值
- Selenium 会话重建阈值
- 提交验证码重试次数
- 页面超时时间
- 日志页容量

程序会在 `DATA_DIR/.app_secrets.json` 中自动持久化内部密钥。这样即使以后修改 `ADMIN` 或 `PASSWORD`，也不会导致历史用户密码全部失效。

## Hugging Face Space 部署

### 1. 创建 Space

在 Hugging Face 上创建一个新的 Space：

- SDK 选择 `Docker`
- 端口使用 `7860`
- 仓库内容直接推送本项目即可

本仓库根目录已经提供好 `README.md` 的 Space metadata 和 `Dockerfile`。

### 2. 设置 Space Secrets

进入 `Settings -> Variables and secrets`，至少配置：

- `ADMIN=你的超级管理员账号`
- `PASSWORD=你的超级管理员密码`

通常不需要再设置其他环境变量。

如果你想显式指定数据目录，也可以增加：

- `DATA_DIR=/data`

### 3. 开启持久化存储

如果你希望以下数据在 Space 重启后仍然保留，建议在 Space 设置里开启 Persistent Storage：

- 用户账号
- 管理员账号
- 课程目标
- 任务历史
- 运行日志
- 自动生成的内部密钥文件

当前 Dockerfile 已按 `/data` 目录进行适配，并预先处理了目录权限，方便在 Space 中直接持久化。

### 4. 推送部署

如果你使用 git 推送到 Hugging Face Space，可以参考：

```bash

git remote add space https://huggingface.co/spaces/<your-name>/<your-space>

git push space main

```

### 5. 启动方式

容器启动命令已经写入 `Dockerfile`：

```bash

gunicorn --bind 0.0.0.0:${PORT:-7860} --workers 1 --threads 8 --timeout 180 app:app

```

这里使用 `1` 个 gunicorn worker，是为了避免多进程情况下每个进程都各自启动一套本地任务调度器。并发能力由应用内部的线程调度和管理员可配置的任务并行数控制。

## Space 端建议配置

推荐的初始运行策略：

- 后台并行数先设置为 `1` 或 `2`
- 只有在 Space CPU / 内存足够稳定时，再逐步提升
- 在真实高峰前，先做一次小规模联调

对于 CPU 较小的 Space，同时拉起过多 Chromium 会明显增加失败率，因此管理员后台提供了并行数动态调整功能。

## 管理员联调清单

部署到 Space 后，建议按以下顺序联调：

1. 访问 `/admin`，使用 `ADMIN` / `PASSWORD` 登录超级管理员。
2. 在管理员后台创建 1 个普通管理员、2 个测试用户。
3. 为两个测试用户分别录入不同课程号和课序号。
4. 将并行数设置为 `2`。
5. 分别触发两个用户任务，确认两条任务都能进入队列，并按并行数启动。
6. 在管理员日志面板确认日志持续刷新，且可以看到不同学号的执行记录。
7. 使用用户账号访问 `/login`，确认用户只能看到自己的课程和日志。
8. 在任务运行过程中测试停止任务，确认状态能变为“停止中”并最终收敛。
9. 如果学校页面出现提交验证码，确认日志中能看到提交阶段验证码识别提示。

## 自动化测试

仓库当前已补充以下自动化测试：

- `tests/test_config.py`
  验证内部密钥在超级管理员账号变更后依然保持稳定。
- `tests/test_course_bot.py`
  验证 Selenium 会话错误累计后会触发浏览器重建，并验证提交阶段验证码分支。
- `tests/test_task_manager.py`
  验证任务调度器会严格遵守管理员设置的并行上限。
- `.github/workflows/linux-tests.yml`
  在 `ubuntu-latest` 上自动运行上述测试，避免关键逻辑只在 Windows 本地验证。

本地运行测试：

```bash

python -m unittest discover -s tests -v

```

## 本地运行

### 直接运行

```bash

pip install -r requirements.txt

set ADMIN=admin

set PASSWORD=change-me

python main.py

```

### Docker 运行

```bash

docker build -t advanced-scu-course-catcher .

docker run --rm -p 7860:7860 \

  -e ADMIN=admin \

  -e PASSWORD=change-me \

  advanced-scu-course-catcher

```

## 重要说明

- 本项目当前的任务模型是“持续轮询直到成功、手动停止或达到错误上限”。
- 用户密码会以应用内部密钥加密后保存在数据库中，用于后台自动登录教务系统。
- 管理员可以看到全部用户、课程和日志，请在实际使用前明确权限边界。
- 如果学校选课页面 DOM 结构变化较大，需要同步更新 `core/course_bot.py` 中的选择器以及 `javascript/` 下的辅助脚本。
- `course_catcher/` 目录是仓库中保留的旧实现，当前运行链路以 `space_app.py + core/*` 为准。