xsk-education-management/app

新时空教务管理系统

这是一个面向新时空教务业务的综合管理系统。迁移后 VPS 是正式业务数据主机，负责保存 classnotes.txt、学生课时账户.md、课程小结库、审核任务和操作记录；本机只保留微信群聊天记录采集/识别，并把课程小结批量推送到 VPS。

目录

• app/：FastAPI 后端和内置前端页面。
• MAINTENANCE.md：日常检查、部署、数据保护和回滚流程。
• Makefile：常用维护命令入口。
• scripts/deploy_to_vps.py：部署新时空教务管理系统到 VPS。
• scripts/import_course_summaries.py：一次性导入历史课程小结 Markdown。
• scripts/sync_to_vps.py：旧版正式数据同步脚本，迁移后不要继续常驻运行。
• scripts/smoke_test.js：轻量前端行为烟测。
• scripts/install_gitea_backup_hook.py：安装提交后自动推送到 Gitea 的 Git hook。
• scripts/install_launch_agent.py：安装 Mac 开机常驻同步任务。
• launchd/com.xsk.education-management.sync.plist.template：LaunchAgent 模板。

后端结构

• app/main.py：FastAPI 应用入口，只负责注册路由和全局异常处理。
• app/routers/：按业务入口拆分 API 和页面路由，包括登录页面、课程记录、课时账户、管理后台、课程小结推送和健康检查。
• app/config.py：路径、环境变量、Cookie 名称和进程内写锁。
• app/auth.py：网页登录、Basic Auth、管理后台和课程小结推送鉴权。
• app/schemas.py：请求体 Pydantic 模型。
• app/api_utils.py：API 层通用读取、文件元信息和请求体转换。
• app/domain.py：领域数据结构、学生/科目别名、状态和识别常量。
• app/storage.py：原子写入、权限继承和业务数据备份。
• app/data.py：业务数据解析、登记、审核、课程小结入库和查询逻辑。

首次部署

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

cd /Users/yangdawei/Desktop/新时空业务源数据/tools/xsk-education-management
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'

手动同步数据

迁移完成后不要再用本机 classnotes.txt 和 学生课时账户.md 覆盖 VPS。下面命令只保留给迁移前或灾难恢复时使用，日常新增课程小结应走 POST /api/ingest/course-summaries。

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/

课程小结推送

VPS 接收接口：

POST /api/ingest/course-summaries
Header: X-INGEST-TOKEN: <VPS .env 中的 INGEST_AUTH_TOKEN>

本机采集脚本默认在 --write 时推送到该接口。建议在本机 shell 配置：

export XSK_INGEST_URL='http://121.199.172.246:18080/api/ingest/course-summaries'
export XSK_INGEST_TOKEN='填写VPS里的INGEST_AUTH_TOKEN'

然后运行：

python3 /Users/yangdawei/Desktop/新时空业务源数据/新时空课程记录与课时账户/课程小结采集/批量采集微信课程小结.py --write

推送成功批次会归档到本机 课程小结采集/推送归档/，失败批次会进入 课程小结采集/推送失败队列/，可用 --retry-failed 重试。需要临时恢复旧流程时再加 --local-write。

历史小结导入

把本机历史课程小结目录同步或上传到 VPS 后，可在容器内执行一次性导入。历史导入只重建小结库和状态；历史 classnotes缺失.txt 默认转为审核任务，不自动扣课时。

cd /root/新时空教务管理系统/app
docker compose exec xsk-education-management python scripts/import_course_summaries.py \
  --source /data/import/课程小结采集 \
  --target /data/course_summaries \
  --state /data/course_summary_state.json \
  --tasks /data/admin_tasks.json \
  --operation-logs /data/operation_logs.jsonl \
  --missing-table /data/import/课程小结采集/classnotes缺失.txt

数据备份

通过登记 API、课程小结自动入账或审核批准修改正式课时数据时，服务会在写入前自动备份本次会改动的业务文件。正式数据和辅助状态位于：

/root/新时空教务管理系统/data/classnotes.txt
/root/新时空教务管理系统/data/学生课时账户.md
/root/新时空教务管理系统/data/course_summaries/
/root/新时空教务管理系统/data/course_summary_state.json
/root/新时空教务管理系统/data/operation_logs.jsonl

备份目录位于：

/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-education-management/sync.log
~/Library/Logs/xsk-education-management/sync.err.log

查看任务：

launchctl list | grep com.xsk.education-management.sync

卸载任务：

launchctl unload ~/Library/LaunchAgents/com.xsk.education-management.sync.plist
rm ~/Library/LaunchAgents/com.xsk.education-management.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：驳回纠错。
• POST /api/ingest/course-summaries：本机采集脚本批量推送课程小结，使用 X-INGEST-TOKEN 鉴权。
• GET /api/admin/course-summaries：管理后台只读查询正式课程小结库。
• GET /api/admin/operation-logs：管理后台读取小结接收、自动入账、审核批准和驳回记录。