Codex
135 lines
4.1 KiB
Markdown
135 lines
4.1 KiB
Markdown
# 维护手册
|
|
|
|
新时空教务管家长期维护时，目标是每次更新都能做到可检查、可部署、可回滚，并且不误改业务数据。
|
|
|
|
## 日常更新流程
|
|
|
|
1. 查看当前改动：
|
|
|
|
```bash
|
|
git status --short
|
|
```
|
|
|
|
2. 修改代码后先跑本地检查：
|
|
|
|
```bash
|
|
make check
|
|
make smoke
|
|
```
|
|
|
|
3. 部署前记录业务数据哈希：
|
|
|
|
```bash
|
|
make data-hash
|
|
```
|
|
|
|
4. 构建、重启、健康检查和部署后哈希复核：
|
|
|
|
```bash
|
|
make deploy
|
|
```
|
|
|
|
5. 确认容器运行状态：
|
|
|
|
```bash
|
|
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。
|
|
|
|
## Gitea 自动备份
|
|
|
|
新时空教务管家推荐把 Gitea SSH 仓库配置为 `origin`，并用 `post-commit` hook 在每次提交后自动推送当前分支。
|
|
|
|
首次配置：
|
|
|
|
```bash
|
|
git remote add origin <你的 Gitea SSH 仓库地址>
|
|
make install-gitea-backup
|
|
```
|
|
|
|
安装后，每次 `git commit` 成功都会执行：
|
|
|
|
```bash
|
|
git push origin HEAD:<当前分支>
|
|
```
|
|
|
|
注意：
|
|
|
|
- 自动备份只推送已提交内容，不会自动提交工作区中的未提交改动。
|
|
- 如果 Gitea 暂时不可用或 SSH key 权限异常，本地 commit 仍会保留，hook 只打印错误提示。
|
|
- 如果当前仓库已有 `.git/hooks/post-commit`，安装脚本会拒绝覆盖；确需覆盖时执行 `python3 scripts/install_gitea_backup_hook.py --force`。
|
|
|
|
## 数据保护
|
|
|
|
业务数据文件位于：
|
|
|
|
```text
|
|
/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、课时账户编辑、课程小结自动入账或审核批准，先确认自动备份目录：
|
|
|
|
```text
|
|
/root/新时空数据/data/backups/
|
|
```
|
|
|
|
恢复备份时先停止服务，把备份文件复制回数据目录，再重新启动服务。
|
|
|
|
## 回滚建议
|
|
|
|
如果部署后页面异常：
|
|
|
|
1. 查看容器和日志：
|
|
|
|
```bash
|
|
make ps
|
|
make logs
|
|
```
|
|
|
|
2. 回到上一个可用 Git 版本后重新部署：
|
|
|
|
```bash
|
|
git status --short
|
|
git log --oneline -5
|
|
```
|
|
|
|
3. 重新执行：
|
|
|
|
```bash
|
|
make deploy
|
|
```
|
|
|
|
如果业务数据哈希异常，先不要继续写入数据，优先从 `../data/backups/` 或外部备份恢复。
|
|
|
|
## 课程小结迁移维护
|
|
|
|
- VPS 是 `classnotes.txt` 和 `学生课时账户.md` 的唯一正式写入方。
|
|
- 本机 `com.xsk.records.sync` 常驻同步迁移后应停止，避免旧本地数据覆盖 VPS。
|
|
- 本机课程小结采集脚本用 `XSK_INGEST_URL` 和 `XSK_INGEST_TOKEN` 推送批次；失败批次保存在本机 `推送失败队列/`。
|
|
- 管理后台的“课程小结审核”处理低置信或冲突小结；“操作记录”追踪接收、自动入账、重复、失败、审核批准和驳回。
|
|
- 历史小结导入使用 `scripts/import_course_summaries.py`，历史 `classnotes缺失.txt` 只生成审核任务，不自动扣课时。
|
|
|
|
## 提交前检查清单
|
|
|
|
- `make check` 通过。
|
|
- `make smoke` 通过。
|
|
- 查询类或前端类改动部署前后业务数据哈希一致。
|
|
- `make health` 正常返回 `ok: true`。
|
|
- 重要功能改动已在 `README.md` 或本文件补充维护说明。
|