267 lines
10 KiB
Markdown
267 lines
10 KiB
Markdown
# 校园广播站点歌系统改造技术方案
|
||
|
||
> 基于 Nuxt 4 与 Node.js 的现代化重构，专注于酷狗音源集成与高效排期管理。
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 项目背景
|
||
|
||
随着校园文化生活需求的提升，原有的点歌系统在用户体验、音源稳定性及管理便捷性上已显不足。为了提供更现代化、简洁且高效的广播服务，决定对现有开源项目 VoiceHub 进行深度改造。
|
||
|
||
### 1.2 改造目标
|
||
|
||
- 引入用户注册机制，实现个性化点歌记录追踪。
|
||
- 精简音源，统一接入酷狗音乐代理服务，确保版权与音质。
|
||
- 开发后台管理功能，支持将排期歌单一键转换为图片，便于移动端导入。
|
||
- 全面升级 UI 设计，采用简洁高级的现代化风格。
|
||
|
||
### 1.3 开源协议
|
||
|
||
本项目遵循 MIT 协议，允许自由使用、修改和分发。
|
||
|
||
<div class="bg-slate-50 rounded-lg p-4 border border-slate-200 flex items-center gap-3">
|
||
<i class="fa-brands fa-github text-2xl text-slate-700"></i>
|
||
<div>
|
||
<p class="font-medium text-slate-900">MIT License</p>
|
||
<p class="text-sm text-slate-500">本项目遵循 MIT 协议，允许自由使用、修改和分发。</p>
|
||
</div>
|
||
</div>
|
||
|
||
---
|
||
|
||
## 2. 功能需求分析
|
||
|
||
为明确系统演进方向，以下表格对比了原始功能与本次改造后的目标需求：
|
||
|
||
| 编号 | 功能模块 | 原始功能 (VoiceHub) | 改造后需求 |
|
||
|------|--------------|---------------------------------------------|--------------------------------------------------|
|
||
| 1 | 用户系统 | 匿名点歌，无记录 | 增加注册/登录，支持历史记录查看 |
|
||
| 2 | 音乐来源 | 多源聚合（网易云/QQ等），维护困难 | 仅保留酷狗音乐，部署专用代理 |
|
||
| 3 | 后台管理 | 基础排期列表，审核操作 | 新增“歌单图片生成”功能 |
|
||
| 4 | 界面设计 | 传统后台管理风格 | 现代化、扁平化、响应式设计 |
|
||
|
||
---
|
||
|
||
## 3. 技术架构设计
|
||
|
||
### 3.1 前端架构
|
||
|
||
前端采用现代化Web框架体系，保障性能与可维护性：
|
||
|
||
| 组件 | 技术选型 | 说明 |
|
||
|----------------|-----------------------------------|----------------------------------------|
|
||
| 框架 | Nuxt 4 (Vue 3) | 支持SSR渲染，提升首屏加载速度 |
|
||
| UI库 | Nuxt UI / Tailwind CSS | 原子化CSS，快速构建响应式界面 |
|
||
| 状态管理 | Pinia | 轻量级状态管理，适配Vue 3组合式API |
|
||
|
||
### 3.2 后端架构
|
||
|
||
后端基于Node.js构建微服务化架构，具备高扩展性与灵活性：
|
||
|
||
| 组件 | 技术选型 | 说明 |
|
||
|----------------|-----------------------------------|----------------------------------------|
|
||
| 运行环境 | Node.js LTS | 稳定版本，长期支持 |
|
||
| 业务模块 | Auth (JWT), Music (Proxy), Schedule (CRUD) | 模块化设计，职责分离 |
|
||
| 代理服务 | 内置酷狗API Hash算法解析 | 封装外部接口加密逻辑，降低耦合 |
|
||
|
||
### 3.3 系统架构图描述
|
||
|
||
系统采用分层架构设计，各组件间通过标准化接口通信：
|
||
|
||
```
|
||
用户端 (Nuxt) ↔ API网关 ↔ Node.js服务
|
||
↓
|
||
MySQL DB（数据持久化）
|
||
↓
|
||
酷狗代理 → 酷狗API（外部音源获取）
|
||
```
|
||
|
||
**可视化节点颜色标识**：
|
||
- **蓝色**：用户端 (Nuxt)，主入口
|
||
- **绿色**：API网关 & Node.js服务，核心逻辑处理
|
||
- **黄色**：MySQL DB，数据存储
|
||
- **紫色**：酷狗代理，接口封装
|
||
- **粉色**：酷狗API，第三方服务
|
||
|
||
通信链路建议使用 ECharts 力导向图展示，支持动态缩放与交互探索。
|
||
|
||
### 3.4 MySQL 数据库设计
|
||
|
||
数据库设计遵循第三范式，确保数据一致性与查询效率。
|
||
|
||
#### `users` 表（用户信息）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------------|--------------------|--------------------------|
|
||
| id | INT PK | 用户ID |
|
||
| username | VARCHAR(50) | 用户名 |
|
||
| password_hash | VARCHAR(255) | 加密密码（bcrypt） |
|
||
| role | ENUM('user','admin') | 角色（普通用户/管理员） |
|
||
|
||
#### `songs` 表（歌曲信息）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------------|--------------------|--------------------------|
|
||
| id | INT PK | 歌曲ID |
|
||
| kg_hash | VARCHAR(64) | 酷狗音乐Hash值 |
|
||
| title | VARCHAR(100) | 歌名 |
|
||
| singer | VARCHAR(100) | 歌手 |
|
||
| cover_url | VARCHAR(255) | 封面图URL |
|
||
|
||
---
|
||
|
||
## 4. 功能实现步骤
|
||
|
||
### 4.1 用户注册流程
|
||
|
||
采用 JWT (JSON Web Token) 实现无状态认证机制，保障安全性与可扩展性。
|
||
|
||
**实现流程如下**：
|
||
|
||
1. 前端提交注册表单（用户名/密码）；
|
||
2. 后端验证用户名唯一性，并使用 bcrypt 对密码进行哈希加密后存入数据库；
|
||
3. 登录成功后签发 JWT Token，通过 HttpOnly Cookie 返回客户端；
|
||
4. 后续请求由中间件自动校验 Token 有效性，实现身份鉴权。
|
||
|
||
**数据流示意**：
|
||
```
|
||
Client → API → MySQL
|
||
```
|
||
|
||
### 4.2 音源集成（酷狗代理）
|
||
|
||
为解决酷狗API跨域限制与参数加密问题，部署Node.js中间件作为反向代理。
|
||
|
||
```javascript
|
||
// server/routes/music.js
|
||
router.get('/kg/search', async (req, res) => {
|
||
const { keyword } = req.query;
|
||
// 模拟酷狗 Hash 生成逻辑
|
||
const signature = generateKugouSignature(keyword);
|
||
try {
|
||
const response = await axios.get(`https://mobilecdn.kugou.com/api/v3/search/song?keyword=${keyword}&signature=${signature}`);
|
||
res.json(response.data);
|
||
} catch (error) {
|
||
res.status(500).json({ error: 'Music service unavailable' });
|
||
}
|
||
});
|
||
```
|
||
|
||
> 注：`generateKugouSignature` 为自定义算法封装，用于模拟酷狗客户端签名机制。
|
||
|
||
### 4.3 歌单下载功能（图片生成）
|
||
|
||
利用 HTML5 Canvas API 将排期歌曲列表绘制成图片，便于广播员通过手机端应用导入。
|
||
|
||
#### 实现逻辑
|
||
|
||
1. 获取用户输入的歌单标题和歌曲列表；
|
||
2. 使用 Canvas 绘制包含标题、日期、序号、歌曲名、歌手的图像；
|
||
3. 添加渐变头背景与页脚水印增强视觉识别；
|
||
4. 提供“下载”按钮触发 `canvas.toDataURL()` 并创建临时链接导出 PNG 图像。
|
||
|
||
#### 示例控制面板
|
||
|
||
- **歌单标题**：`2026-03-21 校园午间广播`
|
||
- **歌曲列表**：
|
||
```
|
||
晴天 - 周杰伦
|
||
稻香 - 周杰伦
|
||
起风了 - 买辣椒也用券
|
||
New Boy - 朴树
|
||
```
|
||
|
||
生成结果为一张尺寸为 **400×600** 的 PNG 图片，适配移动端查看与分享场景。
|
||
|
||
---
|
||
|
||
## 5. 界面设计指南
|
||
|
||
### 5.1 色彩方案
|
||
|
||
采用现代极简风格配色，突出品牌识别与阅读舒适性。
|
||
|
||
| 编号 | 颜色名称 | HEX 值 | 用途 |
|
||
|------|------------------|--------------|------------------------------------|
|
||
| 1 | Primary Blue | `#2563EB` | 主色调、按钮、高亮元素 |
|
||
| 2 | Neutral Dark | `#0F172A` | 标题文字、深色文本 |
|
||
| 3 | Background | `#F8FAFC` | 页面背景色 |
|
||
|
||
### 5.2 字体与布局
|
||
|
||
| 项目 | 设计规范 |
|
||
|------------|----------------------------------------------|
|
||
| 字体 | Inter / System UI，强调可读性与跨平台一致性 |
|
||
| 布局 | Bento Grid (便当盒) 风格卡片布局，模块化清晰 |
|
||
| 交互反馈 | 按钮与卡片增加微弱悬停上浮效果，提升操作感知 |
|
||
|
||
**示意图占位**：
|
||
```
|
||
[短条]
|
||
[长条]
|
||
[中条]
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 部署方案
|
||
|
||
### 6.1 PM2 前端部署
|
||
|
||
使用 PM2 管理 Nuxt 构建后的 Node.js 服务进程，保障稳定性与自动重启能力。
|
||
|
||
```bash
|
||
# 1. 构建项目
|
||
npm run build
|
||
|
||
# 2. 使用 PM2 启动
|
||
pm2 start npm --name "voicehub-nuxt" -- start
|
||
|
||
# 3. 设置开机自启
|
||
pm2 startup
|
||
pm2 save
|
||
```
|
||
|
||
### 6.2 Docker 编排配置
|
||
|
||
通过 Docker Compose 实现应用与数据库的一体化部署，提升环境一致性。
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
app:
|
||
build: .
|
||
ports:
|
||
- "3000:3000"
|
||
depends_on:
|
||
- db
|
||
environment:
|
||
- DATABASE_URL=mysql://user:pass@db:3306/voicehub
|
||
db:
|
||
image: mysql:8.0
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: rootpass
|
||
MYSQL_DATABASE: voicehub
|
||
```
|
||
|
||
> 建议配合 `.env` 文件管理敏感配置项，避免硬编码。
|
||
|
||
---
|
||
|
||
## 7. 风险分析与后续优化
|
||
|
||
### 7.1 风险与应对策略
|
||
|
||
| 编号 | 风险点 | 风险等级 | 应对策略 |
|
||
|------|------------------------|---------|--------------------------------------------------------------------------|
|
||
| 1 | 酷狗 API 接口变动 | 高 | 封装代理层，预留配置接口，便于快速切换加密算法 |
|
||
| 2 | 图片生成性能瓶颈 | 中 | 使用 Worker 线程处理 Canvas 绘制，避免阻塞主线程 |
|
||
| 3 | 数据库连接泄露 | 低 | 使用连接池（如 mysql2/promise），定期监控连接数，防止资源耗尽 |
|
||
|
||
### 7.2 后续优化建议
|
||
|
||
- **引入 Redis 缓存热门歌曲搜索结果**：减少重复请求压力，提升响应速度；
|
||
- **增加 WebSocket 实现前端播放进度同步**：适用于多终端协同广播场景；
|
||
- **开发小程序端入口**：拓展移动端使用场景，提升师生参与便利性。 |