<div align="center">

# HAOVP

**High Availability Online Video Platform · 高可用在线视频平台**

基于 Spring Cloud 与 Vue 3 构建的前后端分离视频平台，覆盖视频上传、播放、弹幕评论、社交互动、内容推荐和后台治理等完整业务链路。

![Java 17](https://img.shields.io/badge/Java-17-ED8B00?logo=openjdk&logoColor=white)
![Spring Boot 3.2.4](https://img.shields.io/badge/Spring_Boot-3.2.4-6DB33F?logo=springboot&logoColor=white)
![Spring Cloud 2023.0.1](https://img.shields.io/badge/Spring_Cloud-2023.0.1-6DB33F?logo=spring&logoColor=white)
![Vue 3](https://img.shields.io/badge/Vue-3-4FC08D?logo=vuedotjs&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178C6?logo=typescript&logoColor=white)
![Docker Compose](https://img.shields.io/badge/Docker_Compose-ready-2496ED?logo=docker&logoColor=white)

[功能特性](#功能特性) · [系统架构](#系统架构) · [快速开始](#快速开始) · [部署方式](#部署方式) · [项目文档](#项目文档)

</div>

## 项目简介

HAOVP 是一个面向学习、实验与工程实践的在线视频平台。项目不是单一的视频播放页面，而是由用户端、运营管理端、统一网关、六个业务微服务以及一套可观测基础设施组成的完整系统。

项目采用 Nacos 统一管理服务发现与配置，通过 Spring Cloud Gateway 提供统一入口，使用 MySQL、Redis、MinIO 和 RocketMQ 支撑数据、缓存、对象存储与异步消息，并提供单机 Docker Compose、1Panel 和 Debian 多节点三种部署方案。

> 当前推荐服务使用用户行为权重、标签兴趣、视频相似度和热门策略进行组合推荐；多节点方案中的 MinIO 使用主节点写入与副本同步，不是 MinIO 原生纠删码集群。有关高可用边界，请参阅[项目架构文档](docs/基于Spring%20Cloud的高可用在线视频平台项目架构.md)。

## 项目预览

<p align="center">
  <img src="frontend/video-frontend-web/acceptance-video-author.png" alt="HAOVP 视频播放与互动页面" width="80%" />
</p>

## 功能特性

### 用户端

- 用户注册、验证码登录、Access Token / Refresh Token 刷新；
- 视频上传、播放、搜索、分类与标签浏览；
- 点赞、收藏、播放历史、评论、回复和弹幕互动；
- 用户主页、关注与粉丝、私信和站内通知；
- 个人资料、隐私设置和通知偏好管理；
- 首页推荐、热门视频、相似视频和标签推荐；
- 响应式页面与移动端导航适配。

### 管理端

- 独立的管理员认证体系；
- 基于角色与权限的访问控制（RBAC）；
- 用户状态和用户资料管理；
- 视频列表、详情与内容审核；
- 分类、标签和评论治理；
- 管理员、角色、权限与操作日志管理；
- 运营数据仪表盘和可视化统计。

### 平台能力

- Gateway 统一路由、JWT 校验、CORS 与限流；
- Nacos 服务发现、动态配置和环境隔离；
- OpenFeign 服务调用与降级处理；
- Redis 缓存与 Sentinel 模式配置；
- MinIO 视频、封面和头像对象存储；
- RocketMQ 异步消息链路；
- Sentinel 流量治理；
- Actuator、Prometheus 与 Grafana 可观测性；
- 单机编排、1Panel 部署和三节点高可用编排。

## 系统架构

```mermaid
flowchart LR
    Web[用户端<br/>Vue 3 + Vant] --> Gateway[video-gateway<br/>:9000]
    AdminWeb[管理端<br/>Vue 3 + Element Plus] --> Gateway

    Gateway --> Auth[认证服务<br/>:9001]
    Gateway --> User[用户服务<br/>:9002]
    Gateway --> Content[内容服务<br/>:9003]
    Gateway --> Comment[评论服务<br/>:9004]
    Gateway --> Recommend[推荐服务<br/>:9005]
    Gateway --> Admin[管理服务<br/>:9006]

    Nacos[(Nacos<br/>注册与配置)] -.-> Gateway
    Nacos -.-> Auth
    Nacos -.-> User
    Nacos -.-> Content
    Nacos -.-> Comment
    Nacos -.-> Recommend
    Nacos -.-> Admin

    Auth & User & Content & Comment & Recommend & Admin --> MySQL[(MySQL)]
    Auth & User & Content & Comment & Recommend & Admin --> Redis[(Redis)]
    User & Content --> MinIO[(MinIO)]
    Content --> RocketMQ[(RocketMQ)]
```

所有客户端请求默认经过 `video-gateway:9000`。网关通过 Nacos 发现业务服务；服务间调用使用 OpenFeign，环境相关配置由 Nacos 和环境变量共同提供。

完整的技术栈、服务边界、请求链路、部署形态和高可用边界请参阅：[基于 Spring Cloud 的高可用在线视频平台项目架构](docs/基于Spring%20Cloud的高可用在线视频平台项目架构.md)。

### 后端服务

| 模块 | 端口 | 主要职责 |
| --- | ---: | --- |
| `video-gateway` | 9000 | 统一入口、动态路由、JWT 校验、限流与 CORS |
| `video-auth` | 9001 | 用户认证、验证码、Token 签发与刷新、登录统计 |
| `video-user` | 9002 | 用户资料、关注关系、私信、通知与用户设置 |
| `video-content` | 9003 | 视频、分类、标签、上传、收藏、弹幕、统计与审核接口 |
| `video-comment` | 9004 | 评论、回复、点赞、置顶与评论治理 |
| `video-recommend` | 9005 | 首页、热门、相似、标签推荐与用户兴趣建模 |
| `video-admin` | 9006 | 管理员认证、RBAC、用户/内容/评论管理与运营统计 |

### 技术栈

| 层级 | 技术 |
| --- | --- |
| 后端基础 | Java 17、Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0 |
| 微服务治理 | Spring Cloud Gateway、Nacos Discovery/Config、OpenFeign、LoadBalancer、Sentinel |
| 数据与安全 | Spring Security、JWT、MyBatis-Plus 3.5.11、MySQL 8、Redis 7 |
| 存储与消息 | MinIO、RocketMQ 5.1.4、FFmpeg |
| 用户端 | Vue 3、TypeScript、Vite、Pinia、Vant 4、DPlayer 1.27.1（内置弹幕） |
| 管理端 | Vue 3、TypeScript、Vite、Pinia、Element Plus、ECharts、DPlayer 1.27.1 |
| 运维监控 | Docker Compose、Nginx、Actuator、Prometheus、Grafana |

## 快速开始

以下流程适用于本地开发和单机演示。后端基础设施与业务服务使用 Docker Compose，两个前端使用 Vite 开发服务器。

### 1. 环境要求

- JDK 17；
- Maven 3.9+；
- Node.js 18+ 与 npm；
- Docker Engine；
- Docker Compose v2。

可先检查本机环境：

```bash
java -version
mvn -version
node -v
npm -v
docker compose version
```

### 2. 准备后端环境变量

在仓库根目录执行：

```bash
cp backend/.env.example backend/.env
```

PowerShell 可使用：

```powershell
Copy-Item backend/.env.example backend/.env
```

随后编辑 `backend/.env`，替换所有 `replace-with-*` 占位值。请特别注意：

- `NACOS_AUTH_TOKEN` 应使用足够长的 Base64 字符串，例如通过 `openssl rand -base64 48` 生成；
- 首次初始化时，`NACOS_PASSWORD` 需要与 `backend/sql/nacos-schema.sql` 中的 Nacos 初始账号一致；当前初始账号为 `nacos / nacos`；
- 生产环境应在 Nacos 控制台修改初始密码，并同步更新 `backend/.env`；
- `USER_JWT_SECRET`、`ADMIN_JWT_SECRET` 与 `SERVICE_AUTH_TOKEN` 应使用互不相同的高强度随机值；
- `.env` 已被 Git 忽略，不要把真实密码或密钥提交到仓库。

### 3. 启动基础设施

```bash
cd backend
docker compose up -d mysql redis redis-sentinel nacos rmqnamesrv rmqbroker minio sentinel
docker compose ps
```

首次启动会自动创建业务数据库、Nacos 数据库并导入 Nacos 配置。建议等待 MySQL、Nacos、Redis、RocketMQ 和 MinIO 健康后，再启动业务服务。

### 4. 构建并启动后端服务

业务服务的 Dockerfile 会复制各模块 `target` 下的 JAR，因此需要先完成 Maven 构建：

```bash
# 当前目录：backend
mvn clean package -DskipTests

docker compose up -d --build \
  video-gateway video-auth video-user video-content \
  video-comment video-recommend video-admin
```

PowerShell 可写成一行：

```powershell
mvn clean package -DskipTests
docker compose up -d --build video-gateway video-auth video-user video-content video-comment video-recommend video-admin
```

查看运行状态与日志：

```bash
docker compose ps
docker compose logs -f video-gateway
```

如果希望在 IDE 中启动后端，仅用 Compose 启动基础设施，然后为各 Spring Boot 模块设置 `SPRING_PROFILES_ACTIVE=dev`。服务会从 Nacos 加载 `common.yaml`、`common-redis-dev.yaml` 和各服务同名配置。

### 5. 启动用户端

在 `frontend/video-frontend-web/.env.local` 中配置本地网关：

```dotenv
VITE_PROXY_TARGET=http://127.0.0.1:9000
```

然后启动：

```bash
cd frontend/video-frontend-web
npm ci
npm run dev
```

访问 <http://localhost:3000>。

### 6. 启动管理端

在 `frontend/video-frontend-admin/.env.local` 中写入相同的网关代理配置，然后执行：

```bash
cd frontend/video-frontend-admin
npm ci
npm run dev
```

访问 <http://localhost:3100>。首次启动 `video-admin` 时会创建用户名为 `admin` 的超级管理员，密码为 `backend/.env` 中的 `ADMIN_INIT_PASSWORD`。

### 常用地址

| 服务 | 地址 | 说明 |
| --- | --- | --- |
| 用户端 | <http://localhost:3000> | Vite 开发服务器 |
| 管理端 | <http://localhost:3100> | Vite 开发服务器 |
| API 网关 | <http://localhost:9000> | 客户端统一 API 入口 |
| Nacos | <http://localhost:8848/nacos/> | 服务注册与配置中心 |
| MinIO Console | <http://localhost:9101> | 对象存储管理界面 |
| Sentinel Dashboard | <http://localhost:8880> | 流量治理控制台 |

> Grafana 默认使用宿主机 `3000` 端口，与用户端开发服务器冲突。需要本地启用监控时，请停止用户端开发服务器，或调整其中一个服务的端口。

## 配置说明

项目的配置优先级为：**环境变量 > Nacos 配置 > 本地 `application.yml`**。

| 配置位置 | 用途 |
| --- | --- |
| `backend/.env` | 数据库、Redis、Nacos、MinIO、JWT、内部服务令牌和管理员初始密码 |
| `backend/sql/nacos-config-init.sql` | 首次初始化时导入公共配置与各微服务配置 |
| `backend/*/src/main/resources/application.yml` | 服务端口、应用名和 Nacos 导入入口 |
| `frontend/*/.env.local` | 前端 API 地址与 Vite 开发代理目标 |

`backend/.env` 和前端 `.env.local` 均不应提交。修改 JWT 密钥、数据库密码或 Nacos 凭据时，请同时检查所有引用该凭据的服务配置。

## 构建与测试

### 后端

```bash
cd backend
mvn test
mvn package -DskipTests
```

### 用户端

```bash
cd frontend/video-frontend-web
npm ci
npm run build
```

### 管理端

```bash
cd frontend/video-frontend-admin
npm ci
npm run build
```

前端构建命令会先执行 `vue-tsc` 类型检查，再由 Vite 生成生产构建产物。

## 项目结构

```text
HAOVP/
├── backend/
│   ├── video-common/          # 公共响应、异常、安全与基础模型
│   ├── video-gateway/         # API 网关
│   ├── video-auth/            # 用户认证服务
│   ├── video-user/            # 用户与社交服务
│   ├── video-content/         # 视频内容服务
│   ├── video-comment/         # 评论服务
│   ├── video-recommend/       # 推荐服务
│   ├── video-admin/           # 运营管理服务
│   ├── config/                # MySQL、Redis、RocketMQ、Nginx 配置
│   ├── monitoring/            # Prometheus 与 Grafana 配置
│   ├── sql/                   # 业务库、Nacos schema 与配置初始化脚本
│   ├── docker-compose.yml     # 本地/单机编排
│   └── docker-compose-node-*  # 多节点编排
├── frontend/
│   ├── video-frontend-web/    # 用户端 Vue 应用
│   └── video-frontend-admin/  # 管理端 Vue 应用
├── docs/                      # 架构、接口、开发和部署文档
└── README.md
```

## 部署方式

- **本地或单机 Docker Compose**：使用 `backend/docker-compose.yml`；
- **1Panel 单机部署**：参阅 [HAOVP 1Panel 单机部署指南](docs/DEPLOY_1PANEL.md)；
- **Debian 12 多节点部署**：参阅 [Debian 12 多节点部署手册](docs/Debian%2012%20高可用集群部署手册.md)。

对外部署前，请至少完成以下事项：替换全部初始凭据、限制基础设施端口暴露、配置 HTTPS、设置数据库和对象存储备份、验证监控告警，并根据实际负载调整 JVM 与容器资源限制。

## 常见问题

### Docker 构建提示找不到 JAR

业务服务镜像直接复制 `target/video-*.jar`。先在 `backend` 目录执行 `mvn clean package -DskipTests`，再运行 `docker compose up -d --build ...`。

### 后端无法连接 Nacos，或出现 `unknown user` / `authorization failed`

检查 `backend/.env` 中的 `NACOS_USERNAME`、`NACOS_PASSWORD` 是否与 Nacos 数据库中的账号一致，并确认 Nacos 已健康。首次初始化使用 `nacos / nacos`，修改控制台密码后也要同步更新环境变量并重启业务服务。

### 前端接口返回 404 或请求到了错误主机

确认两个前端目录的 `.env.local` 均包含：

```dotenv
VITE_PROXY_TARGET=http://127.0.0.1:9000
```

修改环境变量后需要重启 Vite 开发服务器。用户端默认把 `/api` 代理至网关；管理端使用 `/api/admin`。

### 修改初始化 SQL 后没有生效

MySQL 的 `/docker-entrypoint-initdb.d` 只会在数据目录为空时执行。已有数据环境应使用迁移 SQL；不要为了重新初始化而直接删除生产数据卷。

更多部署排查方法见 [1Panel 部署指南的常见问题](docs/DEPLOY_1PANEL.md#12-常见问题)。

## 项目文档

| 文档 | 内容 |
| --- | --- |
| [开发环境搭建](docs/开发环境搭建.md) | 环境要求、本地启动、构建和测试 |
| [项目架构](docs/基于Spring%20Cloud的高可用在线视频平台项目架构.md) | 技术栈、服务边界、请求链路与部署形态 |
| [前端架构](docs/frontend-architecture.md) | 两个 Vue 应用的目录、请求和认证设计 |
| [接口索引](docs/HAOVP接口列表.md) | Controller 与网关路由前缀索引 |
| [Nacos 配置指南](docs/nacos-config-guide.md) | 配置命名、环境切换、初始化和排查 |
| [1Panel 单机部署](docs/DEPLOY_1PANEL.md) | 生产构建、反向代理、验证、更新与备份 |
| [Debian 12 多节点部署](docs/Debian%2012%20高可用集群部署手册.md) | 节点职责、启动顺序、高可用边界与安全 |

各后端模块的职责和接口说明也可以在 [`docs/`](docs/) 目录中查阅。接口实现以各模块 `controller` 下的 Spring MVC 注解、DTO 和 VO 为准。

## 参与贡献

欢迎通过 Issue 或 Pull Request 改进项目。提交代码前建议完成对应模块测试，并同步更新受影响的接口、配置和部署文档。

建议的提交前检查：

```bash
# 后端
cd backend && mvn test

# 用户端和管理端分别执行
npm run build
```

## 开源许可

当前仓库尚未包含明确的开源许可证。在添加 `LICENSE` 文件之前，项目代码默认不授予复制、修改或再分发许可；如需在其他项目中使用，请先取得项目维护者授权。