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

技术栈：Go (Gin + GORM) + PHP + MySQL 5.7 + Redis 主要功能： - 多班级完全隔离（class_id 贯穿全系统） - 后端从 Python FastAPI 重写为 Go Gin（端口 56789） - 超级管理员独立登录（env 配置路径，默认账密 admin/Admin123） - 科任老师/课代表新角色 - 课代表作业管理页面 - 排行榜分项排行（操行分/考勤/作业） - 角色加减分上下限由班主任配置 - 家长改密功能（可开关） - 班级角色按需开关 - 宿舍号格式：南0-000 - 周度/月度重置功能 - MySQL 5.7 兼容 - Nginx 反向代理部署开发者: Canglan 版权归属: Sea Network Technology Studio 许可证: Apache License 2.0
2026-06-22 10:21:52 +08:00
commit 124d7f645e
140 changed files with 21103 additions and 0 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -0,0 +1,455 @@
+# 多班级版班级管理系统 - 安装部署指南
+
+## 环境要求
+
+### 服务器配置
+- **操作系统**: 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 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密钥（32位以上随机字符串）
+- `PASSWORD_SALT` - 密码加密盐值
+
+#### 5.3 编译并运行
+
+```bash
+cd /www/wwwroot/SharedClassManager/backend-go
+go mod tidy
+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"
+
+### 8. 初始化系统管理员
+
+Go 后端首次启动时会**自动创建**超级管理员账号，登录信息从环境变量读取：
+
+- **登录路径**：由 `SUPER_ADMIN_LOGIN_PATH` 配置（默认 `/super-admin/login`）
+- **默认用户名**：由 `SUPER_ADMIN_DEFAULT_USERNAME` 配置（默认 `admin`）
+- **默认密码**：由 `SUPER_ADMIN_DEFAULT_PASSWORD` 配置（默认 `Admin123`）
+
+> **注意**：首次登录后请立即修改密码。
+
+---
+
+## 手动部署（无宝塔面板）
+
+### 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  # 根据实际情况修改配置
+
+# 编译
+go mod tidy
+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
+```
+
+---
+
+## 环境变量说明
+
+Go 后端 `.env` 文件全部配置项（参考 `backend-go/.env.example`）：
+
+### 应用配置
+| 配置项 | 说明 | 示例 |
+|-------|------|------|
+| `APP_NAME` | 应用名称 | 多班级版班级管理系统 |
+| `APP_ENV` | 运行环境 | production / development |
+| `DEBUG` | 调试模式 | false（生产环境） |
+| `APP_PORT` | 服务端口 | 56789 |
+
+### MySQL 数据库
+| 配置项 | 说明 | 示例 |
+|-------|------|------|
+| `DB_HOST` | 数据库地址 | localhost |
+| `DB_PORT` | 数据库端口 | 3306 |
+| `DB_USER` | 数据库用户名 | class_admin |
+| `DB_PASSWORD` | 数据库密码 | YourPassword |
+| `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 |
+
+### 密码加密
+| 配置项 | 说明 | 示例 |
+|-------|------|------|
+| `PASSWORD_SALT` | 密码加密盐值 | your-fixed-salt-string |
+
+### 系统管理员
+| 配置项 | 说明 | 示例 |
+|-------|------|------|
+| `SUPER_ADMIN_LOGIN_PATH` | 超级管理员登录路径 | /super-admin/login |
+| `SUPER_ADMIN_DEFAULT_USERNAME` | 默认用户名 | admin |
+| `SUPER_ADMIN_DEFAULT_PASSWORD` | 默认密码 | Admin123 |
+
+### 日志配置
+| 配置项 | 说明 | 示例 |
+|-------|------|------|
+| `LOG_LEVEL` | 日志级别 | info |
+| `LOG_FILE` | 日志文件路径 | logs/app.log |
+
+> **注意**：扣分规则等班级级配置已迁移到数据库 `class_settings` 表中，班主任可在管理端"班级设置"页面修改，无需修改环境变量。
+
+---
+
+## 初始化系统管理员
+
+Go 后端首次启动时会**自动创建**超级管理员账号，无需手动操作：
+
+1. 确认 `.env` 中以下配置项已正确设置：
+   - `SUPER_ADMIN_LOGIN_PATH` — 登录页面路径
+   - `SUPER_ADMIN_DEFAULT_USERNAME` — 默认用户名
+   - `SUPER_ADMIN_DEFAULT_PASSWORD` — 默认密码
+2. 启动 Go 后端服务
+3. 访问 `https://your-domain.com/{SUPER_ADMIN_LOGIN_PATH}` 登录
+4. 首次登录后请**立即修改密码**
+5. 创建班级，然后为班级指定班主任
+
+---
+
+## 多班级使用流程
+
+1. 系统管理员登录 → 创建班级
+2. 为班级添加班主任（管理员管理）
+3. 班主任登录 → 导入学生 → 开始使用
+4. 班主任可在"班级设置"中自定义本班扣分规则和功能开关
+
+---
+
+## 常见问题
+
+### Q1: 后端启动失败
+- 检查端口 56789 是否被占用：`sudo lsof -i :56789`
+- 检查数据库和 Redis 连接配置
+- 查看日志：`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`
+- 执行 `go mod tidy` 拉取依赖
+- 检查网络连接（可能需要配置 Go 代理：`go env -w GOPROXY=https://goproxy.cn,direct`）
+
+---
+
+## 技术支持
+
+- 开发者: Canglan
+- 联系方式: admin@sea-studio.top
+- 版权归属: Sea Network Technology Studio
+- 许可证: Apache License 2.0