HAOVP/README.md

HAOVP

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

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

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

项目简介

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

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

当前推荐服务使用用户行为权重、标签兴趣、视频相似度和热门策略进行组合推荐；多节点方案中的 MinIO 使用主节点写入与副本同步，不是 MinIO 原生纠删码集群。有关高可用边界，请参阅项目架构文档。

项目预览

功能特性

用户端

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

管理端

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

平台能力

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

系统架构

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 的高可用在线视频平台项目架构。

后端服务

模块	端口	主要职责
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。

可先检查本机环境：

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

2. 准备后端环境变量

在仓库根目录执行：

cp backend/.env.example backend/.env

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. 启动基础设施

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 构建：

# 当前目录：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 可写成一行：

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

查看运行状态与日志：

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 中配置本地网关：

VITE_PROXY_TARGET=http://127.0.0.1:9000

然后启动：

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

访问 http://localhost:3000。

6. 启动管理端

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

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 凭据时，请同时检查所有引用该凭据的服务配置。

构建与测试

后端

cd backend
mvn test
mvn package -DskipTests

用户端

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

管理端

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

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

项目结构

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 单机部署指南；
• Debian 12 多节点部署：参阅 Debian 12 多节点部署手册。

对外部署前，请至少完成以下事项：替换全部初始凭据、限制基础设施端口暴露、配置 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 均包含：

VITE_PROXY_TARGET=http://127.0.0.1:9000

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

修改初始化 SQL 后没有生效

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

更多部署排查方法见 1Panel 部署指南的常见问题。

项目文档

文档	内容
开发环境搭建	环境要求、本地启动、构建和测试
项目架构	技术栈、服务边界、请求链路与部署形态
前端架构	两个 Vue 应用的目录、请求和认证设计
接口索引	Controller 与网关路由前缀索引
Nacos 配置指南	配置命名、环境切换、初始化和排查
1Panel 单机部署	生产构建、反向代理、验证、更新与备份
Debian 12 多节点部署	节点职责、启动顺序、高可用边界与安全

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

参与贡献

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

建议的提交前检查：

# 后端
cd backend && mvn test

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

开源许可

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