WeBan: a Python bot that automates Weiban safety courses and exams

What WeBan automates on the Weiban platform

Weiban is a Chinese campus safety education platform where students work through projects, categories and courses, then sit an exam. The work is repetitive: page turns, short quizzes inside lessons, a minimum study duration per course, and a final exam drawn from a question pool. WeBan, published as hangone/WeBan, automates that sequence. The README describes it as implementing course learning and automatic exam answering based on a question bank, with multi-user multithreaded execution and automatic captcha recognition.

The intended user is a student with an account on a school's Weiban deployment, not an integration developer. The README opens with a three-step pitch aimed at people with no Python experience: download a binary, run it, type school, student ID and password. Everything else in the project exists to make that path survive a real login flow, a slider captcha and a lesson player.

How the course and exam loop actually runs

The mechanism is browser automation rather than HTTP replay. nodriver is a declared dependency, and the parameter table exposes browser_path, cdp_host and cdp_port, so the tool attaches to a Chrome instance and drives the real page. That choice explains the captcha handling: a login slider and in-course click captchas are solved by an OpenCV pipeline shipped as captcha_model.onnx, described in the README as two rounds of three attempts before falling back to manual input.

The learning loop walks project, then category, then course, simulating page turns and in-lesson answering, and waiting out the study duration before marking a course complete. The README states that courses and exams alternate by project. Exam answering is lookup-based: questions are matched against answer/answer.json, single and multiple choice are both handled, and unmatched questions are either answered randomly or left for manual entry depending on random_answer. Before and after an exam the tool syncs the question bank from the server, so multiple users share one pool. In perfect mode, a run that does not score full marks can sit the exam again; the README calls this resuming an interrupted exam.

One detail worth noting is jupiter_fallback, which re-sends jupiter page-turn traces for courses that never loaded apicenext.js. That is a compatibility shim for a specific front-end variant, and it tells you the automation is coupled to how the site is built, not to a stable API.

Installing WeBan from a release binary or Docker

The README's recommended path is the prebuilt binary. Open the latest release page, pick the file for your system, and run it. On Linux the documented steps are to make it executable and start it:

chmod +x WeBan-linux-*
./WeBan-linux-x64     # ARM 服务器换成 WeBan-linux-arm64

On first run with no config file, the program prompts for school, username and password, validates the login, and writes config.toml next to the binary. If the school name or credentials are wrong it asks again instead of writing a broken config.

If you would rather not answer prompts, the README gives an environment-variable form. These three names are the ones the project documents:

WB_TENANT_NAME="你的学校全称" WB_USERNAME=你的学号 WB_PASSWORD=你的密码 ./WeBan-macos-arm64

Precedence is documented as command line over environment over config file, and every key has three spellings: the snake_case config key, the --kebab-case flag, and the WB_SNAKE_CASE variable. So study_time maps to --study-time and WB_STUDY_TIME.

For containers, the repository Dockerfile defines two targets. without-browser ships the PyInstaller binary alone and expects you to point cdp_host and cdp_port at a browser on the host; it sets WB_DATA_DIR=/app/data and ENVIRONMENT=docker and declares that directory as a volume. with-browser builds on chromedp/headless-shell so the browser is inside the image. The README notes that Docker, cron and background environments run non-interactively, and that the data directory persists config, logs and answer data.

Where WeBan breaks or is the wrong choice

The biggest structural risk is the answer bank. Exam answers come from answer/answer.json, and the README invites users to submit pull requests to improve it. Coverage therefore depends on other people having met the same questions. The exam_submit_match_rate option exists to refuse submission below a match threshold, which is a sensible guard, but it also means a poorly covered question set can block a run rather than complete it.

Captcha recognition has a documented fallback, not a guarantee. The README says the in-course click captcha is attempted twice with three tries each and only then handed to the user. In a headless container there is no user to hand it to, so a run can stall where an interactive session would simply prompt.

There is also a maintenance question. The last push to the repository was on 2026-08-21, and the newest release listed is v3.10.1 on the same date. That is recent, but the pyproject.toml carries an explicit warning against upgrading numpy past 1.x and opencv past 4.10.0.84, because numpy 2.x wheels target x86-64-v2 and crash on QEMU virtual CPUs that only expose SSE2. The pins are deliberate, and they mean the project cannot simply track upstream releases without retesting. The README does not document rollback or how to revert a partially completed course, so if a run half-finishes, recovery is on you.

WeBan compared with writing your own requests script

The obvious alternative is a small script that logs in over HTTP, posts lesson progress and submits exam answers. That approach is faster and runs anywhere, but it has to reproduce the site's request signing and captcha handling by hand, and it breaks the moment the front end changes. WeBan takes the opposite route: it drives a real browser through nodriver, which absorbs front-end changes but costs a browser process, a CDP endpoint and a headless shell image in Docker.

The second alternative is doing the courses manually. That is the only option that guarantees your answers are your own. WeBan's bank is shared and community-maintained, so its accuracy is a property of the group, not of the software. If your school's question pool is small and stable, the bank will likely cover it; if it rotates often, expect unmatched questions and decide in advance whether random_answer should be true.

Licence, upgrades and what a fork inherits

WeBan is GPL-3.0. If you fork it and distribute a modified binary, the licence's copyleft terms apply to what you distribute; if you only run it locally, that is a different situation. This is a description of the licence identifier in the repository, not legal advice, and anyone embedding WeBan in a product should read the licence text themselves.

Upgrade cost is dominated by the pinned scientific stack. numpy is constrained to >=1.26.4,<2 and opencv-python-headless to exactly 4.10.0.84, with a comment in pyproject.toml stating that 4.11+ and 5.x have unverified binary compatibility with numpy 1.x and that any bump should be tested on QEMU first. Python itself is pinned to >=3.12,<3.13. In practice that means a version bump is a three-part change: edit pyproject.toml, regenerate uv.lock, then rebuild the PyInstaller binary and the Docker image, and re-verify captcha recognition on a machine without AVX2 if that is your deployment target. The Dockerfile accepts an APP_VERSION build argument that rewrites the version field during the build, so image tags and package metadata can drift if you pass it inconsistently.

Editorial conclusion

WeBan suits students who have to clear Weiban safety courses and want the exam answered from a maintained question bank rather than by hand, and it is workable on a 1 GB QEMU VPS because the dependency pins avoid AVX2. It is the wrong tool for anyone who wants a supported, documented product: the README covers usage but not rollback, the answer bank only improves when users submit PRs, and the login flow still needs a real browser reachable over CDP unless you use the with-browser image. Before running it, check that your Weiban deployment still loads apicenext.js, since the jupiter_fallback option exists precisely for courses that do not, and confirm which release tag matches the binary you downloaded.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes