music-website 全栈音乐网站部署指南:Vue 3 + Spring Boot + MySQL 从本地快速启动到 Docker Compose 上线

原创2026-10-14 22:00:201,840 阅读
文章标签:后端前端音视频

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. 配置数据库

  1. 在 MySQL 中创建数据库,并导入 sql/yin_music.sql;
  2. 编辑 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/ 目录的截图与各模块源码继续深入。

登录后查看全文
music-website