BYW-VoiceHub/校园广播站点歌系统改造技术方案.md

校园广播站点歌系统改造技术方案

基于 Nuxt 4 与 Node.js 的现代化重构，专注于酷狗音源集成与高效排期管理。

---

1. 项目概述

1.1 项目背景

随着校园文化生活需求的提升，原有的点歌系统在用户体验、音源稳定性及管理便捷性上已显不足。为了提供更现代化、简洁且高效的广播服务，决定对现有开源项目 VoiceHub 进行深度改造。

1.2 改造目标

• 引入用户注册机制，实现个性化点歌记录追踪。
• 精简音源，统一接入酷狗音乐代理服务，确保版权与音质。
• 开发后台管理功能，支持将排期歌单一键转换为图片，便于移动端导入。
• 全面升级 UI 设计，采用简洁高级的现代化风格。

1.3 开源协议

本项目遵循 MIT 协议，允许自由使用、修改和分发。

MIT License

本项目遵循 MIT 协议，允许自由使用、修改和分发。

---

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中间件作为反向代理。

// 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 服务进程，保障稳定性与自动重启能力。

# 1. 构建项目
npm run build

# 2. 使用 PM2 启动
pm2 start npm --name "voicehub-nuxt" -- start

# 3. 设置开机自启
pm2 startup
pm2 save

6.2 Docker 编排配置

通过 Docker Compose 实现应用与数据库的一体化部署，提升环境一致性。

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 实现前端播放进度同步：适用于多终端协同广播场景；
• 开发小程序端入口：拓展移动端使用场景，提升师生参与便利性。