docs(readme): refresh platform overview and media docs
- Rework the README to present HAOVP as a complete video platform. - Clarify features, architecture, and deployment context for readers. - Align the docs with the current DPlayer-based player stack. - Refresh the preview image so the README matches the current UI.
This commit is contained in:
Toys-A
@@ -1 +1,380 @@
|
||||
# HA-OVP
|
||||
<div align="center">
|
||||
|
||||
# HAOVP
|
||||
|
||||
**High Availability Online Video Platform · 高可用在线视频平台**
|
||||
|
||||
基于 Spring Cloud 与 Vue 3 构建的前后端分离视频平台，覆盖视频上传、播放、弹幕评论、社交互动、内容推荐和后台治理等完整业务链路。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[功能特性](#功能特性) · [系统架构](#系统架构) · [快速开始](#快速开始) · [部署方式](#部署方式) · [项目文档](#项目文档)
|
||||
|
||||
</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` 文件之前，项目代码默认不授予复制、修改或再分发许可；如需在其他项目中使用，请先取得项目维护者授权。
|
||||
|
||||
Reference in New Issue
Block a user