xsk-education-management/app/MAINTENANCE.md

维护手册

新时空教务管家长期维护时，目标是每次更新都能做到可检查、可部署、可回滚，并且不误改业务数据。

日常更新流程

1. 查看当前改动：

   git status --short
   

2. 修改代码后先跑本地检查：

   make check
   make smoke
   

3. 部署前记录业务数据哈希：

   make data-hash
   

4. 构建、重启、健康检查和部署后哈希复核：

   make deploy
   

5. 确认容器运行状态：

   make ps
   

常用命令

• make check：检查前端 JS 语法和后端 Python 编译。
• make smoke：运行轻量前端行为烟测，覆盖排序按钮、组内排序和纠错后排序。
• make data-hash：输出 classnotes.txt、学生课时账户.md，以及存在时的 admin_tasks.json 的 SHA-256。
• make build：构建 Docker 镜像。
• make up：重启 Docker Compose 服务。
• make health：带认证访问 /api/health。
• make deploy：按推荐顺序执行检查、构建、重启、健康检查和哈希复核。
• make logs：查看最近服务日志。
• make install-gitea-backup：安装提交后自动推送到 Gitea 的 Git hook。

Gitea 自动备份

新时空教务管家推荐把 Gitea SSH 仓库配置为 origin，并用 post-commit hook 在每次提交后自动推送当前分支。

首次配置：

git remote add origin <你的 Gitea SSH 仓库地址>
make install-gitea-backup

安装后，每次 git commit 成功都会执行：

git push origin HEAD:<当前分支>

注意：

• 自动备份只推送已提交内容，不会自动提交工作区中的未提交改动。
• 如果 Gitea 暂时不可用或 SSH key 权限异常，本地 commit 仍会保留，hook 只打印错误提示。
• 如果当前仓库已有 .git/hooks/post-commit，安装脚本会拒绝覆盖；确需覆盖时执行 python3 scripts/install_gitea_backup_hook.py --force。

数据保护

业务数据文件位于：

/root/新时空数据/data/classnotes.txt
/root/新时空数据/data/学生课时账户.md
/root/新时空数据/data/admin_tasks.json

普通前端和查询类改动不应该改变这些文件。部署前后 make data-hash 输出应一致；如果涉及登记 API、课时账户编辑或纠错审核批准，先确认自动备份目录：

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

恢复备份时先停止服务，把备份文件复制回数据目录，再重新启动服务。

回滚建议

如果部署后页面异常：

1. 查看容器和日志：

   make ps
   make logs
   

2. 回到上一个可用 Git 版本后重新部署：

   git status --short
   git log --oneline -5
   

3. 重新执行：

   make deploy
   

如果业务数据哈希异常，先不要继续写入数据，优先从 ../data/backups/ 或外部备份恢复。

提交前检查清单

• make check 通过。
• make smoke 通过。
• 查询类或前端类改动部署前后业务数据哈希一致。
• make health 正常返回 ok: true。
• 重要功能改动已在 README.md 或本文件补充维护说明。