music-website 全栈音乐网站部署指南:Vue 3 + Spring Boot + MySQL 从本地快速启动到 Docker Compose 上线
music-website 全栈音乐网站部署指南:Vue 3 + Spring Boot + MySQL 从本地快速启动到 Docker Compose 上线
本文以仓库根文档 README.en.md(对应中文版 README.md)为主体,结合仓库内真实的源码、配置与部署文件,系统讲解 music-website 的架构布局、技术选型、本地开发环境搭建、四服务启动顺序,以及面向 Linux 服务器的 Docker Compose 一键部署方案。读完本文,你将掌握:媒体资源目录的正确放置方式、数据库初始化与 profile 配置方法、前端后端各自的启动命令与端口约定,以及镜像构建与编排中的关键环境变量,从而能够独立把该项目跑通在本地或云服务器上。
项目概况:三层结构的全栈音乐网站
music-website 是一个用于学习交流的全栈音乐网站,客户端与管理端使用 Vue 实现,服务端使用 Spring Boot + MyBatis,数据库使用 MySQL。从仓库目录结构(见 README.en.md)可以清晰看出它被拆分为四个相对独立的模块:
music-website/
├── music-client/ # 前台 Web 客户端(Vue 3)
├── music-manage/ # 后台管理端(Vue 3)
├── music-server/ # 后端 API(Spring Boot)
│ └── data/ # 本地媒体与日志(img / song / logs)
├── deploy/ # Docker Compose 编排(镜像由各应用 Dockerfile 构建)
├── sql/ # 数据库初始化脚本
└── docs/ # 文档
- music-client:面向普通用户的网页客户端,包含首页、歌单、歌手、搜索、歌词、个人中心等页面;
- music-manage:管理后台,提供 Banner、用户、歌曲、歌手、歌单、评论等管理能力;
- music-server:提供全部 REST API 的 Spring Boot 后端,同时以
music-server/data作为本地媒体存储(图片、歌曲)与日志输出目录; - deploy:Docker Compose 编排目录,只负责容器间的组合与启动顺序,镜像本身由各应用目录下的
Dockerfile构建; - sql:数据库初始化脚本 yin_music.sql,包含建库建表语句与种子数据;
- docs:文档与项目截图资源(
docs/assets/下存放前台、后台的预览截图)。
主要功能模块
根据 README.en.md 的功能表,项目覆盖了音乐网站的典型业务闭环:
| 模块 | 能力 |
|---|---|
| 用户 | 登录注册、资料编辑、个人中心 |
| 发现 | 歌单推荐、歌单与歌手展示、歌曲/歌单搜索 |
| 互动 | 歌单与歌曲评论、收藏 |
| 播放器 | 播放、暂停、进度拖动、音量控制、歌词同步、下载 |
| 管理后台 | Banner、用户、歌曲、歌手、歌单、评论管理 |
这些能力在前后端代码中均有对应落地:客户端路由(music-client/src/router/index.ts)中可以看到 /song-sheet、/singer、/lyric/:id、/search、/personal 等页面,后端则以 SingerController、SongController、SongListController、CommentController、CollectController、BannerController、AdminController、UserSupportController 等一组控制器(位于 music-server/src/main/java/com/yin/music/controller/)提供接口支撑。
技术栈一览
README.en.md 的技术栈表格与仓库内实际依赖相互印证:
| 层级 | 技术 |
|---|---|
| 后端 | Spring Boot · MyBatis · Redis · 本地媒体存储(music-server/data) |
| 前端 | Vue 3 · TypeScript · Vue Router · Pinia · Axios · Element Plus(客户端)/ Naive UI(管理端) |
| 部署 | Docker · Docker Compose |
从源码可以进一步确认细节:
- 后端:
pom.xml(music-server/pom.xml)声明 Spring Boot 2.6.2 作为父工程、Java 版本 1.8,依赖包含mybatis-plus-boot-starter(3.5.1)、spring-boot-starter-data-redis、spring-boot-starter-mail、spring-security-crypto(用于 BCrypt 口令校验)、MinIO 8.3.0 与配套的 OkHttp 4.12.0(pom 注释特别说明:MinIO 8.x 需要 OkHttp 4,Spring Boot 2.6 默认带入的 OkHttp 3 会导致MinioClient初始化失败、应用无法启动)。 - 客户端:
music-client/package.json(music-client/package.json)确认使用 Vue 3.2、Vue Router 4、Pinia、Element Plus 2、Axios;脚本命令为vue-cli-service serve / build / lint。 - 管理端:
music-manage/package.json(music-manage/package.json)确认管理端 UI 组件库为 Naive UI 2.44,并额外引入echarts(后台统计图表)与cropperjs(头像裁剪),同样基于 Vue 3 + TypeScript。 - Redis 的作用:除会话与缓存外,还承担“忘记密码验证码”的存储(
app.password-reset.code-ttl-minutes等配置项,见下文),因此后端启动依赖 Redis。
开发环境要求
依据 README.en.md,本地开发推荐以下版本组合:
| 工具 | 版本 |
|---|---|
| JDK | 8+(如 jdk-8u141) |
| MySQL | 8.0+ |
| Redis | 5.0.8+(或用 Docker 启动 Redis) |
| Node.js | 16+ |
| IDE | IntelliJ IDEA / VS Code |
其中后端代码以 Java 8 编译(pom.xml 中 java.version=1.8),故 JDK 8 及以上均可;MySQL 要求 8.0+,Redis 要求 5.0.8+。前端依赖 Vue CLI 5(@vue/cli-service ~5.0.0),Node 16+ 即可满足。
快速开始:本地四步启动
1. 克隆仓库
git clone git@github.com:Yin-Hongwei/music-website.git
cd music-website
2. 下载媒体资源
音乐与图片资源需要从网盘下载(链接与提取码见 README.en.md),将 data 文件夹放到 music-server 下,最终得到:
music-server/data/img/
music-server/data/song/
注意: 请保持上述路径;本地日志默认写入
music-server/data/logs/。
为什么必须放在 music-server/data 下? 这由后端的媒体配置决定。application-dev.properties(music-server/src/main/resources/application-dev.properties)中 app.media.root=data,即媒体根目录相对进程工作目录,而后端默认从 music-server 目录启动,因此实际落点就是 music-server/data。目录内部的子目录划分与静态资源映射一一对应:img/avatarImages(用户头像)、img/singerPic(歌手图片)、img/songPic(歌曲封面)、img/songListPic(歌单封面)、img/swiper(轮播图)以及 song(音频文件)。这些映射在 WebMvcConfig.java 的 addResourceHandlers 中注册,缓存周期为 3600 秒。
进一步看,data/song 下的音频与图片资源不仅通过静态资源处理器暴露,还由 MediaController.java 提供统一读取入口(MinIO 优先、本地 data/ 回退、classpath 默认头像兜底的三级策略),并支持 HTTP Range 断点续传(ACCEPT_RANGES: bytes),这对播放器拖动进度条至关重要;LocalMediaStore.java 则在读文件前做了路径规范化与 .. 拦截,防止路径穿越。
3. 配置数据库
- 在 MySQL 中创建数据库,并导入 sql/yin_music.sql;
- 编辑
music-server/src/main/resources/application-dev.properties,修改spring.datasource.username与spring.datasource.password。
关于 profile 机制:application.properties(music-server/src/main/resources/application.properties)最后一行 spring.profiles.active=dev 表明默认激活 dev profile;dev profile 对应 application-dev.properties,其数据源默认值为:
spring.datasource.url=jdbc:mysql://localhost:3306/yin_music?serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&useUnicode=true&characterEncoding=utf8&autoReconnect=true
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
本地开发只需按实际情况改掉 username 与 password 即可;JDBC URL 中的 serverTimezone=Asia/Shanghai、characterEncoding=utf8 等参数建议保留,它们保证了时区与中文编码的正确性。仓库还提供了生产 profile application-prod.properties(music-server/src/main/resources/application-prod.properties),其中数据源等敏感配置全部改为 SPRING_* 环境变量注入,且默认 app.security.allow-legacy-md5=false(生产关闭旧 MD5 口令校验),适合服务器部署时配合环境变量使用。
导入的种子账号:初始化脚本自带演示数据——管理端账号 admin / 密码 123(BCrypt 存储,见 yin_music.sql 中 INSERT INTO admin 与注释 “DEMO ONLY”);用户表中 momo、yoona、Yin 等种子用户共享弱口令 123(旧 MD5 格式,见 yin_music.sql 的注释)。这些账号仅用于本地演示,公开部署前必须重置口令。
4. 按序启动四个服务
按以下顺序启动(可开多个终端窗口):
| 服务 | 目录 | 命令 |
|---|---|---|
| 后端 API | music-server |
./mvnw clean spring-boot:run(Windows 使用 mvnw.cmd) |
| Redis | — | redis-server |
| 前台客户端 | music-client |
npm install && npm run serve |
| 管理后台 | music-manage |
npm install && npm run serve |
后端启动命令详情(来自 README.en.md):
# macOS / Linux(推荐,使用项目自带 Maven Wrapper)
./mvnw clean spring-boot:run
# Windows(推荐)
mvnw.cmd clean spring-boot:run
# 备选:本机已安装 Maven 时
mvn clean spring-boot:run
仓库在 music-server 目录下确实内置了 mvnw 与 mvnw.cmd,可离线自举下载 Maven 依赖;pom 还配置了阿里云镜像仓库(见 pom.xml)以加速国内依赖拉取。
前端如何知道后端地址? 客户端 axios 实例的 baseURL 取自 process.env.VUE_APP_NODE_HOST || process.env.NODE_HOST(见 music-client/src/utils/request.ts),而 NODE_HOST 由 music-client/vue.config.js 在构建期注入,默认 http://localhost:8888。也就是说:本地开发时前后端都在本机、后端监听 8888 端口即可互通;部署时则通过构建参数覆盖该地址(见下文 Docker 部分)。请求层还统一封装了 api() 方法,把响应断言为 code / message / success / data 约定的 ApiResponse<T> 结构,并在 401/403 时自动跳转回首页。
常见问题排查
README.en.md 给出了两条高频排障指引:
| 现象 | 处理方式 |
|---|---|
| 图片或音乐加载失败 | 确认资源位于 music-server/data/img 与 music-server/data/song,并在 music-server 目录下启动后端 |
| 音乐无法播放 | 资源文件可能损坏,请从网盘重新下载并替换 |
第一条对应本文“下载媒体资源”一节强调的目录约束——资源路径错误或后端工作目录不对都会导致 404;第二条则是网盘资源在传输中出现损坏时的兜底方案。此外,结合源码还可以补充两点排查建议:若前端请求被跨域拦截,检查 app.security.cors.allowed-origins 是否包含当前页面来源(dev profile 默认放行 localhost:3000/8080/8081 与 127.0.0.1 对应端口,见 application-dev.properties);若忘记密码功能异常,确认 Redis 已启动——验证码存于 Redis,且 dev 环境默认 app.password-reset.mock-without-mail=true(不发真实邮件,接口 data.debugCode 直接返回验证码,方便本地测试)。
Docker Compose 一键部署
本地开发可跳过本节。适用于 Linux 服务器部署。
编排与镜像的分工
与多数项目不同,本仓库的部署体系把“镜像构建”与“容器编排”解耦:镜像定义放在各应用目录(music-server / music-client / music-manage 的 Dockerfile),deploy/docker-compose.yml 只负责编排。
cd deploy
docker compose up --build
启动后各服务地址:
| 服务 | 地址 |
|---|---|
| 前台 | http://localhost:8080 |
| 管理端 | http://localhost:8081 |
| API | http://localhost:8888 |
三个 Dockerfile 的构建细节
- 后端(music-server/Dockerfile):多阶段构建,
maven:3-openjdk-8-slim阶段执行mvn clean package -DskipTests产出yin-0.0.1-SNAPSHOT.jar,最终镜像为openjdk:8-jre-alpine,暴露 8888 端口,配置通过SPRING_PROFILES_ACTIVE与环境变量注入(与application-prod.properties的占位符设计呼应)。 - 两个前端(music-client/Dockerfile 与 music-manage/Dockerfile):同为多阶段构建——
node:20-alpine阶段用npm ci安装依赖并执行npm run build,产物dist交给nginx:1.27-alpine提供服务;ARG NODE_HOST即为构建期写入前端的后端地址。nginx 配置(music-client/nginx.conf)使用try_files $uri $uri/ /index.html实现 SPA 路由回退。
编排文件的关键环境变量
deploy/docker-compose.yml(deploy/docker-compose.yml)一共编排了 5 个服务:db(mysql:8.0)、redis(redis:7-alpine)、server、client、manage,并定义了 db-data 数据卷。其中可供部署者覆盖的可选环境变量有:
| 变量 | 作用 | 默认值 |
|---|---|---|
MYSQL_ROOT_PASSWORD |
MySQL root 密码,同时被 server 服务作为数据源密码引用 |
123456 |
API_PUBLIC_URL |
前端构建时写入的后端地址(NODE_HOST),前端所有 API 请求都打到该地址 |
http://localhost:8888 |
APP_SECURITY_ALLOW_LEGACY_MD5 |
是否允许旧 MD5 口令校验;种子数据含旧 MD5 口令,故本地默认 true,对外生产建议设 false 并重置用户密码 |
true |
除此之外,编排文件还固定注入了一批 server 服务环境变量,理解了它们就理解了生产部署的完整链路:
SPRING_PROFILES_ACTIVE: prod
SPRING_DATASOURCE_URL: jdbc:mysql://db:3306/yin_music?serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&useUnicode=true&characterEncoding=utf8&autoReconnect=true
SPRING_DATASOURCE_USERNAME: root
SPRING_DATASOURCE_PASSWORD: ${MYSQL_ROOT_PASSWORD:-123456}
SPRING_REDIS_HOST: redis
SPRING_REDIS_PORT: 6379
APP_SECURITY_CORS_ALLOWED_ORIGINS: http://localhost:8080,http://127.0.0.1:8080,http://localhost:8081,http://127.0.0.1:8081
这些 SPRING_* / APP_* 变量正是 application-prod.properties 中 ${...} 占位符的注入来源(如 SPRING_REDIS_HOST、SPRING_DATASOURCE_URL、APP_SECURITY_CORS_ALLOWED_ORIGINS,见 application-prod.properties),与 WebMvcConfig 中 CORS 白名单的 CSV 解析逻辑(WebMvcConfig.java)一一对应。此外还有几个值得注意的编排细节:
db服务通过../sql/yin_music.sql:/docker-entrypoint-initdb.d/yin_music.sql:ro把初始化脚本挂载进 MySQL 容器,首次启动自动建表并灌入种子数据;db配置了mysqladmin ping健康检查,server通过depends_on ... condition: service_healthy等待数据库就绪后再启动;server通过../music-server/data:/app/data将宿主媒体目录挂载进容器,与app.media.root的路径设计保持一致;client/manage的NODE_HOST构建参数来自API_PUBLIC_URL,因此生产环境务必将API_PUBLIC_URL设为客户端可访问的后端公网地址(例如https://api.example.com),否则浏览器里的前端将无法请求到后端。
部署到公网时的注意事项
- 数据库口令:生产环境务必通过
MYSQL_ROOT_PASSWORD覆盖默认的123456(编排文件注释明确提醒“正式环境务必覆盖,勿使用默认 123456”); - 旧口令兼容:种子用户口令为旧 MD5 格式,对外生产应设
APP_SECURITY_ALLOW_LEGACY_MD5=false并重置用户密码;管理端admin/123同样需要修改; - CORS 白名单:将
APP_SECURITY_CORS_ALLOWED_ORIGINS改为实际域名(前台与管理端来源),否则浏览器跨域请求会被后端拦截; - HTTPS:
application-prod.properties注释建议 HTTPS 部署时开启server.servlet.session.cookie.secure=true,并调整same-site等 Cookie 策略; - 媒体存储:生产建议将
app.media.root设为绝对路径(如/var/yin-music/data),并保证目录挂载与权限正确。
许可与使用约定
依据 README.en.md,该项目以 Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) 协议开源,禁止商用;作者在项目说明中亦声明项目仅作技术学习交流分享。引用本仓库源码或文档时请遵守上述约定。
小结
music-website 是一个结构清晰、开箱即用的全栈音乐网站示例:前端(Vue 3 + TypeScript + Pinia)与后端(Spring Boot + MyBatis + Redis)职责分明,媒体资源走 music-server/data 本地目录并通过安全读取组件暴露,数据库初始化脚本自带演示账号,部署体系则由“应用级 Dockerfile + Compose 编排”双层构成。无论你是想学习 Vue 3 与 Spring Boot 的联动开发,还是需要一个可直接在服务器上跑通的音乐站参考实现,都可以按本文的本地四步流程或 Docker 一键编排快速落地,再结合仓库内 docs/ 目录的截图与各模块源码继续深入。