Release · XB 现场笔记

发布清单应点名每一个已发布的字节

Sun, 23 Aug 2026 00:00:00 +0000

静态制品是一个目录，而不是一个可执行文件。只记录源码提交或只记录首页校验和会留下缺口：缺失的图片、陈旧的别名或变化的下载可能悄悄存活下来。一份发布清单应枚举每个常规文件。

生成稳定的列表

从制品根目录运行命令，使路径保持相对。在固定区域设置下按路径排序：

cd public
find . -type f -exec sha256sum {} + | LC_ALL=C sort -k2 > ../release.sha256

清单是关于制品的证据，因此把它放在被测量目录之外，除非清单本身有意作为发布的一部分。

传输后验证

在目标端，逐个文件验证：

cd /srv/www/site.new
sha256sum -c /path/to/release.sha256

这能捕获变化的字节与缺失的路径。它不会报告意外的多余文件，因此也要比较目标端的文件列表：

find . -type f | LC_ALL=C sort > destination.files
awk '{print $2}' /path/to/release.sha256 | LC_ALL=C sort > expected.files
diff -u expected.files destination.files

为发布记录增加聚合摘要

对清单自身做哈希，为日志与部署记录生成一个短标识：

sha256sum release.sha256

聚合摘要只有在清单生成规则固定时才有意义：相对路径形式、排序区域、哈希算法，以及是否包含生成的元数据，都属于流程的一部分。

不要把完整性等同于真实性

SHA-256 证明两个字节序列一致。如果攻击者既能替换制品也能替换清单，那么这种检查不能确立是谁产生的它们。制品签名与可信分发是独立的控制手段。

来源

GNU Coreutils: sha2 utilities，校验和生成与检查，已核验 2026-08-23。
sha256sum(1)，命令行为与输出格式，已核验 2026-08-23。

通过切换完整目录发布静态网站

Sun, 23 Aug 2026 00:00:00 +0000

直接把新文件复制到活动的静态目录上，会造成一段访问者可能从一个版本拿到 HTML、从另一个版本拿到资源的时期。更安全的模式是：在活动树旁预置一棵完整的树，验证它，再改变目录名。

把所有发布目录放在同一文件系统上

当活动树、预置树与回滚树共享同一文件系统与父目录时，名字替换最强。先检查：

df -P /srv/www

在该父目录下创建唯一命名的中转目录。不要把未解析的变量或宽泛通配符当成删除目标来复用。

stage=$(mktemp -d /srv/www/site.new.XXXXXX)

填充并验证预置目录

把生成制品复制进空目录，然后检查代表性文件与期望的文件数：

tar -C public -cf - . | tar -C "$stage" -xf -

test -s "$stage/index.html"
test -s "$stage/404.html"
find "$stage" -type f | wc -l

当工具支持目录参数时，对预置路径运行链接与校验和检查。未通过验证的预置目录绝不能获得活动目录的名字。

用显式回滚路径切换名字

在第一次移动前解析每个路径：

live=/srv/www/site
stamp=$(date -u +%Y%m%dT%H%M%SZ)
rollback=/srv/www/site.old-$stamp

test -d "$live"
test -d "$stage"
test ! -e "$rollback"

mv "$live" "$rollback"
if mv "$stage" "$live"; then
 test -s "$live/index.html"
else
 mv "$rollback" "$live"
 exit 1
fi

这段序列在两个移动之间留下一个短窗口。对每次请求都对根的单一静态服务进程来说，该窗口通常很小但仍可观察。平台特定的 rename 或符号链接模式可以收紧切换；在依赖更强断言之前，请测试确切的文件系统与服务器行为。

验证公共边缘

切换之后，请求首页、一个深层路由、一个带指纹的资源与一个缺失路径。把公共字节与预置制品比较。在检查完成与观察窗口结束之前，保留回滚目录。

来源

POSIX rename()，名字替换语义，已核验 2026-08-23。
Linux rename(2)，文件系统与替换行为，已核验 2026-08-23。
GNU tar manual，归档创建与解包，已核验 2026-08-23。

发布在公共边缘一致之前不算完成

Sat, 22 Aug 2026 00:00:00 +0000

静态发布消除了应用运行时的复杂度，但不会消除生成目录与公共响应之间的边界。发布检查应同时覆盖两边。

从干净的制品开始

使用固定生成器构建到干净的目录。记录源码提交、生成器版本、输出文件列表，以及用户会下载的文件的校验和。一次干净的构建能捕获复制式部署可能会意外保留的陈旧文件。

make verify
find public -type f -print | sort

文件列表是证据，不是装饰。如果某条路由消失，diff 应能说明是该来源被移除，还是生成器未能产出它。

演练三类响应

请求一个 HTML 页面、一个静态资源与一个缺失路径。检查状态码、内容类型、缓存策略与安全头：

curl -fsS -D - -o /dev/null https://www.example.test/
curl -fsS -D - -o /dev/null https://www.example.test/downloads/check-http-headers.sh
curl -sS -D - -o /dev/null https://www.example.test/does-not-exist

第三条命令有意不用 -f：404 是预期结果，仍应被捕获。把公共正文与生成的 404.html 比较，并确认状态始终为 404。

让回滚保持简单

在新目录通过检查之前，不要删除上一个目录。回滚应选择一个已知良好目录，而不是在事故中凭记忆重新构造一个。发布检查清单与HTTP 响应头检查都刻意做得足够小，能在干净的 shell 里运行。

来源

RFC 9110 — HTTP Semantics，状态与表示语义，已核验 2026-08-22。
curl manual，响应检查选项，已核验 2026-08-22。
静态网站发布检查清单，本地配套资源。

静态网站的发布检查清单

Sat, 22 Aug 2026 00:00:00 +0000

静态网站发布很简单，但简单并不免除发布检查的需要。有用的检查足够小，能在每次发布运行，也足够具体，能为真实的理由而失败。

构建干净的制品

使用固定版本的生成器，构建到一次性的输出目录：

hugo version
hugo --gc --minify --destination public

确切命令因项目而异，但关键属性是：输出能从受跟踪的源码复现。不要在构建之后手改生成的 HTML。

检查制品，而不只是源码

检视生成的树，确认期望的入口点存在：

test -s public/index.html
test -s public/404.html
test -s public/robots.txt
test -s public/sitemap.xml
find public -type f -print | sort

然后搜索意外的占位符、本地路径与仅开发用的主机：

rg -n 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '!notes/a-release-checklist-for-a-static-site/**'

文章里有意保留的示例应用围栏明确标注为示例。链接里的主机名或私有路径通常是发布错误。

验证公共路由

在本地提供制品并请求访问者可达的路径：

hugo server --bind 127.0.0.1 --port 1313 --disableFastRender
curl -I http://127.0.0.1:1313/
curl -I http://127.0.0.1:1313/notes/
curl -I http://127.0.0.1:1313/resources/
curl -I http://127.0.0.1:1313/missing-page/

确认 404 路由在生产服务器上返回 404 状态。一个外观精美但状态 200 的错误页，仍然会破坏监控与缓存。

记录结果

在发布记录中保留源码提交、生成器版本与每个可下载资源的校验和。这样无需依赖记忆，就能把线上文件与产生它的源码进行比较。

这份检查清单的可下载版本在资源一节中。

来源

Hugo command reference，干净生产构建的生成器标志，已核验 2026-08-22。
curl manual，HTTP 验证与响应头检查选项，已核验 2026-08-22。
静态网站发布检查清单，可下载的配套资源。