# WebProject

**Repository Path**: Shu-doc/WebProject

## Basic Information

- **Project Name**: WebProject
- **Description**: 基于Vue3+Springboot的线上自习室项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebProject - 在线自习室

Spring Boot 3.2 + Vue 3 全栈在线自习室系统，支持多人实时学习房间、番茄钟打卡、学习时长统计、用户关注互动等功能。适用于考研备考、编程学习、语言练习等场景。

---

## 目录

- [环境要求](#环境要求)
- [快速开始（本地开发）](#快速开始本地开发)
- [Docker 部署](#docker-部署)
- [常见问题](#常见问题)
- [项目结构](#项目结构)

---

## 环境要求

| 依赖 | 版本 |
|------|------|
| JDK | 17+ |
| MySQL | 8.x |
| Node.js | 20.x（>=20.19.0）或 22.x（>=22.12.0） |
| pnpm | 最新版 |

---

## 安装指引

### 1. 安装 Node.js

从 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本并安装，安装后验证：

```bash
node -v
npm -v
```

### 2. 安装 pnpm

```bash
npm install -g pnpm
```

### 3. 安装 JDK 17+

从 [Adoptium](https://adoptium.net/) 或 [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) 下载 JDK 17+ 并安装。

> **Windows 用户**：安装后需设置 `JAVA_HOME` 环境变量指向 JDK 安装目录，并将 `%JAVA_HOME%\bin` 加入 `Path` 系统变量。安装程序通常会自动配置，可在终端执行 `java -version` 验证。

### 4. 安装 MySQL 8.x

从 [MySQL 官网](https://dev.mysql.com/downloads/) 下载安装包。安装后启动 MySQL 服务，记下 root 密码。

> **Windows 用户**：安装完成后可在"服务管理器"（`services.msc`）中确认 `MySQL80` 服务状态为"正在运行"。如通过 XAMPP/Laragon 安装，请通过对应工具的控制面板启动。

---

## 快速开始（本地开发）

> 以下命令默认使用 **Git Bash** 或 **PowerShell 7+** 执行。如使用 Windows CMD，请将路径中的 `/` 替换为 `\`，将 `cp` 替换为 `copy`。

### 1. 克隆项目

```bash
git clone https://gitee.com/Shu-doc/WebProject.git
cd WebProject
```

### 2. 配置并启动后端

**2.1 初始化数据库**

执行 `backend/src/main/resources/schema.sql`，该脚本会自动创建 `db_osr` 数据库及所有表，并插入默认管理员账号。

```bash
# Git Bash / Linux / macOS
mysql -u root -p < backend/src/main/resources/schema.sql
```

```powershell
# PowerShell（若 mysql 客户端在 PATH 中）
Get-Content backend/src/main/resources/schema.sql | mysql -u root -p
```

> 也可以使用 Navicat、DBeaver、HeidiSQL 等 GUI 工具直接导入并执行 `schema.sql` 文件。

**2.2 配置数据库连接**

```bash
# Git Bash / Linux / macOS
cp backend/src/main/resources/application.properties.example backend/src/main/resources/application.properties
```

```cmd
:: Windows CMD
copy backend\src\main\resources\application.properties.example backend\src\main\resources\application.properties
```

```powershell
# PowerShell
Copy-Item backend/src/main/resources/application.properties.example backend/src/main/resources/application.properties
```

编辑 `backend/src/main/resources/application.properties`，将 `spring.datasource.password` 改为你的 MySQL 密码。

**2.3 启动后端**

```bash
cd backend

# macOS / Linux
./mvnw spring-boot:run

# Windows
mvnw.cmd spring-boot:run
```

后端启动后访问 http://localhost:8080，API 文档地址 http://localhost:8080/doc.html。

> 请确保后端已完成启动（http://localhost:8080 可正常访问），否则前端 API 请求和 WebSocket 连接将失败。

### 3. 启动前端

本项目使用 pnpm monorepo 管理两个前端应用：

| 应用 | 路径 | 说明 |
|------|------|------|
| Vue-001 | `frontend/Vue-001/` | 用户端（JavaScript） |
| Vue-Project | `frontend/Vue-Project/` | 管理端（TypeScript） |

> 依赖安装和启动**必须**在 `frontend/` 根目录执行（该目录包含 `pnpm-workspace.yaml` 配置文件），不要在子项目目录单独执行 `pnpm install`。

```bash
cd frontend

# 安装依赖（根目录 + 两个子项目）
pnpm install

# 启动用户端（默认 http://localhost:5173）
pnpm --filter vue-001 dev

# 启动管理端（默认 http://localhost:5174，新开终端）
pnpm --filter vue-project dev
```

> 如 5173 / 5174 端口被占用，Vite 会自动递增端口号。请确保这两个端口均可用，或通过 `--port` 参数显式指定。

> Vite 已配置代理：`/api` 和 `/ws` 请求自动转发至后端 `http://127.0.0.1:8080`。

### 4. 访问系统

| 入口 | 地址 |
|------|------|
| 用户端 | http://localhost:5173 |
| 管理端 | http://localhost:5174 |
| 后端 API | http://localhost:8080 |
| API 文档 | http://localhost:8080/doc.html |

---

## Docker 部署

### 前提条件

- 安装 [Docker Desktop](https://docs.docker.com/engine/install/)（Windows 需启用 WSL 2 后端）和 [Docker Compose](https://docs.docker.com/compose/install/)
- Windows / macOS / Linux 均可。推荐使用 Git Bash 或 PowerShell 7+ 执行 docker 命令。

### 本地运行

```bash
# 在项目根目录执行（如尚未克隆，先执行 git clone ...）
cd WebProject

# 一键启动（首次会自动构建镜像，耗时数分钟）
docker compose up -d
```

启动后访问：

| 入口 | 地址 |
|------|------|
| 用户端 | http://localhost/ |
| 管理端 | http://localhost/admin/ |
| API 文档 | http://localhost/api/doc.html |

### 远程服务器部署

详见 [部署文档](docs/deploy/DEPLOY.md) — 包含服务器初始化、HTTPS 配置、数据库备份等完整流程。

### 常用命令

```bash
# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

# 更新代码后重新构建并重启
git pull
docker compose up -d --build

# 清理未被使用的悬空镜像（不影响其他 Docker 项目）
docker image prune -f
```

### 服务说明

| 服务 | 镜像 | 说明 |
|------|------|------|
| `mysql` | mysql:8.0 | 数据库（数据持久化到卷） |
| `redis` | redis:7-alpine | 缓存 |
| `backend` | 自构建 | Spring Boot 后端 |
| `frontend` | 自构建 | Nginx + Vue 静态文件 |

> Docker 部署使用独立的 `application-docker.properties` 配置，不会影响本地开发配置。

---

## 常见问题

**启动报 "global is not defined"**
> 项目已在 `vite.config.js` 中添加 `global: 'globalThis'` polyfill，确保使用项目自带的配置文件。

**WebSocket 连接失败**
> Vite 开发服务器已代理 `/ws` 到后端 8080 端口，检查后端是否已启动且 8080 端口未被占用。

**数据库连接失败**
> 确认 MySQL 服务已启动，且 `application.properties` 中的用户名密码正确。默认连接 `localhost:3306/db_osr`。
>
> **Windows 用户**：打开服务管理器（`services.msc`）确认 `MySQL80` 服务状态为"正在运行"。如通过 XAMPP/Laragon 安装，请通过对应工具的控制面板启动。

**端口被占用**
> 使用以下命令查看端口占用情况：
> ```bash
> # Windows
> netstat -ano | findstr :8080
>
> # Linux / macOS
> lsof -i :8080
> ```

**Docker 构建失败**
> 确认 Docker Desktop 已安装且能正常访问外网。首次构建需下载 Maven 依赖和 npm 包，耗时取决于网络。

**Windows 上 Java 命令找不到**
> 确保已设置 `JAVA_HOME` 环境变量指向 JDK 17 安装目录，并将 `%JAVA_HOME%\bin` 加入 `Path` 系统变量。设置后需重新打开终端生效。

---

## 项目结构

```
WebProject/
├── backend/                    # Spring Boot 后端
│   └── src/main/resources/
│       ├── schema.sql          # 数据库初始化脚本
│       ├── seed_data.sql       # 测试种子数据
│       └── application.properties.example
├── frontend/                   # pnpm monorepo
│   ├── Vue-001/                # 用户端 (Vue 3 + Element Plus)
│   └── Vue-Project/            # 管理端 (Vue 3 + TypeScript)
├── docker-compose.yml          # Docker 编排
├── docs/                       # 文档目录
│   └── deploy/
│       └── DEPLOY.md           # 服务器部署指南
└── CLAUDE.md                   # AI 协作指引
```