做过几个前后端分离的音乐类项目之后，我最大的感受是：音乐网站看起来简单，真正动手做才发现，它并不是一个“能放歌的网页”那么简单。尤其当标题里加上“企业级”“管理系统”这两个词，意味着你要处理的就远不止播放暂停，还有用户体系、版权素材管理、歌单收藏、评论互动、后台数据统计这些完整闭环。
这篇文章就以一套 SpringBoot + Vue + MyBatis + MySQL 实现的 web 音乐网站管理系统为例，从业务功能拆解、数据库设计、后端接口实现，到前端播放器交互、部署上线和常见故障排查，把整个项目怎么落地讲清楚。适合正在做课程设计、毕业设计，或者想从零搭建一个完整全栈项目的开发者参考。内容会偏实战，代码上不会整段贴完，但关键的实现思路、表结构、接口设计、踩坑点都会交代清楚。
1. 做项目之前先想清楚：音乐网站的核心业务闭环
1.1 音乐站不是只有播放器，还要有“管理”二字
很多人一上来就写播放器，做得再炫酷，本质上还只是一个前端 Demo。企业级 web 音乐系统，重点落在“管理”上：管理员要能维护歌曲、歌手、专辑、歌单，用户要能注册、登录、搜歌、收藏、评论，系统要能记录播放行为并做数据统计。这样一套业务闭环，才是“管理系统”四个字的真正含义。
所以动手编码前，我习惯先把业务模块画成一张脑图。以我这个项目为例，整体拆成了两个端：
- C 端（用户端）：注册登录、首页推荐、歌曲搜索、歌手专辑浏览、歌单详情、播放器、收藏、评论、个人中心、播放历史。
- B 端（管理端）：仪表盘统计、用户管理、歌手管理、专辑管理、歌曲管理、歌单管理、评论审核、系统配置。
两端共用一套 SpringBoot 后端接口，前端分别用 Vue 构建两个独立应用，部署时同域共端口，通过路径前缀区分。这么做的好处是权限模型清晰：管理员接口统一走/admin/**前缀，普通用户接口走/api/**前缀，后端通过拦截器区分角色。
1.2 什么样的功能清单才算“企业级”
我见过不少音乐系统，功能写得很满，但一细看就露馅：没有权限校验、没有统一的返回格式、没有全局异常处理、SQL 全是SELECT *。所谓企业级，我认为最少要满足以下标准：
一是统一响应协议。所有接口返回{ code, message, data }结构，方便前端统一处理错误码。二是完善的登录鉴权。用户和管理员两套身份体系，接口必须做权限控制，不能前端隐藏按钮就算安全。三是合理的数据表设计和索引。业务数据随便查都是几十毫秒内响应，不能一个报表接口搞到数据库 CPU 飙红。四是可配置、可维护。比如文件上传路径、CDN 地址、歌曲转码参数，都应该写在配置文件中。
这套标准的背后，对应的是扎实的 SpringBoot 工程结构。我习惯分包为controller / service / mapper / entity / dto / config / common，把拦截器、异常处理器、工具类都归到 common 包下，避免 controller 里写一大堆业务逻辑。
2. 技术选型的账这样算：SpringBoot+Vue+MyBatis+MySQL为什么能打
2.1 放弃SSH、放弃JPA的原因
早几年做 Java Web，绕不开 Spring MVC + Spring + MyBatis 这套 SSM 组合，配置繁琐到让人怀疑人生。SpringBoot 出现后，通过自动配置把大量 XML 配置干掉，内嵌 Tomcat，一个mvn spring-boot:run就能起服务，这也让它成为目前 Java 后端的绝对主流。
说到 MyBatis 和 JPA，很多新手纠结。我的实际体验是：音乐系统里大量涉及多表关联查询、动态条件筛选、统计报表，这类 SQL 用 MyBatis 的 XML 文件维护起来非常灵活，你可以精确控制每一条 SQL；而 JPA 在简单 CRUD 上确实更爽，但一旦遇到复杂查询，要么写 JPQL，要么走原生 SQL，反而绕远路。MyBatis 还有个优势是 SQL 可以直接拿出去在 Navicat 里执行验证，排查数据问题时效率高得不是一点半点。
2.2 Vue 在前端选型中的主导地位
Vue 在国内开发者中的普及度不言而喻。对于音乐站这种交互密集的应用，Vue 的响应式数据绑定和组件化开发能极大提升开发效率。尤其播放器这类的核心模块，我把播放状态、播放列表、当前歌曲封装成一个全局组件，通过 Vuex 管理状态，这样在页面跳转后播放不会中断。
Vue 生态里的 Vue Router 和 Pinia/Vuex 基本是标配。老项目喜欢 Vuex，新项目建议直接用 Pinia，API 更简洁，还天然支持 TypeScript 类型推导。我这个项目用的是 Vuex，主要是为了兼容团队既有代码，如果你从零开始，直接上 Pinia 就行。
2.3 版本选型的血泪教训
版本是坑最多的地方。SpringBoot 3.x 要求 JDK 17+，如果你本地还是 JDK 8，强行升级会碰到一堆依赖不兼容问题。我的建议是：做企业项目优先选 SpringBoot 2.7.x + JDK 8 这套组合，稳定、教程多、遇到问题网上随便一搜都有答案。MyBatis 用 mybatis-spring-boot-starter 2.3.x 版本，MySQL 用 8.0 以上，连接驱动记得加com.mysql.cj.jdbc.Driver而不是老的com.mysql.jdbc.Driver。
前端的话，Vue 3 + Vite 是主流方向，Vue 2 已进入维护末期，新项目别再用了。Node 版本至少要 16+，装依赖时如果报ERESOLVE unable to resolve dependency tree，多半是 npm 版本和依赖冲突，换个淘宝镜像源，或者用 pnpm 可以省很多事。
3. 数据库建模：把“音乐”拆成表是最费脑力的一步
3.1 核心表设计与ER关系
数据库设计决定了项目能走多远。我把音乐系统拆成以下核心表：
user：用户表，字段包括 id、username、password（BCrypt加密）、nickname、avatar、gender、phone、email、status、create_time。singer：歌手表，字段包括 id、name、avatar、intro、area（华语/欧美/日韩）、style（流行/摇滚/民谣）。album：专辑表，字段包括 id、singer_id、name、cover、publish_time、description。song：歌曲表，字段包括 id、album_id、singer_id、name、duration、url、lyric、play_count、status。song_list：歌单表，字段包括 id、user_id、name、cover、description、play_count、type（分类标签）。song_list_song：歌单歌曲关联表，字段包括 id、song_list_id、song_id。favorite：用户收藏表，字段包括 id、user_id、type（0歌曲/1歌单/2专辑）、target_id、create_time。comment：评论表，字段包括 id、user_id、song_id、content、parent_id、like_count、create_time。play_history：播放历史表，字段包括 id、user_id、song_id、play_time、duration_played。admin：管理员表，字段包括 id、username、password、role、last_login_time。
表之间的核心关系很简单：歌手一对多专辑，专辑一对多歌曲，用户多对多歌单，用户多对多歌曲（通过收藏）。但在实际的 ER 图中你会发现问题集中在关联表的设计上，比如一个歌单里歌曲顺序是否要记录？我的做法是加一个sort_order字段，方便歌单自定义排序。
3.2 索引、唯一约束与外键的最佳实践
表结构设计完，索引设计直接决定线上性能。我在这些位置加了索引：
- 登录场景：
user.username、admin.username建唯一索引。 - 搜索场景：
song.name、singer.name建普通索引，量大了以后可以升级为全文索引。 - 列表展示：
song.singer_id、song.album_id、song_list.user_id建普通索引，避免联合查询全表扫描。 - 播放历史：
play_history.user_id + play_history.play_time建联合索引，个人中心查询最近播放走这个索引非常快。
外键这块，我项目里没有使用物理外键，全部通过逻辑关联维护。原因很简单：互联网业务模块拆分后，外键约束会严重拖累写入性能，而且后续如果要分库分表，物理外键会变成巨大的阻碍。你只需要在应用层保证删除歌手时同时删除其专辑歌曲，或者标记删除状态即可。
3.3 MySQL版本与字符集踩坑
MySQL 8.0 推荐使用utf8mb4字符集，不是utf8！因为utf8在 MySQL 里最多 3 字节，存不了 emoji 表情。用户昵称里一旦出现 emoji，写入就报错，这种问题排查起来特别隐蔽。
另外，MySQL 8.0 默认认证插件是caching_sha2_password，老版本的驱动连不上会报Unable to load authentication plugin 'caching_sha2_password'，要么换驱动版本，要么创建用户时指定mysql_native_password。这里我踩过好几次坑，建议直接写在建库脚本里：
CREATE DATABASE music_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER 'music_app'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password'; GRANT ALL PRIVILEGES ON music_db.* TO 'music_app'@'%';这样后端配置连接串时，指定characterEncoding=utf8&serverTimezone=Asia/Shanghai基本就不会再遇到乱码和时区问题了。
4. 后端核心模块落地：认证、文件、播放和搜索
4.1 JWT实现登录态，Session为何退场
传统单体应用喜欢用 Session + Cookie 保存登录态，但前后端分离后，前端可能部署在独立域名下，接口服务器是另一个地址，Cookie 跨域处理非常麻烦。我的选择是用 JWT，后端把用户 id、角色、过期时间签发进 token，前端存到 localStorage，每次请求在Authorization头里带上。
JWT 实现认证的流程并不复杂：
- 登录接口校验用户名密码，成功则用
jjwt库生成 token 返回。 - 自定义拦截器，拦截需要认证的路径，从 header 取 token 并解析。
- 校验通过后，把用户信息放入
ThreadLocal，业务代码直接获取当前用户。 - token 过期返回 401，前端收到后跳转登录页。
至于 token 过期时间，我的设置是普通用户 24 小时，管理员 2 小时。没有做 refresh token 机制，因为音乐网站对登录连续性的要求没那么高。
4.2 歌曲/专辑封面的上传与静态资源映射
管理端需要上传歌曲文件和封面图片，这里涉及两个问题：文件存哪里、前端怎么访问。本地开发时我建议直接把文件存到磁盘某个固定目录，比如/data/music/cover和/data/music/audio，不要存数据库，数据库只放 URL 路径。
SpringBoot 需要配置静态资源映射，把 URL 路径映射到磁盘目录：
spring: servlet: multipart: max-file-size: 50MB max-request-size: 100MB resources: static-locations: classpath:/META-INF/resources/,classpath:/resources/,classpath:/static/,classpath:/public/,file:/data/music/再把 WebMvcConfigurer 里的 addResourceHandlers 加一个映射，这样上传后的文件路径存/cover/xxx.jpg，前端就能直接通过域名访问到。注意生产环境千万别把文件和应用放在同一块小磁盘上，日志和音频并发写入会把磁盘 IO 拖垮。
4.3 m3u8播放链路的接入与兼容方案
音乐网站对接音频流时，经常会遇到 m3u8 格式。m3u8 本质是一个索引文件，里面记录了一串 ts 分片地址，播放器按顺序拉取分片实现流式播放。这种格式的优势在于支持多码率、拖动进度方便、天然适合 CDN 分发。
我做这个项目时客户给的素材有一部分就是 m3u8 直播录制文件。Vue 前端播放 m3u8，原生<audio>标签是不支持的，我用了hls.js这个库，用法非常简单：
import Hls from 'hls.js'; function playM3u8(url, videoElement) { if (Hls.isSupported()) { const hls = new Hls(); hls.loadSource(url); hls.attachMedia(videoElement); hls.on(Hls.Events.MANIFEST_PARSED, () => { videoElement.play(); }); } else if (videoElement.canPlayType('application/vnd.apple.mpegurl')) { videoElement.src = url; videoElement.play(); } }但这里有个后端必须配合的点：浏览器跨域请求 m3u8 文件时，如果响应头里没有Access-Control-Allow-Origin，分片 ts 文件会被拦截。我在 Nginx 代理音频路径时统一加了 CORS 头，这问题才算彻底解决。
4.4 模糊搜索与热门歌单推荐的小技巧
搜索是音乐站的高频操作，我做了歌曲、歌手、专辑的全局模糊搜索，对应 SQL 大概是这样：
SELECT s.id, s.name, s.duration, s.url, si.name AS singer_name FROM song s LEFT JOIN singer si ON s.singer_id = si.id WHERE s.name LIKE CONCAT('%', #{keyword}, '%') OR si.name LIKE CONCAT('%', #{keyword}, '%') ORDER BY s.play_count DESC LIMIT 30数据量不大时 LIKE 完全够用。但如果歌曲表到了百万级，建议接入 Elasticsearch 或 MySQL 全文索引。推荐模块我偷了个懒，用了最简单的“热门歌单”：按播放量倒序取前 10 个歌单，再随机打乱返回给用户首页，成本和效果达到了一个不错的平衡。
5. 前端Vue工程：把播放体验做成“自来水”
5.1 项目初始化和路由设计
Vue 前端我拆成了两个工程，music-admin和music-web，这样管理端和用户端独立开发、独立部署。初始化用 Vite 脚手架：
npm create vite@latest music-web -- --template vue cd music-web npm install路由设计上，用户端包含首页、歌单、歌手、排行榜、搜索页、歌单详情、歌手详情、个人中心这些页面。前端路由需要按需加载，用const routes = [{ path: '/', component: () => import('@/views/Home.vue') }]这种写法，避免首屏包体过大。
管理端路由要设置一个前置守卫，每次跳转时检查 localStorage 里有没有 token，没有就重定向到登录页。后端接口也要校验，不能只靠前端拦，这点必须反复强调。
5.2 播放器组件与状态管理的集成玩法
播放器是整个前端最复杂的组件。它的状态太多：当前播放歌曲、播放列表、播放状态、当前时间、总时长、音量、播放模式（顺序/随机/单曲循环）。我把它封装成全局组件PlayerBar.vue，用 Vuex 管理播放状态。
播放器设计有一个重要细节：歌曲切换时，如果直接替换<audio>标签的 src，浏览器会重新加载，中间存在明显卡顿。我的做法是保留一个隐藏的<audio>元素，切换歌曲时只更新 src 并调用load() + play()，进度条用timeupdate事件更新，拖动进度条时用currentTime赋值。
收藏功能与播放器的联动也需要设计好。播放列表里每首歌显示红心图标，用户点击后调收藏接口，成功后更新 Vuex 中的收藏列表。这里的关键是接口返回后要有一个 loading 状态，避免用户连续点击导致重复调用。
5.3 你大概率会遇到的m3u8和跨域问题
前端联调时最常遇到两个问题。一个是本地开发跨域，Vite 的 dev server 配置 proxy 解决：
server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }另一个是上面提到的 m3u8 播放。我一开始用video.js播放 m3u8，发现移动端兼容性不好，后来换了hls.js，桌面浏览器兼容性直接拉满。还有一个坑是音频文件如果代理配置不对，浏览器拿到的是 HTML 而不是音频流，加载直接失败，这种情况下先开 DevTools Network 面板看响应内容，比瞎猜效率高得多。
6. Nginx部署与线上故障排查记录
6.1 前后端分离部署的目录与代理配置
前端打包后生成dist目录，里面有静态的 html、css、js 文件。Nginx 里我按两个 server 块配置：一个负责用户端，一个负责管理端，也可以合并成同一个 server 用不同 location。我是独立域名分开的，结构更清晰：
server { listen 80; server_name www.music-example.com; root /data/www/music-web/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /audio/ { alias /data/music/audio/; add_header Access-Control-Allow-Origin *; } }try_files这行是解决 Vue Router history 模式下刷新页面 404 的关键。如果没有它，用户在/song/123页面刷新，Nginx 找不到对应文件，直接返回 404。加上这行之后，刷新请求会全部回退到 index.html，由前端路由接管。
6.2 线上音乐加载慢：定位与优化
部署后用户反馈点一首歌要转好几秒，第一反应是接口慢，但打开 Network 面板发现接口 50ms 就返回了，卡在音频文件加载上。查了下发现音频文件存在普通磁盘上，单个文件 8MB，用户带宽一般，自然要等很久。
我的优化方案有几步：第一，音频文件改用对象存储 OSS，开启 CDN 加速，静态资源访问速度快很多；第二，接口返回歌曲列表时，数据里带一个preload字段，前端在当前歌曲即将播放完时预加载下一首；第三，封面图片都走 WebP 格式压缩，体积降低 60% 以上。经过这三步优化，实际体感基本是秒开。
6.3 会话失效、静态资源404、数据库连接池爆掉
线上遇到过几个很典型的故障，这里做一个记录。
会话失效问题：用户反馈用着用着突然跳登录，排查发现是因为 JWT token 没有续期策略。登录状态保持 24 小时，对音乐网站来说够用，但用户长时间停留页面，token 到期后任何请求都 401，前端统一弹登录框。后来我在前端加了一层拦截：401 时静默刷新一次 token（用本地存的 refreshToken），刷新失败才跳登录页，体验提升很多。
静态资源 404：部署管理端后发现登录页的 JS/CSS 加载不出来，看 Nginx error log 发现路径被拼错了。管理端打包时默认资源路径是/assets/xxx.js，而管理端部署在子路径/admin下，导致请求到了/assets/找不到文件。解决方式是 Vite 配置base: '/admin/'，重新构建一次就正常了。
数据库连接池爆掉：上线初期连接池配置用的是 HikariCP 默认值maximum-pool-size: 10，每天高峰时段都会有几十个请求报Connection is not available, request timed out。调整配置后解决：
spring: datasource: hikari: maximum-pool-size: 50 minimum-idle: 10 connection-timeout: 30000 max-lifetime: 1800000核心逻辑是：连接池大小不是越大越好，一般CPU核心数*2 + 磁盘数量是一个参考值。但业务高峰期查询量大，适当调大连接数并增加 wait 超时时间，能有效缓解瞬时并发压力。同时给play_history这类高频写入表加批量插入逻辑，减少连接占用。
配置调整之后还是要治本，检查慢 SQL。我用show processlist抓到几条全表扫描的统计 SQL，给相关字段补了索引，连接池占用率马上降下来了。这算是线上调优最实在的一课。
7. 这套源码还能怎么改
项目做完后，我常被问的一个问题是“接下来还能加点什么”。我说几个我认为性价比很高的方向：
一是做推荐算法。目前首页的热门歌单是纯按播放量排序，你可以把用户的历史播放数据做一个协同过滤推荐，算出的用户相似度存入一张user_recommend表，定时任务每天更新一次。虽然算法本身不复杂，但带来的体验提升非常明显。
二是评论系统增强。当前评论只支持一级评论，你可以扩展为楼中楼，增加点赞、举报、审核状态。这块后端改动不大，主要是前端组件结构要支持嵌套。
三是接入第三方登录。目前只有账号密码登录，加上微信扫码或 GitHub OAuth，用户门槛会低很多。OAuth 的核心逻辑就是引导用户跳第三方授权页，拿到 code 后后端调接口换 token，再解析用户信息，整体不难。
四是在线播放数据统计。目前只有播放总量，没有每首歌的 UV、PV、播放完成率，你可以基于play_history表做一个定时分析任务，输出运营日报。
如果你手头正好要做一个音乐站的课程项目，或者想基于这套架构接一个真实的商业需求，建议先把用户管理、权限控制、文件存储这几条主链路吃透，剩下的一切都是锦上添花。我在实际开发中体会最深的一点是：项目跑通只是开始，把数据库索引和连接池这些地基打牢，才是后面不被线上事故追着跑的前提。
