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

feat: 多班级版 v2.0 - Go后端重写 + 43轮代码审查

Browse Source 
- 后端从 Python FastAPI 重写为 Go Gin（端口 56789）
- 多班级完全隔离
- 超级管理员独立登录
- 课代表作业管理、排行榜分项排行
- 角色加减分上下限可配置
- 家长改密功能（可开关）
- 周度/月度重置功能
- MySQL 5.7 兼容
- 43轮代码审查+全部修复
- Apache 2.0 许可证
This commit is contained in:
canglan
2026-06-22 10:06:10 +08:00
parent 4084afc53c
commit d6dec878bd
214 changed files with 12622 additions and 9725 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
INSTALL.md
View File

@@ -1,4 +1,4 @@
# 班级操行分管理系统 - 安装部署指南
# 多班级版班级管理系统 - 安装部署指南
## 环境要求
@@ -11,7 +11,7 @@
### 软件依赖
| 软件 | 版本 | 用途 |
|------|------|------|
| Python | 3.9+ | 后端运行环境 |
| Go | 1.21+ | 后端运行环境 |
| MySQL | 5.7+ | 数据存储 |
| Redis | 6.0+ | 缓存、会话 |
| Nginx | 1.18+ | Web服务器、反向代理 |
@@ -36,150 +36,174 @@ url=https://download.bt.cn/install/installStable.sh;if [ -f /usr/bin/curl ];then
| 软件名称 | 版本要求 | 用途 |
|---------|---------|------|
| Nginx | 1.21+ | Web服务器 |
| Nginx | 1.18+ | Web服务器 |
| MySQL | 5.7+ | 数据库 |
| Redis | 6.0+ | 缓存服务 |
| PHP | 8.0+ | 前端处理 |
| Python项目管理器 | 最新版 | 后端部署 |
### 3. 创建数据库
### 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. 填写数据库信息：
- 数据库名：`class_manager`
- 用户名：`class_user`
- 数据库名：`classmanagerdb`
- 用户名：`class_admin`
- 密码：生成强密码并保存
4. 点击"导入"，选择 `sql/init.sql` 文件导入
### 4. 部署后端服务
### 5. 部署 Go 后端
#### 4.1 上传代码
#### 5.1 上传代码
1. 进入宝塔面板"文件"菜单
2. 进入 `/www/wwwroot/` 目录
3. 创建项目目录 `classmanager`
4. 上传或克隆代码到 `/www/wwwroot/classmanager`
#### 4.2 使用Python项目管理器部署
1. 进入宝塔面板"网站 -> Python项目"
2. 点击"添加项目"：
- 项目路径：`/www/wwwroot/classmanager/backend`
- Python版本：3.9+
- 框架：FastAPI
- 启动方式：`uvicorn main:app --host 127.0.0.1 --port 8000 --workers 4`
- 项目名称：`classmanager_backend`
#### 4.3 配置环境变量
在 `/www/wwwroot/classmanager/backend/` 目录下：
3. 上传或克隆代码到 `/www/wwwroot/SharedClassManager`
```bash
# 复制环境变量示例文件
cp .env.example .env
# 编辑配置
vim .env
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` - 数据库密码
- `REDIS_PASSWORD` - Redis密码（如有）
- `SECRET_KEY` - 应用密钥（32位以上随机字符串）
- `JWT_SECRET_KEY` - JWT密钥（32位以上随机字符串）
- `DEBUG_PATH` - 调试入口路径（生产环境请修改为随机字符串）
- `PASSWORD_SALT` - 密码加密盐值
### 5. 部署前端
#### 5.3 编译并运行
#### 5.1 上传前端代码
```bash
cd /www/wwwroot/SharedClassManager/backend-go
go mod tidy
go build -o sharedclassmanager ./cmd/server
```
将代码上传或克隆到 `/www/wwwroot/classmanager`
#### 5.4 使用 Systemd 管理服务
#### 5.2 创建网站
创建 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/classmanager/frontend`
- 根目录：`/www/wwwroot/SharedClassManager/frontend`
- PHP版本：8.0
#### 5.3 配置伪静态
#### 6.2 配置 Nginx 反向代理
在站点设置中：
1. 点击"伪静态"
2. 选择"thinkphp"或添加以下规则：
在站点设置中，点击"配置文件"，替换为以下内容：
```nginx
location / {
if (!-e $request_filename){
rewrite ^(.*)$ /index.php?s=$1 last;
break;
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;
}
}
```
---
**部署方式二：一体化部署（同域名）**
如果希望前后端使用同一个域名（如 `https://your-domain.com`），需要配置反向代理：
在站点设置中：
1. 点击"反向代理"
2. 添加反向代理：
- 目标URL：`http://127.0.0.1:8000`
- 发送域名：`$host`
- 代理目录：`/api/`
3. 前端 `.env` 配置：
```
API_BASE_URL=https://your-domain.com
```
---
#### 5.4 配置伪静态（续）
在站点设置中：
1. 点击"伪静态"
2. 选择"thinkphp"或添加以下规则：
```nginx
location / {
if (!-e $request_filename){
rewrite ^(.*)$ /index.php?s=$1 last;
break;
}
}
```
### 6. 配置SSL证书
### 7. 配置 SSL 证书
1. 在站点设置中点击"SSL"
2. 选择"Let's Encrypt"免费证书
3. 勾选"强制HTTPS"
### 7. 初始化管理员账号
### 8. 初始化系统管理员
使用调试接口创建初始管理员（仅首次部署使用）：
Go 后端首次启动时会**自动创建**超级管理员账号，登录信息从环境变量读取：
```bash
# 替换 your-domain.com 为您的域名
# 替换 /a7k9x2m4q8w1e3r5t6y7u8i9o0p1z2x3 为 .env 中配置的 DEBUG_PATH
- **登录路径**：由 `SUPER_ADMIN_LOGIN_PATH` 配置（默认 `/super-admin/login`）
- **默认用户名**：由 `SUPER_ADMIN_DEFAULT_USERNAME` 配置（默认 `admin`）
- **默认密码**：由 `SUPER_ADMIN_DEFAULT_PASSWORD` 配置（默认 `Admin123`）
curl -X POST https://your-domain.com/a7k9x2m4q8w1e3r5t6y7u8i9o0p1z2x3 \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "Admin@123",
"real_name": "班主任",
"role_type": "班主任"
}'
```
**注意**：创建成功后，请立即登录系统修改密码，并在生产环境中禁用或修改 DEBUG_PATH。
> **注意**：首次登录后请立即修改密码。
---
@@ -190,10 +214,10 @@ curl -X POST https://your-domain.com/a7k9x2m4q8w1e3r5t6y7u8i9o0p1z2x3 \
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y python3 python3-pip python3-venv mysql-server redis-server nginx php8.0 php8.0-fpm php8.0-mysql
sudo apt install -y golang-go mysql-server redis-server nginx php8.0 php8.0-fpm php8.0-mysql
# CentOS
sudo yum install -y python3 python3-pip mysql-server redis nginx php php-fpm php-mysql
sudo yum install -y golang mysql-server redis nginx php php-fpm php-mysql
```
### 2. 数据库配置
@@ -208,54 +232,53 @@ mysql -u root -p
```
```sql
CREATE DATABASE class_manager CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'class_user'@'localhost' IDENTIFIED BY 'YourStrongPassword';
GRANT ALL PRIVILEGES ON class_manager.* TO 'class_user'@'localhost';
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_user -p class_manager < sql/init.sql
mysql -u class_admin -p classmanagerdb < sql/init.sql
```
### 3. 后端部署
### 3. Go 后端部署
```bash
# 创建项目目录
sudo mkdir -p /var/www/classmanager
sudo chown -R $USER:$USER /var/www/classmanager
sudo mkdir -p /www/wwwroot/SharedClassManager
sudo chown -R $USER:$USER /www/wwwroot/SharedClassManager
# 上传代码到 /var/www/classmanager/backend/
cd /var/www/classmanager/backend
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 上传代码
cd /www/wwwroot/SharedClassManager/backend-go
# 配置环境变量
cp .env.example .env
vim .env # 根据实际情况修改配置
# 使用Systemd管理服务
sudo vim /etc/systemd/system/classmanager.service
# 编译
go mod tidy
go build -o sharedclassmanager ./cmd/server
# 使用 Systemd 管理服务
sudo vim /etc/systemd/system/sharedclassmanager.service
```
Systemd服务文件内容：
Systemd 服务文件内容：
```ini
[Unit]
Description=ClassManager Backend
After=network.target
Description=SharedClassManager Go Backend
After=network.target mysql.service redis.service
[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/classmanager/backend
Environment="PATH=/var/www/classmanager/backend/venv/bin"
ExecStart=/var/www/classmanager/backend/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
WorkingDirectory=/www/wwwroot/SharedClassManager/backend-go
ExecStart=/www/wwwroot/SharedClassManager/backend-go/sharedclassmanager
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
@@ -264,26 +287,21 @@ WantedBy=multi-user.target
启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl start classmanager
sudo systemctl enable classmanager
sudo systemctl start sharedclassmanager
sudo systemctl enable sharedclassmanager
```
### 4. 前端部署
```bash
# 上传前端代码到 /var/www/classmanager/frontend/
# 配置Nginx
sudo vim /etc/nginx/sites-available/classmanager
```
Nginx配置示例：
Nginx 配置示例：
```nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/classmanager/frontend;
root /www/wwwroot/SharedClassManager/frontend;
index index.php;
# PHP 处理
location / {
try_files $uri $uri/ /index.php?$query_string;
}
@@ -293,17 +311,20 @@ server {
fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
}
# Go API 反向代理
# 前后端通过 Nginx 反代同域通信，无需 CORS
location /api/ {
proxy_pass http://127.0.0.1:8000/;
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/classmanager /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/sharedclassmanager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```
@@ -312,51 +333,118 @@ sudo systemctl restart nginx
## 环境变量说明
后端 `.env` 文件主要配置项：
Go 后端 `.env` 文件全部配置项（参考 `backend-go/.env.example`）：
### 应用配置
| 配置项 | 说明 | 示例 |
|-------|------|------|
| `APP_NAME` | 应用名称 | 班级操行分管理系统 |
| `APP_NAME` | 应用名称 | 多班级版班级管理系统 |
| `APP_ENV` | 运行环境 | production / development |
| `DEBUG` | 调试模式 | false（生产环境） |
| `SECRET_KEY` | 应用密钥 | 32位以上随机字符串 |
| `APP_PORT` | 服务端口 | 56789 |
### MySQL 数据库
| 配置项 | 说明 | 示例 |
|-------|------|------|
| `DB_HOST` | 数据库地址 | localhost |
| `DB_USER` | 数据库用户名 | class_user |
| `DB_PORT` | 数据库端口 | 3306 |
| `DB_USER` | 数据库用户名 | class_admin |
| `DB_PASSWORD` | 数据库密码 | YourPassword |
| `DB_NAME` | 数据库名 | class_manager |
| `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位以上随机字符串 |
| `DEBUG_PATH` | 调试入口路径 | /random-string |
| `DEDUCTION_HOMEWORK_NOT_SUBMIT` | 作业未提交扣分 | 2 |
| `DEDUCTION_HOMEWORK_LATE` | 作业迟交扣分 | 1 |
| `DEDUCTION_ATTENDANCE_ABSENT` | 缺勤扣分 | 5 |
| `DEDUCTION_ATTENDANCE_LATE` | 迟到扣分 | 2 |
| `DEDUCTION_ATTENDANCE_LEAVE` | 请假扣分 | 1 |
| `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: 后端启动失败
- 检查端口8000是否被占用
- 检查数据库和Redis连接配置
- 查看日志：`sudo journalctl -u classmanager -f`
- 检查端口 56789 是否被占用：`sudo lsof -i :56789`
- 检查数据库和 Redis 连接配置
- 查看日志：`sudo journalctl -u sharedclassmanager -f`
### Q2: 前端页面空白或报错
- 检查Nginx配置中的root路径
- 检查PHP-FPM是否运行
- 检查文件权限：`sudo chown -R www-data:www-data /var/www/classmanager`
- 检查 Nginx 配置中的 root 路径
- 检查 PHP-FPM 是否运行：`sudo systemctl status php8.0-fpm`
- 检查文件权限：`sudo chown -R www-data:www-data /www/wwwroot/SharedClassManager`
### Q3: API请求404
- 检查反向代理配置
- 确认后端服务已启动
### Q3: API 请求 404
- 检查反向代理配置是否正确（`/api/` → `127.0.0.1:56789`）
- 确认 Go 后端服务已启动：`sudo systemctl status sharedclassmanager`
- 检查防火墙设置
### Q4: 数据库连接失败
- 确认MySQL已启动
- 检查用户名密码
- 确认 MySQL 已启动
- 检查 `.env` 中的数据库用户名、密码、数据库名
- 确认用户有数据库权限
### Q5: Go 编译失败
- 确认 Go 版本 >= 1.21：`go version`
- 执行 `go mod tidy` 拉取依赖
- 检查网络连接（可能需要配置 Go 代理：`go env -w GOPROXY=https://goproxy.cn,direct`）
---
## 技术支持
@@ -364,4 +452,4 @@ sudo systemctl restart nginx
- 开发者: Canglan
- 联系方式: admin@sea-studio.top
- 版权归属: Sea Network Technology Studio
- 许可证: MIT License
- 许可证: Apache License 2.0