维护手册

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

以下命令默认在仓库根目录 /root/新时空教务管理系统 执行。根目录 Makefile 会转发到 app/ 下的实际应用配置；不要在根目录直接运行裸 docker compose，需要直接调用时使用 docker compose -f app/docker-compose.yml <命令>。

日常更新流程

查看当前改动：
```
git status --short
```
修改代码后先跑本地检查：
```
make check
make smoke
```
部署前记录业务数据哈希：
```
make data-hash
```
构建、重启、健康检查和部署后哈希复核：
```
make deploy
```
确认容器运行状态：
```
make ps
```

常用命令

make check：检查前端 JS 语法和后端 Python 编译。
make smoke：运行轻量前端行为烟测，覆盖排序按钮、组内排序和纠错后排序。
make data-hash：输出 classnotes.txt、学生课时账户.md，以及存在时的 admin_tasks.json、course_summary_state.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。

收尾验证注意事项

收尾阶段要验证“当前运行服务”，不要只验证工作区文件。应用镜像在构建时把源码复制进容器；修改 Python、HTML、JS、CSS 后，如果没有重新执行 make build 和 make up，curl 到的接口和浏览器加载的页面仍可能是旧镜像内容。

部署类验证按依赖顺序执行，不要并行运行 make up、make ps、curl。先等 make up 完成，再看 make ps，最后访问接口或页面。
如果接口返回旧字段或旧页面，先确认是否已重建并重启容器；不要直接把旧响应判断成代码逻辑错误。
前端脚本或样式变更后，记得同步更新 HTML 中对应静态资源的 ?v= 参数，再构建镜像，避免浏览器继续使用缓存。
用 curl 做收尾验证时优先使用简单命令。需要检查 HTML 内容时，先直接获取页面；如果要配合 grep，先在本地确认引号转义正确，避免把 shell 引号错误误判成服务问题。
如果 curl http://127.0.0.1:<端口> 连接失败，但 make ps 显示容器和端口正常，先区分执行环境网络限制和服务异常；必要时再看 make logs。

推荐收尾顺序：

make check
make build
make up
make ps

随后再访问具体接口或页面，例如：

set -a; . ./app/.env
curl -sS -u "admin:${ACCOUNTS_AUTH_PASSWORD}" "http://127.0.0.1:${APP_PORT:-18080}/api/student-health"
curl -sS -u "admin:${ACCOUNTS_AUTH_PASSWORD}" "http://127.0.0.1:${APP_PORT:-18080}/admin"

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
/root/新时空教务管理系统/data/course_summaries/
/root/新时空教务管理系统/data/course_summary_state.json
/root/新时空教务管理系统/data/operation_logs.jsonl

普通前端和查询类改动不应该改变这些文件；课程小结查询页是只读功能，也不应该改变这些文件。部署前后 make data-hash 输出应一致；如果涉及登记 API、学生档案编辑、课程小结自动入账或审核批准，先确认自动备份目录：

/root/新时空教务管理系统/data/backups/

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

回滚建议

如果部署后页面异常：

查看容器和日志：
```
make ps
make logs
```
回到上一个可用 Git 版本后重新部署：
```
git status --short
git log --oneline -5
```
重新执行：
```
make deploy
```

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

课程小结迁移维护

VPS 是 classnotes.txt 和 学生课时账户.md 的唯一正式写入方。
本机课程小结采集脚本用 XSK_INGEST_URL 和 XSK_INGEST_TOKEN 推送批次；失败批次保存在本机 推送失败队列/。
管理后台的“课程小结审核”处理低置信或冲突小结；“操作记录”追踪接收、自动入账、重复、失败、审核批准和驳回。
历史小结导入使用 scripts/import_course_summaries.py，历史 classnotes缺失.txt 只生成审核任务，不自动扣课时。

提交前检查清单

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

5.9 KiB Raw Blame History Unescape Escape