Initial commit: secondary school grade archive system.
Add FastAPI/React app with Docker deployment, Ubuntu one-click install, and docs for junior/senior high score tracking and mistake bank. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
+304
@@ -0,0 +1,304 @@
|
||||
# Ubuntu 部署文档
|
||||
|
||||
> **中学成绩档案系统**（Secondary School Grade Archive）
|
||||
> 版权所有 © 马建军 · 微信 **dekun03** · 手机 **18364911125**
|
||||
> 代码仓库：[https://git.bz121.com/dekun/secondary-school-grade-archive.git](https://git.bz121.com/dekun/secondary-school-grade-archive.git)
|
||||
|
||||
---
|
||||
|
||||
## 1. 部署概述
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 目标系统 | Ubuntu 20.04 / 22.04 / 24.04（推荐 22.04+） |
|
||||
| 运行用户 | **root**（一键脚本要求） |
|
||||
| 安装目录 | **`/opt/secondary-school-grade-archive`** |
|
||||
| 部署方式 | Docker Compose |
|
||||
| 对外端口 | **`23566`**（HTTP，可在 `.env` 修改 `WEB_PORT`） |
|
||||
| 反向代理 | **不包含在本项目中**，需用户自行配置 Nginx/Caddy 等 |
|
||||
|
||||
### 1.1 架构说明
|
||||
|
||||
```
|
||||
浏览器 ──► :23566 (Nginx/Web) ──► API (内部) ──► PostgreSQL (内部)
|
||||
│
|
||||
└──► Ollama (宿主机，可选)
|
||||
└──► uploads/ (宿主机挂载)
|
||||
```
|
||||
|
||||
- **Web**：Nginx 提供前端静态文件，并将 `/api` 反向代理到后端容器
|
||||
- **API**：FastAPI，不直接暴露端口到宿主机
|
||||
- **PostgreSQL**：仅 Docker 内网访问，不映射宿主机端口
|
||||
- **Ollama**：可选，运行在宿主机，容器通过 `host.docker.internal` 访问
|
||||
|
||||
---
|
||||
|
||||
## 2. 环境要求
|
||||
|
||||
### 2.1 硬件（建议）
|
||||
|
||||
| 资源 | 最低 | 推荐 |
|
||||
|------|------|------|
|
||||
| CPU | 2 核 | 4 核+ |
|
||||
| 内存 | 2 GB | 4 GB+（启用 OCR 建议 8 GB） |
|
||||
| 磁盘 | 10 GB | 20 GB+ |
|
||||
|
||||
### 2.2 软件
|
||||
|
||||
- Ubuntu Server（64 位）
|
||||
- 可访问互联网（拉取 Docker 镜像与 Git 仓库）
|
||||
- 防火墙放行 **23566/TCP**（若需外网访问）
|
||||
|
||||
### 2.3 端口
|
||||
|
||||
| 端口 | 用途 | 是否必须对外开放 |
|
||||
|------|------|------------------|
|
||||
| **23566** | Web 前端 + API（经 Nginx 统一入口） | 是 |
|
||||
| 11434 | Ollama（宿主机，错题 AI 解法） | 仅本机，可不对外 |
|
||||
| 5432 | PostgreSQL | **否**（已关闭对外映射） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 一键部署（推荐）
|
||||
|
||||
以 **root** 登录 Ubuntu 服务器后执行：
|
||||
|
||||
```bash
|
||||
# 方式 A：克隆后执行（仓库已有代码时）
|
||||
git clone https://git.bz121.com/dekun/secondary-school-grade-archive.git /opt/secondary-school-grade-archive
|
||||
cd /opt/secondary-school-grade-archive
|
||||
chmod +x deploy/*.sh
|
||||
bash deploy/install.sh
|
||||
```
|
||||
|
||||
```bash
|
||||
# 方式 B：仅下载安装脚本（仓库已推送 install.sh 后）
|
||||
export WEB_PORT=23566
|
||||
export INSTALL_DIR=/opt/secondary-school-grade-archive
|
||||
curl -fsSL https://git.bz121.com/dekun/secondary-school-grade-archive/raw/branch/main/deploy/install.sh -o /tmp/install.sh
|
||||
chmod +x /tmp/install.sh
|
||||
bash /tmp/install.sh
|
||||
```
|
||||
|
||||
### 3.1 脚本自动完成的事项
|
||||
|
||||
1. 检测是否为 root 用户
|
||||
2. 检测 Ubuntu/Debian 系操作系统
|
||||
3. 检测内存、磁盘（不足时警告）
|
||||
4. 检测 **23566** 端口是否占用
|
||||
5. 安装 `git`、`curl`、`openssl` 等基础工具
|
||||
6. 若未安装 Docker，自动安装 **Docker CE + Compose 插件**
|
||||
7. 克隆/更新代码到 `/opt/secondary-school-grade-archive`
|
||||
8. 自动生成 `.env`（随机 `SECRET_KEY`、数据库密码）
|
||||
9. `docker compose up -d --build` 构建并启动
|
||||
10. 等待 API 健康检查通过后输出访问地址
|
||||
|
||||
### 3.2 部署成功后的访问
|
||||
|
||||
```
|
||||
http://<服务器IP>:23566
|
||||
```
|
||||
|
||||
首次使用请在页面 **注册** 账号，然后登录添加学生。
|
||||
|
||||
---
|
||||
|
||||
## 4. 环境变量（`.env`）
|
||||
|
||||
部署后配置文件位于：
|
||||
|
||||
```
|
||||
/opt/secondary-school-grade-archive/.env
|
||||
```
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `WEB_PORT` | `23566` | Web 对外端口 |
|
||||
| `SECRET_KEY` | 自动生成 | JWT 密钥，生产环境请勿泄露 |
|
||||
| `POSTGRES_PASSWORD` | 自动生成 | 数据库密码 |
|
||||
| `CORS_ORIGINS` | 含服务器 IP | 前端跨域白名单 |
|
||||
| `OLLAMA_BASE_URL` | `http://host.docker.internal:11434` | Ollama 地址 |
|
||||
| `OLLAMA_MODEL` | `qwen2.5:7b` | 模型名称 |
|
||||
| `FLUCTUATION_THRESHOLD` | `0.08` | 成绩波动高亮阈值（8%） |
|
||||
|
||||
修改 `.env` 后重启：
|
||||
|
||||
```bash
|
||||
cd /opt/secondary-school-grade-archive
|
||||
docker compose --env-file .env up -d
|
||||
```
|
||||
|
||||
修改 `WEB_PORT` 后需重新创建容器：
|
||||
|
||||
```bash
|
||||
docker compose --env-file .env up -d --force-recreate web
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 常用运维命令
|
||||
|
||||
```bash
|
||||
cd /opt/secondary-school-grade-archive
|
||||
|
||||
# 查看运行状态
|
||||
docker compose ps
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
docker compose logs -f api
|
||||
docker compose logs -f web
|
||||
|
||||
# 停止服务
|
||||
docker compose down
|
||||
|
||||
# 启动服务
|
||||
docker compose --env-file .env up -d
|
||||
|
||||
# 更新版本（拉代码 + 重建）
|
||||
bash deploy/update.sh
|
||||
|
||||
# 数据备份
|
||||
bash deploy/backup.sh
|
||||
|
||||
# 卸载容器（保留数据）
|
||||
bash deploy/uninstall.sh
|
||||
|
||||
# 卸载并删除数据库卷（危险）
|
||||
REMOVE_VOLUMES=1 bash deploy/uninstall.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Ollama 可选配置（错题 AI 解法）
|
||||
|
||||
错题上传后的「整理题目 / 生成解法」依赖宿主机 Ollama。若不安装，OCR 仍可用，AI 解法需手动填写。
|
||||
|
||||
```bash
|
||||
# 安装 Ollama（参考 https://ollama.com）
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
|
||||
# 拉取模型
|
||||
ollama pull qwen2.5:7b
|
||||
|
||||
# 确认服务运行
|
||||
curl http://127.0.0.1:11434/api/tags
|
||||
```
|
||||
|
||||
确保 `.env` 中：
|
||||
|
||||
```
|
||||
OLLAMA_BASE_URL=http://host.docker.internal:11434
|
||||
OLLAMA_MODEL=qwen2.5:7b
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 反向代理（用户自行配置）
|
||||
|
||||
**本项目不包含 HTTPS、域名、反向代理配置。** 若需通过域名访问或启用 HTTPS，请在宿主机自行配置 Nginx/Caddy/Traefik 等。
|
||||
|
||||
### 7.1 原则
|
||||
|
||||
- 反向代理将流量转发到 **`http://127.0.0.1:23566`**
|
||||
- 代理需支持 **WebSocket**（若未来扩展）及 **大文件上传**（错题图片最大 10MB）
|
||||
- 代理 `/api` 与 `/` 均应转发到同一 upstream（本项目 Nginx 已统一处理）
|
||||
|
||||
### 7.2 Nginx 示例（仅供参考，不包含在项目中）
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name grade.example.com;
|
||||
|
||||
ssl_certificate /path/to/fullchain.pem;
|
||||
ssl_certificate_key /path/to/privkey.pem;
|
||||
client_max_body_size 10M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:23566;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
使用 HTTPS 反向代理后，请同步修改 `.env` 中的 `CORS_ORIGINS`，加入 `https://grade.example.com`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 防火墙示例（UFW）
|
||||
|
||||
```bash
|
||||
ufw allow 22/tcp
|
||||
ufw allow 23566/tcp
|
||||
ufw enable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 故障排查
|
||||
|
||||
| 现象 | 处理 |
|
||||
|------|------|
|
||||
| 无法访问 23566 | `docker compose ps` 确认 web 运行；`ufw status` 检查防火墙 |
|
||||
| 注册/登录 502 | `docker compose logs api` 查看后端；确认 db 健康 |
|
||||
| OCR 很慢/失败 | 首次运行需下载 PaddleOCR 模型；查看 api 日志 |
|
||||
| AI 解法失败 | 确认宿主机 Ollama 运行；`curl host.docker.internal:11434` 从 api 容器内测试 |
|
||||
| 端口被占用 | 修改 `.env` 中 `WEB_PORT` 或释放占用进程 |
|
||||
|
||||
进入 API 容器调试：
|
||||
|
||||
```bash
|
||||
docker compose exec api bash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 数据备份与恢复
|
||||
|
||||
### 备份
|
||||
|
||||
```bash
|
||||
bash /opt/secondary-school-grade-archive/deploy/backup.sh
|
||||
```
|
||||
|
||||
生成文件位于 `backups/`：
|
||||
|
||||
- `db_YYYYMMDD_HHMMSS.sql` — 数据库
|
||||
- `uploads_YYYYMMDD_HHMMSS.tar.gz` — 错题图片
|
||||
|
||||
### 恢复数据库（示例）
|
||||
|
||||
```bash
|
||||
cd /opt/secondary-school-grade-archive
|
||||
docker compose exec -T db psql -U postgres student_archive < backups/db_XXXXXX.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 版权与授权
|
||||
|
||||
本软件著作权归 **马建军** 所有。部署和使用须遵守 [LICENSE](../LICENSE) 与 [COPYRIGHT.md](../COPYRIGHT.md)。
|
||||
|
||||
- 微信：**dekun03**
|
||||
- 手机：**18364911125**
|
||||
|
||||
未经授权不得用于商业分发或去除版权信息。
|
||||
|
||||
---
|
||||
|
||||
## 12. 自定义安装参数
|
||||
|
||||
```bash
|
||||
# 自定义端口
|
||||
WEB_PORT=23566 bash deploy/install.sh
|
||||
|
||||
# 自定义目录
|
||||
INSTALL_DIR=/opt/my-grade-app bash deploy/install.sh
|
||||
|
||||
# 指定分支
|
||||
BRANCH=main bash deploy/install.sh
|
||||
```
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
# 使用说明
|
||||
|
||||
> **中学成绩档案系统**（初中 / 高中）
|
||||
> 版权所有 © 马建军 · 微信 **dekun03** · 手机 **18364911125**
|
||||
|
||||
---
|
||||
|
||||
## 1. 系统简介
|
||||
|
||||
本系统面向**初中、高中**学生，提供：
|
||||
|
||||
- 多用户账号，数据互相隔离
|
||||
- 学生档案管理（学段、年级、班级）
|
||||
- 成绩录入：周考、月考、期末
|
||||
- 分科成绩占比曲线（上升绿色、下降红色、大幅波动高亮）
|
||||
- 错题库：拍照上传 → OCR 识别 → AI 生成解法（可编辑）
|
||||
- 成绩 CSV 导出
|
||||
|
||||
部署方式见 [DEPLOY.md](./DEPLOY.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 快速上手
|
||||
|
||||
### 2.1 登录与注册
|
||||
|
||||
1. 浏览器打开 `http://<服务器IP>:23566`
|
||||
2. 首次使用点击 **注册**，设置用户名（≥3 字符）和密码（≥6 字符）
|
||||
3. 注册成功后自动登录
|
||||
|
||||
> 系统无默认管理员账号，首个注册用户即为普通用户，数据仅本人可见。
|
||||
|
||||
### 2.2 添加学生
|
||||
|
||||
1. 首页点击 **添加学生**
|
||||
2. 填写：
|
||||
- **姓名**（必填）
|
||||
- **学段**：初中 / 高中
|
||||
- **年级**：初一～初三 或 高一～高三
|
||||
- **班级**：如「3班」（可选）
|
||||
3. 保存后在卡片上可看到学段标签
|
||||
|
||||
### 2.3 录入成绩
|
||||
|
||||
进入学生详情 → **成绩录入** 标签：
|
||||
|
||||
1. 点击 **录入成绩**
|
||||
2. 选择 **考试类型**：周考 / 月考 / 期末
|
||||
3. 选择 **考试日期**
|
||||
4. 在表格中填写各科 **总分**、**得分**（未考科目可留空）
|
||||
5. 系统自动计算 **占比**
|
||||
6. 保存后在列表中可编辑或删除
|
||||
|
||||
**校验规则：**
|
||||
|
||||
- 总分必须 > 0
|
||||
- 得分不能大于总分
|
||||
- 至少录入一科成绩
|
||||
|
||||
---
|
||||
|
||||
## 3. 成绩分析
|
||||
|
||||
### 3.1 成绩总览
|
||||
|
||||
**成绩总览** 标签以表格展示历次考试各科得分与占比。
|
||||
|
||||
- 顶部 **波动预警** 会标记相邻两次占比变化 ≥ 8% 的考试
|
||||
- 可横向滚动查看所有科目
|
||||
|
||||
### 3.2 分科曲线
|
||||
|
||||
**分科曲线** 标签：
|
||||
|
||||
1. 选择科目
|
||||
2. 查看占比（%）随时间变化折线图
|
||||
|
||||
**图例说明：**
|
||||
|
||||
| 元素 | 含义 |
|
||||
|------|------|
|
||||
| 绿色线段 | 较上一次占比 **上升** |
|
||||
| 红色线段 | 较上一次占比 **下降** |
|
||||
| 橙色大圆点 | **大幅波动**（变化 ≥ 8%） |
|
||||
| Tooltip | 显示日期、考试类型、占比、较上次变化 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 错题库
|
||||
|
||||
### 4.1 上传错题
|
||||
|
||||
进入 **错题库** 标签：
|
||||
|
||||
1. 选择 **科目**
|
||||
2. 点击 **上传错题图片**（支持 jpg/png/webp，最大 10MB）
|
||||
3. 上传后后台自动：**OCR 识别 → AI 整理题目 → 生成解法**
|
||||
4. 处理状态：处理中 → 已识别 → 已生成解法
|
||||
|
||||
> AI 解法依赖服务器上的 **Ollama**。未配置时仍可 OCR，解法需手动填写。
|
||||
|
||||
### 4.2 查看与编辑
|
||||
|
||||
点击错题卡片打开详情：
|
||||
|
||||
- **左侧**：原始试卷图片、OCR 原文
|
||||
- **右侧**：识别题目、解法（均可编辑）
|
||||
- **保存编辑**：手动修正后点击保存
|
||||
- **重新 OCR**：识别不准时可重试
|
||||
- **重新生成解法**：基于当前题目重新调用 AI
|
||||
|
||||
> 解法标注「AI 生成，请核对」，使用前请人工确认。
|
||||
|
||||
### 4.3 筛选与搜索
|
||||
|
||||
- 按 **科目** 筛选
|
||||
- **搜索** 题目/解法关键词
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据导出
|
||||
|
||||
学生详情页点击 **导出 CSV**，下载该生全部成绩记录，可用 Excel 打开。
|
||||
|
||||
---
|
||||
|
||||
## 6. 预置科目
|
||||
|
||||
语文、数学、英语、物理、化学、生物、历史、地理、政治。
|
||||
|
||||
---
|
||||
|
||||
## 7. 常见问题
|
||||
|
||||
**Q：忘记密码怎么办？**
|
||||
A：当前版本无找回密码功能，需管理员在数据库中重置或重新注册（生产环境建议后续增加找回流程）。
|
||||
|
||||
**Q：多人能否共用一台服务器？**
|
||||
A：可以。每人注册独立账号，数据互不可见。
|
||||
|
||||
**Q：能否同时管理初中和高中孩子？**
|
||||
A：可以。添加学生时分别选择学段即可。
|
||||
|
||||
**Q：换手机/电脑能否访问？**
|
||||
A：可以。使用同一服务器地址与账号登录即可。
|
||||
|
||||
**Q：HTTPS 和域名怎么配置？**
|
||||
A：本项目不包含反向代理配置，请参考 [DEPLOY.md 第 7 节](./DEPLOY.md#7-反向代理用户自行配置) 自行设置。
|
||||
|
||||
---
|
||||
|
||||
## 8. 技术支持与版权
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 作者 | 马建军 |
|
||||
| 微信 | dekun03 |
|
||||
| 手机 | 18364911125 |
|
||||
| 仓库 | [secondary-school-grade-archive](https://git.bz121.com/dekun/secondary-school-grade-archive.git) |
|
||||
|
||||
使用本软件须遵守 [LICENSE](../LICENSE) 与 [COPYRIGHT.md](../COPYRIGHT.md)。
|
||||
商业使用或二次分发请联系作者取得授权。
|
||||
Reference in New Issue
Block a user