JavaWeb音乐播放器项目实战：从Servlet到Tomcat部署全解析

很多朋友一开始做JavaWeb项目，都会选“音乐播放器”这个方向，毕竟人人都听歌，需求清晰，演示起来也直观。但真正动手之后才会发现，这个题目想做得像个样子，牵扯到的技术点远比想象中多：用户登录注册怎么串进来、歌曲文件存在哪、播放时怎么处理音频流、前端怎样优雅地拿到歌曲列表、最后怎么把整个项目发布到Windows服务器上跑起来。这篇文章我就把自己从零搭建一个JavaWeb音乐播放器的完整过程记录下来，包含MySQL表结构设计、Servlet三层架构、流式音频播放、VSCode开发配置，以及Apache+Tomcat在Windows Server上的部署方案。内容适合刚学完JavaSE和MySQL基础、准备做第一个完整Web项目的同学，也适合临近期末或找工作需要整理项目经验的开发者参考。

1. 为什么用JavaWeb而不是一上来就上Spring Boot：项目定位与选型思路

1.1 这个项目到底在训练什么能力

很多人问我，现在企业里都用Spring Boot，做个音乐播放器为何还要抱着Servlet和JSP不放？我的回答是：因为练手项目和真实业务项目的目标根本不同。你最终要获得的不是“我会用Spring Boot写增删改查”，而是“我理解一个Web系统从请求到响应的完整链路”。纯Servlet项目里，请求怎么被Tomcat接收、Servlet如何匹配URL、Session怎么维持登录状态、JDBC连接如何获取和释放、JSP怎么渲染动态页面，每一个环节都暴露在你面前。用上Spring Boot之后，这些东西大部分被封装进框架，初学者反而失去了感知底层的机会。

换句话说，JavaWeb音乐播放器这个题目，本质上是把你之前学的Java语法、集合框架、IO流、多线程、JDBC、MySQL、HTML/CSS/JavaScript全部串起来的一次综合演练。第一次做完整项目的人，最大的收获不是播放功能本身，而是理解分层思想——Controller层负责接收请求，Service层负责业务逻辑，Dao层负责数据访问。这个思想一旦建立，后面学框架、做分布式、看微服务源码，都会轻松很多。

1.2 具体选型清单与取舍理由

这里给出我实际使用的技术栈清单，每一行都附上选择理由，方便你评估自己项目是否能直接复用。

这套组合最大的特点是：每个组件都能让你看到它存在的必要性。比如选Maven，是因为Servlet离不开javax.servlet-api依赖，如果不引入构建工具，拷Jar包会非常痛苦；选JSP而不是前后端分离，是因为这个阶段你还不熟悉跨域和JSON接口设计，JSP在服务端渲染页面可以直接拿到User对象，不用手动拼接口文档。

1.3 哪些功能应该做，哪些功能不该碰

项目功能边界一定要提前划清楚，不然会陷入无休止的“加需求”状态。以音乐播放器来说，我做的是这些功能：用户注册登录、歌曲列表展示、歌曲详情页、在线播放、歌词展示、收藏歌曲、播放历史、搜索歌曲。这些功能覆盖了JavaWeb的核心考点：表单提交、Session、JDBC查询、外键关联、模糊搜索、文件上传下载、流式响应。至于那些与核心学习目标无关的功能，比如随机播放算法、评论区的敏感词过滤、推荐系统，我建议第一版全部砍掉。它们要么属于算法范畴，要么需要额外中间件，放到第二期再扩展完全来得及。

选好定位之后，接下来从数据库设计开始落地。

2. MySQL表结构设计：歌曲数据与用户行为的建模

2.1 核心表的职责划分

数据库设计是这个项目里最不能跳过思考的环节。我第一次做的时候，想着“不就是几张表吗”，结果建了三张表就发现逻辑互相矛盾：用户在“歌曲表”里直接加了收藏字段，播放历史又不知道存到哪。正确的做法是，把数据按业务主体拆分。我的项目最终保留了四张表：用户表，存储账号信息；歌曲表，存储歌曲元数据和文件路径；收藏表，记录用户跟歌曲之间的多对多关系；播放历史表，记录“谁在什么时间听了什么歌”。

这四张表实际上对应了三种业务角色：用户、资源、关系。记住一个原则：用户和歌曲之间的行为关系，永远不应该以字段形式挂在用户表或歌曲表上，而应该单独建一张关系表。哪怕你现在只需要“收藏”一个功能，也要用独立的收藏表来承载，这样后续加“我喜欢”“最近播放”“歌单”时，不需要重新设计数据库。

2.2 歌曲表设计中的关键字段：文件路径还是BLOB

歌曲文件的存储策略是个值得展开讲的点。最初我纠结过：把MP3文件直接以二进制对象存进MySQL的BLOB字段行不行？答案是技术上可行，但实践上不要这么干。原因有两点：第一，BLOB字段会让数据库表变得无比庞大，备份、查询、索引优化全都受影响；第二，播放器加载音频时，需要按照字节范围分段读取，直接把BLOB取出来再写流，实现起来非常别扭。正确的方案是：歌曲文件上传到服务器磁盘的某个目录（比如D:/music_files/），数据库里只存文件的相对路径或访问URL。播放请求到达时，后端根据路径定位文件，以流的形式写给前端。

这样设计的好处是：数据库保持轻量，文件管理和迁移都方便；同时前端audio标签可以直接请求一个play?id=xxx的Servlet地址，由后端控制音频流输出，后续做权限校验、防盗链都很容易。以下是歌曲表的实际建表SQL，我加了注释，方便你对照理解。

sql复制CREATE TABLE `t_song` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '歌曲ID',
  `song_name` varchar(100) NOT NULL COMMENT '歌曲名称',
  `singer` varchar(100) DEFAULT NULL COMMENT '歌手',
  `album` varchar(100) DEFAULT NULL COMMENT '专辑',
  `duration` int(11) DEFAULT NULL COMMENT '音频时长(秒)',
  `lyric` text COMMENT 'LRC歌词文本',
  `file_path` varchar(255) NOT NULL COMMENT '音频文件服务器路径',
  `cover_path` varchar(255) DEFAULT NULL COMMENT '封面图片路径',
  `play_count` int(11) DEFAULT '0' COMMENT '播放次数',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '上传时间',
  PRIMARY KEY (`id`),
  KEY `idx_song_name` (`song_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='歌曲信息表';

2.3 用户表、收藏表与播放历史表的关联设计

用户表相对简单，但有一个关键点要提醒：密码字段不能存明文。第一次做项目的人最容易在这里偷懒，直接INSERT INTO t_user VALUES('admin', '123456')，这等于把用户账号裸奔在数据库里。我的做法是使用JDK自带的MessageDigest做SHA-256加盐哈希，盐值取用户名加固定前缀，虽然比不上BCrypt专业，但作为教学项目已经足够说明安全意识。建表时注意密码字段长度至少要64个字符，因为SHA-256摘要固定是64位十六进制字符串。

收藏表和播放历史表都属于关联表，结构大同小异。收藏表的唯一约束是(user_id, song_id)，避免同一个用户重复收藏；播放历史表则不设唯一约束，每次播放都插入新记录，并用时间戳倒序查询来得到“最近播放”列表。需要特别注意的是，关联表必须添加联合索引，否则数据量上去之后，查询“某用户收藏了哪些歌曲”会走全表扫描，慢得让人怀疑人生。

sql复制CREATE TABLE `t_favorite` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user_id` int(11) NOT NULL COMMENT '用户ID',
  `song_id` int(11) NOT NULL COMMENT '歌曲ID',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '收藏时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_song` (`user_id`, `song_id`),
  KEY `idx_song_id` (`song_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='收藏表';

CREATE TABLE `t_history` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user_id` int(11) NOT NULL COMMENT '用户ID',
  `song_id` int(11) NOT NULL COMMENT '歌曲ID',
  `play_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '播放时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_time` (`user_id`, `play_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放历史表';

数据库的字段类型、索引设计这些细节，建议你建表之前用Visio或Draw.io画一下ER图，把表之间的关系标清楚。我在实际编码前就吃过没画图的亏：收藏表和历史表字段几乎一样，改来改去，最后是靠重新画图才理清的。

3. 后端编码落地：Servlet三层架构与核心业务实现

3.1 项目目录结构与包名规划

用Maven创建一个标准的Web项目后，目录结构应该是这样的：src/main/java存放Java源码，src/main/resources存放配置文件，src/main/webapp存放JSP页面和静态资源。Java源码分包我采用了最经典的三层结构，这一点很重要，建议你尽早养成习惯。

控制器层放在com.demo.music.controller包下，里面写的是各个Servlet类；业务层放在com.demo.music.service包下，定义接口和实现类；数据访问层放在com.demo.music.dao包下，负责JDBC操作。此外我还加了三个辅助包：entity放实体类，util放工具类如DBUtil、MD5Util，filter放字符编码过滤器。这样的分层在初期会显得“绕”，但当你同时改动一个播放接口和一个收藏接口时，就会发现改业务代码不会被数据库代码干扰，排查问题也只需要沿着Controller→Service→Dao的方向看调用链。

3.2 统一编码与统一响应：从Filter开始

JavaWeb项目刚跑起来遇到的第一批报错，十有七八跟编码有关。Windows下VSCode默认文件编码可能是GBK，而浏览器和MySQL用的是UTF-8，结果就是页面上出现一堆乱码，控制台日志也乱得没法看。解决办法是三步：第一，VSCode右下角把项目文件编码统一改为UTF-8；第二，MySQL连接URL加上characterEncoding=utf8参数；第三，写一个编码过滤器，对所有请求和响应设置UTF-8。

java复制@WebFilter("/*")
public class EncodingFilter implements Filter {
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) resp;
        request.setCharacterEncoding("UTF-8");
        response.setCharacterEncoding("UTF-8");
        response.setContentType("text/html;charset=UTF-8");
        chain.doFilter(request, response);
    }
}

这段代码看着简单，但在项目里起到的是一票否决的作用。没有这个过滤器，你后续所有POST表单提交的中文参数都会变成问号，所有JSP渲染出来的中文都是乱码。这个Filter应该作为所有JavaWeb项目的标配，跟数据库连接池一样，一上来就配上。

3.3 注册登录：Session管理与密码加密

注册登录是音乐播放器的进入门槛，也是JavaWeb项目最常考的知识点。需要做的核心事情有三件：用户提交表单、Servlet校验参数、Service调用Dao完成Jdbc操作。注册逻辑里要判断用户名是否已存在，登录逻辑里要验证密码是否正确。验证通过后，把用户ID和用户名存入Session，后续页面就可以通过session.getAttribute("user")来判断是否已登录，决定是否显示收藏按钮。

密码加密这一块，我使用SHA-256加盐算法，核心代码如下：

java复制public static String sha256(String rawPassword, String salt) {
    String result = null;
    try {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        digest.update((salt + rawPassword).getBytes(StandardCharsets.UTF_8));
        byte[] bytes = digest.digest();
        StringBuilder builder = new StringBuilder();
        for (byte b : bytes) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) builder.append('0');
            builder.append(hex);
        }
        result = builder.toString();
    } catch (NoSuchAlgorithmException e) {
        e.printStackTrace();
    }
    return result;
}

需要注意的坑是：Integer.toHexString返回的十六进制字符串，当值小于16时开头会省略0，导致最终摘要长度不足64位。因此必须做补零操作，否则同一密码在不同次运行下可能得到不同长度的密文，登录时校验必挂。这个补零问题非常隐蔽，我调试了将近半小时才反应过来。

3.4 歌曲列表与搜索：PreparedStatement防SQL注入

歌曲列表页需要从数据库查出所有歌曲，展示在页面上。传统写法是Statement拼接SQL字符串，比如SELECT * FROM t_song WHERE song_name LIKE '%' + keyword + '%'。这种写法在功能上没问题，但存在SQL注入风险。用户输入一个' OR 1=1 --就能把整张表捞出来，这在练习项目里看似无所谓，但一旦养成习惯，后面工作写代码就会踩大坑。正确做法是全程使用PreparedStatement的?占位符。

java复制public List<Song> searchSongs(String keyword) {
    String sql = "SELECT id, song_name, singer, album, duration, file_path FROM t_song WHERE song_name LIKE ? OR singer LIKE ?";
    List<Song> list = new ArrayList<>();
    try (Connection conn = DBUtil.getConnection();
         PreparedStatement ps = conn.prepareStatement(sql)) {
        ps.setString(1, "%" + keyword + "%");
        ps.setString(2, "%" + keyword + "%");
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Song song = new Song();
                song.setId(rs.getInt("id"));
                song.setSongName(rs.getString("song_name"));
                song.setSinger(rs.getString("singer"));
                song.setAlbum(rs.getString("album"));
                song.setDuration(rs.getInt("duration"));
                song.setFilePath(rs.getString("file_path"));
                list.add(song);
            }
        }
    } catch (SQLException e) {
        e.printStackTrace();
    }
    return list;
}

为了提高搜索性能，我在建表时给song_name和singer都加了索引。不过要注意，LIKE '%keyword%'这种前后模糊匹配，在MySQL里是没法走普通B+树索引的，数据量小无所谓，数据量上万后查询会有明显延迟。这个阶段不用刻意优化，能认识到问题在哪就够了。

3.5 音频流式播放：支持拖拽进度条的关键实现

播放器项目里技术含量最高的部分，就是音频流播放接口。前端audio标签请求play?id=1时，如果后端直接把整个MP3文件一次性通过OutputStream写出去，功能能实现，但用户体验会很差：打开页面就要加载完整首歌，拖动进度条也不行，更别提服务端一次性读取几百兆文件对内存的冲击。

正确的思路是支持HTTP Range请求。浏览器的audio标签播放音频时，会先发送一个带Range: bytes=0-的请求，表示“我要从文件开头开始读取”。用户拖动进度条时，浏览器会再次发送类似Range: bytes=102400-的请求，希望从第102400字节开始读取。后端识别Range头，用RandomAccessFile跳转到指定位置，输出指定长度的字节流，并设置响应状态码206 Partial Content，就能完美实现进度条拖拽。

下面是我在项目里使用的音频流播放Servlet核心代码：

java复制@WebServlet("/play")
public class PlayServlet extends HttpServlet {
    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
        int songId = Integer.parseInt(request.getParameter("id"));
        Song song = songService.getSongById(songId);
        File audioFile = new File(song.getFilePath());
        if (!audioFile.exists()) {
            response.sendError(404, "音频文件不存在");
            return;
        }
        long fileLength = audioFile.length();
        String range = request.getHeader("Range");
        long start = 0;
        long end = fileLength - 1;
        if (range != null && range.startsWith("bytes=")) {
            String rangeValue = range.substring("bytes=".length());
            if (rangeValue.endsWith("-")) {
                start = Long.parseLong(rangeValue.substring(0, rangeValue.length() - 1));
            }
        }
        if (start > 0) {
            response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT);
        }
        response.setContentType("audio/mpeg");
        response.setHeader("Accept-Ranges", "bytes");
        response.setHeader("Content-Length", String.valueOf(end - start + 1));
        response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileLength);

        try (RandomAccessFile raf = new RandomAccessFile(audioFile, "r");
             ServletOutputStream out = response.getOutputStream()) {
            raf.seek(start);
            byte[] buffer = new byte[4096];
            int len;
            long remain = end - start + 1;
            while (remain > 0 && (len = raf.read(buffer, 0, (int) Math.min(buffer.length, remain))) != -1) {
                out.write(buffer, 0, len);
                remain -= len;
            }
        }
    }
}

这里有几个细节需要格外注意：Content-Length必须设置为实际响应的字节数，如果设置错误，浏览器会卡在加载状态一直转圈；Accept-Ranges: bytes必须声明，否则浏览器会认为服务端不支持分段读取；缓冲区大小4096字节在局域网开发够用，如果歌曲文件非常大，可以调大到8192甚至16384，减少读取次数。

4. 前端播放器页面：从JSP取数到Audio标签播放

4.1 JSP页面的数据渲染方式

后端把歌曲列表查出来后，如何交给前端展示？两种方案：一种是用JSP的<c:forEach>标签循环渲染HTML列表，另一种是让Servlet返回JSON，前端用Ajax异步加载。考虑到项目定位是教学性质，我选择用JSP服务端渲染，因为这样代码更直观，初学者一眼就能看到request.setAttribute("songs", list)与页面${songs}之间的对应关系。

歌曲列表页一个比较实用的布局是：左侧是歌曲列表表格，右侧是固定的播放器操作区。列表中每一行展示歌曲名、歌手、专辑、时长，以及两个操作按钮：“播放”和“收藏”。播放按钮的href直接指向play?id=${song.id}，点击后浏览器音频播放器接管播放。

4.2 歌词展示的实现思路

歌词功能是我加在项目里的“加分项”，但实现起来不难。歌曲表的lyric字段存放的是LRC格式歌词文本，形如[00:12.34]第一句歌词。前端拿到文本后，通过JavaScript逐行解析，把时间戳换算成秒，存成一个数组。在audio标签的timeupdate事件里，判断当前播放时间落在哪个时间区间，就把对应的歌词行高亮显示。

需要注意，LRC歌词的时间戳格式不统一，有的写[00:12.34]，有的写[00:12.340]，还有的行里有多个时间戳。解析时要先做正则清洗：

javascript复制function parseLrc(lrcText) {
    const lines = lrcText.split('\n');
    const result = [];
    const regex = /\[(\d{2}):(\d{2})\.(\d{2,3})\]/g;
    for (const line of lines) {
        let match;
        while ((match = regex.exec(line)) !== null) {
            const minute = parseInt(match[1]);
            const second = parseInt(match[2]);
            const millisecond = parseInt(match[3].padEnd(3, '0'));
            const time = minute * 60 + second + millisecond / 1000;
            const text = line.replace(regex, '').trim();
            if (text) {
                result.push({ time: time, text: text });
            }
        }
    }
    result.sort((a, b) => a.time - b.time);
    return result;
}

这个解析器要注意对时间戳缺失秒数的情况做容错，比如[01:02]这种只有分和秒的格式。我实际测试时发现，不少网上下载的歌词文件格式并不标准，解析器写得太严格会漏掉很多行，所以解析失败时直接丢弃该行而不是报错，是更稳妥的策略。

4.3 播放模式与音频对象管理

前端播放器的核心是<audio>标签，页面加载时先不设置src，用户点击歌曲列表后，动态把src赋值为play?id=xxx，然后调用play()方法。这里需要注意，play()返回的是一个Promise对象，在浏览器自动播放策略限制下，如果没有用户点击这个“用户激活”操作，Promise会被拒绝。所以必须在点击事件的处理函数里同步调用play()，不能在Ajax回调函数里再调用，否则部分浏览器会拦截。

收藏按钮的业务逻辑也比较典型：点击后发起一个POST请求到favorite?action=add&songId=xxx，如果用户未登录就跳转登录页面。登录用户已经收藏过的歌曲，按钮要显示为“已收藏”并置灰，这需要在JSP渲染列表时，通过favoriteService.isFavorite(userId, songId)方法逐一判断。为了减少数据库查询次数，可以先把该用户收藏的所有歌曲ID查出来放入Set，在JSP里直接set.contains(song.id)判断。

5. VSCode环境下的JavaWeb开发：从创建项目到Tomcat调试

5.1 VSCode搭建JavaWeb项目的最小配置

为什么要提VSCode？因为近段时间很多同学开始用VSCode代替IDEA做Java开发，热搜词里“vscode创建javaweb项目”也频繁出现。VSCode本身只是一个编辑器，做JavaWeb开发需要安装三个关键扩展：Extension Pack for Java、Tomcat for Java、Maven for Java。装完之后，还需要在settings.json里配置Tomcat的安装路径，否则Tomcat for Java扩展无法识别你的本地Tomcat。

用VSCode创建一个Maven项目的步骤是：按Ctrl+Shift+P打开命令面板，输入“Maven: Create Maven Project”，选择maven-archetype-webapp骨架，然后输入groupId（一般是com.example）、artifactId（项目名），最后选择Maven本地仓库路径。项目生成后，目录结构与IDEA里的标准Web工程完全一致，src/main/webapp下会有WEB-INF/web.xml。接着用命令面板里的“Tomcat: Add to Tomcat Server”把项目部署到Tomcat，就可以在浏览器里调试了。

5.2 热部署与调试技巧

VSCode开发JavaWeb项目的一个痛点是热部署不如IDEA顺畅，修改Java代码后需要手动重启Tomcat。我的解决方案是：在VSCode的tasks.json里配置一个“restart tomcat”的任务，用catalina.bat stop和catalina.bat start两条命令完成重启。虽然不能像IDEA那样自动检测更新，但手动重启的耗时也就两三秒，调试体验还算可以。

调试技巧方面，推荐在launch.json里配置Java调试配置，并让Tomcat以catalina.bat jpda start方式启动，这样VSCode的调试器就可以订阅到Tomcat的调试端口，打断点查看变量。实测下来，比在代码里到处System.out.println高效得多。不过要记住，调试模式下Tomcat的启动速度会比正常启动慢一些，这是JVM调试机制的固有开销，不是配置错误。

5.3 常见的小白坑：编译版本不一致和缺失web.xml

VSCode里容易踩的第一个坑是Maven项目默认编译级别与JDK版本不匹配，表现为代码写的是Java 8语法，但编译时提示“release version 5不支持”，这是因为项目没有显式指定maven.compiler.source和maven.compiler.target。在pom.xml里补上这段配置即可：

xml复制<properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

第二个坑是Servlet 3.x之后web.xml不是必需的，但如果你用了@WebServlet注解，同时又保留了web.xml，里面可能会因为声明一个空的<web-app>导致项目部署不识别注解，页面全部404。解决办法是：要么删掉web.xml，要么在web.xml里明确设置metadata-complete="false"。如果项目使用Maven骨架生成旧版本的web.xml，建议把web-app标签的版本号改成3.1以上，否则@WebServlet注解也不会生效。

6. Windows Server上的Apache与Tomcat联合部署

6.1 为什么需要在Windows服务器上做多Web服务器配合

本地开发调试没问题之后，就要把项目发布到服务器上。热搜词里“winsever apache + tomcat 发布javaweb项目”出现的频率很高，说明这条路是很多人真正会走的部署路径，毕竟一堆Windows服务器在跑中小型Java应用。为什么要用Apache加Tomcat而不是只装一个Tomcat？因为Apache HTTP Server作为一个独立的Web服务器，处理静态资源（图片、CSS、JS）的效率更高，并发连接能力更强，还能充当反向代理和负载均衡；Tomcat则专注处理Servlet和JSP动态请求。实际部署时，请求先到Apache，Apache把静态文件直接返回给用户，把*.jsp、*.do、/play这类动态请求转发给后端的Tomcat。

6.2 Apache + Tomcat联调的完整配置

第一步，在两台（或同一台）Windows服务器上分别安装Apache HTTP Server和Tomcat。Apache默认监听80端口，Tomcat默认监听8080端口。为了让用户访问时不带端口号，需要修改Apache的httpd.conf，启用mod_proxy和mod_proxy_http模块，并加入反向代理配置。核心配置片段如下：

apache复制LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

ProxyRequests Off
ProxyPass /music/ ajp://localhost:8009/music/
ProxyPassReverse /music/ ajp://localhost:8009/music/

这里有两种转发协议可选：HTTP和AJP。AJP是Tomcat特有的二进制协议，效率更高，Apache和Tomcat默认已经配好了AJP连接器（Tomcat的server.xml里默认注释掉的<Connector port="8009" protocol="AJP/1.3"/>），所以直接把proxy_pass指向AJP端口。如果不想用AJP，也可以直接改写成http://localhost:8080/music/，功能上至少跑得通，性能差异在低并发场景下基本感受不到。

第二步，把项目打包成WAR包。在VSCode里执行mvn clean package，然后到target目录下找到music-player.war，把它复制到Tomcat的webapps目录。Tomcat启动时会自动解压WAR包到同名目录。注意Windows下如果之前部署过同名项目，最好先停掉Tomcat，删除旧的解压目录，再放入新WAR包，否则可能出现旧文件残留导致页面无法更新。

第三步，启动顺序有讲究：必须先启动Tomcat，再启动Apache。启动Tomcat后，用浏览器访问http://localhost:8080/music/确认项目可用；然后启动Apache，再访问http://localhost/music/，如果配置正确，会看到同样的页面。如果Apache转发的页面正常但CSS样式丢失，多半是反向代理配置把静态资源的相对路径搞乱了，需要检查页面引用的资源路径是否以/music/开头。

6.3 Windows部署后的资源管理与日志排查

服务器部署完成后，资源管理很重要。我的经验是给Tomcat设置合理的JVM内存参数，在Tomcat的bin/catalina.bat文件中添加set JAVA_OPTS=-Xms256m -Xmx512m -Dfile.encoding=UTF-8。音频文件是相对占内存的资源，并发播放时Java堆内存会飙升，不设置上限可能会出现OutOfMemoryError。音频文件本身建议放在Tomcat之外的独立目录，比如D:/music_files，这样即使Tomcat重新部署导致webapps目录被清理，音乐文件也不会丢失。

日志排查方面，Windows下Tomcat的日志分两处：logs目录下的catalina.out（或catalina.*.log）记录Tomcat运行日志，localhost_access_log记录访问日志。联合部署时如果出现页面打不开，排查顺序应该是：先用浏览器访问Tomcat的8080端口，如果正常，问题出在Apache转发；如果8080也不正常，问题在Tomcat应用本身。这个“先动态后静态、先Tomcat后Apache”的顺序，是我调通整套部署流程后总结出来的高效排查路径。

7. 踩坑记录与几个值得留意的细节

7.1 中文文件名导致的URL编码问题

在歌曲列表里，如果歌曲文件本身是中文名（比如“晴天.mp3”），前端播放请求地址是/play?id=1，文件名为中文明面上不影响播放。但如果直接通过文件路径去访问，比如下载接口，就存在URL编码问题。Tomcat的URIEncoding默认按UTF-8处理，但Windows操作系统的文件名默认是GBK编码，两者对中文文件名的处理可能不一致。解决方案是：做文件上传时，对文件名做重命名处理，统一用数字ID或UUID作为存储文件名，原始中文名只保存在数据库的song_name字段里。这样既保证文件系统编码统一，也避免用户下载时出现乱码。

7.2 歌曲上传时的大文件大小限制

如果项目里有管理员后台需要上传MP3文件，默认的Tomcat配置可能过不了大文件上传这一关。Tomcat的maxPostSize默认是2MB，MP3文件动辄5到10MB，超过了就会被静默拒绝。需要修改Tomcat的server.xml中<Connector>节点，加上maxPostSize="-1"表示不限制，或者设成104857600（100MB）。同时maxSwallowSize也要相应调大，这个参数控制连接器读取请求体的最大字节数，默认也是2MB，不调整的话上传大文件时会直接抛出IllegalStateException: The request contained too many parameters or form fields之类的异常。

7.3 播放历史记录的数据去重策略

播放历史表如果每播放一次就插入一条记录，数据库很快就会积累大量重复数据。用户反复听同一首歌，历史列表会出现十几个相同条目，体验很差。我的处理是：在插入历史前先查询是否已存在相同(user_id, song_id)的记录，如果存在则更新play_time，否则插入新记录。这样既保证历史数据不膨胀，又能让“最近播放”排序正确。虽然每次播放多一次查询，但对于个人项目规模来说完全可以接受。

7.4 静态资源缓存：图片和歌词的浏览器缓存策略

前端页面的封面图片和后端的歌词文件，如果每次都重新请求，会增加服务器负担。通过给Servlet响应设置Cache-Control头，可以让浏览器缓存这些资源。比如封面图片可以设置Cache-Control: max-age=86400，表示一天之内不需要重新请求。初次做项目的人容易忽略这个细节，但它确实能明显提升页面二次打开的速度。唯一要注意的是，如果后台更新了歌曲封面，用户浏览器可能还显示旧图，这时需要在上传逻辑里同步修改图片文件名（加版本号），强制浏览器重新拉取。

8. 关于这个项目我最后想补充的

如果你打算拿着这个JavaWeb音乐播放器项目去面试，或者作为课程设计提交，我的建议是抓住两个核心亮点来讲：一个是音频流式播放时的Range请求处理，它体现了你对HTTP协议和IO流的理解，属于拉开差距的技术点；另一个是三层架构与数据库关系建模的思路，它能体现你对代码规范和扩展性的意识。这两个点讲清楚了，项目本身就足够有说服力，不必刻意追求功能数量。

从开发到部署的整个过程里，我踩过最多的坑其实都在那些“看起来无关紧要的小细节”上：Filter没写导致全站乱码、密码加密摘要长度不一致导致登录失败、Range响应没设置Content-Length导致播放器卡死、Tomcat默认限制导致上传失败。一开始我也觉得这些细节琐碎无聊，但正是这一堆小坑，让我真正把Servlet、HTTP、Tomcat这套链路串了起来。哪怕后面转到Spring Boot，再遇到类似的问题，我脑子里也有了一个清晰的排查方向。

最后分享一个实际部署中的小技巧：如果你所在的生产环境是Windows Server，并且经常要更新项目，建议把Tomcat的autoDeploy设为true。这样替换WAR包时Tomcat会自动检测并重新部署，省去手动停开服务的步骤。不过自动部署偶尔会留下旧资源缓存，稳妥起见，正式大版本更新我还是会手动停Tomcat、清理work目录再启动。这个习惯让我少踩了很多“更新了代码但页面还是旧版”的坑。