视频上传最容易被低估前端把 MP4 提交给接口后端把它写进目录看上去就完成了。但当文件变大、并发上传增加、用户重复提交、磁盘空间紧张或者后续需要预览、转码、下载和删除时“保存一个路径”的做法很快失效。本文聚焦视频上传本身不依赖字幕识别或 AI 工作流。固定案例是运营人员上传一条 18.6 MB、93 秒的 MP4后台需要让它可靠进入视频库。我们要解决的不是“如何播放视频”而是四个基础问题上传完成前怎样避免半文件可见服务端怎样确认它确实是可用视频文件怎样存放才不串用户和任务上线后怎样查询、归档和删除而不误删仍在使用的文件。示例环境为 Java 17、Spring Boot 风格服务层、MySQL 8.x 和本地磁盘。目录规则与数据模型同样适用于 MinIO、S3、OSS 等对象存储不同之处只是最终的storage_key指向本地相对路径还是对象键。本文只讨论单请求上传的 MP4超过服务配置上限的大文件可在同一数据模型上增加分片和断点续传不在这里展开。目录先看一次上传成功却不能使用的故障视频上传模块应该交付什么结果整体方案接收、暂存、校验、存储和管理文件存储目录、命名和访问边界数据模型视频文件不能只保存一个URLJava实现把临时文件提交为可用视频预期输出和JUnit测试SQL验证怎样发现脏数据和异常文件上传后的管理边界和上线验收小结和延伸阅读一、先看一次上传成功却不能使用的故障运营人员上传活动回顾.mp4接口立刻返回成功页面也拿到了一个文件地址。十分钟后另一个人上传了同名文件后台按原始文件名写入公共目录第一条视频被覆盖。更麻烦的是服务在一次上传中断后留下了活动回顾.mp4下载接口只检查文件是否存在便把这个不完整文件当成可播放视频。这类故障的共同点是系统只知道“某个路径有文件”却没有把文件变成一条可验证的业务记录。上传模块至少需要区分写入中和可用状态知道文件属于谁、内容是否完整、元数据是否已识别、是否允许访问和何时可以清理。固定输入如下上传请求REQ-VIDEO-20260929-002 视频编号VID-20260929-002 原始文件名活动回顾.mp4 声明类型video/mp4 文件大小18.6 MB 视频时长93 秒 上传人admin图1同名覆盖、半写入和缺少文件登记都会让“上传成功”变成不可用视频。二、视频上传模块应该交付什么结果一个可上线的视频上传模块应该交付可验证的结果而不是只返回一个 URL目标具体要求验收方式文件完整未写完的文件不能被预览、下载或后续处理读取只有AVAILABLE状态可对外访问文件可信扩展名、声明类型、大小和媒体元数据经过校验记录大小、SHA-256、时长、分辨率文件隔离同名文件不会覆盖用户输入不参与存储路径两次同名上传得到不同storage_key可追溯能查到上传人、请求号、创建时间和存储位置按视频编号查询完整记录可治理可以归档、删除、清理临时文件并发现存储不一致定时 SQL 和文件巡检有明确输出本例的最小承诺是接口返回成功时VID-20260929-002已有一条AVAILABLE视频记录文件保存在系统生成的位置大小和 SHA-256 已落库异步元数据识别已拿到时长和分辨率。任何一步失败记录停在失败状态或被补偿清理不把半成品暴露给页面。三、整体方案接收、暂存、校验、存储和管理方案分为五个阶段。客户端上传只是第一步真正的提交发生在文件校验完成之后阶段负责方主要动作关键输出接收Spring Boot 接口校验请求、归属、扩展名、声明类型和大小上传请求记录暂存文件服务写入临时文件*.uploading不可访问的临时文件校验文件服务与媒体探测器计算 SHA-256读取时长、分辨率、编码信息校验结果和媒体元数据提交文件服务与 MySQL原子改名或对象存储提交状态置为AVAILABLE稳定storage_key管理管理接口与定时任务预览授权、下载、归档、删除、巡检生命周期记录在本地磁盘上“提交”通常是将临时文件原子改名在对象存储中先上传到临时对象键再复制或提升为正式对象键。无论底层介质是什么调用方只使用数据库中的storage_key不能自行拼接目录或相信浏览器传来的文件名。图2视频只有经过暂存、校验和正式提交后才进入可访问的管理状态。四、文件存储目录、命名和访问边界本地磁盘示例按创建日期和视频编号组织文件。日期方便归档视频编号保证隔离原始文件名仅作为元数据保存video-storage/ 2026/ 09/ 29/ VID-20260929-002/ source/ original.mp4 upload.meta.json preview/ poster.jpg preview.mp4 metadata/ ffprobe.json logs/ upload.log manifest.jsonsource/original.mp4是经校验后保留的原件不被预览或转码任务覆盖。preview保存可替换的封面和预览文件metadata保存媒体探测原始结果便于重新解析logs存储外部命令摘要manifest.json是一次视频入库时的文件清单。预览、封面、转码产物即使失败也不能影响原始视频的可用状态。存储路径不应直接暴露给前端。下载或播放接口先鉴权再用视频编号查询storage_key以受控方式输出文件或签发短期访问地址。这样从本地磁盘迁移到对象存储时页面和业务表都不需要改成另一套路径规则。图3目录按视频编号隔离原件、预览、探测元数据和运行日志各自有明确位置。五、数据模型视频文件不能只保存一个URL文件系统保存字节数据库保存视频的业务事实。一个最小表结构如下CREATETABLEvideo_asset(idBIGINTPRIMARYKEYAUTO_INCREMENT,video_noVARCHAR(64)NOTNULL,request_idVARCHAR(64)NOTNULL,original_file_nameVARCHAR(255)NOTNULL,declared_content_typeVARCHAR(128)NULL,detected_content_typeVARCHAR(128)NULL,storage_providerVARCHAR(32)NOTNULL,storage_keyVARCHAR(500)NOTNULL,file_sizeBIGINTNOTNULL,sha256CHAR(64)NOTNULL,duration_msBIGINTNULL,widthINTNULL,heightINTNULL,video_statusVARCHAR(32)NOTNULL,upload_user_idBIGINTNOTNULL,available_timeDATETIMENULL,archived_timeDATETIMENULL,deleted_timeDATETIMENULL,create_timeDATETIMENOTNULL,update_timeDATETIMENULL,UNIQUEKEYuk_video_no(video_no),UNIQUEKEYuk_request_id(request_id),UNIQUEKEYuk_storage_key(storage_key),KEYidx_status_created(video_status,create_time),KEYidx_sha256(sha256),CHECK(video_statusIN(UPLOADING,VERIFYING,AVAILABLE,FAILED,ARCHIVED,DELETED)));request_id用于处理浏览器重试同一个请求重复提交时应返回同一条视频记录而不是创建两份文件。sha256用于确认落盘内容与数据库记录一致也能辅助发现同一用户的重复上传。storage_key保存相对路径或对象键不保存D:\video-storage这类部署机绝对路径。video_status是访问门槛只有AVAILABLE才能播放、下载或交给下游任务。图4一条视频记录不仅有位置还要有摘要、媒体元数据、状态和生命周期时间。六、Java实现把临时文件提交为可用视频下面的服务层示例体现上传提交的核心边界先登记或锁定请求临时落盘计算摘要调用媒体探测原子改名最后把记录更新为AVAILABLE。真正的媒体探测可以由ffprobe在独立进程或 Worker 中完成探测失败时不应把视频标记为可用。importjava.io.InputStream;importjava.nio.file.Files;importjava.nio.file.Path;importjava.nio.file.StandardCopyOption;importjava.security.MessageDigest;importjava.time.LocalDate;importjava.time.LocalDateTime;importjava.util.HexFormat;importorg.springframework.transaction.annotation.Transactional;importorg.springframework.web.multipart.MultipartFile;publicclassVideoUploadService{privatefinalPathstorageRoot;privatefinalVideoAssetRepositoryassetRepository;privatefinalVideoMetadataProbemetadataProbe;Transactional(rollbackForException.class)publicVideoAssetupload(UploadVideoCommandcommand,MultipartFileupload){VideoAssetexistingassetRepository.findByRequestId(command.requestId()).orElse(null);if(existing!null)returnexisting;validateUpload(upload);VideoAssetassetassetRepository.createUploading(command.videoNo(),command.requestId(),upload.getOriginalFilename(),upload.getContentType(),command.userId(),LocalDateTime.now());PathsourceDirresolveVideoDir(asset.videoNo(),LocalDate.now()).resolve(source);PathtempFilesourceDir.resolve(original.mp4.uploading);PathfinalFilesourceDir.resolve(original.mp4);try{Files.createDirectories(sourceDir);try(InputStreaminputupload.getInputStream()){Files.copy(input,tempFile,StandardCopyOption.REPLACE_EXISTING);}FileDigestdigestsha256(tempFile);MediaInfomediametadataProbe.probe(tempFile);validateMedia(media);Files.move(tempFile,finalFile,StandardCopyOption.ATOMIC_MOVE);returnassetRepository.markAvailable(asset.id(),newAvailableVideoCommand(relativize(finalFile),digest.size(),digest.sha256(),media.durationMs(),media.width(),media.height(),LocalDateTime.now()));}catch(Exceptionex){assetRepository.markFailed(asset.id(),abbreviate(ex.getMessage()));deleteQuietly(tempFile);thrownewBizException(视频上传失败请重新上传,ex);}}privatevoidvalidateUpload(MultipartFileupload){if(upload.isEmpty()||upload.getSize()500L*1024*1024){thrownewBizException(视频不能为空且大小不能超过500MB);}Stringnameupload.getOriginalFilename();if(namenull||!name.toLowerCase().endsWith(.mp4)){thrownewBizException(当前接口只接收MP4视频);}}privatePathresolveVideoDir(StringvideoNo,LocalDatedate){PathresultstorageRoot.resolve(String.valueOf(date.getYear())).resolve(String.format(%02d,date.getMonthValue())).resolve(String.format(%02d,date.getDayOfMonth())).resolve(videoNo).normalize();if(!result.startsWith(storageRoot.normalize()))thrownewBizException(视频存储路径越界);returnresult;}}有三点不能省略。第一扩展名和浏览器传来的Content-Type只能作为初筛ffprobe或等价媒体探测结果才决定文件是否可用。第二ATOMIC_MOVE让临时文件在最后一步才成为正式文件如果底层文件系统不支持原子移动应使用同一卷内移动或改用对象存储的提交策略。第三文件系统与数据库不是同一个事务资源失败后需要把记录置为FAILED并清理临时文件定时巡检再处理极端情况下残留的孤儿文件。图5浏览器提交的文件先进入临时状态只有校验通过后才会成为可访问的视频资产。七、预期输出和JUnit测试固定案例上传成功后的预期结果video_no VID-20260929-002 video_status AVAILABLE storage_key 2026/09/29/VID-20260929-002/source/original.mp4 original_file_name 活动回顾.mp4 file_size 19503512 sha256 非空 duration_ms 93000 width 1920 height 1080JUnit 不需要真的执行 FFmpeg将VideoMetadataProbe替换为测试桩即可固定上传服务的文件边界classVideoUploadServiceTest{TestvoidshouldMakeVideoAvailableAfterValidation(){MultipartFileuploadfixture.mp4(活动回顾.mp4,video-data.getBytes());when(metadataProbe.probe(any())).thenReturn(newMediaInfo(93000L,1920,1080));VideoAssetassetservice.upload(newUploadVideoCommand(VID-20260929-002,REQ-VIDEO-20260929-002,1L),upload);assertEquals(AVAILABLE,asset.videoStatus());assertEquals(活动回顾.mp4,asset.originalFileName());assertTrue(asset.storageKey().endsWith(/source/original.mp4));assertNotNull(asset.sha256());}TestvoidshouldRejectNonMp4BeforeWritingFile(){MultipartFileuploadfixture.file(活动回顾.mov,video/quicktime,newbyte[]{1,2});BizExceptionerrorassertThrows(BizException.class,()-service.upload(newUploadVideoCommand(VID-20260929-002,REQ-VIDEO-20260929-002,1L),upload));assertTrue(error.getMessage().contains(只接收MP4));verifyNoInteractions(metadataProbe);}TestvoidshouldReturnExistingAssetForRepeatedRequest(){VideoAssetexistingfixture.availableVideo(REQ-VIDEO-20260929-002);when(assetRepository.findByRequestId(existing.requestId())).thenReturn(Optional.of(existing));VideoAssetresultservice.upload(newUploadVideoCommand(VID-20260929-002,existing.requestId(),1L),fixture.mp4(活动回顾.mp4,newbyte[]{1}));assertEquals(existing.id(),result.id());verifyNoInteractions(metadataProbe);}}集成测试再覆盖一次真实 MP4上传后用ffprobe验证时长和分辨率模拟探测失败确认数据库是FAILED、正式路径不存在、临时文件最终被清理。这样既不把外部工具塞进单元测试也没有放弃对真实媒体文件的验证。八、SQL验证怎样发现脏数据和异常文件上线后至少保留这些只读检查。查“看似成功却没有完整元数据”的视频SELECTvideo_no,storage_key,file_size,duration_ms,width,heightFROMvideo_assetWHEREvideo_statusAVAILABLEAND(file_size0ORduration_msISNULLORwidthISNULLORheightISNULL);查长时间停留在上传或校验中的请求识别中断上传和补偿失败SELECTvideo_no,request_id,video_status,create_timeFROMvideo_assetWHEREvideo_statusIN(UPLOADING,VERIFYING)ANDcreate_timeDATE_SUB(NOW(),INTERVAL30MINUTE);查同一内容的重复上传作为运营治理或秒传优化的候选项而不是直接删除SELECTsha256,COUNT(*)AScnt,SUM(file_size)ASbytesFROMvideo_assetWHEREvideo_statusAVAILABLEGROUPBYsha256HAVINGCOUNT(*)1;查已标记删除但仍占用存储的记录交给异步清理任务复核SELECTvideo_no,storage_provider,storage_key,deleted_timeFROMvideo_assetWHEREvideo_statusDELETEDANDdeleted_timeDATE_SUB(NOW(),INTERVAL7DAY);SQL 只能验证数据库内部是否自洽。还要有文件巡检抽样重新计算 SHA-256确认storage_key指向的对象存在扫描存储目录找出没有数据库记录、且超过保留期的临时文件。两份结果对不上时先告警和人工确认再决定是否删除。九、上传后的管理边界和上线验收上传模块负责让原始视频可靠入库不负责替业务决定所有后续动作。预览转码、封面截取、内容审核、字幕处理可以订阅AVAILABLE事件但它们的失败不能把原件改回不可用状态。删除也应分两步先在数据库标记DELETED并禁止访问经过保留期再异步删除实际文件这样可以避免误操作后无法恢复。上线前按下面清单验收1. 同名 MP4 上传到不同视频编号两个正式文件不会覆盖。 2. 上传中断时正式路径不存在临时文件不会被下载接口访问。 3. 上传成功后数据库包含大小、SHA-256、时长、分辨率和 AVAILABLE 状态。 4. 重复 request_id 不会生成第二份文件或第二条记录。 5. 探测失败时记录为 FAILED页面不能播放该视频。 6. 播放和下载接口按视频编号鉴权不暴露物理路径。 7. 标记删除后立即禁止访问实际删除由异步任务和保留期控制。 8. 文件巡检能发现孤儿临时文件、缺失对象和摘要不一致。十、小结和延伸阅读视频上传的核心不是把字节写到磁盘而是把一个不可信的浏览器文件提交为一条可访问、可校验、可治理的视频资产。临时文件隔离半写入媒体探测确认可用性存储键隔离同名冲突数据库记录承担追溯和生命周期管理。当这个基础层稳定后预览转码、封面截取、审核、字幕和发布都可以作为独立下游能力接入它们不再依赖猜测目录或文件名而是读取同一条AVAILABLE视频资产记录。延伸阅读Spring FrameworkMultipartFileJava SE 17FilesJava SE 17MessageDigestFFmpegffprobe DocumentationMySQL 8.0 Reference ManualCREATE TABLE