canglan/SharedClassManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 多班级版班级管理系统 v2.0

Browse Source 
技术栈：Go (Gin + GORM) + PHP + MySQL 5.7 + Redis

主要功能：
- 多班级完全隔离（class_id 贯穿全系统）
- 后端 Go Gin（端口 56789），Nginx 反代
- 超级管理员独立登录（env 配置，默认账密 admin/Admin123）
- bcrypt 密码加密（无 PASSWORD_SALT）
- 科任老师/课代表新角色
- 课代表作业管理页面
- 排行榜分项排行（操行分/考勤/作业）
- 角色加减分上下限由班主任配置
- 家长改密功能（可开关）
- 班级角色按需开关
- 宿舍号格式：南0-000
- 周度/月度重置功能
- MySQL 5.7 兼容
- 43 轮代码审查 + 全部修复

开发者: Canglan
版权归属: Sea Network Technology Studio
许可证: Apache License 2.0
This commit is contained in:
canglan
2026-06-22 10:21:52 +08:00
commit 16059ad3bf
135 changed files with 19933 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

572
INSTALL.md Normal file
View File

@@ -0,0 +1,572 @@
# 多班级版班级管理系统 - 安装部署指南
## 环境要求
### 服务器配置
- **操作系统**: Linux (Ubuntu 20.04+ / CentOS 7+)
- **CPU**: 2核+
- **内存**: 4GB+
- **磁盘**: 20GB+
### 软件依赖
| 软件 | 版本 | 用途 |
|------|------|------|
| Go | 1.21+ | 后端运行环境 |
| MySQL | 5.7+ | 数据存储 |
| Redis | 6.0+ | 缓存、会话 |
| Nginx | 1.18+ | Web服务器、反向代理 |
| PHP | 8.0+ | 前端页面处理 |
---
## 宝塔面板部署（推荐）
### 1. 安装宝塔面板
```bash
# 通用安装脚本（免登录版）
url=https://download.bt.cn/install/installStable.sh;if [ -f /usr/bin/curl ];then curl -sSO $url;else wget -O installStable.sh $url;fi;bash installStable.sh ed8484bec
```
安装完成后，根据提示访问宝塔面板地址，完成初始化设置。
### 2. 安装运行环境
在宝塔面板的"软件商店"中安装以下软件：
| 软件名称 | 版本要求 | 用途 |
|---------|---------|------|
| Nginx | 1.18+ | Web服务器 |
| MySQL | 5.7+ | 数据库 |
| Redis | 6.0+ | 缓存服务 |
| PHP | 8.0+ | 前端处理 |
### 3. 安装 Go 环境
在服务器上安装 Go 1.21+：
```bash
# 下载 Go（以 1.21.0 为例，请替换为最新稳定版）
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
# 解压到 /usr/local
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
# 配置环境变量
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
# 配置 Go 代理（国内环境必配，否则依赖拉取可能失败）
go env -w GOPROXY=https://goproxy.cn,direct
# 验证安装
go version
```
### 4. 创建数据库
在宝塔面板中：
1. 进入"数据库"菜单
2. 点击"添加数据库"
3. 填写数据库信息：
- 数据库名：`classmanagerdb`
- 用户名：`class_admin`
- 密码：生成强密码并保存
4. 点击"导入"，选择 `sql/init.sql` 文件导入
### 5. 部署 Go 后端
#### 5.1 上传代码
1. 进入宝塔面板"文件"菜单
2. 进入 `/www/wwwroot/` 目录
3. 上传或克隆代码到 `/www/wwwroot/SharedClassManager`
```bash
git clone https://hz-gitea.sea-studio.top/canglan/SharedClassManager.git /www/wwwroot/SharedClassManager
```
#### 5.2 配置环境变量
```bash
cd /www/wwwroot/SharedClassManager/backend-go
cp .env.example .env
vim .env # 根据实际环境修改配置
```
**必须修改的配置项**：
- `DB_USER` - 数据库用户名
- `DB_PASSWORD` - 数据库密码
- `JWT_SECRET_KEY` - JWT 密钥（使用下方命令生成）
**生成 JWT 密钥**：
```bash
openssl rand -base64 32
```
将输出的随机字符串填入 `.env` 的 `JWT_SECRET_KEY` 配置项。
#### 5.3 编译并运行
```bash
cd /www/wwwroot/SharedClassManager/backend-go
# 方式一：使用 Makefile（推荐，自动配置 GOPROXY）
make tidy
make build
# 方式二：手动编译（国内环境需指定 GOPROXY）
# GOPROXY=https://goproxy.cn,direct go mod tidy
# GOPROXY=https://goproxy.cn,direct go build -o sharedclassmanager ./cmd/server
```
#### 5.4 使用 Systemd 管理服务
创建 systemd 服务文件：
```bash
sudo vim /etc/systemd/system/sharedclassmanager.service
```
写入以下内容：
```ini
[Unit]
Description=SharedClassManager Go Backend
After=network.target mysql.service redis.service
[Service]
Type=simple
User=www-data
WorkingDirectory=/www/wwwroot/SharedClassManager/backend-go
ExecStart=/www/wwwroot/SharedClassManager/backend-go/sharedclassmanager
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl start sharedclassmanager
sudo systemctl enable sharedclassmanager
```
> 也可使用宝塔面板的"Python项目"管理器管理 Go 进程，将启动命令指向编译后的二进制文件即可。
### 6. 部署前端
#### 6.1 创建网站
1. 进入宝塔面板"网站"菜单
2. 点击"添加站点"：
- 域名：填写您的域名
- 根目录：`/www/wwwroot/SharedClassManager/frontend`
- PHP版本：8.0
#### 6.2 配置 Nginx 反向代理
在站点设置中，点击"配置文件"，替换为以下内容：
```nginx
server {
listen 80;
server_name your-domain.com;
root /www/wwwroot/SharedClassManager/frontend;
index index.php;
# PHP 处理
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
}
# Go API 反向代理
# 前后端通过 Nginx 反代同域通信，无需 CORS
location /api/ {
proxy_pass http://127.0.0.1:56789/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
3. 前端 `.env` 配置：
```
API_BASE_URL=https://your-domain.com
```
### 7. 配置 SSL 证书
1. 在站点设置中点击"SSL"
2. 选择"Let's Encrypt"免费证书
3. 勾选"强制HTTPS"
---
## 手动部署（无宝塔面板）
### 1. 安装系统依赖
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y golang-go mysql-server redis-server nginx php8.0 php8.0-fpm php8.0-mysql
# CentOS
sudo yum install -y golang mysql-server redis nginx php php-fpm php-mysql
```
### 2. 数据库配置
```bash
# 启动MySQL
sudo systemctl start mysqld
sudo systemctl enable mysqld
# 登录MySQL创建数据库
mysql -u root -p
```
```sql
CREATE DATABASE classmanagerdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'class_admin'@'localhost' IDENTIFIED BY 'YourStrongPassword';
GRANT ALL PRIVILEGES ON classmanagerdb.* TO 'class_admin'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```
导入初始化数据：
```bash
mysql -u class_admin -p classmanagerdb < sql/init.sql
```
### 3. Go 后端部署
```bash
# 创建项目目录
sudo mkdir -p /www/wwwroot/SharedClassManager
sudo chown -R $USER:$USER /www/wwwroot/SharedClassManager
# 上传代码
cd /www/wwwroot/SharedClassManager/backend-go
# 配置环境变量
cp .env.example .env
vim .env # 根据实际情况修改配置
# 生成 JWT 密钥
openssl rand -base64 32
# 将输出填入 .env 的 JWT_SECRET_KEY
# 编译（使用 Makefile 自动配置 GOPROXY）
make tidy
make build
# 或手动编译：
# GOPROXY=https://goproxy.cn,direct go mod tidy
# GOPROXY=https://goproxy.cn,direct go build -o sharedclassmanager ./cmd/server
# 使用 Systemd 管理服务
sudo vim /etc/systemd/system/sharedclassmanager.service
```
Systemd 服务文件内容：
```ini
[Unit]
Description=SharedClassManager Go Backend
After=network.target mysql.service redis.service
[Service]
Type=simple
User=www-data
WorkingDirectory=/www/wwwroot/SharedClassManager/backend-go
ExecStart=/www/wwwroot/SharedClassManager/backend-go/sharedclassmanager
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl start sharedclassmanager
sudo systemctl enable sharedclassmanager
```
### 4. 前端部署
Nginx 配置示例：
```nginx
server {
listen 80;
server_name your-domain.com;
root /www/wwwroot/SharedClassManager/frontend;
index index.php;
# PHP 处理
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
}
# Go API 反向代理
# 前后端通过 Nginx 反代同域通信，无需 CORS
location /api/ {
proxy_pass http://127.0.0.1:56789/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
启用站点：
```bash
sudo ln -s /etc/nginx/sites-available/sharedclassmanager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```
---
## 密码加密说明
系统使用 **bcrypt** 算法进行密码哈希，bcrypt 内置随机盐值管理机制。
- **无需配置 `PASSWORD_SALT`**：已移除该环境变量，bcrypt 自动生成盐值并嵌入哈希结果中，无需外部管理。
- **密码强度要求**：密码长度 6-20 位，必须包含大写字母、小写字母、数字、特殊符号中的至少 3 种。
- **兼容性**：所有用户（超级管理员、普通管理员、学生、家长）均使用 bcrypt 统一加密。
---
## MySQL 5.7 兼容说明
系统已针对 MySQL 5.7 进行兼容适配：
- **已移除 CHECK 约束**：初始化 SQL 不包含 MySQL 8.0.16+ 才支持的 CHECK 约束语法。
- **已移除窗口函数**：不使用 ROW_NUMBER()、RANK() 等 8.0+ 窗口函数。
- **索引创建兼容**：通过存储过程安全创建索引，避免在 5.7 中直接使用 `IF NOT EXISTS` 等不兼容语法。
- **字符集**：统一使用 `utf8mb4` + `utf8mb4_unicode_ci`，兼容 5.7 和 8.0。
> **建议**：推荐使用 MySQL 5.7.8+ 版本（支持 JSON 类型）。如使用 MySQL 8.0+，所有功能同样兼容。
---
## 超级管理员首次登录
Go 后端首次启动时会**自动创建**超级管理员账号，无需手动操作。
### 默认账号信息
| 配置项 | 环境变量 | 默认值 |
|-------|---------|-------|
| 登录路径 | `SUPER_ADMIN_LOGIN_PATH` | `/super-admin` |
| 用户名 | `SUPER_ADMIN_DEFAULT_USERNAME` | `admin` |
| 密码 | `SUPER_ADMIN_DEFAULT_PASSWORD` | `Admin123` |
### 首次登录流程
1. 启动 Go 后端服务
2. 访问 `https://your-domain.com/SUPER_ADMIN_LOGIN_PATH`（路径由 `.env` 中 `SUPER_ADMIN_LOGIN_PATH` 配置）
3. 使用默认用户名和密码登录
4. **系统强制要求修改密码**：首次登录后将自动跳转到改密页面，修改密码后方可进入管理后台
> **安全提示**：强烈建议在 `.env` 中将 `SUPER_ADMIN_DEFAULT_PASSWORD` 修改为强密码后再启动服务，避免使用默认密码暴露在生产环境中。
---
## 多班级使用流程
### 完整操作步骤
1. **系统管理员登录** — 使用超级管理员账号登录管理后台
2. **创建班级** — 在"班级管理"中创建班级（可设置年级、描述等信息）
3. **为班级添加班主任** — 在"管理员管理"中创建普通管理员账号，并关联到对应班级
4. **班主任登录并配置班级** — 班主任首次登录后：
- 导入学生名单（支持 JSON 批量导入）
- 配置班级设置（扣分规则、初始积分等）
- 启用/禁用班级功能开关
5. **各角色开始使用**
- **班主任/管理员**：考勤管理、操行分管理、作业管理、排行榜查看
- **课代表**：发布和管理作业
- **学生**：查看个人信息、考勤记录、作业、排行榜
- **家长**：查看学生考勤和历史记录、修改密码
### 班级设置说明
班主任可在管理端"班级设置"页面自定义本班配置，包括：
- **扣分规则**：缺勤扣分、迟到扣分、未交作业扣分、迟交作业扣分等
- **初始积分**：新学生入班时的默认积分
- **功能开关**：按需启用或禁用各项班级功能
> **注意**：扣分规则等班级级配置已迁移到数据库 `class_settings` 表中，班主任可在管理端自行修改，无需修改环境变量。
---
## 新增功能说明
### 周期重置（周/月）
系统支持按周期重置学生积分：
- **周重置**：每周一自动将学生积分重置为初始值
- **月重置**：每月 1 日自动将学生积分重置为初始值
- 周期类型在班级设置中配置，历史数据保留在学期记录中
### 课代表作业管理
班主任可为管理员分配"课代表"角色，使其拥有作业管理权限：
- 课代表可发布作业（标题、描述、截止时间）
- 课代表可查看作业提交情况
- 学生端可查看作业列表及截止时间
### 排行榜分项排行
排行榜支持按类别分项查看：
- **综合排行**：所有积分汇总排名
- **考勤排行**：仅考勤相关积分排名
- **作业排行**：仅作业相关积分排名
- **操行排行**：仅操行分相关积分排名
### 家长改密（可开关）
家长账号支持修改学生密码，该功能可通过班级功能开关控制：
- **开启**：家长登录后可在"修改密码"页面为学生修改密码
- **关闭**：家长端不显示改密入口，密码仅由班主任管理
### 班级角色开关
系统支持为每个班级独立启用/禁用功能模块：
- 考勤管理
- 操行分管理
- 作业管理
- 排行榜
- 家长改密
- 等更多可配置项
> 功能开关存储在数据库 `class_features` 表中，班主任可在"班级设置"页面管理。
---
## 环境变量说明
Go 后端 `.env` 文件全部配置项（参考 `backend-go/.env.example`）：
### 应用配置
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `APP_NAME` | 应用名称 | 多班级版班级管理系统 |
| `APP_ENV` | 运行环境 | production |
| `DEBUG` | 调试模式（生产环境设为 false） | false |
| `APP_PORT` | 服务端口 | 56789 |
### MySQL 数据库
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `DB_HOST` | 数据库地址 | localhost |
| `DB_PORT` | 数据库端口 | 3306 |
| `DB_USER` | 数据库用户名 | class_admin |
| `DB_PASSWORD` | 数据库密码 | *(无默认值，必须配置)* |
| `DB_NAME` | 数据库名 | classmanagerdb |
| `DB_MAX_OPEN_CONNS` | 最大打开连接数 | 25 |
| `DB_MAX_IDLE_CONNS` | 最大空闲连接数 | 10 |
| `DB_CONN_MAX_LIFETIME` | 连接最大生命周期(秒) | 300 |
### Redis 缓存
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `REDIS_HOST` | Redis 地址 | localhost |
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码（可选，留空则无密码） | *(空)* |
| `REDIS_DB` | Redis 数据库编号 | 0 |
| `REDIS_MAX_CONNECTIONS` | 最大连接数 | 500 |
### JWT 认证
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `JWT_SECRET_KEY` | JWT 密钥（32位以上随机字符串，**必填**） | *(无默认值，必须配置)* |
| `JWT_ALGORITHM` | JWT 签名算法 | HS256 |
| `JWT_EXPIRE_MINUTES` | Token 过期时间(分钟) | 60 |
| `JWT_IDLE_TIMEOUT_MINUTES` | 空闲超时时间(分钟) | 10 |
> **生成方法**：`openssl rand -base64 32`
### 超级管理员
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `SUPER_ADMIN_LOGIN_PATH` | 超级管理员登录页面路径 | /super-admin |
| `SUPER_ADMIN_DEFAULT_USERNAME` | 默认超级管理员用户名 | admin |
| `SUPER_ADMIN_DEFAULT_PASSWORD` | 默认超级管理员密码（**部署时必须修改**） | Admin123 |
### 日志配置
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `LOG_LEVEL` | 日志级别（debug/info/warn/error） | info |
| `LOG_FILE` | 日志文件路径 | logs/app.log |
> **注意**：密码加密使用 bcrypt 自动加盐，无需配置 `PASSWORD_SALT`。扣分规则等班级级配置已迁移到数据库 `class_settings` 表中，班主任可在管理端"班级设置"页面修改，无需修改环境变量。
---
## 常见问题
### Q1: 后端启动失败
- 检查端口 56789 是否被占用：`sudo lsof -i :56789`
- 检查数据库和 Redis 连接配置
- 确认 `JWT_SECRET_KEY` 已配置（不能为空）
- 查看日志：`sudo journalctl -u sharedclassmanager -f`
### Q2: 前端页面空白或报错
- 检查 Nginx 配置中的 root 路径
- 检查 PHP-FPM 是否运行：`sudo systemctl status php8.0-fpm`
- 检查文件权限：`sudo chown -R www-data:www-data /www/wwwroot/SharedClassManager`
### Q3: API 请求 404
- 检查反向代理配置是否正确（`/api/` → `127.0.0.1:56789`）
- 确认 Go 后端服务已启动：`sudo systemctl status sharedclassmanager`
- 检查防火墙设置
### Q4: 数据库连接失败
- 确认 MySQL 已启动
- 检查 `.env` 中的数据库用户名、密码、数据库名
- 确认用户有数据库权限
### Q5: Go 编译失败
- 确认 Go 版本 >= 1.21：`go version`
- 执行 `make tidy` 拉取依赖（Makefile 已内置 GOPROXY 配置）
- 或手动配置 Go 代理：`go env -w GOPROXY=https://goproxy.cn,direct`
- 检查网络连接（国内环境访问 Google 服务受限，必须配置 GOPROXY）
### Q6: 首次登录后忘记修改默认密码
- 默认超管密码通过 `.env` 中 `SUPER_ADMIN_DEFAULT_PASSWORD` 设置
- 首次登录系统会强制跳转到改密页面
- 如需重置密码，可修改 `.env` 中的密码配置后重启服务，系统将使用新密码重新初始化
### Q7: MySQL 5.7 导入 SQL 报错
- 确认使用项目提供的 `sql/init.sql`，已针对 5.7 兼容
- 如从旧版本升级，请先备份数据库再执行导入
---
## 技术支持
- 开发者: Canglan
- 联系方式: admin@sea-studio.top
- 版权归属: Sea Network Technology Studio
- 许可证: Apache License 2.0