SharedClassManager/INSTALL.md

班级操行分管理系统 - 安装部署指南

环境要求

服务器配置

• 操作系统: Linux (Ubuntu 20.04+ / CentOS 7+)
• CPU: 2核+
• 内存: 4GB+
• 磁盘: 20GB+

软件依赖

软件	版本	用途
Python	3.9+	后端运行环境
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.21+	Web服务器
MySQL	5.7+	数据库
Redis	6.0+	缓存服务
PHP	8.0+	前端处理
Python项目管理器	最新版	后端部署

3. 创建数据库

在宝塔面板中：

1. 进入"数据库"菜单
2. 点击"添加数据库"
3. 填写数据库信息：
   • 数据库名：class_manager
   • 用户名：class_user
   • 密码：生成强密码并保存
4. 点击"导入"，选择 sql/init.sql 文件导入

4. 部署后端服务

4.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/ 目录下：

# 复制环境变量示例文件
cp .env.example .env

# 编辑配置
vim .env

根据实际环境修改以下配置：

• DB_USER - 数据库用户名
• DB_PASSWORD - 数据库密码
• REDIS_PASSWORD - Redis密码（如有）
• SECRET_KEY - 应用密钥（32位以上随机字符串）
• JWT_SECRET_KEY - JWT密钥（32位以上随机字符串）
• DEBUG_PATH - 调试入口路径（生产环境请修改为随机字符串）

5. 部署前端

5.1 上传前端代码

将代码上传或克隆到 /www/wwwroot/classmanager

5.2 创建网站

1. 进入宝塔面板"网站"菜单
2. 点击"添加站点"：
   • 域名：填写您的域名
   • 根目录：/www/wwwroot/classmanager/frontend
   • PHP版本：8.0

5.3 配置伪静态

在站点设置中：

1. 点击"伪静态"
2. 选择"thinkphp"或添加以下规则：

location / {
    if (!-e $request_filename){
        rewrite ^(.*)$ /index.php?s=$1 last;
        break;
    }
}

---

部署方式二：一体化部署（同域名）

如果希望前后端使用同一个域名（如 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"或添加以下规则：

location / {
    if (!-e $request_filename){
        rewrite ^(.*)$ /index.php?s=$1 last;
        break;
    }
}

6. 配置SSL证书

1. 在站点设置中点击"SSL"
2. 选择"Let's Encrypt"免费证书
3. 勾选"强制HTTPS"

7. 初始化管理员账号

使用调试接口创建初始管理员（仅首次部署使用）：

# 替换 your-domain.com 为您的域名
# 替换 /a7k9x2m4q8w1e3r5t6y7u8i9o0p1z2x3 为 .env 中配置的 DEBUG_PATH

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。

---

手动部署（无宝塔面板）

1. 安装系统依赖

# 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

# CentOS
sudo yum install -y python3 python3-pip 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 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';
FLUSH PRIVILEGES;
EXIT;

导入初始化数据：

mysql -u class_user -p class_manager < sql/init.sql

3. 后端部署

# 创建项目目录
sudo mkdir -p /var/www/classmanager
sudo chown -R $USER:$USER /var/www/classmanager

# 上传代码到 /var/www/classmanager/backend/
cd /var/www/classmanager/backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
vim .env  # 根据实际情况修改配置

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

Systemd服务文件内容：

[Unit]
Description=ClassManager Backend
After=network.target

[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
Restart=always

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl start classmanager
sudo systemctl enable classmanager

4. 前端部署

# 上传前端代码到 /var/www/classmanager/frontend/
# 配置Nginx
sudo vim /etc/nginx/sites-available/classmanager

Nginx配置示例：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/classmanager/frontend;
    index index.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;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

启用站点：

sudo ln -s /etc/nginx/sites-available/classmanager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

---

环境变量说明

后端 .env 文件主要配置项：

配置项	说明	示例
APP_NAME	应用名称	班级操行分管理系统
DEBUG	调试模式	false（生产环境）
SECRET_KEY	应用密钥	32位以上随机字符串
DB_HOST	数据库地址	localhost
DB_USER	数据库用户名	class_user
DB_PASSWORD	数据库密码	YourPassword
DB_NAME	数据库名	class_manager
REDIS_HOST	Redis地址	localhost
REDIS_PASSWORD	Redis密码	可选
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

---

常见问题

Q1: 后端启动失败

• 检查端口8000是否被占用
• 检查数据库和Redis连接配置
• 查看日志：sudo journalctl -u classmanager -f

Q2: 前端页面空白或报错

• 检查Nginx配置中的root路径
• 检查PHP-FPM是否运行
• 检查文件权限：sudo chown -R www-data:www-data /var/www/classmanager

Q3: API请求404

• 检查反向代理配置
• 确认后端服务已启动
• 检查防火墙设置

Q4: 数据库连接失败

• 确认MySQL已启动
• 检查用户名密码
• 确认用户有数据库权限

---

技术支持

• 开发者: Canglan
• 联系方式: admin@sea-studio.top
• 版权归属: Sea Network Technology Studio
• 许可证: MIT License