前一阵在整理一个基于JavaSSMFlask的视频播放器系统交付包源码、论文文档、调试记录、讲解视频全都要备齐。很多同学拿到这种题目时第一反应是直接拿SpringBootVue一套带走但仔细看题目要求——Java、SSM、Flask、视频解码、媒体播放这明显不是让你单框架糊一个Demo而是希望你在架构层面做一次前后端分离加异构服务的组合。这篇就把我实际搭建这套系统时的全部思路、代码结构、调试经验整理出来给正在做同类课设、毕设或想从零搞一个可演示视频播放器的朋友一个能直接照做的参考。先说结论视频播放器系统本身不难难点都在视频怎么进来、怎么转成浏览器能播的格式、怎么在不同设备上流畅播放、Java和Python两个服务怎么协作这些细节上。你不需要从零写解码器也不要想着纯前端硬扛所有格式——用SSM管业务用Flask管视频处理各干各擅长的这条路线是最省力也最容易被答辩老师认可的。1. 为什么这套系统要同时用Java SSM和Flask1.1 单框架做视频项目会卡在哪如果你只用SSM做整个项目会遇到一个非常现实的问题视频上传之后浏览器播放并不友好。直接传MP4格式在小范围测试没问题但一旦涉及转码、截取缩略图、把大视频转成HLS流、抽帧分析这些操作Java写起来极其痛苦。FFmpeg命令虽然可以在Java里通过ProcessBuilder调用但进程管理、输出日志解析、出错重试这套东西在Java里做非常繁琐如果还要做视频画面抽帧、加水印、字幕解析更是绕不开Python生态的OpenCV、PIL、imageio这些现成库。反过来如果只用Flask做整个项目业务端又会很难受。用户注册登录、评论管理、视频分类、后台权限、数据统计这些活儿Python写也能写但Spring的依赖注入、MyBatis的Mapper管理、SpringMVC的参数绑定在Java Web开发里太成熟了团队协作、后期维护、论文里画架构图都比Flask单打独斗有说服力。所以这套混合架构的动机很简单Java负责稳定和业务Python负责灵活和多媒体。1.2 混合架构下各自负责什么我把系统拆成三个模块SSM主服务端口8080跑用户、视频元信息、分类、评论、收藏、后台管理等业务逻辑数据库用MySQL。Flask媒体服务端口5000接收来自Java的转码请求调用FFmpeg完成视频解码、转码、HLS切片、缩略图生成也直接对外提供流文件访问。前端页面这里我用的方案是简单的HTMLJSPJavaScript播放器部分用video.js配合HLS.js不做太重的Vue脚手架原因后面说。两个服务之间通过HTTP接口通信文件层面通过共享目录交换。Java上传的视频原文件落在公共目录/data/videos/rawFlask转码后把切片输出到/data/videos/hls这些目录两边都能访问到。模块技术栈端口核心职责主服务Spring SpringMVC MyBatis8080业务接口、权限、视频元信息媒体服务Flask FFmpeg5000解码、转码、切片、缩略图前端HTML video.js HLS.js8080静态资源播放、上传、交互这么做还有一个隐性的好处你可以单独把媒体服务部署到一台性能更好的机器上视频处理不占用业务Tomcat的线程池。答辩时老师问为什么不用一个项目搞定这个部署解耦的理由立得住。1.3 项目交付包里应该包含什么既然题目里写了源码、LW论文、调试文档、讲解这套东西的工程化程度就不能太低。我的交付目录大致是这个结构video-player-system/ ├── java-ssm/ # SSM主服务源码 │ ├── src/main/java/com/video/ │ │ ├── controller/ # 用户、视频、评论、后台控制器 │ │ ├── service/ # 业务层接口与实现 │ │ ├── mapper/ # MyBatis Mapper接口 │ │ └── common/ # 统一返回、拦截器、工具类 │ ├── src/main/resources/ │ │ ├── mapper/ # XML映射文件 │ │ ├── spring/ # Spring与SpringMVC配置 │ │ └── mybatis-config.xml │ └── pom.xml ├── flask-media/ # Flask媒体服务源码 │ ├── app.py # 主入口与路由 │ ├── transcoder.py # FFmpeg封装 │ ├── config.py # 路径与参数配置 │ └── requirements.txt ├── docs/ │ ├── LW论文/ # 系统设计、数据库、测试章节 │ ├── 调试文档/ # 环境搭建、常见报错解决 │ └── 讲解PPT/ # 演示用的架构图和流程图 └── sql/ └── videodb.sql # 建库建表脚本这样做的好处是你给人演示代码或写文档的时候每个模块的边界非常清楚老师扫一眼目录结构就知道你系统想清楚了。2. SSM主服务端业务、权限与视频元数据管理2.1 数据库设计视频播放器系统里视频文件本身不存放在数据库数据库只存指向文件的路径和描述信息。我建了这几张核心表用户表、视频表、分类表、评论表、收藏表。视频表是最关键的字段设计直接影响后面播放和转码状态跟踪CREATE TABLE video ( id int(11) NOT NULL AUTO_INCREMENT, title varchar(100) NOT NULL COMMENT 视频标题, category_id int(11) DEFAULT NULL COMMENT 分类ID, raw_path varchar(255) DEFAULT NULL COMMENT 原始文件路径, hls_path varchar(255) DEFAULT NULL COMMENT HLS目录相对路径, cover_path varchar(255) DEFAULT NULL COMMENT 封面图路径, duration int(11) DEFAULT NULL COMMENT 时长单位秒, size bigint(20) DEFAULT NULL COMMENT 文件大小字节, status tinyint(4) DEFAULT 0 COMMENT 0等待处理 1转码中 2可播放 3处理失败, user_id int(11) DEFAULT NULL COMMENT 上传者, create_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里我特别说明一下status字段视频上传成功并不代表立刻能播因为Flask还要转码。所以在业务系统里视频必须有一个状态机。前端在上传后轮询状态等它从1变成2才显示播放按钮。很多同学会忽略这个字段结果就是视频刚传完前端立刻拿原始地址去播要么格式不支持要么卡半天没反应。charsetutf8mb4也是为了兼容视频标题里可能出现的特殊字符和表情用utf8会报字符集不完整的错这是个很容易踩但很好解决的坑。2.2 核心接口SSM侧我按资源划分接口统一返回JSON格式。用SpringMVC的ResponseBody配合一个自己写的Result类封装状态码和消息。核心接口清单如下POST /api/user/register注册POST /api/user/login登录返回tokenPOST /api/video/upload上传视频元信息文件GET /api/video/list分页获取视频列表GET /api/video/detail/{id}获取详情包含播放地址POST /api/video/like收藏/取消收藏POST /api/comment/add发表评论GET /api/comment/list/{videoId}评论列表GET /api/admin/video/check后台审核列表可选上传接口是核心代码上我用的是MultipartFile接收文件同时把标题、分类等字段一起接进来PostMapping(/api/video/upload) ResponseBody public Result upload(RequestParam(file) MultipartFile file, RequestParam(title) String title, RequestParam(categoryId) Integer categoryId, HttpServletRequest request) { // 1. 校验文件类型和大小 if (file.isEmpty() || file.getSize() 1024L * 1024 * 1024) { return Result.error(文件为空或超过1GB限制); } // 2. 生成唯一文件名防止冲突 String suffix FilenameUtils.getExtension(file.getOriginalFilename()); String rawName UUID.randomUUID().toString().replace(-, ) . suffix; // 3. 保存到共享目录 File target new File(uploadDir rawName); file.transferTo(target); // 4. 写入video表status0初始状态 Video video new Video(); video.setTitle(title); video.setCategoryId(categoryId); video.setRawPath(/raw/ rawName); video.setStatus(0); video.setUserId(getLoginUserId()); videoService.insert(video); // 5. 异步通知Flask开始转码 mediaClient.notifyTranscode(video.getId()); return Result.success(video); }注意第5步上传接口不能等转码完成才返回一定要异步触发。转码通常要几秒到几十秒如果同步等前端请求直接超时。我这里是在Service里开了个线程池去调Flask的接口Spring容器启动时初始化一个ExecutorService即可。2.3 登录拦截与权限控制权限这块用SpringMVC拦截器实现不引入Spring Security因为毕设或课设的演示场景里手写一个HandlerInterceptor就够用还能在论文里把流程讲明白。用户登录成功后生成一个随机UUID作为token存Redis或者直接存内存Map规模小的话Map更省事响应头里返回token字段。拦截器校验请求头里的token校验通过后把用户信息放进request的attribute里供Controller取用。public class LoginInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (OPTIONS.equalsIgnoreCase(request.getMethod())) { return true; // 放行预检请求 } String token request.getHeader(token); User user tokenService.getUser(token); if (user null) { response.setStatus(401); response.getWriter().write({\code\:401,\msg\:\未登录\}); return false; } request.setAttribute(loginUser, user); return true; } }后台管理员页面单独用一个/api/admin/**的拦截规则检查用户的role字段是否为admin。拦截器配置放在SpringMVC的XML里指定exclude-mappings放行登录注册和静态资源。2.4 视频文件上传的细节文件上传有两个容易被低估的问题一个是Tomcat的maxUploadSize默认限制另一个是本地目录权限。SpringMVC里用CommonsMultipartResolver配置上传大小bean idmultipartResolver classorg.springframework.web.multipart.commons.CommonsMultipartResolver property namemaxUploadSize value1048576000/ property namemaxInMemorySize value1048576/ property namedefaultEncoding valueUTF-8/ /bean如果你不配置这个bean或者只配置了spring.servlet.multipart.max-file-size但搭的是XML配置的SSM项目那上传稍大点的文件就会抛MaxUploadSizeExceededException。这里我用的100000KB是按1GB估的按需调整。文件保存目录我放在/data/videos/raw通过配置项注入而不是硬编码调试的时候改路径不用重新打包。保存文件时还要注意一定要用UUID重命名不能用用户原始文件名。两个用户同时上传同名视频直接覆盖是小事更麻烦的是文件名里的中文和特殊字符会导致后续FFmpeg解析路径出错。我一开始图省事直接用原名结果传了一个我的视频(最终版).mp4Flask那边路径解析直接崩从那以后所有上传一律UUID重命名原始文件名只存到DB的title字段里。3. Flask媒体服务视频解码、转码与切片处理3.1 为什么把解码放到Python侧视频解码这件事业界通用做法就是调FFmpeg没有哪个正经项目自己从头写解码器。Flask侧做解码、转码的优势在于可以用subprocess干净地管理FFmpeg进程用ffmpeg-python或imageio-ffmpeg封装调用逻辑输出解析、异常捕获都可以用Python灵活的字符串和异常机制处理而且Python生态里还有PIL做封面裁切、moviepy做片段拼接这些方便工具。另外毕设场景里Flask代码量小、结构透明转码逻辑独立成模块方便你在论文里画流程图。Java那边通常就是发起请求、查状态真正的视频管线全在Python侧这样职责单一两边代码都很容易读懂。3.2 FFmpeg探测与转码管线转码的第一步是探测视频信息。上传到共享目录的原始文件可能是MP4、AVI、MOV、MKV甚至还有FLV播放器不可能全兼容所以必须统一转成H.264编码的MP4或HLS流。探测用ffprobeffprobe -v error -select_streams v:0 -show_entries streamcodec_name,width,height,duration -of json /data/videos/raw/xxx.mp4在Flask里用subprocess.run捕获输出解析JSON拿到编码、分辨率、时长。这个信息要回传给JavaJava存到video表的duration字段。拿到信息之后决定转码策略。我的策略很简单原文件是H.264AAC的MP4直接切片其他格式先转成统一的MP4中间文件再切片分辨率超过1080p的降一下码率。转码核心命令长这样ffmpeg -i input.mp4 \ -vf scale1280:-2 \ -c:v libx264 -preset veryfast -crf 23 \ -c:a aac -b:a 128k \ -movflags faststart \ output.mp4-movflags faststart这个参数特别重要它把moov元数据移到文件头部否则浏览器播放时要把整个MP4下载完才知道时长信息表现为播放进度条拖不动、加载很久不出画面。我在调试阶段被这个卡过一晚上加上这个参数后秒开。3.3 缩略图与HLS切片封面缩略图和HLS切片可以放到同一个转码流程里。切片命令ffmpeg -i input.mp4 \ -c:v libx264 -c:a aac -strict -2 \ -hls_time 10 \ -hls_list_size 0 \ -hls_segment_filename /data/videos/hls/abc_%03d.ts \ /data/videos/hls/abc.m3u8hls_time 10表示每段10秒hls_list_size 0表示生成完整播放列表而不是只保留最近几段。HLS的好处是浏览器端可以边下边播拖动进度条只加载需要的分片不像单文件MP4那样需要服务端支持Range请求。封面抽帧命令ffmpeg -i input.mp4 -ss 5 -vframes 1 -q:v 2 /data/videos/hls/abc.jpg-ss 5取第5秒的画面注意-ss要放在-i前面这样是快速定位不是先解码全部再跳转速度差非常多。3.4 异步任务与临时文件清理Flask里绝对不要在请求处理函数里同步执行FFmpeg。一个视频转码几十秒Gunicorn的worker只有一个线程的话整个服务就卡死了。我这边的方案是把转码任务放到一个后台线程里跑请求接口只返回已受理import threading jobs {} def transcode_worker(video_id, raw_path, hls_dir): try: # 更新任务状态... run_ffmpeg_cmd(...) # 生成封面... # 写完成标记文件 except Exception as e: # 写失败标记 app.route(/api/transcode/int:video_id, methods[POST]) def transcode(video_id): t threading.Thread(targettranscode_worker, args(...)) t.start() return {code: 0, msg: task started}用threading.Thread在演示规模下完全够用不必上Celery。真正要注意的是临时文件的清理转码产生的中间文件、没有用的原片分片、低于0KB的空文件要定期删。我在Flask里加了一个cleanup()函数每小时跑一次删除超过24小时的临时目录内容避免磁盘被撑满。另外FFmpeg子进程的日志要设置stdout和stderr重定向到日志文件不然前端调用一直挂着等管道输出会阻塞。我在代码里统一用stdoutopen(log_path, w)来接管。4. Java与Flask的对接细节4.1 RestTemplate调用与超时设置Java侧调用Flask我用的是Spring自带的RestTemplate简单直接。关键是超时要配置好。第一次联调时我没配超时Flask转码中崩了没响应Java那边傻等两分钟才报错前端看起来就是上传后白屏。public MediaClient() { HttpComponentsClientHttpRequestFactory factory new HttpComponentsClientHttpRequestFactory(); factory.setConnectTimeout(3000); // 连接超时 factory.setReadTimeout(30000); // 读取超时转码请求只返回受理不用太长 this.restTemplate new RestTemplate(factory); }调用Flask接口时只传video_id和raw_path不要传整个文件流文件已经在共享目录里了两边只需要路径字符串。这样接口载荷非常轻出问题也好排查。4.2 共享文件目录Java和Flask不在同一个进程它们怎么访问同一个视频文件最省事的方案是共享目录。我开发时直接在同一台机器上跑两边配置同样的根目录一个写/data/videos/raw另一个读同一个路径。部署到不同机器时用NFS或者Samba把目录挂载过去或者干脆把Flask和Java部署在同一台服务器避免文件传输的复杂度。这里有个路径规范问题数据库里存的路径统一用相对路径比如raw/abc.mp4hls/abc.m3u8。Java拼成完整本地路径时用File.separator处理Flask里用os.path.join处理。绝对不要把Linux的/data/...直接写进数据库换Windows调试分分钟全崩。4.3 视频状态机与一致性保证转码过程Java这边怎么知道完成了不能靠猜。我的方案是Flask转码完写一个{video_id}.complete标记文件同时Java提供一个回调接口Flask用requests.post主动通知。如果回调失败Java还有一个定时任务每30秒扫描一次标记文件兜底。# Flask转码完成后 requests.post(http://localhost:8080/api/video/transcode-callback, json{videoId: video_id, status: success, duration: duration, hlsPath: hls/abc.m3u8})Java的回调接口里根据通知内容更新video表的status字段2表示可播放3表示失败。失败时把error_msg写进去前端可以展示转码失败请重新上传。状态轮询的时序我梳理了一下实际演示测试表现如下时间点Java视频状态前端表现上传完成0 等待处理显示上传成功处理中Flask受理1 转码中显示进度图标转码切片完成2 可播放出现播放器和封面FFmpeg异常3 失败显示错误提示这个状态机是整套系统最值得在论文里展开画图的部分逻辑闭环不会出现播放按钮点了没反应这种说不清的问题。4.4 CORS与跨域问题前端页面如果在8080Flask在5000浏览器直接访问Flask的流文件会有跨域问题。解决分两层第一前端尽量不直接请求Flask的业务接口流文件通过Java的/api/video/stream代理转发第二给Flask加上CORS响应头或者用Flask-CORS扩展。如果走Java代理注意用InputStreamResource把文件流传给前端避免一次性把整个文件读进内存GetMapping(/api/video/stream/{videoId}) public ResponseEntityResource stream(PathVariable Integer videoId) throws IOException { Video video videoService.getById(videoId); File file new File(baseDir video.getHlsPath()); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_TYPE, application/vnd.apple.mpegurl) .body(new InputStreamResource(new FileInputStream(file))); }不过这里有个取舍HLS切片特别多走Java代理每个.ts请求都过一遍SpringMVC线程性能一般。演示规模无所谓如果追求性能更优做法是Flask或Nginx直接配静态目录映射Java只代理.m3u8索引文件.ts分片由Nginx直出。我用的是Nginx映射方案后面部署章节会说。5. 前端播放链路从流地址到页面5.1 播放器选型前端播放器我用的是video.js加HLS.js。为什么不直接用原生video标签因为原生标签对HLS的支持在PC端Chrome、Firefox并不好HLS是苹果系原生支持的东西安卓和PC浏览器需要hls.js来把HLS封装成fMP4喂给MediaSource。video.js的皮肤和API成熟论文里也不需要为为什么选播放器费太多口舌。需要强调一点我没有引入Vue或者React用的是原生JS加JSP。原因是这个项目的核心不是前端框架是业务媒体处理的链路完整性JSP可以直接在SSM里渲染服务端能拿用户信息演示简单不容易在前端打包环节翻车。如果你是拿这套代码去改前端用Vue也不影响API照对接即可。5.2 HLS播放配置播放器初始化的核心逻辑var player videojs(my-player, { controls: true, autoplay: false, preload: auto, poster: video.coverPath }); if (video.hlsPath.endsWith(.m3u8)) { if (Hls.isSupported()) { var hls new Hls(); hls.loadSource(video.hlsPath); hls.attachMedia(player.tech().el()); } else if (player.canPlayType(application/vnd.apple.mpegurl)) { // Safari原生播放 player.src({ src: video.hlsPath, type: application/vnd.apple.mpegurl }); } } else { player.src({ src: video.rawPath, type: video/mp4 }); }video.hlsPath是Java返回的数据里面已经是代理或静态映射后的完整URL。播放列表右侧的缓冲策略由hls.js自动处理我手动设置的参数只有maxBufferLength: 30和maxMaxBufferLength: 60控制内存占用。5.3 兼容性处理兼容性集中在几个点上一是MIME类型.m3u8需要application/vnd.apple.mpegurl.ts需要video/mp2t这在Nginx的mime.types里默认可能没有要手动加二是HLS分片的跨域如果按Nginx直出的方案需要加add_header Access-Control-Allow-Origin *;三是360/IE这种老浏览器直接提示请使用Chrome或Edge访问不做多余的兼容代码演示时用Chrome省得被奇怪的兼容bug拖时间。播放过程中的日志也很重要我在前端做了个player.on(error, ...)回调把错误码打出来。hls.js的报错信息必须开debug: true才能看到详情我调试时开着上线演示前关掉。6. 调试实录与部署验证6.1 排查过的典型坑整套系统联调下来我整理了五个最有代表性的问题每个都是在现场真实踩过的现象根因解决方式上传后视频状态一直停在0Java异步线程池没有初始化mediaClient.notifyTranscode异常被吞Service层加try-catch统一记录日志线程池用PostConstruct初始化并验证HLS播放黑屏但m3u8能访问.ts分片路径不对m3u8里写的是相对路径浏览器按当前目录解析404FFmpeg生成时用绝对输出路径m3u8文件内容用sed替换为相对路径或加前缀播放进度条能拖但画面卡顿MP4没有faststart转码命令加-movflags faststartFlask返回500但Java看不到原因Gunicorn日志没打开subprocess.run的stderr没捕获统一把FFmpeg输出重定向到独立日志文件请求异常写error_log.txt中文视频标题乱码数据库表用了utf8MySQL连接串没加characterEncodingutf8连接串加参数建表用utf8mb4其中第二个坑我多说一句FFmpeg在-hls_segment_filename里给了绝对路径后生成的m3u8索引文件里既可能是绝对路径、也可能是相对路径取决于你输入文件怎么给的。我踩到的是abc.m3u8里面写了/data/videos/hls/abc_000.ts这种服务器绝对路径浏览器拿到后按根目录解析自然404。后来我统一约定-hls_segment_filename用/data/videos/hls/abc_%03d.ts生成但在写完m3u8后做一个路径清洗把开头的/data/videos/hls/替换成./保证索引文件内部是相对路径同时Nginx的location指到/data/videos/hls/作为根目录。这套约定在文档里写清楚后面没人再踩。6.2 部署拓扑最终部署到Linux服务器上的时候我的拓扑是这样的Nginx(80) ├── / → Tomcat(8080) # SSM业务接口和页面 └── /hls/ → 静态映射到 /data/videos/hls # 直出流文件 Gunicorn(5000) → Flask媒体服务 MySQL(3306) → 业务库Nginx配置里加了两个关键项.m3u8的MIME类型、.ts分片的Cache-Control。分片缓存建议给上max-age86400否则同一个分片被用户拖进度条拖来拖去反复请求浪费带宽。server { listen 80; server_name localhost; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /hls/ { alias /data/videos/hls/; types { application/vnd.apple.mpegurl m3u8; video/mp2t ts; } add_header Access-Control-Allow-Origin *; expires 7d; } }6.3 从零到一的验收流程部署完成后我按以下顺序完整走一遍验收每步都拍照留档这部分内容还能直接放进调试文档和讲解PPT注册一个新用户登录后上传一个MP4和一个AVI格式的视频。观察video表状态从0→1→2的变化确认Flask日志里有对应的FFmpeg命令输出。等待转码完成后打开视频详情页确认封面、时长、播放器加载正常。拖动进度条到中间位置确认HLS分片按需加载Network面板里能看到按10秒一个的.ts请求。评论、收藏、后台管理走一遍确认拦截器对未登录请求返回401。重启Flask服务确认未完成的转码任务状态能兜底更新不会永久卡在状态1。整个验收走下来大概20分钟每一步都有对应的日志和截图。做毕设的同学把这套流程写进测试章节比空写系统运行稳定有说服力得多。最后再分享一个小技巧整个系统调试阶段最优先做好的不是功能而是日志。Java侧用log4j2按天滚动Flask侧每个转码任务独立一个log文件FFmpeg的stdout、stderr全要落盘。联调出现任何问题第一件事不是猜而是去最后一条日志里找答案。这套日志先行的习惯帮我省下了大量排查时间也直接决定了整个交付周期能不能按时完成。
前一阵在整理一个基于JavaSSMFlask的视频播放器系统交付包源码、论文文档、调试记录、讲解视频全都要备齐。很多同学拿到这种题目时第一反应是直接拿SpringBootVue一套带走但仔细看题目要求——Java、SSM、Flask、视频解码、媒体播放这明显不是让你单框架糊一个Demo而是希望你在架构层面做一次前后端分离加异构服务的组合。这篇就把我实际搭建这套系统时的全部思路、代码结构、调试经验整理出来给正在做同类课设、毕设或想从零搞一个可演示视频播放器的朋友一个能直接照做的参考。先说结论视频播放器系统本身不难难点都在视频怎么进来、怎么转成浏览器能播的格式、怎么在不同设备上流畅播放、Java和Python两个服务怎么协作这些细节上。你不需要从零写解码器也不要想着纯前端硬扛所有格式——用SSM管业务用Flask管视频处理各干各擅长的这条路线是最省力也最容易被答辩老师认可的。1. 为什么这套系统要同时用Java SSM和Flask1.1 单框架做视频项目会卡在哪如果你只用SSM做整个项目会遇到一个非常现实的问题视频上传之后浏览器播放并不友好。直接传MP4格式在小范围测试没问题但一旦涉及转码、截取缩略图、把大视频转成HLS流、抽帧分析这些操作Java写起来极其痛苦。FFmpeg命令虽然可以在Java里通过ProcessBuilder调用但进程管理、输出日志解析、出错重试这套东西在Java里做非常繁琐如果还要做视频画面抽帧、加水印、字幕解析更是绕不开Python生态的OpenCV、PIL、imageio这些现成库。反过来如果只用Flask做整个项目业务端又会很难受。用户注册登录、评论管理、视频分类、后台权限、数据统计这些活儿Python写也能写但Spring的依赖注入、MyBatis的Mapper管理、SpringMVC的参数绑定在Java Web开发里太成熟了团队协作、后期维护、论文里画架构图都比Flask单打独斗有说服力。所以这套混合架构的动机很简单Java负责稳定和业务Python负责灵活和多媒体。1.2 混合架构下各自负责什么我把系统拆成三个模块SSM主服务端口8080跑用户、视频元信息、分类、评论、收藏、后台管理等业务逻辑数据库用MySQL。Flask媒体服务端口5000接收来自Java的转码请求调用FFmpeg完成视频解码、转码、HLS切片、缩略图生成也直接对外提供流文件访问。前端页面这里我用的方案是简单的HTMLJSPJavaScript播放器部分用video.js配合HLS.js不做太重的Vue脚手架原因后面说。两个服务之间通过HTTP接口通信文件层面通过共享目录交换。Java上传的视频原文件落在公共目录/data/videos/rawFlask转码后把切片输出到/data/videos/hls这些目录两边都能访问到。模块技术栈端口核心职责主服务Spring SpringMVC MyBatis8080业务接口、权限、视频元信息媒体服务Flask FFmpeg5000解码、转码、切片、缩略图前端HTML video.js HLS.js8080静态资源播放、上传、交互这么做还有一个隐性的好处你可以单独把媒体服务部署到一台性能更好的机器上视频处理不占用业务Tomcat的线程池。答辩时老师问为什么不用一个项目搞定这个部署解耦的理由立得住。1.3 项目交付包里应该包含什么既然题目里写了源码、LW论文、调试文档、讲解这套东西的工程化程度就不能太低。我的交付目录大致是这个结构video-player-system/ ├── java-ssm/ # SSM主服务源码 │ ├── src/main/java/com/video/ │ │ ├── controller/ # 用户、视频、评论、后台控制器 │ │ ├── service/ # 业务层接口与实现 │ │ ├── mapper/ # MyBatis Mapper接口 │ │ └── common/ # 统一返回、拦截器、工具类 │ ├── src/main/resources/ │ │ ├── mapper/ # XML映射文件 │ │ ├── spring/ # Spring与SpringMVC配置 │ │ └── mybatis-config.xml │ └── pom.xml ├── flask-media/ # Flask媒体服务源码 │ ├── app.py # 主入口与路由 │ ├── transcoder.py # FFmpeg封装 │ ├── config.py # 路径与参数配置 │ └── requirements.txt ├── docs/ │ ├── LW论文/ # 系统设计、数据库、测试章节 │ ├── 调试文档/ # 环境搭建、常见报错解决 │ └── 讲解PPT/ # 演示用的架构图和流程图 └── sql/ └── videodb.sql # 建库建表脚本这样做的好处是你给人演示代码或写文档的时候每个模块的边界非常清楚老师扫一眼目录结构就知道你系统想清楚了。2. SSM主服务端业务、权限与视频元数据管理2.1 数据库设计视频播放器系统里视频文件本身不存放在数据库数据库只存指向文件的路径和描述信息。我建了这几张核心表用户表、视频表、分类表、评论表、收藏表。视频表是最关键的字段设计直接影响后面播放和转码状态跟踪CREATE TABLE video ( id int(11) NOT NULL AUTO_INCREMENT, title varchar(100) NOT NULL COMMENT 视频标题, category_id int(11) DEFAULT NULL COMMENT 分类ID, raw_path varchar(255) DEFAULT NULL COMMENT 原始文件路径, hls_path varchar(255) DEFAULT NULL COMMENT HLS目录相对路径, cover_path varchar(255) DEFAULT NULL COMMENT 封面图路径, duration int(11) DEFAULT NULL COMMENT 时长单位秒, size bigint(20) DEFAULT NULL COMMENT 文件大小字节, status tinyint(4) DEFAULT 0 COMMENT 0等待处理 1转码中 2可播放 3处理失败, user_id int(11) DEFAULT NULL COMMENT 上传者, create_time datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里我特别说明一下status字段视频上传成功并不代表立刻能播因为Flask还要转码。所以在业务系统里视频必须有一个状态机。前端在上传后轮询状态等它从1变成2才显示播放按钮。很多同学会忽略这个字段结果就是视频刚传完前端立刻拿原始地址去播要么格式不支持要么卡半天没反应。charsetutf8mb4也是为了兼容视频标题里可能出现的特殊字符和表情用utf8会报字符集不完整的错这是个很容易踩但很好解决的坑。2.2 核心接口SSM侧我按资源划分接口统一返回JSON格式。用SpringMVC的ResponseBody配合一个自己写的Result类封装状态码和消息。核心接口清单如下POST /api/user/register注册POST /api/user/login登录返回tokenPOST /api/video/upload上传视频元信息文件GET /api/video/list分页获取视频列表GET /api/video/detail/{id}获取详情包含播放地址POST /api/video/like收藏/取消收藏POST /api/comment/add发表评论GET /api/comment/list/{videoId}评论列表GET /api/admin/video/check后台审核列表可选上传接口是核心代码上我用的是MultipartFile接收文件同时把标题、分类等字段一起接进来PostMapping(/api/video/upload) ResponseBody public Result upload(RequestParam(file) MultipartFile file, RequestParam(title) String title, RequestParam(categoryId) Integer categoryId, HttpServletRequest request) { // 1. 校验文件类型和大小 if (file.isEmpty() || file.getSize() 1024L * 1024 * 1024) { return Result.error(文件为空或超过1GB限制); } // 2. 生成唯一文件名防止冲突 String suffix FilenameUtils.getExtension(file.getOriginalFilename()); String rawName UUID.randomUUID().toString().replace(-, ) . suffix; // 3. 保存到共享目录 File target new File(uploadDir rawName); file.transferTo(target); // 4. 写入video表status0初始状态 Video video new Video(); video.setTitle(title); video.setCategoryId(categoryId); video.setRawPath(/raw/ rawName); video.setStatus(0); video.setUserId(getLoginUserId()); videoService.insert(video); // 5. 异步通知Flask开始转码 mediaClient.notifyTranscode(video.getId()); return Result.success(video); }注意第5步上传接口不能等转码完成才返回一定要异步触发。转码通常要几秒到几十秒如果同步等前端请求直接超时。我这里是在Service里开了个线程池去调Flask的接口Spring容器启动时初始化一个ExecutorService即可。2.3 登录拦截与权限控制权限这块用SpringMVC拦截器实现不引入Spring Security因为毕设或课设的演示场景里手写一个HandlerInterceptor就够用还能在论文里把流程讲明白。用户登录成功后生成一个随机UUID作为token存Redis或者直接存内存Map规模小的话Map更省事响应头里返回token字段。拦截器校验请求头里的token校验通过后把用户信息放进request的attribute里供Controller取用。public class LoginInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (OPTIONS.equalsIgnoreCase(request.getMethod())) { return true; // 放行预检请求 } String token request.getHeader(token); User user tokenService.getUser(token); if (user null) { response.setStatus(401); response.getWriter().write({\code\:401,\msg\:\未登录\}); return false; } request.setAttribute(loginUser, user); return true; } }后台管理员页面单独用一个/api/admin/**的拦截规则检查用户的role字段是否为admin。拦截器配置放在SpringMVC的XML里指定exclude-mappings放行登录注册和静态资源。2.4 视频文件上传的细节文件上传有两个容易被低估的问题一个是Tomcat的maxUploadSize默认限制另一个是本地目录权限。SpringMVC里用CommonsMultipartResolver配置上传大小bean idmultipartResolver classorg.springframework.web.multipart.commons.CommonsMultipartResolver property namemaxUploadSize value1048576000/ property namemaxInMemorySize value1048576/ property namedefaultEncoding valueUTF-8/ /bean如果你不配置这个bean或者只配置了spring.servlet.multipart.max-file-size但搭的是XML配置的SSM项目那上传稍大点的文件就会抛MaxUploadSizeExceededException。这里我用的100000KB是按1GB估的按需调整。文件保存目录我放在/data/videos/raw通过配置项注入而不是硬编码调试的时候改路径不用重新打包。保存文件时还要注意一定要用UUID重命名不能用用户原始文件名。两个用户同时上传同名视频直接覆盖是小事更麻烦的是文件名里的中文和特殊字符会导致后续FFmpeg解析路径出错。我一开始图省事直接用原名结果传了一个我的视频(最终版).mp4Flask那边路径解析直接崩从那以后所有上传一律UUID重命名原始文件名只存到DB的title字段里。3. Flask媒体服务视频解码、转码与切片处理3.1 为什么把解码放到Python侧视频解码这件事业界通用做法就是调FFmpeg没有哪个正经项目自己从头写解码器。Flask侧做解码、转码的优势在于可以用subprocess干净地管理FFmpeg进程用ffmpeg-python或imageio-ffmpeg封装调用逻辑输出解析、异常捕获都可以用Python灵活的字符串和异常机制处理而且Python生态里还有PIL做封面裁切、moviepy做片段拼接这些方便工具。另外毕设场景里Flask代码量小、结构透明转码逻辑独立成模块方便你在论文里画流程图。Java那边通常就是发起请求、查状态真正的视频管线全在Python侧这样职责单一两边代码都很容易读懂。3.2 FFmpeg探测与转码管线转码的第一步是探测视频信息。上传到共享目录的原始文件可能是MP4、AVI、MOV、MKV甚至还有FLV播放器不可能全兼容所以必须统一转成H.264编码的MP4或HLS流。探测用ffprobeffprobe -v error -select_streams v:0 -show_entries streamcodec_name,width,height,duration -of json /data/videos/raw/xxx.mp4在Flask里用subprocess.run捕获输出解析JSON拿到编码、分辨率、时长。这个信息要回传给JavaJava存到video表的duration字段。拿到信息之后决定转码策略。我的策略很简单原文件是H.264AAC的MP4直接切片其他格式先转成统一的MP4中间文件再切片分辨率超过1080p的降一下码率。转码核心命令长这样ffmpeg -i input.mp4 \ -vf scale1280:-2 \ -c:v libx264 -preset veryfast -crf 23 \ -c:a aac -b:a 128k \ -movflags faststart \ output.mp4-movflags faststart这个参数特别重要它把moov元数据移到文件头部否则浏览器播放时要把整个MP4下载完才知道时长信息表现为播放进度条拖不动、加载很久不出画面。我在调试阶段被这个卡过一晚上加上这个参数后秒开。3.3 缩略图与HLS切片封面缩略图和HLS切片可以放到同一个转码流程里。切片命令ffmpeg -i input.mp4 \ -c:v libx264 -c:a aac -strict -2 \ -hls_time 10 \ -hls_list_size 0 \ -hls_segment_filename /data/videos/hls/abc_%03d.ts \ /data/videos/hls/abc.m3u8hls_time 10表示每段10秒hls_list_size 0表示生成完整播放列表而不是只保留最近几段。HLS的好处是浏览器端可以边下边播拖动进度条只加载需要的分片不像单文件MP4那样需要服务端支持Range请求。封面抽帧命令ffmpeg -i input.mp4 -ss 5 -vframes 1 -q:v 2 /data/videos/hls/abc.jpg-ss 5取第5秒的画面注意-ss要放在-i前面这样是快速定位不是先解码全部再跳转速度差非常多。3.4 异步任务与临时文件清理Flask里绝对不要在请求处理函数里同步执行FFmpeg。一个视频转码几十秒Gunicorn的worker只有一个线程的话整个服务就卡死了。我这边的方案是把转码任务放到一个后台线程里跑请求接口只返回已受理import threading jobs {} def transcode_worker(video_id, raw_path, hls_dir): try: # 更新任务状态... run_ffmpeg_cmd(...) # 生成封面... # 写完成标记文件 except Exception as e: # 写失败标记 app.route(/api/transcode/int:video_id, methods[POST]) def transcode(video_id): t threading.Thread(targettranscode_worker, args(...)) t.start() return {code: 0, msg: task started}用threading.Thread在演示规模下完全够用不必上Celery。真正要注意的是临时文件的清理转码产生的中间文件、没有用的原片分片、低于0KB的空文件要定期删。我在Flask里加了一个cleanup()函数每小时跑一次删除超过24小时的临时目录内容避免磁盘被撑满。另外FFmpeg子进程的日志要设置stdout和stderr重定向到日志文件不然前端调用一直挂着等管道输出会阻塞。我在代码里统一用stdoutopen(log_path, w)来接管。4. Java与Flask的对接细节4.1 RestTemplate调用与超时设置Java侧调用Flask我用的是Spring自带的RestTemplate简单直接。关键是超时要配置好。第一次联调时我没配超时Flask转码中崩了没响应Java那边傻等两分钟才报错前端看起来就是上传后白屏。public MediaClient() { HttpComponentsClientHttpRequestFactory factory new HttpComponentsClientHttpRequestFactory(); factory.setConnectTimeout(3000); // 连接超时 factory.setReadTimeout(30000); // 读取超时转码请求只返回受理不用太长 this.restTemplate new RestTemplate(factory); }调用Flask接口时只传video_id和raw_path不要传整个文件流文件已经在共享目录里了两边只需要路径字符串。这样接口载荷非常轻出问题也好排查。4.2 共享文件目录Java和Flask不在同一个进程它们怎么访问同一个视频文件最省事的方案是共享目录。我开发时直接在同一台机器上跑两边配置同样的根目录一个写/data/videos/raw另一个读同一个路径。部署到不同机器时用NFS或者Samba把目录挂载过去或者干脆把Flask和Java部署在同一台服务器避免文件传输的复杂度。这里有个路径规范问题数据库里存的路径统一用相对路径比如raw/abc.mp4hls/abc.m3u8。Java拼成完整本地路径时用File.separator处理Flask里用os.path.join处理。绝对不要把Linux的/data/...直接写进数据库换Windows调试分分钟全崩。4.3 视频状态机与一致性保证转码过程Java这边怎么知道完成了不能靠猜。我的方案是Flask转码完写一个{video_id}.complete标记文件同时Java提供一个回调接口Flask用requests.post主动通知。如果回调失败Java还有一个定时任务每30秒扫描一次标记文件兜底。# Flask转码完成后 requests.post(http://localhost:8080/api/video/transcode-callback, json{videoId: video_id, status: success, duration: duration, hlsPath: hls/abc.m3u8})Java的回调接口里根据通知内容更新video表的status字段2表示可播放3表示失败。失败时把error_msg写进去前端可以展示转码失败请重新上传。状态轮询的时序我梳理了一下实际演示测试表现如下时间点Java视频状态前端表现上传完成0 等待处理显示上传成功处理中Flask受理1 转码中显示进度图标转码切片完成2 可播放出现播放器和封面FFmpeg异常3 失败显示错误提示这个状态机是整套系统最值得在论文里展开画图的部分逻辑闭环不会出现播放按钮点了没反应这种说不清的问题。4.4 CORS与跨域问题前端页面如果在8080Flask在5000浏览器直接访问Flask的流文件会有跨域问题。解决分两层第一前端尽量不直接请求Flask的业务接口流文件通过Java的/api/video/stream代理转发第二给Flask加上CORS响应头或者用Flask-CORS扩展。如果走Java代理注意用InputStreamResource把文件流传给前端避免一次性把整个文件读进内存GetMapping(/api/video/stream/{videoId}) public ResponseEntityResource stream(PathVariable Integer videoId) throws IOException { Video video videoService.getById(videoId); File file new File(baseDir video.getHlsPath()); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_TYPE, application/vnd.apple.mpegurl) .body(new InputStreamResource(new FileInputStream(file))); }不过这里有个取舍HLS切片特别多走Java代理每个.ts请求都过一遍SpringMVC线程性能一般。演示规模无所谓如果追求性能更优做法是Flask或Nginx直接配静态目录映射Java只代理.m3u8索引文件.ts分片由Nginx直出。我用的是Nginx映射方案后面部署章节会说。5. 前端播放链路从流地址到页面5.1 播放器选型前端播放器我用的是video.js加HLS.js。为什么不直接用原生video标签因为原生标签对HLS的支持在PC端Chrome、Firefox并不好HLS是苹果系原生支持的东西安卓和PC浏览器需要hls.js来把HLS封装成fMP4喂给MediaSource。video.js的皮肤和API成熟论文里也不需要为为什么选播放器费太多口舌。需要强调一点我没有引入Vue或者React用的是原生JS加JSP。原因是这个项目的核心不是前端框架是业务媒体处理的链路完整性JSP可以直接在SSM里渲染服务端能拿用户信息演示简单不容易在前端打包环节翻车。如果你是拿这套代码去改前端用Vue也不影响API照对接即可。5.2 HLS播放配置播放器初始化的核心逻辑var player videojs(my-player, { controls: true, autoplay: false, preload: auto, poster: video.coverPath }); if (video.hlsPath.endsWith(.m3u8)) { if (Hls.isSupported()) { var hls new Hls(); hls.loadSource(video.hlsPath); hls.attachMedia(player.tech().el()); } else if (player.canPlayType(application/vnd.apple.mpegurl)) { // Safari原生播放 player.src({ src: video.hlsPath, type: application/vnd.apple.mpegurl }); } } else { player.src({ src: video.rawPath, type: video/mp4 }); }video.hlsPath是Java返回的数据里面已经是代理或静态映射后的完整URL。播放列表右侧的缓冲策略由hls.js自动处理我手动设置的参数只有maxBufferLength: 30和maxMaxBufferLength: 60控制内存占用。5.3 兼容性处理兼容性集中在几个点上一是MIME类型.m3u8需要application/vnd.apple.mpegurl.ts需要video/mp2t这在Nginx的mime.types里默认可能没有要手动加二是HLS分片的跨域如果按Nginx直出的方案需要加add_header Access-Control-Allow-Origin *;三是360/IE这种老浏览器直接提示请使用Chrome或Edge访问不做多余的兼容代码演示时用Chrome省得被奇怪的兼容bug拖时间。播放过程中的日志也很重要我在前端做了个player.on(error, ...)回调把错误码打出来。hls.js的报错信息必须开debug: true才能看到详情我调试时开着上线演示前关掉。6. 调试实录与部署验证6.1 排查过的典型坑整套系统联调下来我整理了五个最有代表性的问题每个都是在现场真实踩过的现象根因解决方式上传后视频状态一直停在0Java异步线程池没有初始化mediaClient.notifyTranscode异常被吞Service层加try-catch统一记录日志线程池用PostConstruct初始化并验证HLS播放黑屏但m3u8能访问.ts分片路径不对m3u8里写的是相对路径浏览器按当前目录解析404FFmpeg生成时用绝对输出路径m3u8文件内容用sed替换为相对路径或加前缀播放进度条能拖但画面卡顿MP4没有faststart转码命令加-movflags faststartFlask返回500但Java看不到原因Gunicorn日志没打开subprocess.run的stderr没捕获统一把FFmpeg输出重定向到独立日志文件请求异常写error_log.txt中文视频标题乱码数据库表用了utf8MySQL连接串没加characterEncodingutf8连接串加参数建表用utf8mb4其中第二个坑我多说一句FFmpeg在-hls_segment_filename里给了绝对路径后生成的m3u8索引文件里既可能是绝对路径、也可能是相对路径取决于你输入文件怎么给的。我踩到的是abc.m3u8里面写了/data/videos/hls/abc_000.ts这种服务器绝对路径浏览器拿到后按根目录解析自然404。后来我统一约定-hls_segment_filename用/data/videos/hls/abc_%03d.ts生成但在写完m3u8后做一个路径清洗把开头的/data/videos/hls/替换成./保证索引文件内部是相对路径同时Nginx的location指到/data/videos/hls/作为根目录。这套约定在文档里写清楚后面没人再踩。6.2 部署拓扑最终部署到Linux服务器上的时候我的拓扑是这样的Nginx(80) ├── / → Tomcat(8080) # SSM业务接口和页面 └── /hls/ → 静态映射到 /data/videos/hls # 直出流文件 Gunicorn(5000) → Flask媒体服务 MySQL(3306) → 业务库Nginx配置里加了两个关键项.m3u8的MIME类型、.ts分片的Cache-Control。分片缓存建议给上max-age86400否则同一个分片被用户拖进度条拖来拖去反复请求浪费带宽。server { listen 80; server_name localhost; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /hls/ { alias /data/videos/hls/; types { application/vnd.apple.mpegurl m3u8; video/mp2t ts; } add_header Access-Control-Allow-Origin *; expires 7d; } }6.3 从零到一的验收流程部署完成后我按以下顺序完整走一遍验收每步都拍照留档这部分内容还能直接放进调试文档和讲解PPT注册一个新用户登录后上传一个MP4和一个AVI格式的视频。观察video表状态从0→1→2的变化确认Flask日志里有对应的FFmpeg命令输出。等待转码完成后打开视频详情页确认封面、时长、播放器加载正常。拖动进度条到中间位置确认HLS分片按需加载Network面板里能看到按10秒一个的.ts请求。评论、收藏、后台管理走一遍确认拦截器对未登录请求返回401。重启Flask服务确认未完成的转码任务状态能兜底更新不会永久卡在状态1。整个验收走下来大概20分钟每一步都有对应的日志和截图。做毕设的同学把这套流程写进测试章节比空写系统运行稳定有说服力得多。最后再分享一个小技巧整个系统调试阶段最优先做好的不是功能而是日志。Java侧用log4j2按天滚动Flask侧每个转码任务独立一个log文件FFmpeg的stdout、stderr全要落盘。联调出现任何问题第一件事不是猜而是去最后一条日志里找答案。这套日志先行的习惯帮我省下了大量排查时间也直接决定了整个交付周期能不能按时完成。
