班级宠物园部署指南

前言

班级宠物园（class-pet-garden）是一款面向中小学教师的游戏化班级管理工具，将传统的积分评价系统与电子宠物养成玩法相结合，让班级管理变得更有趣。本文将详细介绍该项目的部署安装步骤和使用方法，帮助你快速搭建并使用这个工具。

一、项目简介

班级宠物园是一个开源的班级管理工具，核心特点包括：

🎓 多班级管理：支持创建和管理多个班级，一键切换
👨‍🎓 学生管理：添加、编辑、删除、搜索、批量导入学生
🐾 宠物养成：24 种可爱宠物，8 级成长体系，每级形态变化
⭐ 积分评价：83 条默认规则，支持自定义，覆盖学习 / 行为 / 健康 / 其他
📊 数据可视化：排行榜、成长进度、评价统计
💾 数据安全：SQLite 数据库，支持备份 / 恢复 / 导出
📱 响应式设计：适配电脑、平板、手机

技术架构

该项目采用前后端分离架构：

前端：Vue 3 + TypeScript + Tailwind CSS
后端：Node.js + Express
数据库：SQLite
构建工具：Vite

二、环境准备

在部署项目之前，需要准备以下环境：

Node.js：版本建议 16.x 及以上，用于运行前端和后端服务
Git：用于克隆项目代码
npm：Node.js 的包管理工具，随 Node.js 一起安装

安装 Node.js 和 Git

Node.js 下载 ：https://nodejs.org/，选择 LTS 版本安装，安装时勾选 "Add Node.js to PATH"
Git 下载 ：https://git-scm.com/downloads，安装时默认选项即可

安装完成后，打开终端，输入以下命令验证安装：

bash 复制代码

# 验证Node.js版本
node -v
# 验证npm版本
npm -v
# 验证Git版本
git --version

三、本地开发部署

1. 克隆项目代码

打开终端，进入想要存放项目的目录，执行以下命令：

bash 复制代码

# 克隆项目
git clone https://github.com/gaotong132/class-pet-garden.git
# 进入项目目录
cd class-pet-garden

2. 安装项目依赖

在项目根目录下执行以下命令安装所有依赖：

bash 复制代码

npm install

3. 启动开发服务

可以选择同时启动前端和后端服务，或者分别启动：

bash 复制代码

# 同时启动前端和后端服务
npm start

# 或者分别启动
# 启动前端开发服务
npm run dev
# 启动后端服务
npm run server

启动成功后，在浏览器中访问http://localhost:5173即可进入项目主界面。

四、生产部署

1. 构建前端项目

在项目根目录下执行以下命令构建前端静态文件：

bash 复制代码

npm run build

构建完成后，静态文件会生成在dist目录中。

2. 启动生产服务

可以使用项目提供的启动脚本启动后端服务：

bash 复制代码

bash start-server.sh

或者直接启动后端服务：

bash 复制代码

npm run server

启动成功后，在浏览器中访问http://localhost:3000即可访问生产环境的项目。

3. 服务器部署（可选）

如果需要部署到远程服务器，可以将项目文件上传到服务器，然后按照上述步骤安装依赖、构建前端、启动服务，同时可以使用 Nginx 进行反向代理，配置示例如下：

nginx 复制代码

server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/class-pet-garden/dist;
        try_files $uri $uri/ /index.html;
    }

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

五、项目功能使用

1. 班级管理

创建班级：点击顶部的 "创建班级" 按钮，输入班级名称即可创建新班级
切换班级：通过顶部的下拉菜单可以快速切换不同的班级
删除班级：在班级管理界面可以删除不需要的班级（注意：删除班级会同时删除该班级的所有数据）
数据备份：可以将班级数据导出为 JSON 文件进行备份
数据恢复：可以导入 JSON 文件恢复班级数据

2. 学生管理

添加学生：可以单个添加学生，也可以通过 Excel 文件批量导入学生
编辑学生：点击学生卡片可以编辑学生的姓名、学号等信息
删除学生：可以单个或批量删除学生
搜索学生：通过搜索框可以快速查找学生

3. 宠物系统

班级宠物园提供了 24 种可爱宠物，分为普通动物和神兽两类，每个宠物有 8 级成长体系，学生通过获得积分让宠物成长升级。

宠物图鉴：可以查看所有宠物的形态和成长阶段
更换宠物：学生可以更换自己的宠物类型
成长进度：可以查看宠物的成长进度和升级所需积分

4. 评价系统

评价系统提供了 83 条默认评价规则，覆盖学习、行为、健康、其他四个分类，同时支持自定义评价规则。

快速评价：可以通过分类标签快速给学生加分或扣分
自定义规则：可以添加、编辑、删除自定义评价规则
评价记录：可以查看所有的评价记录，支持撤回最近的评价

六、常见问题解决

1. 依赖安装失败

如果执行npm install时出现依赖安装失败的情况，可以尝试以下方法：

清除 npm 缓存：npm cache clean --force
使用淘宝镜像源：npm install --registry=https://registry.npmmirror.com
检查 Node.js 版本是否符合要求，建议使用 16.x 及以上版本

2. 服务启动失败

检查端口是否被占用：可以使用netstat -ano | findstr 3000（Windows）或lsof -i:3000（Mac/Linux）查看端口占用情况，关闭占用端口的进程
检查数据库文件是否存在：后端服务依赖server/pet-garden.db数据库文件，如果该文件不存在，会自动创建

3. 页面无法访问

检查服务是否正常启动：查看终端输出的启动日志，确认服务是否成功启动
检查浏览器地址是否正确：本地开发环境访问http://localhost:5173，生产环境访问http://localhost:3000
检查网络连接是否正常

七、总结

班级宠物园是一个非常实用的游戏化班级管理工具，通过本文的介绍，你可以快速部署并使用这个工具。该项目还在持续开发中，后续会添加更多功能，比如商店系统、数据统计、用户系统等。如果你在使用过程中遇到问题，可以通过 GitHub Issues 反馈，也可以参与项目的开发和贡献。