xzs-mysql: a Java and Vue exam system you deploy yourself

What xzs-mysql is for, and who actually needs it

xzs-mysql is the MySQL edition of the Xuezhisi open source exam system (学之思开源考试系统), a Java plus Vue project with separated frontend and backend. It targets people who must run exams on infrastructure they control: a school IT department, a training company, an internal assessment team. The README lists three clients (student web, WeChat mini program, admin console) and three deployment shapes (integrated, separated frontend and backend, and Docker). The problem it solves is concrete. You have a question bank, cohorts of students, and a need to schedule papers and collect answers, and you do not want to rent that from a vendor. The README also points to a PostgreSQL edition under a different repository name (mindskip/uexam on Gitee, mindskip/xzs on GitHub), so the database choice is a fork of the same codebase rather than a configuration switch. That matters: if you run PostgreSQL, you are on a different repository with its own release cadence.

Papers, tasks and the three exam modes in the admin console

The admin side is where the design shows. The README describes paper creation as producing one of three types: a timed paper (时段试卷), a fixed paper (固定试卷), or a task paper (任务试卷). The distinction is not cosmetic. A fixed paper can be practised repeatedly and self-graded by the student. A timed paper adds a window in which that repetition is allowed. A task paper is published by an administrator to a grade, and the README states each student can attempt it only once. So the same question bank feeds three different assessment semantics, and the choice of paper type is the choice of how strict the attempt is. Question authoring covers single choice, multiple choice, true or false, fill in the blank, and short answer, with stems that accept text, images, tables and mathematical formulas. Students answer in text. There is a wrong-answer notebook that collects missed questions automatically, exam records, a message centre, and per-user activity logs on the admin side. The dashboard reports paper count, question count, user activity and monthly question volume. Nothing here is unusual for an exam system, but the mapping from paper type to attempt rule is the part worth understanding before you build a curriculum on it.

Deploying xzs-mysql: what the repository gives you

The repository layout is the deployment documentation. Alongside README.md and LICENSE there are four directories: docker/, docs/, release/, source/, and sql/. The README states the system supports integrated deployment, separated frontend and backend deployment, and Docker deployment, and it links to a documentation site at https://www.mindskip.net:999 and a video tutorial series on Bilibili. What the README does not give is a command sequence: there is no docker compose up line, no environment variable table, no port number, and no stated Java or Node version. So the honest first step is to read the files in docker/ and docs/ before typing anything, because those are the only places the actual parameters can live. A reasonable order of operations, based on the directory names alone, is: load the schema from sql/ into a MySQL instance, build the Java backend from source/, build the Vue frontend, then either serve them together or run the Docker definition in docker/. Treat that as a plan to verify against the files, not as instructions the README provides.

A first run, using the folders the project ships

Because the README documents deployment shapes rather than commands, the only defensible tutorial is one that inspects what is actually in the repository. Start by listing the deployment and schema directories so you know what you are working with before you install anything.

git clone https://github.com/mindskip/xzs-mysql.git
cd xzs-mysql
ls docker docs release source sql

The listing should show the five top-level entries plus README.md and LICENSE. The sql/ directory is where the MySQL schema lives; docker/ is where the container definition lives. Read both before proceeding, since the README does not name the schema file or the image. If docker/ contains a compose file, that file is the authoritative source for ports, service names and environment variables, and you should copy those values from it rather than from any summary. If it does not, the separated deployment path applies and you build the Java backend and the Vue frontend yourself. Either way, the admin console and the student client are separate frontends pointed at the same backend, so a successful backend start with no reachable frontend means the API is up but nothing is usable yet.

Where xzs-mysql is the wrong tool

Two limitations are visible from the repository. First, the interface and documentation are Chinese. The README, the documentation site, and the video tutorials are all in Chinese, and the README names QQ groups and a WeChat contact for support. If your examiners or students do not read Chinese, you are adopting a system whose operating language you will have to change yourself, and the README gives no indication of an internationalisation layer. Second, the README does not document upgrades. There is a release/ directory, but no migration guide, no version compatibility statement, and no rollback procedure appears in the README. For a system that will hold student records and exam results, that is a real gap: you will be deciding how to move a populated MySQL schema forward without the project telling you how. A third boundary is scale and integration. Nothing in the README describes an API for external systems, single sign-on, or proctoring. If your requirement is to plug exams into an existing LMS or to invigilate remotely, this project does not claim to do either.

The PostgreSQL edition, and what changes if you pick it

The closest alternative is the same project on PostgreSQL. The README lists mindskip/uexam on Gitee and mindskip/xzs on GitHub as the PostgreSQL editions, against mindskip/xzs-mysql and its Gitee mirror for MySQL. The difference in approach is not architectural; it is operational. Choosing PostgreSQL means you are tracking a different repository, and the two editions are maintained as separate codebases with their own commit histories. If your organisation already runs PostgreSQL and has no MySQL expertise, that edition removes a database from your operational surface. If your organisation has MySQL tooling, backups and monitoring in place, xzs-mysql fits without new work. The trap is assuming you can switch later: because the schema lives in a database-specific sql/ directory, moving between editions means migrating data across two schemas, not flipping a driver. Decide the database before you load any student records.

Licence and the cost of staying current

xzs-mysql is licensed AGPL-3.0, per the licence badge in the README and the LICENSE file at the repository root. AGPL is the strongest of the common copyleft licences, and its network clause is the part that catches people: if you modify the software and let users interact with it over a network, the licence's obligations extend to those users. Running an unmodified copy for internal exams is a different situation from forking the admin console and offering it as a hosted service. This is not legal advice; read the LICENSE file and get your own opinion before you build on it. On maintenance, the repository is not archived and the last push was on 2026-09-23. The upgrade cost is the harder question. Since the README documents no migration path and no versioning scheme for the schema in sql/, every upgrade is a manual comparison between the schema you are running and the one in the new revision. Budget for that: keep your schema changes in version control, and diff sql/ on every pull rather than assuming a drop-in replacement.

Editorial conclusion

Adopt xzs-mysql if you need a self-hosted exam and question-bank console with a student web client and a WeChat mini program, and you can live with AGPL-3.0 and a MySQL schema you load yourself. Do not adopt it if you want a managed SaaS, an English-first interface, or a system whose upgrade path the README spells out; the README documents deployment shapes, not migration. Verify three things first: that the sql folder contains a schema you can actually load, that the student flow you need (fixed paper, timed paper, or one-shot task) exists in your build, and that your team accepts the AGPL obligations before any code leaves your repository.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. mindskip/xzs-mysql on GitHub
4. Project website
5. README