Release · XB 现场笔记

发布一个静态站点并证明边缘一致

Tue, 11 Aug 2026 00:00:00 +0000

一次发布，只有在所需公共边缘检查与选定产物一致时才算完成，而不是上传退出码为零就完成。本教程串起构建、校验、发布与验证，同时区分本地检查和部署变更。发布会改变服务器；结尾的探针才是只读网络观察。

命令假定使用 Bash、GNU find/sort/sha256sum、rsync、Python 3 与项目固定版本的 Hugo。构建步骤从仓库根运行。接触线上主机前，先在一次性目录演练目录切换示例。明确实际服务根、部署负责人、上一版目标与回滚过程。下面的 /srv 布局要求部署已配置完成，不是仓库会自动安装的东西。

指针切换改变失败边界：之前停止可保留旧版，之后需要显式回滚并重验。磁盘检查与边缘样本证明不同事实。

1. 从已记录输入构建一份产物

从干净源码版本开始，运行项目构建并记录已安装生成器版本：

set -eu
git status --short
git rev-parse HEAD
hugo version
make build

短状态为空可支持干净工作树的判断，但命令本身不会强制执行。在称其为某个提交的发布前，应检查所有变更。make build 将短提交号和当前 UTC 构建时间写入 data/buildinfo.toml，再生成 public/。页面中的标记说明记录了哪些输入，不能证明有未提交修改的工作树只含那个提交。

固定 Hugo 与 vendored 主题可减少漂移，但构建时间字段使不同时间的普通构建不一定逐字节相同。应构建选定发布一次、验证后传输这份准确产物，而不是在服务器另行重建。

2. 检查完整离线契约

make check 检查当前产物的生成视觉资源、离线包新鲜度、内部链接、无脚本输出、来源链接及下载校验和。完整仓库关卡则使用：

set -eu
make verify
make check-upstream

完整关卡还运行回归测试、双语文章检查和审阅清单新鲜度校验，再重新构建并检查输出。因此要在最后一次构建后才生成发布清单。构建成功及审阅记录未过期，不能证明每篇文章技术正确，也不证明公共服务器使用了预期头部。页数与耗时会变化，应保留实际输出，不与文章里复制来的计数作比较。

3. 用清单标识产物字节

计算哈希前，确认 public/ 只包含目录与常规文件，并停止所有写入，直到暂存完成。下面的命令不会创建快照，也不会检查每种特殊文件类型。清单放在 public/ 外，避免把自身纳入哈希。NUL 分隔文件名可保留空格及其他 shell 敏感字符：

set -euo pipefail
manifest="$(pwd)/release.sha256"
(
 cd public
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 sha256sum
) > "$manifest"
(cd public && sha256sum -c "$manifest")
sha256sum "$manifest"

GNU 校验行的摘要在文件名前。sha256sum -c 成功说明已列出的文件匹配，不证明没有额外文件。全新的空发布目录可避免目标端残留旧文件，但不能发现计算哈希后在源端新增的额外文件。要证明常规文件清单完整一致，应按相同路径、排序与哈希规则重算暂存清单，在选择指针前比较完整列表。另行检查符号链接：find -type f 不包含它们，而意外链接可能暴露预期根外的文件。将清单及其自身摘要留在发布记录中；校验和证明相对于清单的一致性，不能证明不可信清单的真实性。

4. 暂存并选择完整发布

假定 Caddy 已服务 /srv/www/example-site/current，它是指向 releases/ 内部的符号链接，所有权与读取权限正确。releases 父目录须事先存在。发布者必须串行执行，并选择唯一发布 ID。把此块作为独立 Bash 脚本，在部署机器上包含已验证 public/ 与 release.sha256 的目录中运行。运行前按部署策略检查产物的所有权与读取权限。此块自行设置清单路径和遇错停止策略；前置条件、复制或校验和失败时，必须在选择指针前停止。它拒绝暂存产物内的符号链接；这是会修改部署的步骤。

set -euo pipefail
base=/srv/www/example-site
manifest="$(pwd)/release.sha256"
test -f "$manifest"
test -d public
release_id=20261015T120000Z
release="$base/releases/$release_id"
test -L "$base/current"
previous=$(readlink "$base/current")
mkdir "$release" # Fail if this release already exists.
rsync -a public/ "$release/"
(cd "$release" && sha256sum -c "$manifest")
links=$(find "$release" -type l -print -quit)
if [ -n "$links" ]; then
 echo "Refusing symlinks in the staged artifact" >&2
 exit 1
fi
# Ownership and readable permissions must match the deployment policy.
python3 - "$base" "$release_id" <<'PYTHON'
from pathlib import Path
import os, sys, uuid
base = Path(sys.argv[1])
release = base / "releases" / sys.argv[2]
current = base / "current"
if not current.is_symlink() or not release.is_dir():
 raise SystemExit("Expected current symlink and a complete release directory")
pending = base / (".current-" + uuid.uuid4().hex)
pending.symlink_to(os.path.relpath(release, base), target_is_directory=True)
os.replace(pending, current)
print("selected:", os.readlink(current))
PYTHON
printf 'Previous target: %s\n' "$previous"

临时链接与 current 共用父目录，因此替换通过同文件系统的一次 rename 完成。普通 mv new existing-directory 不会交换两个非空目录。不要用此片段转换已有的真实目录服务根，应单独规划迁移。在预发布环境验证真实服务器的根解析及文件系统行为。

旧目标仍在磁盘上，不等于切换后旧资源 URL 仍可访问。应在新服务命名空间或稳定资源库中保留旧版指纹资源字节。浏览器多个请求可能跨越两个发布，缓存也可能持有旧 HTML。原子命名空间替换不是跨请求快照隔离，也不是断电持久性保证。

5. 验证实际交付字节与策略

切换后，用固定表示选择比较公共响应样本与相应产物文件：

set -euo pipefail
url=https://www.xbcatm.com/
status=$(curl -sS --max-time 20 -H 'Accept-Encoding: identity' \
 -D served.headers -o served.html -w '%{http_code}' "$url")
test "$status" = 200
cmp public/index.html served.html
sh public/downloads/check-http-headers.sh "$url"

从暂存时使用的同一产物目录运行此块。头部辅助脚本使用该可信产物内的副本；此步骤无需源码工作树。cmp 成功证明这个首页样本逐字节匹配。遇到意外重定向、返回 200 的代理错误页、CDN 转换或编码响应时，需要调查。检查 served.headers 中的 Content-Encoding、缓存年龄、CSP 与内容类型。头部脚本打印响应及最终状态，不会强制所有预期条件。

对中文内容、嵌套文章、CSS、SVG、下载项、重定向及错误路由重复适用检查。记录 URL 到文件的映射，包括目录索引。示例的逐项校验只证明所列文件的一致性，不证明暂存清单完整，也不证明所有公共缓存节点的交付结果。完整边缘论断需要更广泛抓取和表示感知检查；少数探针始终只是样本。

切换后的检查失败时，新版仍被选中，直到你采取行动。用新临时链接指向已记录的 previous 值，再次原子替换 current，随后重做探针。不要只移走新树，诊断期间也不要删除证据或上一版。

6. 分别检查 TLS 身份和到期窗口

从仓库根运行到期辅助脚本：

sh static/downloads/check-tls-expiry.sh www.xbcatm.com 30

它提取证书、打印日期、检查剩余到期间隔，却不是完整 TLS 身份测试：当前实现没有让主机名或信任验证失败成为致命错误。应按照公共边缘信任教程执行显式验证握手与 SAN 检查。不能从“至少还有 30 天有效期”推断信任链或吊销检查成功。

临近过期是另一项发布风险。保留实际 notAfter、信任结果与客户端环境，不要把历史签发者或日期复制到发布日志。

7. DNS 变化时纳入缓存窗口

纯内容发布不一定改变 DNS。若主机或边缘变化，应在缓存过期期间继续维护旧目标服务。变更时才降低 TTL，不会缩短已经按旧 TTL 缓存的条目。解析器 serve-stale、负缓存和客户端缓存会让窗口更复杂；TTL 不是保证所有客户端都完成迁移的统一截止点。CAA 变化影响签发策略，不负责把流量路由到新内容。

8. 保留演练过的恢复路径

上一版目录有利于快速回滚，但不是独立备份。磁盘故障、误清理或部署账户被攻破，都可能影响所有本地发布。应保留源码、构建输入、配置及适当的独立产物备份，并在隔离环境演练恢复。一次成功演练证明的是那个时刻的那条恢复路径，不会永久保证之后的变更。

9. 精确记录结果

保留源码版本与干净工作树状态、构建元数据和工具版本、清单摘要、选中与上一版目标、探针时间、HTTP/TLS 观察及任何回滚。说明覆盖的是样本、全部映射 URL，还是多个观测点。关卡失败时，应记录失败与恢复过程，而不是“它工作过”。

切换前失败可以让旧版保持不变；切换后恢复则是需要单独验证的显式操作。区分这两点，才能让发布路径可审计，而不假装每次失败都会自动恢复旧树。

来源

rsync 手册，归档复制与源路径尾斜线语义，已核验 2026-10-15。
RFC 8767：Serving Stale Data，TTL 过期后的 DNS serve-stale 行为，已核验 2026-10-15。
GNU sha256sum 手册，Debian 软件包，校验和输出及验证选项，已核验 2026-10-15。
Python os.replace，原子替换与文件系统限制，已核验 2026-10-15。
Caddy file_server，根与符号链接处理，已核验 2026-10-15。
curl 手册，状态捕获、响应头及内容解码，已核验 2026-10-15。
OpenSSL s_client，显式证书验证，已核验 2026-10-15。
Reproducible Builds：定义，产物身份与可复现性的区别，已核验 2026-10-15。

静态网站的发布检查清单

Thu, 30 Jul 2026 00:00:00 +0000

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

检查对象应是生成制品。干净输出不等于可复现；占位符搜索只是复核线索，真正的链接门禁应基于解析器。发布前服务确切制品，发布后比较两种语言的公共 GET 正文，并保存提交、生成器版本和下载校验和。

构建干净的制品

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

set -eu
hugo version
hugo --cleanDestinationDir --gc --minify --destination public

--gc 回收未使用的构建缓存资源，不会清理陈旧的已发布页面。--cleanDestinationDir 会移除目标目录中的陈旧文件，因此只能用于一次性制品目录，不能指向源码或其他数据所在的目录。把打印出的版本与项目固定版本比较；打印版本本身不会强制版本一致。记录构建输入并验证生成的制品。干净的目标目录不能证明逐字节可复现：时间戳与其他非确定性输入需要单独控制和比较。不要在构建之后手改生成的 HTML。

检查制品，而不只是源码

检视生成的树，确认期望的入口点存在。把下面的断言块作为独立 shell 脚本运行；任何必需文件缺失或为空时，都应在打印清单之前停止：

set -eu
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 -l 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '*.html'

这只是复核线索，不是自动发布门禁：本清单这类示例本来就会命中，翻译页中也一样。这项仅检查 HTML 的扫描不会覆盖 XML 订阅或 JSON 搜索输出。rg 无匹配时退出 1，发生错误时退出 2。逐个复核列出的文件，区分围栏示例与有效链接或属性，并用基于解析器的链接检查作为真正门禁。公开链接中的私有路径属于发布错误。

验证公共路由

让隔离的类生产服务器直接指向这份制品，才能进行更可靠的发布前路由检查。Hugo 开发服务器会重新构建内容；下面是独立的源码预览，不能证明它服务的就是已经检查过的 public/ 字节。第一条命令在一个终端运行，其余请求在另一个终端运行：

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://127.0.0.1:1313/ \
 --disableFastRender --disableLiveReload --renderToMemory
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/

HEAD 检查不比较正文。对待发布服务器再运行 GET，发布后将公共正文与制品比较，并检查两种语言。确认缺失路由在生产服务器上返回 404 状态。一个外观精美但状态 200 的错误页，仍然会破坏监控与缓存。

记录结果

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

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

来源

Hugo command reference，干净生产构建的生成器标志，已核验 2026-07-30。
curl manual，HTTP 验证与响应头检查选项，已核验 2026-07-30。
静态网站发布检查清单，可下载的配套资源。
Hugo server command reference，开发服务器重新构建、内存渲染与实时刷新控制，已核验 2026-10-15。

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

Thu, 16 Jul 2026 00:00:00 +0000

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

测量前停止写入、拒绝符号链接和特殊文件，并将清单保存在制品树外。逐项校验发现缺失或变化的字节；重新生成并比较完整清单还可发现多余文件。对可信源端清单做哈希可得到紧凑标识，真实性与元数据仍需独立控制。

生成稳定的列表

从包含 public/ 的目录，在 Bash 中使用 GNU findutils 与 coreutils 运行以下命令。清单应保存在被测目录之外。发布只能包含目录和常规文件：先检查并拒绝符号链接或特殊文件，因为它们不在该清单的契约内。

set -euo pipefail
manifest="$PWD/release.sha256"
(
 cd public
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$manifest"
test -s "$manifest"

先排序文件名，再计算哈希。工具之间用 NUL 分隔路径，可保留空格、制表符与内嵌换行；GNU sha256sum 会在普通可校验输出中转义特殊文件名。不要用 awk '{print $2}' 解析该输出：文件名中可以合法包含空白。单独赋值会保留 find 失败时的退出状态；只检查其输出，可能把扫描失败误认成空结果。扫描或管道一旦失败，就应把清单视为不完整，不得发布。测量期间停止写入；这些命令不会创建文件系统快照。

传输后验证

在目标端的同一个可丢弃 Bash 会话中，按顺序运行后续片段，使路径变量与 set 选项保持生效。将清单与制品路径设为实际位置：

set -euo pipefail
manifest=/path/to/release.sha256
artifact=/srv/www/site.new
(
 cd "$artifact"
 sha256sum -c "$manifest"
)

检查列出的文件能发现缺失或改变的字节，却不能发现多余文件。因此按相同流程重新生成目标端清单，并比较完整记录：

observed=$(mktemp "${manifest}.observed.XXXXXX")
trap 'rm -f "$observed"' EXIT
(
 cd "$artifact"
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$observed"
diff -u "$manifest" "$observed"

没有差异且退出状态为零，表示常规文件的路径与哈希一致。多出一个陈旧文件也会使检查失败。临时输出位于制品之外，因此检查不会包含自身。空目录、权限、所有者与时间戳不在测量范围内；部署依赖这些属性时需另行验证。

为发布记录增加聚合摘要

对清单本身做哈希，得到紧凑的发布标识：

sha256sum "$manifest"

其含义依赖固定的规则：相对路径、排序区域、算法、工具格式，以及包含哪些元数据。将可信清单与源码提交、构建器版本一起保存。

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

SHA-256 摘要一致，是字节一致的强实用证据，并不能证明作者身份。攻击者若能同时替换制品与清单，也能让检查通过。签名与可信分发是独立控制；只应校验通过预期可信渠道取得的清单。

来源

GNU Coreutils: sha2 utilities，校验和生成与验证；通过下列上游手册源码核对，已核验 2026-10-15。
GNU Coreutils 手册源码，非 tagged 校验和的转义、--check 与 NUL 分隔排序，已核验 2026-10-15。
sha256sum(1)，命令行为与输出格式，已核验 2026-07-16。
GNU Bash: Simple Command Expansion，纯赋值命令保留命令替换的退出状态，已核验 2026-10-18。

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

Thu, 09 Jul 2026 00:00:00 +0000

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

切换前后使用同一份制品。下载行对应文中的 public/downloads/check-http-headers.sh。cmp 比较前会解码受支持的内容编码；服务器转换需有明确比较规则。状态和响应头另行检查，并保留前一目录供主动回滚。

从干净的制品开始

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

set -eu
make verify
find public -type f -print | sort

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

演练三类响应

发布前，用预期服务器配置测试待发布制品。切换目录后，在公共边缘重复检查；探测仍在线的旧站不能验证新发布。请求一个 HTML 页面、一个静态资源与一个缺失路径。检查状态码、内容类型、缓存策略与安全头：

set -eu
curl --compressed -fsS -D page.headers -o page.body https://www.example.test/
curl --compressed -fsS -D asset.headers -o asset.body \
 https://www.example.test/downloads/check-http-headers.sh
curl --compressed -sS -D missing.headers -o missing.body \
 https://www.example.test/does-not-exist

cmp public/index.html page.body
cmp public/downloads/check-http-headers.sh asset.body
cmp public/404.html missing.body

把每个片段作为独立 shell 脚本运行，或放在可丢弃的 shell 会话中执行。set -eu 让这个顺序脚本在构建、传输或比较失败后停止，避免后面的成功命令掩盖先前失败。缺失路径的请求有意不用 -f：404 是预期结果，仍应被捕获。检查各响应头文件的最终状态：依次为 200、200、404；字节比较不会自动完成状态码检查。这里不跟随重定向。--compressed 在比较前解码受支持的内容编码；若服务器有意转换 HTML，需要另行说明比较规则。cmp 相等时不输出，有差异时返回非零。在 /zh/ 及其错误页上重复检查，不能直接假设两种语言一致。

让回滚保持简单

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

来源

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

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

Mon, 01 Jun 2026 00:00:00 +0000

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

两次移动之间 live 缺失，崩溃可能延长空窗。恢复需要尝试并验证。浏览器各次请求彼此独立，旧资源 URL 必须继续可访问。

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

把活动树、预置树与回滚树放在同一文件系统上。以下片段假设使用同一个 Bash 会话、GNU Coreutils，且只有一个发布进程独占这些目录名。任何命令或复制管道任一侧失败，都应停止：

set -euo pipefail
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

当工具支持目录参数时，对预置路径运行链接与校验和检查。还要确认服务用户能穿过目录并读取文件：mktemp -d 初始权限较严，解包后的制品必须具备预期权限。未通过验证的预置目录绝不能获得活动目录的名字。

用显式回滚路径切换名字

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

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

test -d "$live" && test ! -L "$live" || exit 1
test -d "$stage" && test ! -L "$stage" || exit 1
test ! -e "$rollback" && test ! -L "$rollback" || exit 1
df -P "$live" "$stage"
live_device=$(stat -c %d -- "$live") || exit 1
stage_device=$(stat -c %d -- "$stage") || exit 1
test "$live_device" = "$stage_device" || exit 1

mv -T -- "$live" "$rollback" || exit 1
if mv -T -- "$stage" "$live"; then
 test -s "$live/index.html"
else
 mv -T -- "$rollback" "$live" || {
 printf 'Restore failed; inspect %s and %s before retrying.\n' "$rollback" "$live" >&2
 exit 1
 }
 exit 1
fi

这是两步切换，不是一次原子替换：两次移动之间活动路径不存在，崩溃后可能一直缺失，直到恢复。GNU mv -T 可防止已有目录被悄悄当作容器、把发布树移进其中，但不能协调并发发布进程。文件系统检查结果不一致时不要继续。平台特定的原子交换或符号链接替换能消除名字缺失窗口，但必须结合实际服务器测试。

验证公共边缘

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

即使目录名切换是原子的，浏览器请求 HTML 与资源仍不是同一笔事务。让旧指纹资源继续可访问，才能服务缓存中或传输中的 HTML；仅保留一个不对外服务的回滚目录并不能做到这一点。文件系统重命名也不自动保证崩溃后的持久性，这需要平台相应的持久化步骤。

来源

POSIX rename()，名字替换语义，已核验 2026-06-01。
Linux rename(2)，文件系统与替换行为，已核验 2026-10-15。
GNU tar manual，归档创建与解包，已核验 2026-06-01。
GNU Coreutils: 目标目录，-T 与目录嵌套风险，已核验 2026-10-15。
GNU Coreutils: stat，文件系统设备号检查，已核验 2026-10-15。