内容寻址：把本地发布从“覆盖文件”变成“切换已验证版本”

本地发布经常从一条复制命令开始：构建完成后，把新文件覆盖到站点目录。它足够简单，却留下一个危险窗口——读者可能同时看到新旧文件，失败后也很难判断哪些内容已经生效。

更可靠的思路不是让“复制”变复杂，而是改变发布模型：先生成一个不可变且可验证的版本，确认完整后，再一次性切换入口。

1. 内容寻址解决的是什么

普通发布目录通常以版本号或时间命名，例如 releases/42。内容寻址则根据内容本身计算标识：

artifact_id = sha256(artifact_bytes)
releases/sha256-<64位十六进制摘要>/

相同字节产生相同标识；任一字节变化，摘要通常也随之变化。Git 的对象存储就是典型的内容寻址系统：对象内容经过哈希后得到用于检索它的键。相关定义可参阅 Git 官方文档。

这种模型带来三个直接收益：

1. 消除同名覆盖：不同内容不能安静地占用同一个身份。
2. 天然去重：相同构建结果可复用同一 Artifact。
3. 便于追踪：部署记录可以精确指向一组字节，而不是含义可能变化的“最新版”。

SHA-256 输出 256 位消息摘要。NIST FIPS 180-4 将安全哈希的用途描述为检测消息自摘要生成后是否发生变化；OCI Image Descriptor 规范也要求描述符支持 SHA-256 校验，并建议消费不可信来源的内容前重新计算摘要。

但要注意：只有输入字节稳定，内容标识才稳定。压缩包中的时间戳、文件顺序、权限或构建路径都可能改变最终摘要。若希望相同源码得到相同 Artifact，应固定依赖、排序文件，并规范化时间戳、权限和归档参数。

2. 不可变 Artifact：验证过的内容不再修改

内容寻址只有与不可变性结合才有意义。发布流程一旦把 Artifact 写入最终摘要目录，就不应继续修改其中任何文件；若内容需要变化，就重新构建并生成新的摘要目录。

可采用两阶段写入：

staging/<随机任务号>/     # 构建、检查中的临时目录
releases/sha256-<摘要>/  # 验证通过后的只读候选

先在 staging 中完整构建，随后生成清单并校验。只有所有检查通过，才把它提升为候选版本。若目标摘要目录已经存在，应比较或复验，而不是覆盖。

这条约束把故障范围切开了：构建失败只会污染临时目录，不会改变当前版本；一个已经发布的摘要也始终指向原来的字节集合。

3. 校验清单是 Artifact 的结构说明书

只对整个压缩包计算一个摘要，可以验证传输后的包是否一致，却不方便检查展开后的文件是否缺失。实用方案通常同时保留顶层 Artifact 摘要和逐文件清单，例如：

{
  "schemaVersion": 1,
  "artifactDigest": "sha256:…",
  "files": [
    {"path": "index.html", "size": 4821, "sha256": "…"},
    {"path": "assets/app.js", "size": 91834, "sha256": "…"}
  ]
}

验证时应检查：

• 清单格式和版本是否受支持；
• 路径是否为规范化相对路径，且不存在 ..、绝对路径或重复项；
• 实际文件集合与清单完全一致；
• 文件大小和 SHA-256 是否匹配；
• 必需入口是否存在；
• 静态站点引用的关键资源是否能在候选目录内解析。

OCI Image Descriptor 也把媒体类型、大小和摘要组合起来描述内容，并建议在计算摘要前先核对大小。

4. 哈希证明一致性，不证明可信度

这是整套设计最重要的边界。

攻击者如果能够同时替换 Artifact 和清单，就可以为恶意内容生成完全匹配的新摘要。哈希能够回答“拿到的字节是否等于清单所指的字节”，却不能独立回答“清单是谁发布的”“这个版本是否经过授权”或“它是否包含漏洞”。OCI Image Specification 对此也明确区分了按哈希验证与通过签名建立信任。

因此，本地流程至少应把内容身份与发布授权分开：

• 内容身份由 SHA-256 确定；
• 允许发布的摘要来自受控配置、审核记录或经过验证的签名元数据；
• 构建日志、测试结果和来源版本作为审计信息保存；
• 激活时使用已经确认的摘要，不接受临时计算出的任意“最新版”。

即便暂时不引入签名，也应要求操作者明确批准某个完整摘要，而不是只批准一个可变目录名。

5. 原子切换只改变入口

候选版本准备完成后，不要把文件逐个复制到当前站点。应让稳定入口 current 指向某个不可变版本，再原子替换这个入口：

current -> releases/sha256-旧摘要
current.next -> releases/sha256-新摘要

先创建并验证 current.next，然后在同一文件系统内用重命名操作替换 current。POSIX rename 规范规定，当目标目录项已经存在时，重命名期间其他线程看到的目标应始终指向旧对象或新对象；不会暴露一个目标缺失的中间状态。

不过，原子可见性不等于断电后的持久性。POSIX 基础定义说明指出，目录操作即使具有原子性和可串行化，也未必已经持久写入存储；需要抗崩溃保证时，应根据目标平台正确同步新文件及相关目录。

此外，重命名通常不能跨挂载点完成。临时入口、current 和发布目录应放在支持所需语义的同一文件系统，并在正式采用前做平台级故障测试。

6. 回滚不是重新部署

因为旧 Artifact 从未被修改，回滚只需把 current 原子切回先前摘要。发布记录可保存：

previous = sha256:旧摘要
candidate = sha256:新摘要
activated_at = …
health_check = passed | failed

推荐流程如下：

1. 构建到独立临时目录；
2. 规范化输出并生成逐文件清单；
3. 计算顶层 SHA-256，将候选提升到不可变摘要目录；
4. 从该目录重新读取并验证，不信任构建阶段的内存结果；
5. 执行静态检查和本地健康检查；
6. 记录切换前的 current 摘要；
7. 原子切换入口；
8. 从稳定入口再次检查；
9. 若检查失败，立即切回旧摘要并保留失败候选供诊断；
10. 按保留策略清理不再被引用的 Artifact。

清理必须放在最后，并保护当前版本、上一版本和正在验证的候选。否则，自动化可能先删除唯一可回滚的内容，再发现新版本不可用。

结语

可靠发布不是依赖某一个哈希算法或某一条原子命令，而是依赖一组互相约束的机制：内容寻址赋予版本稳定身份，不可变 Artifact 防止身份漂移，校验清单证明内容完整，可信元数据决定哪些摘要可被接受，原子切换缩短生效窗口，保留旧 Artifact 则让回滚成为一次指针切换。

这套结构不局限于静态网站。只要发布结果能够被封装为确定的文件集合，它就适用于本地工具资源、离线包、配置快照和其他文件型交付物。