一个 AI 或媒体工具最难解释的反馈往往不是“任务失败”而是“上周同一个文件、同一个按钮为什么今天结果不一样”。这类问题通常不是模型突然失灵而是系统只保存了一个原始文件名和几项页面参数文件可能被覆盖默认值可能升级用户也无法说明当时究竟选择了哪套配置。本文继续使用脱敏的媒体处理任务PT-20261007-002。用户上传source.mp4选择预设WEB_1080P系统创建一份可重复执行的任务快照。案例中的文件名、摘要值、参数和版本号均为教学示意不公开真实素材、模型提示词、内部路径或服务配置。环境边界Java 17、Spring Boot 风格服务层、Python 3.11 Worker、MySQL 8.x。本文讨论文件身份、参数校验和配置快照不讨论具体模型算法也不公开生产环境的存储地址或运行命令。目录为什么文件名和页面参数不足以复现任务固定案例一次提交应留下哪些事实上传校验先确认文件能不能成为输入资产配置版本保存快照不回头读取页面默认值数据模型文件资产、配置快照与任务引用服务层实现校验、归一化和生成可复现指纹预期输出与自动测试SQL 验证如何发现覆盖、漂移和脏数据异常边界与上线验收小结和延伸阅读一、为什么文件名和页面参数不足以复现任务上传接口收到source.mp4后最简单的做法是把它存成uploads/source.mp4然后把页面上选择的分辨率写进任务表。这个做法会立刻遇到三种歧义第二位用户同名上传会覆盖第一份页面默认码率升级后旧任务重跑得到不同结果用户手工填入的“1080”“1080p”“1080P”被当作三个不同配置。可复现不是要求每次都得到字节完全一致的媒体文件。编码器、依赖版本或硬件差异可能影响二进制结果。它要求的是系统能明确回答任务当时引用哪一份输入、经过哪套归一化配置、使用哪个配置版本并能在环境允许时按这些事实重新运行。没有这份证据所谓“重跑”只是重新点一次按钮。图1文件名便于展示却不能证明文件身份页面参数便于输入却不能代替版本化快照。二、固定案例一次提交应留下哪些事实任务PT-20261007-002的输入和配置如下事实教学示例作用上传显示名source.mp4让用户识别自己提交的文件对象键source/sha256/7f3a.../original.mp4指向不可被同名上传覆盖的对象内容摘要7f3a...识别同一份二进制内容支持去重与复查媒体摘要1920x1080、25fps、90.04s判断是否满足工具输入条件配置版本media-preset-v3固定可用预设和参数语义配置快照WEB_1080P、1080、音频保留重跑时不依赖当前页面默认值复现指纹输入摘要 规范配置 版本区分“同一任务意图”和“新的一次请求”其中对象键可以是对象存储键、受控文件目录中的相对键或其他稳定引用重点是它不能仅由用户文件名组成。内容摘要也不是为了让前端承担安全校验而是给后端建立“文件内容是否相同”的可核对标识。图2用户看见的是文件名系统重跑依赖的是对象键、摘要和固定版本的配置。三、上传校验先确认文件能不能成为输入资产上传成功只说明字节已经到达服务端不说明它适合进入任务队列。校验应分为三个层次层次要检查什么失败后的处理接收层文件大小上限、空文件、上传中断、允许扩展名直接拒绝提示重新上传内容层MIME 仅作辅助读取文件头或媒体探测确认存在视频流标记INPUT_INVALID不创建可执行任务业务层分辨率、时长、帧率、音频要求是否落入当前预设支持范围告知该预设不支持不把问题拖给 Worker扩展名不能单独作为可信依据反过来探测到视频流也不表示任何视频都值得处理。比如WEB_1080P可以允许大于等于 720p 的输入却拒绝零时长和旋转元数据无法读取的文件。校验结果应作为输入资产的一部分保存Worker 不需要再次靠猜测判断“这是什么文件”。{fileId:F-20261007-001,displayName:source.mp4,sha256:7f3a...,sizeBytes:251004832,probe:{video:true,width:1920,height:1080,durationSeconds:90.04},validationStatus:ACCEPTED}图3输入校验在入队之前完成让格式、时长和媒体流问题尽早暴露。四、配置版本保存快照不回头读取页面默认值预设并不只是下拉框文案。它定义哪些参数允许用户选择、缺省值是什么、参数如何组合以及哪些输入条件可接受。例如WEB_1080P在media-preset-v3中可能表示“最长边限制为 1080、保留音频、生成网页兼容结果”。当v4修改了默认质量策略旧任务重跑仍应引用v3的已保存快照而不是静默套用新默认值。可以把配置分为两份配置定义由发布人员管理包含版本和允许字段任务快照由提交时生成只包含已归一化、已验证的具体值。页面只提交业务意图服务端负责填充默认值、拒绝未知字段、排序键并生成规范 JSON。{configVersion:media-preset-v3,presetCode:WEB_1080P,normalized:{maxHeight:1080,keepAudio:true,outputContainer:mp4}}这里的 JSON 不是“把整个页面请求原样塞进数据库”。例如 UI 文案、临时开关、未被允许的自由文本都不应进入 Worker 配置。真正有意义的是一份字段稳定、语义明确、可比较的快照。图4页面默认值可以更新任务配置一经受理就固定以便解释和复跑。五、数据模型文件资产、配置快照与任务引用将上传文件、配置快照和任务分开保存可以避免“任务删了输入丢失”或“配置改了历史被改写”。下面的结构刻意省略存储供应商细节只保留追溯所需事实CREATETABLEinput_asset(idBIGINTPRIMARYKEYAUTO_INCREMENT,asset_noVARCHAR(40)NOTNULL,display_nameVARCHAR(255)NOTNULL,object_keyVARCHAR(255)NOTNULL,sha256CHAR(64)NOTNULL,byte_sizeBIGINTNOTNULL,media_summary_json JSONNOTNULL,validation_statusVARCHAR(24)NOTNULL,created_atDATETIMENOTNULL,UNIQUEKEYuk_asset_no(asset_no),UNIQUEKEYuk_asset_sha256(sha256),CONSTRAINTck_asset_statusCHECK(validation_statusIN(ACCEPTED,REJECTED)));CREATETABLEtool_config_snapshot(idBIGINTPRIMARYKEYAUTO_INCREMENT,config_versionVARCHAR(40)NOTNULL,preset_codeVARCHAR(40)NOTNULL,normalized_json JSONNOTNULL,config_fingerprintCHAR(64)NOTNULL,created_atDATETIMENOTNULL,UNIQUEKEYuk_config_fingerprint(config_fingerprint));ALTERTABLEtool_jobADDCOLUMNinput_asset_idBIGINTNOTNULL,ADDCOLUMNconfig_snapshot_idBIGINTNOTNULL,ADDCONSTRAINTfk_job_assetFOREIGNKEY(input_asset_id)REFERENCESinput_asset(id),ADDCONSTRAINTfk_job_configFOREIGNKEY(config_snapshot_id)REFERENCEStool_config_snapshot(id);input_asset不等于某位用户的任务同一份内容可以被多次合法引用但每次运行仍有独立任务号。tool_config_snapshot也不等于全局配置表它是一次提交所用参数的不可变记录。是否允许对相同摘要和相同快照复用结果属于业务缓存策略不能为了“省算力”而默认把所有用户任务合并。六、服务层实现校验、归一化和生成可复现指纹服务层收到的请求只能包含允许的字段。下面示例先验证输入资产再用配置定义归一化参数最后基于内容摘要、配置版本和规范 JSON 生成复现指纹。它不把原始 JSON 的字段顺序、无关空格或前端临时字段当成配置差异。publicrecordSubmitCommand(LongassetId,StringpresetCode,MapString,Objectoptions){}ServicepublicclassReproducibleJobService{TransactionalpublicStringsubmit(SubmitCommandcommand){InputAssetassetassetRepository.requireAccepted(command.assetId());PresetDefinitiondefinitionpresetCatalog.require(command.presetCode());MapString,Objectnormalizeddefinition.normalizeAndValidate(command.options(),asset.mediaSummary());StringcanonicalJsoncanonicalJsonWriter.write(normalized);Stringfingerprintsha256(asset.getSha256()|definition.version()|canonicalJson);ConfigSnapshotsnapshotsnapshotRepository.findOrCreate(definition.version(),definition.code(),canonicalJson,fingerprint);ToolJobjobToolJob.queued(JobNo.next(),asset.getId(),snapshot.getId());jobRepository.insert(job);returnjob.getJobNo();}}这里的normalizeAndValidate是关键它将1080P这类展示值转换为固定数值将未传字段补为预设默认值并拒绝extraCommand之类不属于配置定义的字段。复现指纹用于定位“相同输入和配置”的任务不应代替用户提交幂等键前者描述技术条件后者描述一次用户意图。七、预期输出与自动测试提交成功后任务查询应同时返回输入资产和配置快照的关键信息{jobNo:PT-20261007-002,input:{assetNo:F-20261007-001,displayName:source.mp4,sha256:7f3a...},configuration:{version:media-preset-v3,preset:WEB_1080P,maxHeight:1080},status:QUEUED}自动测试应覆盖“输入不能进队列”和“语义相同参数产生同一配置快照”两件事TestvoidrejectedAssetCannotCreateJob(){InputAssetassetassetRepository.save(rejectedAsset());assertThatThrownBy(()-service.submit(newSubmitCommand(asset.getId(),WEB_1080P,Map.of()))).hasMessage(INPUT_NOT_ACCEPTED);}TestvoidequivalentOptionsShareTheSameConfigFingerprint(){Stringfirstservice.submit(commandWith(Map.of(height,1080P)));Stringsecondservice.submit(commandWith(Map.of(height,1080)));assertThat(jobRepository.findByNo(first).getConfigSnapshotId()).isEqualTo(jobRepository.findByNo(second).getConfigSnapshotId());}还应补一条版本回归测试配置目录更新到media-preset-v4后历史v3任务的查询和重跑计划仍读取其已保存 JSON不从当前目录重新取默认值。八、SQL 验证如何发现覆盖、漂移和脏数据以下查询可以在上线后检查最常见的数据质量问题执行任务引用了被拒绝输入、配置快照缺失、同一摘要却指向不一致的对象键。-- 预期结果0 行。可执行任务必须只引用已接受的输入资产。SELECTj.job_no,a.validation_statusFROMtool_job jJOINinput_asset aONa.idj.input_asset_idWHEREj.statusIN(QUEUED,RUNNING,READY)ANDa.validation_statusACCEPTED;-- 预期结果0 行。每个任务都必须关联一份不可变配置快照。SELECTj.job_noFROMtool_job jLEFTJOINtool_config_snapshot cONc.idj.config_snapshot_idWHEREc.idISNULL;-- 预期结果0 组。相同内容摘要不应被登记成多个稳定对象键。SELECTsha256,COUNT(DISTINCTobject_key)ASobject_keysFROMinput_assetGROUPBYsha256HAVINGCOUNT(DISTINCTobject_key)1;第三条的前提是系统采用“按内容摘要归档”的存储策略如果产品有意按租户或权限隔离对象键应把隔离维度加入分组而不是机械追求全局唯一。SQL 验证必须服从真实权限模型不能因为去重优化而打破隔离边界。九、异常边界与上线验收场景系统应做什么不应做什么同名文件再次上传保存独立显示记录使用摘要和对象键判断内容关系直接覆盖旧对象探测失败或无视频流标记输入被拒绝返回可理解的失败原因创建QUEUED任务让 Worker 再试用户提交未知参数在服务层拒绝并记录字段名拼接到 Worker 命令或悄悄忽略当前预设升级只影响新的提交历史任务继续引用原快照将旧任务的配置静默改为新默认值同内容再次处理根据业务策略决定复用、复跑或提示因为摘要相同而越权暴露别人的产物上线验收可准备三份脱敏文件两个同名但内容不同的文件、两次内容相同但展示名不同的上传。再使用语义相同的两种参数表达提交任务并在配置升级后查询第一批任务。预期是不同内容得到不同资产相同内容可被系统识别语义相同参数归一化为同一快照历史任务的版本和参数保持不变。图5能解释“当时用了什么”的任务才具备可信的重跑和验收基础。十、小结和延伸阅读文件管理不是给上传接口加一个目录参数管理也不是把请求 JSON 存下来。产品化的核心是将可变的文件名、页面默认值和用户输入转换为稳定的输入资产、规范配置和版本化快照。这样任务失败时能定位原因任务重跑时有明确依据配置升级也不会改写历史。下一篇将讨论长时间任务的队列、进度、取消和状态反馈当输入与配置已经可追溯后如何让用户看懂任务到底在等待、执行、失败还是可以下载。参考资料Spring Framework事务管理参考MySQL 8.4CREATE TABLE 与约束FFmpegffprobe 文档