Jenkins 归档产物损坏不完整速查：半截产物、压缩损坏与指纹对账
更新时间：2026-10-24。FAQ 速查页，面向下载下来的 tar.gz 解不开、jar 包一启动就报清单损坏、或制品库说「校验值对不上」的同学。Jenkins 归档产物损坏的本质是「写入 × 传输 × 校验」三段的任意一段断了：产物在工作空间里生成时就被打断（构建中断、磁盘写满）、从工作空间搬到归档目录或制品库的路上被截（网络闪断、压缩进程被杀）、以及事后没人校验导致坏件悄悄流入下游（指纹未开、校验值不复核）。控制器地址以
jenkins.example.com占位，任务路径以/proj/demo占位。如果是整个产物连影子都找不到而不是损坏，转 Jenkins 构建产物丢失速查；磁盘写满的系统级排查看 Jenkins 磁盘空间不足速查。
本文要回答的问题
- 下载的 tar.gz 解压报
Premature end of file，是下载坏了还是归档时就坏了？ - 构建中途被 abort，归档目录里留下的半截产物会不会被下游误用？
Digest mismatch/ 指纹校验失败，说明产物被改了吗？- 压缩和解压都走同一台机器，为什么还会出现损坏件？
- 怎么让「坏件」在归档那一刻就被拦下，而不是流到下游才炸？
一、报错原文与典型现象
损坏类报错分散在三处：构建日志里的归档阶段、下游解压/启动时的现场、以及指纹页的对账结果：
# 下游解压现场：压缩流被截断
gzip: stdin: unexpected end of file
tar: Premature end of file in archive# 构建日志：归档阶段工作空间文件读不完整
ERROR: Failed to archive artifacts: app/target/app.tar.gz
java.io.IOException: remote file operation failed:
File length changed during transfer# 制品库/指纹对账：校验值不一致
WARNING: fingerprint mismatch for artifact app.tar.gz
expected sha256: a1b2..., actual sha256: c3d4...读现象先分三段：归档阶段日志里有 IOException 是「写入段」坏了；构建日志干干净净但解压失败是「传输段」或下载断了；指纹 mismatch 是「校验段」在报警——它证明文件和归档时不一致，但不证明坏在归档时，也可能是制品库侧或下载链路的事。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| tar 报 Premature end of file | 归档时构建被中断，压缩只写了一半 | 看构建是否 ABORTED 灰色 | 禁归档半截产物，重跑完整构建 |
| Failed to archive: File length changed | 归档与工作区写入并发，文件边写边搬 | 查流水线是否同 stage 并发归档 | 先打包落盘再归档，两步拆开 |
| 解压时 CRC 错误、部分文件为空 | 磁盘写满或配额触顶导致截断 | df -h 查控制器与节点磁盘 | 清磁盘，产物目录加容量监控 |
| 页面下载的件解压失败、重下又好了 | 浏览器下载中断或代理截断响应 | 对比下载件与归档页的 Content-Length | 用 curl -C - 断点续传重拉 |
| fingerprint mismatch | 制品被覆盖上传或传输中字节翻转 | 指纹页对比两次构建的校验值 | 制品库禁覆盖写，重传后复核校验值 |
| 偶发损坏、机器无规律 | 节点磁盘坏道或 NFS 挂载抖动 | dmesg 与挂载日志查 IO error | 换节点复跑，坏盘下线 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：构建日志归档段有没有 IOException 是第一刀——有，坏在写入段，查中断与磁盘；没有，坏在传输段，对比归档页标称大小与本地实际大小。指纹 mismatch 单独一条：它说明「归档时」和「现在」不一致，两边各取一次校验值就知道哪边变了。
四、逐条排查展开
构建中断 = 半截产物的高发源头。 流水线跑到打包阶段被人点 abort、或节点掉线，压缩进程写到一半被杀，归档目录里就留下一个「看着像 tar.gz、实际流被截断」的文件。危险在于它名字完整、大小也有，下游不校验根本发现不了。处置分两层：流水线上把「归档」与「打包」拆成两个 stage，归档前用 currentBuild.result 或 try/finally 确认打包步骤完整成功；制品库侧开启「失败构建不发布制品」的约束，让 ABORTED 构建的半截件进不了库。
File length changed during transfer 是并发写死的信号。 这条报错的意思是归档进程在搬文件时，文件大小还在变——典型剧本是同一个 stage 里后台还有一个进程在往目标文件追加日志或追加压缩分卷。修法是时序而不是权限：先把产物完整落盘（比如 tar czf app.tar.gz 单独一步跑完退出码为 0），再让 archiveArtifacts 搬一个「已经静止」的文件。流水线里凡是「边生成边归档」的写法都要改掉。
磁盘写满是最安静的截断凶手。 压缩进程写到磁盘满时不是立刻报错，而是 write 返回部分写入，最后产出一个「长度不够但结构残缺」的包。验证直接 df -h 看节点与控制器磁盘，再看产物目录所在分区配额。处置之外要加监控：磁盘水位过了阈值就告警，别等解压失败才发现。磁盘类系统排查详见 Jenkins 磁盘空间不足速查。
下载断 ≠ 归档坏，先重拉再定性。 从 Jenkins 页面点下载，浏览器经过代理时连接被重置，拿到的就是半截响应。快速验证：对比归档详情页显示的文件大小与本地下载件大小，不一致就是下载断了；用 curl -C - -O <产物URL> 断点续传重拉一次，能解开就结案——归档本身没坏。
指纹 mismatch 是「有人动过」的物证。 Jenkins 的 fingerprint 功能记录归档时每个文件的校验值，制品库和部署前都可以复核。mismatch 出现时别急着重传：先在指纹页找到该文件的记录，对比「归档时的值」和「当前的值」，再到制品库侧对同一个文件算一次校验——三处值一摆，哪一边变了立刻清楚。常见根因是制品库允许同版本覆盖上传，两次构建用了同一个版本号把对方盖掉。
偶发损坏查硬件与挂载。 同样的流水线、同样的代码，时好时坏，多半是节点磁盘坏道或网络文件系统（NFS 挂载的工作空间）抖动。dmesg 里的 IO error、挂载日志里的重连记录是线索；换一个健康节点复跑同一构建能稳定通过，就把嫌疑节点下线体检。
五、规范做法与预防
- 打包与归档拆两步：产物先完整落盘、退出码为 0，再交给 archiveArtifacts，杜绝边写边搬。
- 失败构建不出制品：ABORTED / FAILURE 状态的构建，制品发布步骤一律跳过，半截件进不了库。
- 归档即校验：开启 fingerprint，部署前用校验值对账，坏件在入库一刻就被拦下。
- 制品库禁覆盖写：同一版本号只允许上传一次，想重发必须升版本，杜绝互相盖。
- 磁盘水位监控：控制器与节点产物分区加阈值告警，磁盘满引发的截断归零。
- 下载用工具不点浏览器：大文件走 curl/wget 断点续传，传输断了能续不重来。
这一篇在知识体系里的位置
本篇是 Jenkins 排错速查簇的「产物完整性」入口：产物整个找不到而不是损坏看 Jenkins 构建产物丢失速查；归档路径写法不对导致收不到文件看 Jenkins 路径找不到速查；磁盘写满的系统级处置看 Jenkins 磁盘空间不足速查；构建被中断的上游原因（超时与卡死）看 Jenkins 构建超时卡死速查。「写入段 → 传输段 → 校验段」三段定位法对一切产物损坏类报错通用。
一句话总结
Jenkins 归档产物损坏先按报错定段：归档日志有 IOException 走写入段——查构建中断与磁盘写满，打包和归档必须拆两步；构建干净但解压失败走传输段——对比大小后用断点续传重拉，多数是下载断了不是归档坏了；指纹 mismatch 走校验段——三处校验值一摆就知道哪边被改，制品库禁覆盖写是根治。失败构建不出制品、归档即校验、磁盘水位监控三条入库，损坏件基本绝迹。