diff --git a/README.md b/README.md index 0943c91..5c6ed00 100644 --- a/README.md +++ b/README.md @@ -1 +1,380 @@ -# HA-OVP \ No newline at end of file +
+ +# 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) + +[功能特性](#功能特性) · [系统架构](#系统架构) · [快速开始](#快速开始) · [部署方式](#部署方式) · [项目文档](#项目文档) + +
+ +## 项目简介 + +HAOVP 是一个面向学习、实验与工程实践的在线视频平台。项目不是单一的视频播放页面，而是由用户端、运营管理端、统一网关、六个业务微服务以及一套可观测基础设施组成的完整系统。 + +项目采用 Nacos 统一管理服务发现与配置，通过 Spring Cloud Gateway 提供统一入口，使用 MySQL、Redis、MinIO 和 RocketMQ 支撑数据、缓存、对象存储与异步消息，并提供单机 Docker Compose、1Panel 和 Debian 多节点三种部署方案。 + +> 当前推荐服务使用用户行为权重、标签兴趣、视频相似度和热门策略进行组合推荐；多节点方案中的 MinIO 使用主节点写入与副本同步，不是 MinIO 原生纠删码集群。有关高可用边界，请参阅[项目架构文档](docs/基于Spring%20Cloud的高可用在线视频平台项目架构.md)。 + +## 项目预览 + +

+ HAOVP 视频播放与互动页面 +

+ +## 功能特性 + +### 用户端 + +- 用户注册、验证码登录、Access Token / Refresh Token 刷新； +- 视频上传、播放、搜索、分类与标签浏览； +- 点赞、收藏、播放历史、评论、回复和弹幕互动； +- 用户主页、关注与粉丝、私信和站内通知； +- 个人资料、隐私设置和通知偏好管理； +- 首页推荐、热门视频、相似视频和标签推荐； +- 响应式页面与移动端导航适配。 + +### 管理端 + +- 独立的管理员认证体系； +- 基于角色与权限的访问控制（RBAC）； +- 用户状态和用户资料管理； +- 视频列表、详情与内容审核； +- 分类、标签和评论治理； +- 管理员、角色、权限与操作日志管理； +- 运营数据仪表盘和可视化统计。 + +### 平台能力 + +- Gateway 统一路由、JWT 校验、CORS 与限流； +- Nacos 服务发现、动态配置和环境隔离； +- OpenFeign 服务调用与降级处理； +- Redis 缓存与 Sentinel 模式配置； +- MinIO 视频、封面和头像对象存储； +- RocketMQ 异步消息链路； +- Sentinel 流量治理； +- Actuator、Prometheus 与 Grafana 可观测性； +- 单机编排、1Panel 部署和三节点高可用编排。 + +## 系统架构 + +```mermaid +flowchart LR + Web[用户端
Vue 3 + Vant] --> Gateway[video-gateway
:9000] + AdminWeb[管理端
Vue 3 + Element Plus] --> Gateway + + Gateway --> Auth[认证服务
:9001] + Gateway --> User[用户服务
:9002] + Gateway --> Content[内容服务
:9003] + Gateway --> Comment[评论服务
:9004] + Gateway --> Recommend[推荐服务
:9005] + Gateway --> Admin[管理服务
:9006] + + Nacos[(Nacos
注册与配置)] -.-> 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 +``` + +访问 。 + +### 6. 启动管理端 + +在 `frontend/video-frontend-admin/.env.local` 中写入相同的网关代理配置，然后执行： + +```bash +cd frontend/video-frontend-admin +npm ci +npm run dev +``` + +访问 。首次启动 `video-admin` 时会创建用户名为 `admin` 的超级管理员，密码为 `backend/.env` 中的 `ADMIN_INIT_PASSWORD`。 + +### 常用地址 + +| 服务 | 地址 | 说明 | +| --- | --- | --- | +| 用户端 | | Vite 开发服务器 | +| 管理端 | | Vite 开发服务器 | +| API 网关 | | 客户端统一 API 入口 | +| Nacos | | 服务注册与配置中心 | +| MinIO Console | | 对象存储管理界面 | +| Sentinel Dashboard | | 流量治理控制台 | + +> 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` 文件之前，项目代码默认不授予复制、修改或再分发许可；如需在其他项目中使用，请先取得项目维护者授权。 diff --git a/docs/frontend-architecture.md b/docs/frontend-architecture.md index f11f87f..efe06a5 100644 --- a/docs/frontend-architecture.md +++ b/docs/frontend-architecture.md @@ -7,7 +7,7 @@ ## 依赖 -两端共用 Vue Router 4、Pinia、Axios、Day.js、NProgress。用户端使用 Vant 4、Artplayer 5.1.7 和 `artplayer-plugin-danmuku` 5.1.0；管理端使用 Element Plus 2.6、ECharts 5.5 和 SortableJS。项目脚本使用 npm、pnpm 均可，具体以各目录 `package.json` 为准。 +两端共用 Vue Router 4、Pinia、Axios、Day.js、NProgress。用户端和管理端均使用 DPlayer 1.27.1，用户端通过 DPlayer 的弹幕配置与后端 API 实现弹幕读取和发送；管理端使用 Element Plus 2.6、ECharts 5.5 和 SortableJS。项目脚本使用 npm、pnpm 均可，具体以各目录 `package.json` 为准。 ## 目录职责 @@ -28,4 +28,4 @@ npm run build npm run preview ``` -用户端播放器是 Artplayer，不再使用早期文档中的 DPlayer。管理端仪表盘接口由 `src/api/statistics.ts` 聚合用户、视频、评论和趋势数据，接口路径以当前 `src/api` 文件为准。 +用户端和管理端播放器均为 DPlayer。管理端仪表盘接口由 `src/api/statistics.ts` 聚合用户、视频、评论和趋势数据，接口路径以当前 `src/api` 文件为准。 diff --git a/docs/基于Spring Cloud的高可用在线视频平台项目架构.md b/docs/基于Spring Cloud的高可用在线视频平台项目架构.md index 7fc3660..ef65c32 100644 --- a/docs/基于Spring Cloud的高可用在线视频平台项目架构.md +++ b/docs/基于Spring Cloud的高可用在线视频平台项目架构.md @@ -8,7 +8,7 @@ - Spring Cloud Gateway、Nacos Discovery/Config、OpenFeign、LoadBalancer、Sentinel - Spring Security、JWT、MyBatis-Plus 3.5.11、MySQL 8、Redis 7 - RocketMQ 5.1.4（内容服务依赖）、MinIO（对象存储）、FFmpeg Java wrapper 0.8.0（内容服务依赖） -- Vue 3、TypeScript、Vite、Pinia；用户端使用 Vant 4、Artplayer + danmaku plugin，管理端使用 Element Plus、ECharts +- Vue 3、TypeScript、Vite、Pinia；用户端和管理端使用 DPlayer，用户端通过 DPlayer 弹幕配置接入后端弹幕接口，管理端使用 Element Plus、ECharts - Docker Compose；Prometheus、Grafana、Micrometer Actuator 用于监控 项目当前没有 Seata 或 Spark 运行时依赖，不应在架构描述中宣称已使用分布式事务或 Spark 推荐。推荐服务目前基于用户行为权重、标签兴趣、视频相似度和热门策略组合推荐。 diff --git a/frontend/video-frontend-web/acceptance-video-author.png b/frontend/video-frontend-web/acceptance-video-author.png index c2a5773..a26d66a 100644 Binary files a/frontend/video-frontend-web/acceptance-video-author.png and b/frontend/video-frontend-web/acceptance-video-author.png differ