SharedClassManager/INSTALL.md

多班级版班级管理系统 - 安装部署指南

环境要求

服务器配置

• 操作系统: 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. 安装宝塔面板

# 通用安装脚本（免登录版）
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+：

# 下载 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

git clone https://hz-gitea.sea-studio.top/canglan/SharedClassManager.git /www/wwwroot/SharedClassManager

5.2 配置环境变量

cd /www/wwwroot/SharedClassManager/backend-go
cp .env.example .env
vim .env  # 根据实际环境修改配置

必须修改的配置项：

• DB_USER - 数据库用户名
• DB_PASSWORD - 数据库密码
• JWT_SECRET_KEY - JWT 密钥（使用下方命令生成）

生成 JWT 密钥：

openssl rand -base64 32

将输出的随机字符串填入 .env 的 JWT_SECRET_KEY 配置项。

5.3 编译并运行

cd /www/wwwroot/SharedClassManager/backend-go
go mod tidy
go build -o sharedclassmanager ./cmd/server

5.4 使用 Systemd 管理服务

创建 systemd 服务文件：

sudo vim /etc/systemd/system/sharedclassmanager.service

写入以下内容：

[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

启动服务：

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 反向代理

在站点设置中，点击"配置文件"，替换为以下内容：

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. 安装系统依赖

# 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. 数据库配置

# 启动MySQL
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 登录MySQL创建数据库
mysql -u root -p

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;

导入初始化数据：

mysql -u class_admin -p classmanagerdb < sql/init.sql

3. Go 后端部署

# 创建项目目录
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

# 编译
go mod tidy
go build -o sharedclassmanager ./cmd/server

# 使用 Systemd 管理服务
sudo vim /etc/systemd/system/sharedclassmanager.service

Systemd 服务文件内容：

[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

启动服务：

sudo systemctl daemon-reload
sudo systemctl start sharedclassmanager
sudo systemctl enable sharedclassmanager

4. 前端部署

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;
    }
}

启用站点：

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
• 执行 go mod tidy 拉取依赖
• 检查网络连接（可能需要配置 Go 代理：go env -w GOPROXY=https://goproxy.cn,direct）

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