别让制品悄悄变质：SHA-256 校验、清单与内容寻址

安装包能解压，不代表它就是构建机产出的那一份；对象存储返回成功，也不代表每一层传输都没有截断或串包。要让发布结果可验证，关键是为确定的字节建立稳定身份，并让生产者与消费者在同一边界计算它。

先分清三个不同问题

校验和常被笼统地称为“安全校验”，但它只解决其中一部分问题：

问题	常用手段	能回答什么
传输是否完整	文件大小、SHA-256	收到的字节是否与预期一致
来源是否可信	数字签名、可信发布通道	摘要是否由可信生产者发布
内容是否可用	格式解析、业务测试	文件在语义上是否正确

攻击者若能同时替换制品和摘要，单独的 SHA-256 无法发现问题。因此，摘要应通过受保护的元数据接口分发，要求更高时再对清单签名。哈希也不是加密：它不提供保密性，更不能代替制品测试。

在生产端生成不可歧义的清单

先完成构建，再对最终交付的字节计算摘要。压缩前后的文件是两个不同对象，不能在一端对目录求哈希，另一端却对压缩包验证。

tar -czf app-linux-amd64.tar.gz dist/
sha256sum app-linux-amd64.tar.gz > SHA256SUMS

# 下载到同一目录后验证
sha256sum --check SHA256SUMS

清单至少应记录文件名、字节数、SHA-256 和构建标识。发布时先上传制品，再发布引用它的清单；消费者只读取已经发布的清单，便不会在制品上传一半时提前取用。若存储支持条件写入，还可拒绝同一构建标识指向不同摘要。

验证时使用流式读取

大文件不应一次性读入内存。下面的实现固定按块计算摘要，并在校验通过前不把文件交给解压或安装步骤：

import hashlib
import hmac
from pathlib import Path


def verify(path: Path, expected: str) -> bool:
    digest = hashlib.sha256()
    with path.open("rb") as file:
        for block in iter(lambda: file.read(1024 * 1024), b""):
            digest.update(block)
    return hmac.compare_digest(digest.hexdigest(), expected.lower())

下载程序可以边接收边更新哈希，但只有流结束、长度符合预期且摘要一致后才能提交临时文件。验证失败要删除隔离区中的内容并记录期望值、实际值、来源和请求标识；不要自动重试到“碰巧成功”后抹掉异常线索。

让摘要直接成为存储地址

传统路径如 releases/latest/app.tar.gz 会随覆盖而改变含义，缓存也难判断同名对象是否已经更新。内容寻址则把摘要放进键中，例如 sha256/ab/cd…：相同字节天然得到相同地址，不同字节不会意外共用缓存项。

业务名称不必消失，而是变成一层很小的映射：版本、平台等可读元数据指向不可变摘要。更新发布只需原子切换映射；回滚则把映射指回旧摘要。垃圾回收不能按文件时间盲删，应先从版本清单、部署记录和保留策略收集仍被引用的摘要，再清理不可达对象。

设计校验边界，而不只是选算法

工程上优先使用 SHA-256 等抗碰撞哈希，不要把 MD5 用于存在恶意输入的完整性判断。但算法选对只是起点，字节边界更重要：是否包含文件权限、压缩参数和生成时间，必须由制品格式明确规定。目录若要整体校验，应先采用确定性的打包规则，或逐项记录规范化路径与文件摘要。

最后把验证嵌入流水线：构建端产出制品与清单，上传端复读校验，下载端先校验再安装，部署记录保存最终摘要。定期抽检存量对象，并监控摘要不一致、长度异常和同名异摘要事件。这样一来，“发布了哪个版本”就不再只是一个容易漂移的标签，而是能追溯到唯一字节集合的工程事实。