xsk-education-management/app

新时空课程记录查询网页

这是一个课程记录查询和登记工具，用于把本机正式业务源中的 classnotes.txt 和 学生课时账户.md 同步到 VPS，并通过网页查询上课记录、课时账户和登记新增记录。

目录

• app/：FastAPI 后端和内置前端页面。
• MAINTENANCE.md：日常检查、部署、数据保护和回滚流程。
• Makefile：常用维护命令入口。
• scripts/deploy_to_vps.py：部署网页服务到 VPS。
• scripts/sync_to_vps.py：同步正式数据文件到 VPS。
• scripts/smoke_test.js：轻量前端行为烟测。
• scripts/install_gitea_backup_hook.py：安装提交后自动推送到 Gitea 的 Git hook。
• scripts/install_launch_agent.py：安装 Mac 开机常驻同步任务。
• launchd/com.xsk.records.sync.plist.template：LaunchAgent 模板。

首次部署

推荐先配置 SSH key。若临时使用密码，可通过环境变量传入，不要写入仓库文件。

cd /Users/yangdawei/Desktop/新时空业务源数据/tools/xsk-records-web
XSK_USE_SSHPASS=1 \
XSK_SSH_PASSWORD='填写SSH密码' \
XSK_WEB_PASSWORD='填写网页访问密码' \
python3 scripts/deploy_to_vps.py --use-sshpass

默认访问地址：

http://121.199.172.246:18080/

默认网页用户名为 wolfydw。网页密码只写入 VPS 的 /root/新时空数据/app/.env，不会提交进 Git。

如果 VPS 无法访问 Docker Hub，部署脚本会默认使用 swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim 作为基础镜像。需要更换时设置：

XSK_PYTHON_IMAGE='python:3.12-slim'

手动同步数据

XSK_USE_SSHPASS=1 \
XSK_SSH_PASSWORD='填写SSH密码' \
python3 scripts/sync_to_vps.py --once --use-sshpass

同步文件：

• /Users/yangdawei/Desktop/新时空业务源数据/新时空课程记录与课时账户/classnotes.txt
• /Users/yangdawei/Desktop/新时空业务源数据/新时空课程记录与课时账户/学生课时账户.md

远端数据目录：

/root/新时空数据/data/

数据备份

通过登记 API 修改数据时，服务会在写入前自动备份本次会改动的业务文件。备份目录位于：

/root/新时空数据/data/backups/

每次登记生成一个事务备份目录，目录内包含变更前的业务文件副本和 metadata.json。系统自动保留最近 50 次备份，超过后删除最旧备份。

查看备份：

ls -lt /root/新时空数据/data/backups/

恢复某次备份时，先停止服务，再把对应备份目录里的文件复制回数据目录，最后重启服务：

cd /root/新时空数据/app
docker compose stop
cp /root/新时空数据/data/backups/<备份目录>/classnotes.txt /root/新时空数据/data/classnotes.txt 2>/dev/null || true
cp /root/新时空数据/data/backups/<备份目录>/学生课时账户.md /root/新时空数据/data/学生课时账户.md 2>/dev/null || true
docker compose up -d

安装自动同步

XSK_USE_SSHPASS=1 \
XSK_SSH_PASSWORD='填写SSH密码' \
python3 scripts/install_launch_agent.py --use-sshpass

日志位置：

~/Library/Logs/xsk-records-web/sync.log
~/Library/Logs/xsk-records-web/sync.err.log

查看任务：

launchctl list | grep com.xsk.records.sync

卸载任务：

launchctl unload ~/Library/LaunchAgents/com.xsk.records.sync.plist
rm ~/Library/LaunchAgents/com.xsk.records.sync.plist

更换网页访问密码

登录 VPS 后修改 /root/新时空数据/app/.env 中的 BASIC_AUTH_PASSWORD，然后重启：

cd /root/新时空数据/app
docker compose up -d

管理后台使用 ADMIN_AUTH_PASSWORD。为兼容旧部署，如果未配置 ADMIN_AUTH_PASSWORD，系统会继续使用原 ACCOUNTS_AUTH_PASSWORD 或 ACCOUNT_AUTH_PASSWORD。

API

• GET /api/health：数据状态。
• GET /api/records?q=王鑫鹏5月数学课：自然语言查询上课记录。
• GET /api/accounts：课时账户列表。
• GET /api/accounts?q=王鑫鹏：按学生筛选账户。
• GET /api/accounts?status=欠费：按账户状态筛选。
• GET /api/accounts/王鑫鹏：单个学生账户。
• POST /api/admin/accounts：管理后台新增课时账户。
• PUT /api/admin/accounts/{student_id}：管理后台修改课时账户。
• POST /api/corrections：课程记录页提交纠错审核。
• GET /api/admin/tasks：管理后台查看审核任务。
• POST /api/admin/tasks/{task_id}/approve：批准纠错并写入正式上课记录。
• POST /api/admin/tasks/{task_id}/reject：驳回纠错。