视频处理任务里最危险的误判是目录里出现了 MP4就认为导出成功。GPU 编码器可能不可用、显存可能不足、进程可能中途退出但留下半成品即使退出码为 0成片也可能没有音轨、时长异常或编码格式不适合目标播放器。第 05 篇已经解决了确认字幕怎样进入成片本文只讨论成片导出。固定案例是一条 93.2 秒的 1080P 带字幕预览视频Worker 优先尝试 NVENC以缩短批量任务耗时GPU 不可用或编码失败时再使用libx264重新导出。系统必须记录每次尝试、每种编码策略和最终验收结果不能让失败文件进入交付目录。示例环境为 Python 3 Worker、FFmpeg/ffprobe、Java 17/Spring Boot 风格服务层和 MySQL 8.x。编码参数与阈值为教学示例生产环境应按目标平台、机器资源和素材特征调整。目录编码选择先看交付目标固定案例和可交付标准GPU首选、CPU降级的导出链路数据模型尝试记录与最终成片分开保存Python实现有条件地降级而不是盲目重试Java实现媒体验收通过才提交预期输出和自动测试SQL验证怎样发现异常交付物异常边界和上线验收小结和延伸阅读一、编码选择先看交付目标h264_nvenc和libx264不是简单的“快”和“慢”。前者依赖 NVIDIA 驱动、编码器支持和可用显存后者主要使用 CPU耗时更长但在没有 NVIDIA GPU 的机器上仍可工作。对需要广泛播放的 MP4视频使用 H.264、音频使用 AAC 通常是保守的交付选择。场景首选策略降级策略为什么GPU 工作节点批量导出H.264 NVENCH.264 libx264优先吞吐失败后仍保证交付无 GPU 的普通服务器H.264 libx264排队或转交 GPU 节点不把不存在的硬件能力写进流程高质量归档母版保留高质量源文件单独归档任务不与面向播放的压缩规则混用移动端或平台上传H.264 AAC faststart平台专用转码优先兼容与首屏播放这里的关键是“策略有顺序结果有证据”。不能因为 NVENC 失败就无限重试也不能在未记录原因的情况下悄悄换成 CPU导致后续无法解释任务为什么突然变慢。图1GPU 编码是优化路径不是交付前提CPU 降级保证任务在受控条件下完成。二、固定案例和可交付标准任务编号VW-20261001-006 输入视频outputs/preview/lesson-burned.mp4 目标交付outputs/delivery/lesson-final.mp4 源视频1920x108093.2 秒含视频和音频流 首选编码h264_nvenc / AAC 降级编码libx264 / AAC 最大时长偏差1.5 秒 最低文件大小1 MB 请求编号REQ-RENDER-006本次故障中任务第一次调用 NVENC 返回“找不到可用编码器”如果程序只报失败用户只能手工重新选择机器。如果程序无条件重复调用同一命令则会制造大量相同失败日志。正确做法是识别“可降级”的编码环境错误创建第二次 CPU 尝试第二次成功后仍要探测最终视频的时长、分辨率、流信息和文件大小。三、GPU首选、CPU降级的导出链路导出服务把“编码尝试”和“最终交付”分成两层。前者记录每次命令的策略、耗时和错误后者只引用验收通过的那一次步骤处理失败时怎样做读取输入只读取READY的预览视频输入不可用直接阻断创建 GPU 尝试写入.writing临时文件记录 stderr 摘要和错误分类判断能否降级仅对编码器不可用、设备不可用等环境错误降级内容损坏、路径错误不应换 CPU 重跑创建 CPU 尝试使用新临时文件和独立 attempt_no保留 GPU 失败记录ffprobe 验收检查流、时长、分辨率、大小失败文件不进入正式目录原子提交移动为正式交付文件并登记READY只有一个最终版本可供下游读取图2GPU 失败并不等于任务失败是否降级取决于错误类型最终仍以媒体验收为准。把编码速度、预设参数、显卡型号等细节都塞进“最终文件”表会混淆事实。最终成片回答“交付了什么”尝试记录回答“过程发生了什么”。四、数据模型尝试记录与最终成片分开保存CREATETABLEvideo_export_attempt(idBIGINTPRIMARYKEYAUTO_INCREMENT,export_job_idBIGINTNOTNULL,attempt_noINTNOTNULL,encoderVARCHAR(32)NOTNULL,preset_nameVARCHAR(32)NULL,attempt_statusVARCHAR(24)NOTNULL,temporary_pathVARCHAR(500)NULL,duration_msBIGINTNULL,exit_codeINTNULL,error_codeVARCHAR(64)NULL,error_summaryVARCHAR(1200)NULL,started_atDATETIMENOTNULL,finished_atDATETIMENULL,UNIQUEKEYuk_export_attempt(export_job_id,attempt_no),CHECK(attempt_statusIN(RUNNING,SUCCEEDED,FAILED)));CREATETABLEvideo_export_job(idBIGINTPRIMARYKEYAUTO_INCREMENT,job_noVARCHAR(64)NOTNULL,source_file_idBIGINTNOTNULL,selected_attempt_idBIGINTNULL,export_statusVARCHAR(24)NOTNULL,output_pathVARCHAR(500)NULL,output_sha256CHAR(64)NULL,output_duration_msBIGINTNULL,output_widthINTNULL,output_heightINTNULL,output_sizeBIGINTNULL,request_idVARCHAR(64)NOTNULL,create_timeDATETIMENOTNULL,update_timeDATETIMENULL,UNIQUEKEYuk_export_request(request_id),CHECK(export_statusIN(PENDING,RUNNING,READY,FAILED)));selected_attempt_id只指向通过媒体探测的一次尝试。这样既能保留 GPU 失败和 CPU 成功的完整上下文也能保证下游只读取一个READY成片。图3最终交付记录只引用验收通过的一次尝试所有失败仍可回查。五、Python实现有条件地降级而不是盲目重试Worker 将 FFmpeg 输出转换成有限的错误类型再决定是否使用 CPU。下面示例只把明确的 GPU 环境错误列为可降级输入文件不存在、滤镜参数错误等问题必须直接失败。fromdataclassesimportdataclassfrompathlibimportPathimportsubprocess FALLBACK_MARKERS(No NVENC capable devices found,Cannot load libcuda,Unknown encoder h264_nvenc)dataclass(frozenTrue)classEncodeProfile:encoder:strextra:list[str]GPUEncodeProfile(h264_nvenc,[-preset,p4,-cq,23])CPUEncodeProfile(libx264,[-preset,medium,-crf,20])defrun_encode(input_path:Path,output_path:Path,profile:EncodeProfile)-tuple[bool,str]:temporaryoutput_path.with_suffix(output_path.suffixf.{profile.encoder}.writing)command[ffmpeg,-y,-i,str(input_path),-c:v,profile.encoder,*profile.extra,-c:a,aac,-movflags,faststart,str(temporary)]resultsubprocess.run(command,capture_outputTrue,textTrue,timeout1800)returnresult.returncode0,result.stderr[-1600:]defexport_with_fallback(input_path:Path,output_path:Path):ok,detailrun_encode(input_path,output_path,GPU)ifok:returnh264_nvenc,detailifnotany(markerindetailformarkerinFALLBACK_MARKERS):raiseRuntimeError(fGPU 编码失败且不允许降级{detail})ok,detailrun_encode(input_path,output_path,CPU)ifnotok:raiseRuntimeError(fCPU 编码也失败{detail})returnlibx264,detail实际 Worker 还需要在每次尝试后执行ffprobe把时长、分辨率、流数量和文件大小作为结构化结果返回。临时文件直到验收通过前都不移动为lesson-final.mp4。图4降级是受控策略不是对任何失败都再跑一次 CPU临时文件必须先通过媒体探测。六、Java实现媒体验收通过才提交Java 服务层负责幂等、输入状态和最终提交。Worker 只报告编码尝试与探测结果不能自行把文件登记为可交付Transactional(rollbackForException.class)publicExportResultexport(ExportCommandcommand){VideoExportJobjobexportRepository.lockByRequestId(command.requestId()).orElseGet(()-exportRepository.createPending(command));if(READY.equals(job.status()))returnExportResult.reused(job.outputPath());WorkflowFileinputfileRepository.findReady(command.sourceFileId()).orElseThrow(()-newBizException(预览视频不可用));exportRepository.markRunning(job.id());WorkerExportResultworkerResultexportWorker.export(input.path(),command.requestId());workerResult.attempts().forEach(item-attemptRepository.save(job.id(),item));if(!workerResult.success()){exportRepository.markFailed(job.id(),workerResult.errorCode());returnExportResult.failed(workerResult.errorCode());}MediaInfomediaworkerResult.mediaInfo();if(!media.playable()||media.videoStreams()!1||media.audioStreams()1||Math.abs(media.durationMs()-input.durationMs())1500||media.fileSize()1_000_000){exportRepository.markFailed(job.id(),MEDIA_VALIDATION_FAILED);returnExportResult.failed(MEDIA_VALIDATION_FAILED);}StringoutputPathfileRepository.commitTemporary(workerResult.temporaryPath(),DELIVERY_VIDEO);exportRepository.markReady(job.id(),workerResult.selectedAttemptId(),outputPath,media);returnExportResult.ready(outputPath,workerResult.encoder());}这个服务方法刻意没有“GPU 失败就自己改参数”的逻辑编码策略属于 Worker 的媒体领域服务层只验证输入、保存证据和决定是否提交。职责分开后错误排查不会变成一团命令字符串。七、预期输出和自动测试第一次尝试h264_nvencFAILEDerror_code GPU_ENCODER_UNAVAILABLE 第二次尝试libx264SUCCEEDED 最终成片lesson-final.mp41920x1080时长 93.2 秒左右H.264 视频 AAC 音频 交付状态READYselected_attempt_id 指向第二次尝试deftest_only_gpu_environment_errors_allow_cpu_fallback():assertany(markerinCannot load libcudaformarkerinFALLBACK_MARKERS)assertnotany(markerinNo such file or directoryformarkerinFALLBACK_MARKERS)deftest_temporary_path_contains_encoder_name(tmp_path):targettmp_path/lesson-final.mp4asserttarget.with_suffix(.mp4.h264_nvenc.writing).name.endswith(.writing)TestvoidshouldCommitCpuOutputAfterGpuUnavailable(){fixture.readyVideo(100L,93_200L);worker.stubGpuUnavailableThenCpuSuccess(93_180L,1920,1080,2_400_000L);ExportResultresultservice.export(newExportCommand(REQ-006,100L));assertTrue(result.success());assertEquals(libx264,result.encoder());assertEquals(2,attemptRepository.countFor(result.jobId()));}TestvoidshouldRejectPlayableFileWithWrongDuration(){fixture.readyVideo(100L,93_200L);worker.stubSuccess(89_000L,1920,1080,2_400_000L);ExportResultresultservice.export(newExportCommand(REQ-007,100L));assertEquals(MEDIA_VALIDATION_FAILED,result.errorCode());}八、SQL验证怎样发现异常交付物-- READY 成片必须关联一条成功尝试预期结果为空SELECTj.job_no,j.output_pathFROMvideo_export_job jLEFTJOINvideo_export_attempt aONa.idj.selected_attempt_idWHEREj.export_statusREADYAND(a.idISNULLORa.attempt_statusSUCCEEDED);-- 查超过 30 分钟仍未结束的导出任务SELECTjob_no,update_timeFROMvideo_export_jobWHEREexport_statusRUNNINGANDupdate_timeDATE_SUB(NOW(),INTERVAL30MINUTE);-- 查 GPU 失败后又重复 GPU 尝试、却没有 CPU 尝试的任务SELECTexport_job_idFROMvideo_export_attemptGROUPBYexport_job_idHAVINGSUM(encoderh264_nvencANDattempt_statusFAILED)1ANDSUM(encoderlibx264)0;图5最终交付不是“最后一次命令跑完”而是成功尝试、媒体探测和正式文件三者一致。九、异常边界和上线验收异常应对方式GPU 不可用或编码器未安装记录环境错误允许一次 CPU 降级输入文件损坏、路径不存在直接失败不进行 CPU 降级CPU 导出超时标记超时保留尝试摘要允许从输入重新发起半成品文件遗留只写入临时目录定时清理未被任务引用的旧临时文件只含视频或只含音频媒体探测失败不进入交付目录时长、分辨率、大小异常标记验收失败保留证据供定位重复请求按request_id复用 READY 结果或返回正在执行状态上线前至少验证GPU 可用时能选中 GPU 尝试GPU 不可用时仅降级一次 CPU输入问题不会触发无意义降级失败文件不会成为DELIVERY_VIDEOSQL 能查出卡住任务和不一致的最终记录。十、小结和延伸阅读稳定导出视频的关键不在于永远使用最快的编码器而在于把编码选择、失败分类、CPU 降级、临时文件和媒体探测放进同一条证据链。GPU 是性能优化CPU 是受控兜底只有验收通过的 MP4 才是交付物。FFmpeg Codecs DocumentationFFmpeg Formats DocumentationFFprobe DocumentationSpring Framework: Transaction ManagementMySQL 8.0 Reference Manual: CREATE TABLE