教程 · XB 现场笔记

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

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

一次发布，只有当公共边缘与你选择的文件一致时才完成——而不是当最后一条上传命令退出码为零。本教程把这个句子变成可重复的过程，使用 release-and-recovery 系列笔记描述的检查。到最后阶段之前，一切都安全地在本地进行；唯一的远端步骤是结尾的只读探针。

工作流有四个阶段，每个阶段产生下一阶段消费的证据：构建、校验、发布、验证。

开始前先让三个事实变得明确，让失败变得廉价：如何运行构建（make build）、活动站点服务的是哪个单一目录、如何把那个目录重命名回上一个树。先把这三个答案写下来，就能把整个过程从一次豪赌变成带可见回滚的脚本。其余教程假设你能回答它们。

1. 构建单一可复现的产物

从干净的控制树开始，而不是服务器上目前的东西。small-systems 笔记主张你能命名的边界；静态构建只需要少数几个。运行项目目标：

$ make build
…
 Pages │ 130 │ 128
 Static files │ 42 │ 42
 Total in 171 ms

构建会把指纹写入 data/buildinfo.toml——源提交与构建时间——首页会渲染它。把指纹留在产物内，让后来的读者能证明哪棵源树产生了这些字节，审计时不必猜测。

2. 针对离线产物契约做验证

在触碰线上主机之前，先运行不需要网络的检查。这些检查在产物内部确认一致性：

$ make check
validated 257 HTML documents; internal targets and script-free contract are intact

验证器验证每一张生成的 SVG、遍历每一个内部链接与片段、强制无 JS 契约，并校验下载项校验和。它在坏产物上失败，而不是在慢网络上失败——这正是 reliable-defaults 所说的把主路径变得无聊。

3. 为每个字节命名清单

发布声明必须能说出具体哪些字节变了，并能证明线上服务的就是它们。把产物哈希成排序清单：

$ cd public && find . -type f | sort | sed 's#^./##' | xargs sha256sum > /tmp/release.sha256
$ grep robots.txt /tmp/release.sha256
robots.txt f6ad425cbc898cef00d4b62bef6b17dc627de9ee0c910b31dcc1ee4d054f3d24

release-manifest 笔记为每个已发布字节命名，使"边缘一致"的声明可以逐字节核对。在整个发布窗口内保留此清单；替换后要和线上那棵树一比。

4. 通过交换完整目录来发布

不要逐文件覆盖线上树。先在现有树旁边暂存完整树，然后交换 Caddy 服务的那个单一目录名——atomic-switch 笔记称之为完整目录发布：

$ rsync -a public/ /srv/www/example-site.new/
$ mv /srv/www/example-site.new /srv/www/example-site

因为服务根是一个目录名，交换是瞬时的，绝不会出现写到一半。旧树还在，因此回滚就是朝反方向的一个 rename（reliable-defaults）。

5. 确认公共边缘与你暂存的一致

在信任替换之前，先证明线上状态与头部与产物匹配。read-only-release-smoke-tests 与 read-public-edge 两篇笔记都把这一步作为最后的关卡——运行这个 helper 并读它的输出：

$ ./downloads/check-http-headers.sh https://www.xbcatm.com/
HTTP/2 200
content-type: text/html; charset=utf-8
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:

带正确 CSP 与内容类型的 200 是第一个一致。第二个一致是字节：把线上树哈希，与第 3 步的清单比较。匹配时，边缘就是你暂存的树。如果线上内容不同，停下——你看的是错的树。

6. 结束前确认证书窗口

发布还没有完成直到证书也健康。check-tls-expiry 在不破坏 TLS 会话的情况下读取有效期窗口：

$ ./downloads/check-tls-expiry.sh www.xbcatm.com 30
subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

certificate remains valid for at least 30 day(s)

临近过期的证书会把"成功"发布变成迫在眉睫的事件。certificate-expiry 笔记与发布清单都把 TLS 窗口当作发布条件的一部分，而不是后来的意外。把 notAfter 读成具体日期，而不是仪表盘颜色。

7. 记住 DNS 缓存窗口

如果你的发布改了 DNS 记录（主机变更、CAA 更新或新的边缘），记住传播遵循一个不由你掌握的进度表。dns-change-window 说明为什么回滚必须包含缓存感知的窗口，而不只是那条记录。一个在本地看起来完整的发布，在远端解析器上可能仍处于传播中途，长达旧 TTL 那么久。

8. 备份一条可恢复的路径，而不只是字节

发布是恢复的另一面。发布前，确认存在只做一次恢复演练的记录——backup-rehearsal 强调备份只有在从它恢复过一次之后才有用。本教程假设"恢复"那个周期步骤已经能工作，因为恢复是让发布可逆而非有风险的那一半。

9. 记录后来者可以审计的结果

当替换完成、窗口检查完毕，留下后续操作者能信赖的事实：commit、清单哈希、两个探针输出。postmortem 条目在指名事实——哪些字节、哪个状态、哪些日期——时，比断言"它工作过"更有用。把同样的结果写进 changelog，让站点自身的演进保持可审计。

路径对应到系列

阶段	证据	笔记
构建	buildinfo 指纹	small-systems, atomic-switch
校验	offline verify 通过	reliable-defaults, release-checklist
清单	每个文件 SHA-256	release-manifest
发布	完整目录交换	atomic-switch, caddy-static-files
验证	HEAD 一致 + 清单哈希	read-only-smoke-tests, public-edge
证书	有效期日期	certificate-expiry
记录	commit + 探针输出	postmortem, changelog

每个阶段消费前一阶段的证据。任一段失败你都要停下，旧树仍是线上服务的那棵——这正是让整个过程可以安全练习的性质。

来源

GNU Coreutils: sha2 utilities，文件级校验与清单，已核验 2026-08-11。
POSIX rename()，完整目录发布，已核验 2026-08-11。
Caddy file_server，根选择与交换，已核验 2026-08-11。
OpenSSL s_client，证书日期，已核验 2026-08-11。

像客户端一样读取活动边缘

Fri, 07 Aug 2026 00:00:00 +0000

HTTP 基础篇的每条笔记各取一纸契约并展示单独的证据。本教程则按顺序走完一次客户端请求触达的完整路径，只用只读命令。到结束时，你已经在任何活动静态边缘上复现了那些笔记描述的检查——不改变它的状态。

我们全程用 www.xbcatm.com。把它换成你要检查的主机。下面每条命令都是只读的：读头部、请求元数据，或要求特定字节范围；没有任何一条会写入源站。

1. 先确定方法可以问什么

在读响应体之前，先确定服务器允许你问什么。静态源站没有事务，所以大多数会改变状态的方法都必须被显式拒绝。问边缘它允许什么：

$ curl -s -o /dev/null -w 'OPTIONS -> HTTP %{http_code}\n' -X OPTIONS https://www.xbcatm.com/
OPTIONS -> HTTP 405

405 Method Not Allowed 是诚实的答案。http-method-semantics 笔记解释了为什么这是静态源站应保持的契约：每个方法要么按文档化语义被支持，要么用表明拒绝的状态码回答。危险的失败模式是代理或导入的 handler 把被拒绝的方法转成静默的 200。如果你的边缘对 POST 也回 200，承诺就不再可见。

2. 读取表示行

第一行告诉你协商出来的交换；头部随后告诉你将要到达的是什么字节。像客户端看到的那样捕获它们、丢弃响应体：

$ curl -s -D - -o /dev/null https://www.xbcatm.com/
HTTP/2 200
accept-ranges: bytes
content-length: 15890
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
content-type: text/html; charset=utf-8
etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff

三个头部值得停下来。content-type: text/html; charset=utf-8 命中了媒体类型，content-type-and-nosniff 说明为什么它必须描述你真正发送的字节。etag: "dkx84jwth7nkc9e" 交给你强验证器。x-content-type-options: nosniff 要求浏览器不要猜测类型。每一个都是证据而不是装饰，合在一起是说：这个边缘在你信任正文之前，就精确告诉你它的策略。

3. 确认 HEAD 等于 GET 但不带正文

HEAD 必须安全，并返回与 GET 相同的元数据，但不带正文。比较 HEAD 的 Content-Length（GET 会返回的字节数）与你真正 READ 到的字节：

$ curl -sI https://www.xbcatm.com/ | grep -i content-length
content-length: 15890
$ curl -s https://www.xbcatm.com/ | wc -c
15890

两者一致：都是 15890。这就是 head-request-parity 契约。若代理在 HEAD 上去掉或改写 Content-Length，这样一对检查就能抓住它。这正是 check-http-headers.sh 用 curl 一起读状态与头部、发布冒烟测试在替换前后比较 HEAD 的原因。

4. 用范围请求精确的字节

因为源站知道自己的表示，它可以只服务其中一部分。范围请求要求一个字节区间，只得到那个区间：

$ curl -s -o /dev/null -H 'Range: bytes=0-99' -w 'HTTP %{http_code} bytes=%{size_download}\n' https://www.xbcatm.com/
HTTP 206 bytes=100

对 100 字节区间给出 206 与 100 字节是诚实的结果。http-range-requests 笔记说明服务器如何选择字节、以及为什么需要强验证器。若服务器对任何范围区间都回 200 全量正文，那是另一种更昂贵的契约，也说明源站并不追踪你要的字节身份。

5. 用验证器让缓存重新验证

现在把方法、表示与字节选择通过缓存结合。存储副本只有在验证器仍然匹配时才是最新。把 ETag 条件式重放：

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'If-None-Match: "dkx84jwth7nkc9e"' https://www.xbcatm.com/
HTTP 304

304 Not Modified 只带极小的头部回复，告诉你所问的副本仍然是答案。这就是 conditional-requests 契约：验证决定存储副本是否新鲜；http-cache-headers 描述两个时钟——来自缓存头部的新鲜度，与来自验证器的正确性。304 从不是错误，它是"你已有正确的字节"的廉价说法。当 ETag 变化，下一次重新验证会返回新的 200。

6. 协商更小的表示

同样的内容在客户端表明能解压时可以传递更少字节。请求 gzip 并观察正文缩水而语义不变：

$ curl -s -o /dev/null -w 'no-enc: %{size_download} bytes\n' https://www.xbcatm.com/
$ curl -s -o /dev/null -H 'Accept-Encoding: gzip' -w 'gzip: %{size_download} bytes\n' https://www.xbcatm.com/
no-enc: 15890 bytes
gzip: 4368 bytes

普通 GET 返回 15890 字节；gzip 协商对同一内容返回 4368。这是 http-compression-negotiation 笔记的核心：改变选中的表示会改变线上字节，元数据（content-length、encoding）也随之改变。请求压缩的客户端与存储编码形式的缓存必须就选了哪种表示达成一致，否则缓存会交付不匹配的结果。

7. 跟随 URL 变化时的故事

身份变化时，响应应说明故事在哪里继续，而不去猜正文：

$ curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' -I http://www.xbcatm.com/ | head -1
308 -> https://www.xbcatm.com/

308 Permanent Redirect 保持方法与故事，正是 redirects-and-status-codes 关心的。无论是永久移动的 301/308，还是由站点处理的 404，状态行都是故事的第一句，应在读正文前先读。

8. 最后让爬虫读地图

边缘也会被根本不请求 HTML 的机器读取。发现机制回答两个不同的问题，robots-and-sitemaps 有说明。确认发现机制指向真实 sitemap：

$ curl -s https://www.xbcatm.com/robots.txt
User-agent: *
Disallow:
Sitemap: https://www.xbcatm.com/sitemap.xml

一个在 robots、sitemap 与 HTTP 头部上都回答同一主机的主机，其操作者在发布前读过公共边缘。

所有检查一览

检查	证明什么	笔记
`OPTIONS` -> 405	源站拒绝不支持的方法	http-method-semantics
`content-type` + `nosniff`	头部描述真实字节	content-type-and-nosniff
HEAD == GET Content-Length	安全、HEAD 一致	head-parity
Range 0-99 -> 206/100	精确字节选择	http-range-requests
`ETag` -> 304	验证器决定新鲜度	conditional-requests
308 保留方法	重定向保留故事	redirects-and-status-codes
robots -> sitemap	发现答案不同	robots-and-sitemaps

每一行原来是一条笔记；现在是你可对任意边缘运行的命令。需要细节时读链接的笔记，把这个表留作再次检查时的速查。

来源

RFC 9110 — HTTP Semantics，方法、验证器与状态码，已核验 2026-08-07。
RFC 9111 — HTTP Caching，新鲜度与重新验证，已核验 2026-08-07。
RFC 7538 — 308 Permanent Redirect，保留方法的重定向，已核验 2026-08-07。
curl 手册，只读检查选项，已核验 2026-08-07。

审计公共边缘的信任

Thu, 06 Aug 2026 00:00:00 +0000

web-security 系列把安全设置当作带作用域与失败模式的契约。本教程以只读方式、端到端地对一个线上主机跑这些契约，并告诉你每个答案的含义。它不改变服务器，只检查服务器愿意对任何人说的话。下面全程用 www.xbcatm.com，请换成你自己的主机。

1. 从边缘宣告的头部开始

第一个契约是浏览器被告知允许什么。用 check-http-headers.sh（或任何只读抓取）取头部，读实际策略：

$ curl -s -D - -o /dev/null https://www.xbcatm.com/
HTTP/2 200
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY

每个头部都是对特定失败模式的声明。对静态站而言带 script-src 'none' 的 content-security-policy 是最强的，security-headers 说明为什么策略应匹配实际页面。带 includeSubDomains 的 strict-transport-security 是传输承诺，hsts-rollout 警告它必须分步推进，因为它具有粘性。nosniff 阻止 MIME 类型猜测。你以为讲的是真的却没有验证过的头部，是 bug 不是特性。

第一步是静态的，但它是浏览器最先看到的契约。对静态站，script-src 'none' 既安全又诚实：没有可执行的，就什么都不运行。重要的习惯是把你相信的策略与边缘实际发送的对比。代理增加或去除某个头部就是静默改变契约；只读 fetch 能抓住这种漂移。若你用 check-http-headers.sh，它把状态与头部一起读，让策略与可达性声明留在同一条记录里。

2. 确认身份是真的，而非猜测

TLS 身份始于叶证书。读它确切的主体、签发者与有效期：

$ echo | openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com 2>/dev/null \
 | openssl x509 -noout -subject -issuer -dates
subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

主体是确切主机名而不是相邻站点的通配符，notAfter 是具体日期。certificate-expiry 把那个日期当作发布关卡而不是仪表盘颜色。操作者应能凭上次审计的记忆报出 notAfter，而不是在续期时才发觉。

3. 读链，而不只是叶

叶只有处在客户端能走到受信根的链中才有价值。问边缘实际呈现哪条链：

$ echo | openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com -showcerts 2>/dev/null | grep 'BEGIN CERT' | wc -l
4

带其叶与中间证书时，这个数应为 4。certificate-chain 笔记解释原因：叶必须由你实际授权的中间签发，边缘必须发送那个中间，深度验证的客户端才会成功。对公共 CA 而言，恰好为 1 是危险信号。

第二个要检查链的原因：第 2 步读到的身份只证明叶，不证明客户端能到达它信任的根。链是补上那个缺口的环节。如果边缘某天开始发送不同的中间证书——比如某天一个测试 CA——issuer 与数量会在页面上任何元素变化之前改变。读链是发现信任发生迁移的最廉价方式。

4. 用一个验证器证明新鲜度完好

conditional-requests 笔记在这里同样适用：活动边缘应对重新验证回 304，这样缓存与客户端不必重新下载。这也是缓存按头部承诺工作起来的证据：

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'If-None-Match: "dkx84jwth7nkc9e"' https://www.xbcatm.com/
HTTP 304

因为本站坚持无脚本策略，CSP 在发布之间从不变化；只有字节变化时 etag 才动。

5. 检查哪个 CA 被允许签发

TLS 身份与 DNS 策略携手。确认 CAA 记录授权你实际使用的签发者，这样只有那个 CA 能合法为域名签名：

$ dig +short CAA www.xbcatm.com

dns-caa-records 把 CAA 当作信任的供应商：它授权签发者，使证书链审计变得有意义。若无 CAA，任何 CA 都能签发；有 CAA，第 3 步的中间应该能追溯到被授权的签发者。若 dig 返回空，意味着没有任何 CA 被限制——这本身是审计结论。

6. 检查谁持有主机密钥

链保护 TLS，但另一条信任边界是 SSH 访问。主机密钥是你 SSH 进去的那台服务器的部署记录。ssh-host-key 把主机密钥当作你信任连接前就固定的记录：

$ ssh-keygen -lf ~/.ssh/known_hosts | grep www.xbcatm.com

确认指纹与你当初记录主机时的一致。重建后主机密钥变化，可能是合法的重装，也可能是该停下的理由——这正是主机密钥策略作为 web-security 边界存在的原因，而不只是便利。

即使无脚本静态站也可能设置 cookie；若它设置了，其作用域就是一种安全声明。cookie-scope 说 cookie 的主机、路径、传输与同站边界应比应用触达更窄。审计不要让 cookie 以超出必要的范围设置，对敏感内容优先 Secure; HttpOnly; SameSite。

把审计当清单

信号	读作	笔记
CSP `script-src 'none'`	无脚本策略在线	security-headers
HSTS `includeSubDomains`	传输承诺是粘性的	hsts-rollout
证书 subject+到期	身份是具体日期	certificate-expiry
链显示 `4` 张证书	中间证书被发送	certificate-chain
重新验证回 `304`	缓存验证器工作	conditional
CAA 被授权	只有 CA 能签发	dns-caa
主机密钥指纹一致	SSH 信任是一条记录	ssh-host-key

每个信号原来是一条笔记；合起来它们是一份清单。在不到一分钟里用两三条只读命令就能全部加完，服务器分毫未动。

常规建议

这个审计应属于定时检查，而不只在发布时。若你已有的一套检查，把这两条 openssl 行与头部抓取加进去。把输出按日期开头的文件名保留，让后来的比较能显示漂移。这样即使什么都没变，静态站点也能保持证据优先。

来源

RFC 9110 — HTTP Semantics，验证器与条件请求，已核验 2026-08-06。
RFC 6797 — HSTS，传输策略，已核验 2026-08-06。
RFC 5280 — X.509 PKI，证书链，已核验 2026-08-06。
OpenSSL s_client，链与身份检查，已核验 2026-08-06。
dig(1)，DNS 记录查找，已核验 2026-08-06。