第 15 课：验收真实学生管理系统

第四阶段 · 真实 student-management-api · 面向 Docker 初学者

本课完成标准

你能够：

• 验收容器、页面和静态资源；
• 验收登录和认证接口；
• 验收教师、班级、学生和成绩接口；
• 验收至少一个 Excel 模板和导入流程；
• 使用日志区分应用、数据库和权限问题；
• 保存一份可追踪的验收记录。

1. 先建立验收顺序

容器（Up / healthy）
        ↓
页面与静态资源（HTML / CSS / JS / 图片）
        ↓
业务流程（登录、读写和导入）

每一步都依赖前一步。页面打不开时先不要测试数据库；登录失败时先不要测试学生写入。

2. 服务层验收

cd /www/wwwroot/student-management-api
docker compose ps
docker compose logs --tail=100 api

现象	含义	下一步
Up / healthy	进程和基础 HTTP 检查通过	验收页面
Up / unhealthy	进程运行，但检查 URL 失败	查看日志和 /login
Exited	应用进程退出	先修启动错误
频繁重启	应用或数据库连接反复失败	查看完整日志时间线

3. 页面和静态资源验收

在 ECS 本机执行：

curl -s -o /dev/null -w "login=%{http_code}\n" http://127.0.0.1:8000/login
curl -s -o /dev/null -w "css=%{http_code}\n" http://127.0.0.1:8000/static/css/common.css
curl -s -o /dev/null -w "js=%{http_code}\n" http://127.0.0.1:8000/static/js/common.js
curl -s -o /dev/null -w "image=%{http_code}\n" http://127.0.0.1:8000/static/images/loginpage.jpg

本课程将 8000 绑定到 ECS 本机，所以浏览器不一定能直接访问公网 IP 加 8000。可以使用 SSH 端口转发，或等第 16 课配置 Nginx 域名。

浏览器开发者工具的 Network 面板可以检查 CSS、JavaScript、图片和字体是否 404。

4. 认证流程验收

登录接口是 POST /api/v1/auth/login，具体字段以 Swagger 文档为准：

curl -X POST http://127.0.0.1:8000/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=测试账号&password=测试密码"

成功时保存“返回了 token”这一结论即可，不要保存真实 token。然后在 Swagger /docs 中点击 Authorize，测试需要登录的接口。

**不要用生产管理员密码做截图。**验收记录中的用户名、密码和 token 全部替换为占位符。

5. 业务接口验收矩阵

业务	路由前缀	最小验收动作
教师/用户	/api/v1/users	登录后查询当前用户或用户列表
班级	/api/v1/grades	查询列表，必要时创建测试数据
学生	/api/v1/students	查询、创建、更新后删除测试数据
成绩	/api/v1/scores	查询成绩或统计接口
统计	/api/v1/grades/{id}/stats	用已有班级 ID 验证统计响应

写入测试数据前先确认数据库已备份，并使用明显的测试标记。生产环境不要随意删除真实学生数据。

6. Excel 流程验收

当前项目提供：

GET  /api/v1/students/excel-template
POST /api/v1/students/import
GET  /api/v1/scores/excel-template
POST /api/v1/scores/import

建议顺序：

1. 下载学生或成绩模板；
2. 复制一份模板，只填一条明确的测试数据；
3. 使用 Swagger 或页面上传；
4. 检查响应中的成功数和错误信息；
5. 再查询列表，确认数据确实写入 MySQL；
6. 删除或标记测试数据。

模板下载成功不等于导入成功；导入成功也要用查询接口确认数据。

7. 用日志定位失败层级

docker compose logs --tail=200 api
docker compose logs -f api

日志关键词	优先判断
404 static	镜像缺少静态文件或路径大小写错误
Access denied / Unknown database	MySQL 用户、密码、数据库名或 Host
Connection refused	DB_HOST、MySQL 监听或网络
422 Unprocessable Entity	请求字段或格式不符合接口模型
401/403	没有 token、token 过期或角色权限不足
500	应用异常；查看完整 traceback

按“HTTP 状态 → 应用日志 → 数据库日志”的顺序收集证据，不要只截图浏览器红字。

8. 验收记录模板

版本：
容器状态：
迁移版本：
页面 /login：
静态 CSS / JS / 图片：
登录接口：
用户接口：
班级接口：
学生接口：
成绩接口：
Excel 模板：
Excel 导入：
数据库读写：
异常与处理：
验收时间：

记录 Git 提交或标签，确保以后能知道验收的是哪个版本。

9. 一分钟自测

问题 1：为什么容器 Up 还不能说明项目验收通过？

• A. 还需要验证页面、静态资源、认证、数据库和业务流程
• B. Up 代表 MySQL 已经备份
• C. Up 代表所有接口都返回 200

问题 2：Excel 导入返回成功后还要做什么？

• A. 再查询接口确认数据真的写入数据库
• B. 立刻删除所有数据库表
• C. 关闭 Docker 日志

答案：1A，2A。

本课通关证据

docker compose ps
docker compose logs --tail=100 api
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/login
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/static/css/common.css

完成标准：登录页面、静态资源、认证、至少一个数据库读写流程和一个 Excel 流程通过；验收记录包含 Git 版本、迁移版本和异常处理。

如果遇到错误，请贴完整命令和输出，但隐藏密码、Token 与私钥。

---

← 第 14 课：SQLModel + Alembic · 第 16 课：Nginx 与域名 →