发布与恢复 · XB 现场笔记

小系统的优势

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

小不等于未完成。它意味着每个组件职责清晰、依赖经过斟酌，并且从请求到结果之间始终可见。

可见性是一种特性

当运维人员能说出每个边界时，他们也能指出缺少哪份证据。日志变得更有用，告警更具体，例行维护风险更低。

对静态网站而言，重要的边界通常很容易列出：

DNS 把主机名指向预期的边缘。
TLS 在预期的代理处终结。
代理只服务一个已知的输出目录。
输出只包含站点需要的文件。
404 响应由站点本身处理，而不是意外的上游。

把这些写下来，比加上一块回答不了任何上述问题的仪表盘更有价值。

复杂性要用实力取得位置

当新的一层消除的不确定性多于它引入的，它才值得。缓存重要时，给资源加指纹的构建步骤会有用；内容需要事务时，数据库才有用。但对一个小而多为静态的站点，这两者都不必然是改进。

对客户端 JavaScript 也适用同一规则。如果页面需要搜索索引或交互编辑器，就加入满足该需求的最小实现，并有意识地更新内容。如果页面是一份文档，纯 HTML 往往更容易检视、更有韧性。

让所有权明确

每个文件都应有存在的理由与明确的更新方式。vendored 主题应记录其上游版本与许可。生成目录应标记为生成物。资源下载应说明它包含什么、何时更新、校验和如何产生。

这些简短声明能防止未来的运维者把偶然产生的制品当作受支持的接口。

为下一次变更留出空间

最好的小系统不是行数最少的那个，而是下一次变更看得见去处的那一个。笔记站可以从 Markdown、静态生成器与一个 Web 服务器起步；如果以后需要搜索或评论，可以独立评估这个新需求，而不是一开始就假设它存在。

来源

Hugo directory structure，内容与资源的目录约定，已核验 2026-08-22。
Caddy file_server 指令，设计中引用的静态文件服务默认值，已核验 2026-08-22。

静态服务器应有一个明确的根目录

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

静态部署最有用的属性是：运维人员不用读应用代码，就能回答"这条响应是哪个目录提供的？"。Caddy 的 root 与 file_server 指令直接提供了这个边界。

让根目录明确

一个最小的站点块可以贴近制品布局：

www.example.test {
 root * /srv/example-site
 encode zstd gzip

 header {
 -Server
 X-Content-Type-Options nosniff
 X-Frame-Options DENY
 Referrer-Policy strict-origin-when-cross-origin
 }

 file_server
}

该路径只是示例，不是该盲目粘贴的值。发布命令应发布一个完整目录、核验它，然后才把这个目录设为配置里的根。在旧的已知良好目录通过冒烟测试之前，保留它。

检查边缘，而不只是文件树

请求一个 HTML 页面、一个可下载的文本文件和一个缺失路径。把内容类型与状态码与本地制品比较。即使 404 页看起来很精致，若返回 200 仍是部署缺陷。

当 Caddy 管理 HTTPS 时，证书签发与 HTTP 到 HTTPS 的重定向都属于边缘行为。请从裸的 HTTP 监听器测试重定向，并从公共主机名读取证书名称。不要只凭进程健康就推断成功。

来源

Caddy file_server 指令，静态文件服务与根目录选择，已核验 2026-08-22。
Caddy header 指令，响应头配置，已核验 2026-08-22。
Caddy Automatic HTTPS，证书签发与 HTTPS 重定向，已核验 2026-08-22。
MDN: X-Frame-Options，防止被嵌套的选项，已核验 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。
静态网站发布检查清单，可下载的配套资源。

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

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。

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

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。

用两条命令读取公共边缘

Mon, 24 Aug 2026 00:00:00 +0000

一次部署，是当公共边缘与你选择的文件一致时才完成，而不是因为最后一条上传命令退出码为零。操作套件里的两个只读小工具，能让任何能到达主机的机器看到这种一致性。

检查响应头

check-http-headers.sh 抓取一个 URL，并打印响应行、响应头与重定向后的最终 URL：

check-http-headers.sh https://www.xbcatm.com/

最近对本站一次运行的结果：

HTTP/2 200
server: nginx
content-type: text/html; charset=utf-8
content-security-policy: default-src 'self'; script-src 'none'; ...
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff

注意正文被丢弃，只显示响应线之外的状态行。要比较一次发布前后的变化，保存一份基线并把新的输出与之相减。

读取证书日期

check-tls-expiry.sh 从 TLS 握手读取服务器证书的过期日期，而不改变服务：

check-tls-expiry.sh www.xbcatm.com 30

它打印证书的 notAfter 以及到该日期剩余的天数。如果剩余天数低于阈值，它以非零状态退出——适合加进发布冒烟测试。

发布冒烟测试里它们配合使用

排定发布冒烟测试时，让一个命令确认法着陆状态，另一个确认即将过期的证书。剩下的剩余风险是活动报表之外、真正浏览无法发现的内容——例如重量级第三方脚本，或是仅在大流量出现的缓存问题。一条只读输出现场完成不了这些，仍需一次真实的浏览器会话。

来源

RFC 9110 — HTTP Semantics，响应语义与条件请求，已核验 2026-08-24。
OpenSSL s_client，TLS 连接与证书日期检查，已核验 2026-08-24。
制品 HTTP 响应头检查，贯穿本记录使用的只读检查。

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

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。
静态网站发布检查清单，本地配套资源。

DNS 变更需要一个感知缓存的回滚窗口

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

改一条地址记录很容易，预测每个解析器何时停止使用旧应答却很难。时间到活性（TTL）值随 DNS 响应传播，并控制缓存可复用的时长。在迁移那一刻降低 TTL，并不能改写更早被缓存下来的应答。

在事件前降低 TTL

如果既有记录是一天的 TTL，至少要在计划切换前一个旧 TTL 时就把它降低。这样在旧端点仍然权威时，缓存有时间去取较短的值。确切间隔应写进变更计划，而不是在迁移中即兴执行。

记录来自权威服务器与至少一个递归解析器的应答：

dig +noall +answer www.example.test A
dig @1.1.1.1 +noall +answer www.example.test A

递归解析器显示的剩余 TTL 是它当前缓存状态的证据。不同解析器合理地显示不同的剩余值。

让两侧都保持有效

切换期间，保持旧端点与新端点都能为预期主机名提供服务。TLS 名称、重定向与应用配置在两侧必须一致。权威记录改变后立刻移除旧端点，会给仍持有先前应答的客户端造成本可避免的停机。

否定应答也会被缓存。一个最近返回 NXDOMAIN 的名字，其出现可能很慢才可见，因为根据区域的权威数据，否定响应可能仍留在递归缓存里。

观察后恢复 TTL

一旦权威与具有代表性的递归应答都指向新端点，且旧缓存窗口已过，就恢复正常 TTL。在变更记录中保留旧值、新值、权威应答与回滚条件。

来源

RFC 1034 — Domain Names: Concepts and Facilities，缓存模型，已核验 2026-08-22。
RFC 1035 — Domain Names: Implementation and Specification，TTL 字段，已核验 2026-08-22。
RFC 2308 — Negative Caching of DNS Queries，否定缓存模型与保留的错误 TTL，已核验 2026-08-22。

重启策略需要一个速率限制

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

对长驻服务来说，自动重启很有用，但无界的循环会把一个清晰的失败变成一个嘈杂的失败。单元文件应同时描述正常进程生命周期与可接受的恢复量。

捕获启动失败

对长驻进程，Type=exec 能在启动时暴露配置程序执行失败，而不是把一次 fork 当成功。把它与显式的 ExecStart 以及能完成工作所需最小权限的 User 搭配使用。

[Service]
Type=exec
User=site
ExecStart=/srv/site/bin/server
Restart=on-failure
RestartSec=5s

Restart=on-failure 是一种恢复策略，不是健康检查。如果进程在提供错误响应的同时保持存活，systemd 不会知道站点坏了；外部冒烟测试仍有其职责。

限制循环

Systemd 通过 StartLimitIntervalSec= 与 StartLimitBurst= 应用启动速率限制。选择允许短暂瞬时停机、但不会让崩溃循环耗尽主机资源的值。当达到限制时，日志里应包含区分"重启成功"与"重复失败后放弃"所需的证据。

修改单元后，核验已加载配置并检查最近日志：

systemctl daemon-reload
systemctl restart example.service
systemctl status --no-pager example.service
journalctl -u example.service -n 80 --no-pager

不要用重启策略掩盖缺失文件、无效权限或糟糕的环境。先修复第一次失败，再测试恢复路径。

来源

systemd.service，服务类型、重启与启动速率限制器，已核验 2026-08-22。
systemd.unit，通用单元段与 drop-in 语义，已核验 2026-08-22。

维护定时器应让其最近结果可见

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

cron 式语法并不是维护任务契约的全部。命令需要一个清晰的服务身份、一个有界的运行时间，以及能区分"未调度"与"运行但失败"的证据。一个 systemd 定时器与 oneshot 服务能把这些关注点分开。

把工作定义成服务

使用显式用户与绝对命令路径：

# /etc/systemd/system/site-check.service
[Unit]
Description=Read-only public site check

[Service]
Type=oneshot
User=sitecheck
ExecStart=/usr/local/bin/check-public-site
TimeoutStartSec=2min

TimeoutStartSec 防止网络或子进程等待无限占用调度。当契约失败时，helper 应返回非零退出码，并且不得修改它所检查的服务。

调度该服务

# /etc/systemd/system/site-check.timer
[Unit]
Description=每小时运行公共站点检查

[Timer]
OnCalendar=hourly
Persistent=true
RandomizedDelaySec=5min
Unit=site-check.service

[Install]
WantedBy=timers.target

Persistent=true 会在机器恢复后补跑错过的日历事件。RandomizedDelaySec 把一个窗口内的例行工作分散开；当任务必须在精确时刻运行时它并不合适。

启用前先验证

检视日历表达式，然后手动启动服务：

systemd-analyze calendar hourly
systemctl start site-check.service
systemctl status site-check.service
journalctl -u site-check.service -n 50 --no-pager

只有当服务在预期的用户、环境、路径与网络访问下成功时才启用定时器：

systemctl enable --now site-check.timer
systemctl list-timers site-check.timer

对服务结果告警

定时器触发并不等于成功。要监控 oneshot 服务的退出状态或日志结果。保持 stdout 简洁，调试需要的详细制品写入一个有界的路径。

来源

systemd.timer(5)，日历定时器、持久化与延迟行为，已核验 2026-08-23。
systemd.time(7)，日历表达式语法，已核验 2026-08-23。
systemd.service，oneshot 服务语义，已核验 2026-08-23。

备份只有在演练过恢复之后才有用

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

“我们有备份"还不是一种恢复能力。一份有用的备份有已知范围、已知新鲜度、一个验证步骤，以及一份确有人实际跑过恢复流程。

定义恢复单元

对静态站点，源码仓库与生成制品用途不同。仓库是权威输入；制品是恢复最近发布版本的最快方式。请把两者的区别说清楚。

至少记录：

源码提交或归档标识；
生成器与主题版本；
制品包含的文件列表；
重要下载的校验和；
保留期限与存储位置。

不要把凭据、私钥、Cookie 或访问令牌放进网站备份。它们应属于独立的机密管理流程。

存储前先验证

打不开的归档不是备份。一个最小的验证循环如下：

tar -czf site-2026-08-22.tar.gz public/
tar -tzf site-2026-08-22.tar.gz >/dev/null
sha256sum site-2026-08-22.tar.gz > site-2026-08-22.tar.gz.sha256

校验和验证的是被存储的这个文件，并不能证明所有应用层面的假设都正确。这正是为什么仍需要一次恢复演练。

在某个可丢弃的地方恢复

把归档解包到临时目录或隔离主机，然后检查入口点与一个有代表性的资源。不要用覆盖唯一活动副本的方式测试恢复。

restore_dir=$(mktemp -d)
tar -xzf site-2026-08-22.tar.gz -C "$restore_dir"
test -s "$restore_dir/public/index.html"
test -s "$restore_dir/public/404.html"

这条命令刻意很平凡。演练应在事故到来之前，暴露出缺失文件、错误权限或未记录的依赖。

诚实地度量新鲜度

备份日程只有在相对可能丢失的工作量时才有意义。如果源码一个月才变一次，每日快照可能不必要；如果某个资源每小时更新，一次月度归档又不够。

写下目标恢复点与恢复时间，再选择能满足这些目标的存储与检查。当最后一次经过验证的恢复备份已经陈旧时，不要宣称"连续保护”。

来源

GNU tar manual，归档创建与验证行为，已核验 2026-08-22。
静态网站发布检查清单，本地配套资源。

可靠的默认行为胜过聪明的恢复

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

小服务往往在正常路径被充分理解之前，就先累积了恢复逻辑。每一次重试、备用端点与兼容分支，都增加了必须被观察和测试的一个状态。

让常见路径变得无聊

一个有用的默认行为是明确的、易于检视的、且可安全重复的。对静态站点，可以简单到：

构建自固定的工具链。
发布一个完整目录。
检查生成的 HTML 与资源。
保留上一个目录以便回滚。

这段序列不如多阶段部署系统炫目，但它的状态可见。当某处失败时，运维者能回答：问题在源码、构建、复制还是 Web 服务器。

只对可限定范围的操作重试

当操作已知是瞬时的、且重复不会产生第二个副作用时，重试才有用。从源站下载可能可安全重试；数据库迁移则未必。把每个错误都看作可重试的，会掩盖需要关注的边界。

当重试适当时，记录尝试次数与最终原因。类似"发布失败：校验和不匹配"的日志条目，比一串静默重试后跟一个笼统超时更有可操作性。

偏好单一权威状态

配置、运行时状态与文档应一致地说明哪个目录是活动的、哪条命令产生它。如果一个发布可以被不同的人复制到三条不同路径，恢复就变成了猜谜。

对静态部署，一份简短的发布记录就够了：

release: 2026-08-22
source: git commit <commit-id>
builder: Hugo 0.165.0
output: public/
verification: links + headers + checksums

占位符 commit ID 应按设计在发布时解析，而不是在文档里杜撰。

恢复应回到已知状态

当恢复把服务带回最后一个已知良好目录，而不是在几个半成品替代品之间选择时，恢复最容易。保留上一次输出直到新输出通过检查，再按保留策略移除旧副本。

目标不是消除失败，而是把失败缩小到能解释、把恢复缩小到能信任。

来源

RFC 9110 — HTTP Semantics，9.2.2 节关于幂等方法与重试，已核验 2026-08-22。
静态网站发布检查清单，本地配套资源。

事故复盘应留下一份事实记录

Mon, 24 Aug 2026 00:00:00 +0000

一份复盘在它的说法能被重新检查时才赢得信任。这意味着每个阶段都要点名产生该事实的命令，而不是某人记忆的转述。下面的四个阶段让任何写下来的复盘在日后都可复核。

检测：症状，而且要带证据

从最小的可验证症状与展示它的命令开始。“截图"好过一段散文描述：

$ check-http-headers.sh https://www.xbcatm.com/
HTTP/2 200
content-security-policy: ... script-src 'none' ...
last-modified: Mon, 24 Aug 2026 11:20:54 GMT

如果症状是某个响应头变了，那么展示旧策略与新策略的输出应并排放在一起。如果是失败，请包含退出状态与错误行。

界定范围：影响多广，以及你如何知道

用证据而不是形容词陈述爆炸半径。修复一个你能检视的边界：

哪些主机或路径返回同样的症状？每个候选主机跑一次 check-http-headers.sh 就能回答。
缓存与源站是否不同？比较 Vary 与验证器。
适用哪个回滚窗口？使用变更前仍生效的 TTL。

修复：变更及其预期效果

写出可重放的正确动作。优先选择恢复契约的最小变更，并说明修复后运行应显示什么：

# 期望出现在响应里的新策略行：
script-src 'none'

验证：事后运行

变更后重复检测命令，并演示观察到的输出现在与预期契约一致。没有最后这一节的复盘只是一个故事；有了它，它就是一份允许自己未来被再检查的记录。

来源

RFC 9110 — HTTP Semantics，响应元数据与条件请求，已核验 2026-08-24。
制品 HTTP 响应头检查，贯穿本记录使用的只读检查。