# 校园广播站点歌系统改造技术方案 > 基于 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中间件作为反向代理。 ```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 实现前端播放进度同步**：适用于多终端协同广播场景； - **开发小程序端入口**：拓展移动端使用场景，提升师生参与便利性。