笔记 · XB 现场笔记

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

Tue, 04 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 限制 oneshot 的激活过程，其中包括命令运行时间；oneshot 默认没有启动超时。超时处理之后还可能需要停止超时，且不能立即结束不可中断的内核 I/O，因此工具本身也需要有界的网络请求。当契约失败时，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 verify /etc/systemd/system/site-check.service \
 /etc/systemd/system/site-check.timer
systemd-analyze calendar hourly
systemctl daemon-reload
systemctl start site-check.service
systemctl status site-check.service
journalctl -u site-check.service -n 50 --no-pager
systemctl show site-check.service -p Result -p ExecMainCode -p ExecMainStatus

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

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

对服务结果告警

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

成功的 oneshot 通常回到 inactive (dead)；这本身不是失败，systemctl status 对非活动服务可能返回非零。应将 Result、退出状态与新的日志时间戳对应，避免把旧运行的成功误认成本次结果。不要为了显示绿色而添加 RemainAfterExit=yes：服务仍处于活动状态时，重复定时器不会启动一个新实例。日历时间默认使用主机时区，而且常规定时器精度会在随机延迟之外增加调度余量。

来源

systemd.timer(5)，日历定时器、持久化与延迟行为，已核验 2026-08-04。
systemd.time(7)，日历表达式语法，已核验 2026-08-04。
systemd.service，oneshot 服务语义，已核验 2026-08-04。
systemd.service upstream manual (v257)，Type=exec/oneshot、就绪、激活超时与重启语义，已核验 2026-10-15。
systemd.timer upstream manual (v257)，持久化会合并错过的运行；活动单元、随机延迟与精度，已核验 2026-10-15。

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

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

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

按配置窗口统计启动次数。启动速率限制可以停止快速反复重启，但不能证明健康，也不限制生命周期重试总数。

捕获启动失败

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

[Unit]
Description=Example foreground site service
StartLimitIntervalSec=60s
StartLimitBurst=5

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

Type=exec 确认程序已执行，并不确认应用已就绪。程序应保持前台运行；应用支持显式就绪通知时可用 Type=notify。Restart=on-failure 是恢复策略，不是健康检查。如果进程在提供错误响应的同时保持存活，systemd 不会知道站点坏了；外部冒烟测试仍有其职责。

限制循环

Systemd 通过 StartLimitIntervalSec= 与 StartLimitBurst= 应用启动速率限制。这两个指令放在 [Unit]，RestartSec 放在 [Service]。示例允许 60 秒内启动五次；快速失败之间只有五秒重启延迟，因此可能达到限制。更长延迟可能让循环一直低于该速率：这并不是整个生命周期的重试次数预算。应按预期故障模式选择限制。当达到限制时，日志里应包含区分"重启成功"与"重复失败后放弃"所需的证据。

在获准使用的测试主机上安装或修改单元后，先验证文件、重载管理器并检查有效配置，再重启。下列命令会改变服务状态，可能中断流量：

systemd-analyze verify /etc/systemd/system/example.service
systemctl daemon-reload
systemctl cat example.service
systemctl show example.service -p Restart -p RestartUSec \
 -p StartLimitIntervalUSec -p StartLimitBurst
systemctl restart example.service
systemctl status --no-pager example.service
journalctl -u example.service -n 80 --no-pager

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

启动限制停止自动重启后，单纯等到间隔结束不会自动排定下一次尝试。修复原因后，可等待间隔结束再启动，或有意识地用 systemctl reset-failed example.service 清除计数器后启动。在隔离服务中测试可执行文件缺失与快速崩溃，并保存第一次失败日志，不要只留下最后的“达到启动限制”消息。

来源

systemd.service，服务类型、重启与启动速率限制器，已核验 2026-08-03。
systemd.unit，通用单元段与 drop-in 语义，已核验 2026-08-03。
systemd.service upstream manual (v257)，Type=exec/oneshot、就绪、激活超时与重启语义，已核验 2026-10-15。
systemd.unit upstream manual (v257)，启动限制所属配置段、速率窗口与 reset-failed 行为，已核验 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。

SSH 主机密钥是部署记录的一部分

Tue, 28 Jul 2026 00:00:00 +0000

在公钥认证中，客户端证明自己持有私钥，但它并不告诉客户端到达的是哪台服务器。服务器的主机密钥与本地 known_hosts 数据库，提供身份检查的后一半。

SSH 服务器身份依赖观察到的主机密钥与独立可信参考之间的比较。严格检查拒绝未知或变化的密钥。首次使用时信任与网络密钥扫描，都不能独立认证首次接触的服务器。

把首次接触与轮换分开

在 StrictHostKeyChecking=yes 下，SSH 拒绝未知主机与变化的密钥。对于一个固定生产端点，只要期望密钥通过可信渠道安装，这就是最安全的默认值。accept-new 是面向预期会出现新主机的、更窄的方便选项：它接受一个从未见过的密钥，但仍拒绝被更改的密钥。

Host production-site
HostName www.example.test
User deploy
IdentityFile ~/.ssh/site_ed25519
StrictHostKeyChecking yes
UserKnownHostsFile ~/.ssh/known_hosts

不要通过给部署脚本加 StrictHostKeyChecking=no 来"修复"警告。它会在客户端限制条件下允许连接到密钥已变化的主机；警告可能仍被打印，但原本遇到身份问题就拒绝的检查已被削弱。如果主机被重建，请记录替换后的指纹，并复核旧密钥为何不再有效。

让指纹可复核

在首次连接之前，从主机所有者或控制台获取指纹，再与客户端看到的值比较。密钥变更应有工单、维护说明或其他他人可检视的解释。

同一规则适用于自动化：known-hosts 文件是带有安全后果的配置，不是可丢弃的缓存数据。把它与部署记录一起备份，但不要把私钥或复制的凭据随站点制品一起公开。

accept-new 是首次使用时信任，并不能独立证明第一次连接的服务器真实可信。ssh-keyscan 能采集候选公钥，但通过同一条不可信网络取回它，并不能认证它。安装前先将指纹与独立可信渠道取得的值比较。

把上面的配置单独保存为 deploy.conf，在不连接服务器的情况下检查有效配置：

ssh -G -F ./deploy.conf production-site | \
 grep -E '^(hostname|user|stricthostkeychecking|userknownhostsfile) '

结果应显示配置中的主机、用户、known-hosts 路径与严格检查（客户端输出可能为 true 或 yes）。这只解析配置，并不测试真实握手。非标准端口的 known-hosts 条目通常采用 [hostname]:port。将主机公钥指纹保存在私有运维发布记录中，不要随公共网站发布；即使主机公钥不是秘密，主机名也可能暴露内部拓扑。

来源

OpenBSD ssh_config，StrictHostKeyChecking 与 UserKnownHostsFile，已核验 2026-07-28。
OpenSSH ssh-keygen 手册，指纹检视，已核验 2026-07-28。
OpenSSH ssh-keyscan，未经核验采集的密钥不能防止中间人攻击，已核验 2026-10-15。
OpenSSH ssh，-G 不建立会话，打印求值后的客户端配置，已核验 2026-10-15。

小系统的优势

Mon, 27 Jul 2026 00:00:00 +0000

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

明确每个请求边界、相关证据与负责人。组件更少只会减少需要理解的路径；恢复承诺仍靠备份与恢复演练支撑。

可见性是一种特性

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

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

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

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

复杂性要用实力取得位置

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

对客户端 JavaScript 也适用同一规则。如果页面确实需要客户端脚本，应选择满足需求的最小实现，并有意识地审查内容安全策略。对本站而言，这首先需要重新评估已接受的零脚本架构及其验证契约，并不是当前策略的例外。如果页面是一份文档，纯 HTML 往往更容易检视、更有韧性。

让所有权明确

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

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

为下一次变更留出空间

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

规模小并不自动带来容错。一个边缘、磁盘或运维者仍可能成为单点故障。明确可接受的恢复时间与数据损失，保留独立备份并演练恢复。组件更少的好处是需要理解的故障路径更少，而不是不会停机。

来源

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

安全响应头应描述实际页面

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

安全响应头不是安全代码的替代品，但它们让浏览器强制实施有用的边界。策略应描述实际被服务的页面，而不是从另一个项目复制来的泛型模板。

把响应头视为部署契约：匹配实际资源，区分强制执行与仅报告策略，再验证准确主机范围和浏览器行为。

从资源图开始

如果站点只提供 HTML、本地样式表、一个 favicon、没有任何可执行 JavaScript，那么一条窄策略是可理解的：

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:

script-src 'none' 只有在站点不需要可执行脚本时才是正确的选择。加入搜索、评论或统计标签会改变资源图，并应触发一次有意识的策略复核。

增加传输与嵌套保护

对仅 HTTPS 的站点，下列响应头是常见起点：

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()

只有当每个子域名都准备好提供 HTTPS 时才启用带 includeSubDomains 的 HSTS。响应头是与未来部署的契约，而不只是扫描器里的一个分数。

检查行为，而不只是存在

请求一个正常页面、一个缺失页面与一个静态资源。错误响应应携带与成功响应同样重要的安全响应头。还要确认压缩与缓存不会改变内容类型，也不会暴露内部路径。

本站的Caddy 示例只是一个起点，不是普适策略。请根据你自己的部署调整主机名、证书处理与应用路由。

通过响应头发送 CSP。meta 策略中的 frame-ancestors 会被忽略，而且它不会继承 default-src；form-action 也需要自己的指令。style-src 'self' 本身不允许内联样式，因此应测试生成的主题，包括深色模式。只有页面确实需要 data 图片时，才在 img-src 中保留 data:。

Content-Security-Policy-Report-Only 可在上线过程中揭示违规，但不会强制执行策略；报告端点还需单独配置。除了查看响应头，也要在真实浏览器中验证执行效果。HSTS 从有效 HTTPS 响应中学习；带有 includeSubDomains 时，它还覆盖设置策略的主机的后代：www.example.test 的策略不覆盖父域 example.test 或同级 api.example.test。确认这个准确范围后，再逐步延长有效期。

来源

MDN: Content Security Policy guide，CSP 指令名称与语法，已核验 2026-07-23。
MDN: Strict-Transport-Security，HSTS 指令与部署注意事项，已核验 2026-07-23。
Caddy header 指令，响应头操作指令，已核验 2026-07-23。
W3C Content Security Policy Level 3，响应头交付、指令回退、嵌套与仅报告策略；当前为工作草案，已核验 2026-10-15。
RFC 6797 — HTTP Strict Transport Security，第 8.1–8.3 节的有效 HTTPS 交付与主机及后代匹配，已核验 2026-10-15。

robots.txt 与 sitemap 回答不同的问题

Tue, 21 Jul 2026 00:00:00 +0000

两个小文件常被当成安全边界使用，但它们不是。robots.txt 描述爬虫偏好，sitemap 则给搜索系统一份属于该站点的 URL 清单。

发现工具不会授予或拒绝访问。继续检查索引列出的每份 sitemap，验证不止 XML 语法，并按真实错误类别处理 robots 响应。

robots.txt 能做什么、不能做什么

规则发布于源站根路径 /robots.txt，由配合的爬虫读取。它不会保护私有目录、不会从网络上移除 URL，也不能替代认证。不应公开的路由需要服务器授权或网络边界。

让文件保持平实，并测试它的实际位置：

User-agent: *
Disallow:
Sitemap: https://www.example.test/sitemap.xml

文件应为 UTF-8。如果部署会重定向它，请核验你想要的爬虫行为，而不是假设每个客户端都遵循同一条链。

sitemap 增加了什么

sitemap 是一份清单，而不是权限列表。使用单一主机的绝对 URL、正确做 XML 转义，并且只列出你准备发布的规范页面。不要因为某个 URL 存在于构建目录就把它列出。

每份 sitemap 最多包含 50,000 个 URL，未压缩大小不超过 50 MB（52,428,800 字节）；gzip 不会提高该限制。小站可以不用 index，但多语言生成器也可以合理地生成指向各语言 sitemap 的索引。应检查根元素并继续检查列出的各份 sitemap，而不是假设 /sitemap.xml 一定是 URL 集合。把它的 XML 校验通过，并像普通页面一样通过同一 HTTPS 边缘请求它。

curl -fsS https://www.example.test/robots.txt
curl -fsS -o sitemap.xml https://www.example.test/sitemap.xml && \
 xmllint --noout sitemap.xml

把下载与解析分开，避免下载失败被解析成功掩盖。XML 格式正确只代表语法通过；还要验证命名空间、URL 数量、规范主机名，以及列出的页面是否存在。若未安装 xmllint，请在发布它的同一个 CI 环境里解析该 XML。重要的是检查要在文件被替换到边缘之前运行。

robots 的 Disallow 不是可靠的搜索索引删除指令。还要测试错误响应：RFC 9309 在 robots 返回 4xx、表示文件不可用时允许抓取，而网络或服务器错误在最初要求全部禁止。意外返回状态为 200 的 HTML 兜底页，因此可能改变爬虫行为，即使 URL 看起来仍然可访问。

来源

RFC 9309 — Robots Exclusion Protocol，robots 规则、文件位置与 user-agent 匹配，已核验 2026-07-21。
Sitemaps Protocol，sitemap XML 结构与发现，已核验 2026-07-21。

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

Mon, 20 Jul 2026 00:00:00 +0000

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

让常见路径可见。先判断并限制重试，再恢复到保留的已知良好状态，避免选择半成品副本。

让常见路径变得无聊

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

构建自固定的工具链。
检查生成的 HTML、资源与完整的待发布目录。
发布该目录，再把公共响应与它核对。
保留上一个目录以便回滚。

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

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

当故障可能是瞬时的、且重复操作不会改变其预期效果时，重试才有用。幂等不等于每次响应或附带日志都相同；响应丢失后，第一次尝试可能早已成功。从源站下载可能可安全重试；数据库迁移则未必。把每个错误都看作可重试的，会掩盖需要关注的边界。

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

偏好单一权威状态

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

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

release: 2026-07-20
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-07-20。
静态网站发布检查清单，本地配套资源。
AWS Builders’ Library: Timeouts, retries, and backoff with jitter，重试放大、有界重试预算、退避与随机抖动，已核验 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。

重定向与错误码应保留故事的完整性

Tue, 14 Jul 2026 00:00:00 +0000

HTTP 状态码是接口的一部分。浏览器可能渲染出一个友好的页面，但监控、爬虫、缓存与 API 客户端也需要状态码与响应头来讲述同一个故事。

有意选择迁移或缺失语义。保留所需方法，解析 Location，考虑缓存，并让错误页状态与事实一致。

永久移动并不都等价

308 Permanent Redirect 在保留请求方法的同时，传达资源有了新的永久 URI。这对发送 POST、PUT 或其他非 GET 方法的客户端很重要。旧页面到新页面的重定向用 GET 很容易测试；端点的迁移则必须用真实调用方实际使用的方法来测试。

curl -sS -D - -o /dev/null https://old.example.test/api/item

不带 --location 时，curl 不会跟随重定向。相对原 URI 解析 Location：绝对 URI、根相对路径或其他相对引用都可能有效。检查解析后的主机、路径与协议。301/302 允许将 POST 改为 GET；307/308 保留方法。改变状态的方法只能在隔离端点测试。308 可以启发式缓存，但仍受方法与缓存控制限制，因此缓存的迁移结果可能在服务器配置变化后继续存在。

如果目的是在完成操作后展示结果，303 See Other 会指向客户端可用 GET 或 HEAD 获取的另一资源。它不是要求客户端在新地址重放原来的写入操作；应有意选择这种行为，而不是把所有重定向都当作迁移。

区分"缺失"与"被移除"

当服务器找不到当前表示且缺失可能是暂时或未知时，使用 404 Not Found。410 Gone 更强：它表示资源已不可访问，且这种情况很可能是永久的；它并不能说明资源消失的原因。两者都应有帮助人类的正文，但都不应因为自定义错误页成功渲染就返回 200。

404 也可以用于隐藏某个禁止访问的资源是否存在。404 与 410 都可以启发式缓存，但仍受方法与缓存控制约束。应为错误响应明确选择缓存策略：路由修复后，已缓存的缺失结果仍可能继续显示。

这条检查应放在边缘：

curl -sS -D missing.headers -o missing.html -w '%{http_code} %{url_effective}\n' \
 https://www.example.test/a-route-that-does-not-exist

在错误路径上也应保留安全响应头。安全头、有用的内容类型与正确的状态码，比一个装饰性的错误动画更有价值。

来源

RFC 9110 — HTTP Semantics，第 15 与 13 节，已核验 2026-07-14。
RFC 7538 — 308 Permanent Redirect，第 3 节，已核验 2026-07-14。
curl manual，状态与重定向检查标志，已核验 2026-07-14。

用两条命令读取公共边缘

Mon, 13 Jul 2026 00:00:00 +0000

部署完成意味着公共响应符合发布契约，而不是最后一条上传命令退出码为零。操作套件里的两个只读工具能提供有用证据，但不能证明整个制品都已正确发布。

这些片段仅为示意。分别判断 HTTP 状态与到期结果；主机名、信任与正文一致性需要对应的独立检查。

检查响应头

check-http-headers.sh 发出 GET、丢弃正文、跟随重定向，打印每一跳的响应头以及最终状态和 URL：

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

以下输出只演示要检查的字段，并非刚刚采集的生产观察结果：

HTTP/2 200
accept-ranges: bytes
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
last-modified: Mon, 24 Aug 2026 11:20:54 GMT
permissions-policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), microphone=(), payment=(), usb=()
referrer-policy: strict-origin-when-cross-origin
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY

HTTP_STATUS 200
FINAL_URL https://www.xbcatm.com/

核对预期状态、最终主机与路径，以及最终响应上的策略。工具没有使用 curl 的 --fail：HTTP 404 或 500 仍可能使 shell 命令成功结束。必须判断它打印的状态。响应头不一致需要调查服务器、代理或缓存配置；单凭这种不一致，不能证明活动输出目录选错了。

检查证书日期

check-tls-expiry.sh HOST [DAYS] 提取使用 SNI 时服务器呈现的证书，并检查距离到期是否至少还有指定天数对应的秒数：

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)

工具打印主体、签发者、日期与 SHA-256 指纹，不打印剩余天数。成功消息只描述到期检查：脚本没有强制验证主机名或信任链，-checkend 也不验证 notBefore。主体 CN 不足以证明主机身份；服务身份应与证书的主体备用名称匹配。有效的通配符也可能合法覆盖该主机。

需要验证这些属性时，另行运行：

openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com \
 -verify_hostname www.xbcatm.com -verify_return_error </dev/null

这使用已配置的信任库，并在 OpenSSL 匹配规则下的证书验证出错时失败。在 OpenSSL 3.0 中，没有合适的 DNS 主题备用名称时，主机名验证可能回退到主题 CN。因此，命令成功本身不能证明符合 RFC 9525 仅使用 SAN 的身份策略：还要检查 SAN 扩展，并单独验证目标客户端的策略。TLS 工具本身没有网络截止时间，应在任务层设置超时。证书检查与自动续期配置仍是两项独立检查。

在发布前后使用两者

发布前：保存预期策略、最终 URL、验证器与证书日期，并注明 UTC 采集时间。
部署已经验证的制品。
发布后：重复探测，并下载代表性正文与该制品比较。

响应头与证书日期不能证明字节一致。Last-Modified 可能不变，也可能在复制中被重写。发布冒烟测试保存正文并直接比较；完整清单可将检查扩展到单个页面之外。浏览器行为、不同地区边缘的差异，以及只在负载下出现的故障，需要另行测试。记录实际检查过的路径与观察点。

来源

curl manual，GET、重定向、响应头输出与 HTTP 失败行为，已核验 2026-10-15。
OpenSSL s_client，SNI、显式主机名检查与验证错误时失败，已核验 2026-10-15。
OpenSSL verification options，主机名匹配与主题 CN 回退，已核验 2026-10-15。
OpenSSL x509，证书显示与只检查到期的 -checkend 行为，已核验 2026-10-15。
RFC 9525 — Service Identity in TLS，主体备用名称与通配符身份匹配，已核验 2026-10-15。
Caddy Automatic HTTPS，自动证书管理与续期配置，已核验 2026-10-15。
MDN: Content Security Policy guide，所示策略的背景说明，已核验 2026-07-13。
RFC 9110 — HTTP Semantics，响应元数据与验证器不能证明完整制品匹配，已核验 2026-10-15。

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

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

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

Tue, 07 Jul 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

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

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

用证据而不是形容词陈述影响范围。先界定能够检视的边界：

哪些主机与路径出现症状？记录每次探测的 URL 与观察时间；一次成功请求不能代表所有边缘或访问者的状态。
缓存与源站是否不同？使用相同请求头，比较两条路径的实际响应、缓存元数据与验证器。Vary 描述选择输入，不能证明响应来自缓存。
什么因素拖延恢复？DNS 变更需记录旧 TTL 与解析器观察结果；HTTP 缓存需另记新鲜度与重新验证策略。DNS TTL 不是通用的回滚期限。

修复：变更及其预期效果

记录实际配置差异与部署标识，让修复动作可理解，并在安全时可重放。下面的响应头片段是预期观察结果，不是 shell 命令，也不是完整策略。优先选择恢复契约的最小变更，并说明修复后运行应显示什么：

Content-Security-Policy: script-src 'none'

验证：事后运行

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

最后记录促成事故的因素、仍不确定的事项，以及带负责人、到期日和验收检查的预防动作。一次探测成功只确认该时刻的采样路径；它本身不能确定原因，也不能防止复发。

来源

RFC 9110 — HTTP Semantics，响应元数据与条件请求，已核验 2026-07-07。
制品 HTTP 响应头检查，贯穿本记录使用的只读检查。
Google SRE: Postmortem Culture，影响、促成因素、证据复核与预防动作，已核验 2026-10-15。
RFC 9111 — HTTP Caching，缓存选择与新鲜度不同于 DNS 缓存寿命，已核验 2026-10-15。

范围请求应证明选中了哪些字节

Mon, 06 Jul 2026 00:00:00 +0000

范围请求让客户端请求表示的一部分。媒体播放器、可断点续传的下载工具与诊断客户端会用到它，但服务器如果错误地声明或返回范围，就可能产生静默损坏，而不是干净的失败。

保持表示与内容编码一致，同时核对区间、总大小与实际正文字节。忽略 Range 时，完整的 200 可以合法；续传需要合适的强验证器。

建立完整大小

选择至少 16 字节、测试期间不变的下载文件。在同一个一次性 shell 会话和临时工作目录中依次运行以下片段，保留 url 与 size。显式的 set -eu 会让顺序执行的传输与字节断言失败时停止；HTTP 状态与范围响应头仍需按下文人工核对：

set -eu
url=https://www.example.test/downloads/archive.tar.gz
curl -fsS -H 'Accept-Encoding: identity' -D full.headers -o full.body "$url"
size=$(wc -c < full.body)
test "$size" -ge 16
awk 'tolower($1) ~ /^(content-length:|content-encoding:|etag:|last-modified:|accept-ranges:)$/ { print }' full.headers

确认完整响应为 200，且没有意外的内容编码。这些命令请求 identity 表示，不做自动解压；字节范围针对所选的编码后表示，因此改变编码会使比较失效。Content-Length 可能缺失，所以用完整正文确定大小。

Accept-Ranges: bytes 是显式信号，但缺少这个头并不能证明范围请求不受支持。去实际请求一次。

请求一个已知区间

请求开头 16 字节，同时保留响应头与正文：

set -eu
curl -sS -D range.headers -o range.body \
 -H 'Accept-Encoding: identity' -H 'Range: bytes=0-15' "$url"

wc -c range.body
head -c 16 full.body > expected.body
cmp expected.body range.body
awk 'tolower($1) ~ /^(content-range:|content-length:|etag:)$/ || /^HTTP\// { print }' range.headers

成功的字节范围响应应使用 206 Partial Content。Content-Range 应指出 0-15 与完整表示长度，而正文应正好包含 16 个字节。

这里的字节比较专门检查部分正文。合法但大于 16 字节的完整 200 会使比较失败并停止当前 shell 会话；先查看已保存的响应头，再判断是否发生损坏。反过来，完整文件恰好为 16 字节时，即便返回 200 也可能通过 cmp，所以仍需核对状态码与 Content-Range。

测试一个不可能的区间

从完整字节数开始请求：大小为 N 的文件，最后一个有效偏移量是 N−1。与任意写一个大常量不同，这确实超出了已知表示：

set -eu
curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' -H "Range: bytes=${size}-" "$url"

服务器用 416 Range Not Satisfiable 拒绝无法满足的字节范围时，应附带 Content-Range（例如 bytes */12345）报告当前大小。当服务器忽略 Range 时返回 200 也可能合法，但它必须返回完整表示，而不是一个标签错误的片段。

让验证器留在故事里

续传工具可以用 If-Range 配合强 ETag。不能使用弱 ETag；只有在没有 ETag、且日期符合强验证器条件时，才能使用 HTTP 日期。如果表示已改变，安全响应是完整的最新表示，而不是从两个版本拼接出的字节。在宣称某个下载"可续传"之前，先测试这一行为。

来源

RFC 9110 — HTTP Semantics，范围单位、部分响应与 Content-Range，已核验 2026-07-06。
curl manual，--range 与响应头选项，已核验 2026-07-06。

HTTP 方法是对副作用做出的承诺

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

请求方法说明客户端要求服务器做什么。只读文件源站的契约很窄，但仅凭“静态站点”并不能证明代理或导入的处理器没有暴露写操作。应检查真正服务该资源的路由。

先区分是否请求改变状态与重复请求的预期效果，再检查实际路由。文件处理器边界有明确适用范围，方法支持与 CORS 权限分开判断。

安全与幂等回答不同的问题

GET 与 HEAD 是安全方法：客户端没有请求改变状态的操作。但附带的日志、指标或计费仍可能改变服务器状态。PUT 与 DELETE 按其定义具有幂等语义，却并不安全：重复相同请求的预期效果与执行一次相同。这不要求响应状态码相同，也不意味着每次网络失败后都适合重试。

对只读静态源站：

GET 获取表示。
HEAD 描述对应的 GET，但不携带响应内容。
OPTIONS 询问目标的通信选项；文件处理器可以拒绝它。
POST / PUT / DELETE / PATCH 不应直接落入成功的文件响应，除非另有明确设计的处理器实现其语义。

Caddy 文件处理器的方法边界

Caddy v2.10.2 的文件服务路径接受 GET 与 HEAD，并以 405 和 Allow: GET, HEAD 拒绝其他方法。重定向、缺失路径、错误处理器与其他配置路由可能更早应答或采取不同处理，因此这不是每个静态网站 URL 的统一响应。

原笔记记录过：

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

这里没有保留原始响应日志，本轮审阅也未重现该在线结果。命令只报告状态码，不能证明必需的 Allow 字段存在，需另行检查。405 表示已知方法不被该目标支持；如果服务器根本不识别或未实现该方法，通常应区分为 501 Not Implemented。

HEAD 一致性允许规范规定的省略

HEAD 应描述与 GET 相同的所选表示，同时省略内容。只有生成内容时才能确定的字段可以省略。如果存在 Content-Length，它必须描述采用相同内容编码的对应 GET 内容长度。

原笔记报告过以下比较：

HEAD content-length: 15890
GET bytes read : 15890

这些历史数字不是固定的期望大小，也不是当前验证结果。仅缺少 HEAD 长度是合法的，提供了错误长度才需要调查。成对探针可参考 head-request-parity 笔记；可下载的 check-http-headers.sh 只检视 GET 响应，并不会自动执行这项比较。

拒绝意外写入，同时说明真实契约

对已识别、但目标不允许的方法，返回 405，并以 Allow 列出实际支持的方法。应用路由的这个列表不一定只包含安全方法。不要为被忽略的写请求返回看似合理的 200 页面。

如果浏览器客户端需要 CORS 预检，应明确配置相应 OPTIONS 行为；方法支持与 CORS 权限是两项不同决策。写入拒绝测试应在获准使用的可丢弃夹具上进行，不要因为公共端点看起来静态，就假设向它发送写请求没有影响。

来源

RFC 9110 — HTTP Semantics，安全/幂等方法与 HEAD、405、501 语义，已核验 2026-10-15。
MDN: HTTP 请求方法，方法概览，已核验 2026-10-15。
curl 手册，方法与响应检视选项，已核验 2026-10-15。
Caddy v2.10.2 文件服务器源码，文件选取后的方法拒绝，已核验 2026-10-15。
WHATWG Fetch 标准，CORS 预检处理，已核验 2026-10-15。

验证器决定缓存副本是否仍是答案

Tue, 30 Jun 2026 00:00:00 +0000

缓存可以询问已存储的副本是否仍可使用，而不必每次重新下载正文。它发送验证器；匹配的条件 GET 可以收到 304 Not Modified，表示变化时通常需要新的 200 响应。验证是在命中时省下正文，并非每次请求都省下。

标签仅为示意；假定请求原本成功。GET/HEAD 使用弱比较；HEAD 无正文。匹配既不证明字节相同，也不证明新鲜度。其他方法通常返回 412；If-Range 不能使用弱 ETag。

验证器类型与强度是两回事

ETag 是带双引号的不透明值，可以是强标签（"release-a"），也可以明确标记为弱标签（W/"release-a"）。强比较要求两者都为强标签且值相等；弱比较忽略 W/ 标记，只比较不透明值。即使字节不同，弱标签也可以描述语义等价。

Last-Modified 是 HTTP 日期中精确到秒的时间戳。通常它是弱验证器，除非满足 RFC 9110 第 8.8.2.2 节的条件、可认定为强验证器。不能把所有 ETag 都归为强验证器，也不能无条件把所有时间戳归为弱验证器。

先前的站点观察记录了：

etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT

这些是历史值；这里未保留原始响应日志，本轮审阅也未重新检查在线结果。Caddy 文件服务器通常会设置这两个字段，但仍取决于文件元数据与配置。

条件 GET 使用弱比较

把收到的 ETag 原样放进 If-None-Match，保留双引号与可能存在的 W/。原笔记针对上述值报告过 HTTP 304，但展示的请求值没有双引号；该请求文本不符合实体标签语法，不应当作可工作的探针照抄。测试在线端点前应取得当前验证器。

下面无需套接字的练习，展示对单个、已解析标签的比较；它不是完整的 HTTP 头部解析器：

def weak_value(tag):
 return tag[2:] if tag.startswith('W/') else tag

def strong_equal(a, b):
 return not a.startswith('W/') and not b.startswith('W/') and a == b

stored = 'W/"release-a"'
current = '"release-a"'
assert weak_value(stored) == weak_value(current)
assert not strong_equal(stored, current)
assert weak_value(stored) != weak_value('"release-b"')
print("weak match: True; strong match: False; changed tag: no match")

对原本会成功的 GET 或 HEAD，If-None-Match 匹配时返回无正文的 304。其他方法上的同一前置条件为假时，通常返回 412 Precondition Failed。若同时存在 If-None-Match 与 If-Modified-Since，ETag 条件优先。通过 If-Range 做字节范围验证时，不能使用弱 ETag。

重新发布时不要保留误导性的验证器

ETag 不一定是内容哈希。Caddy v2.10.2 的默认文件标签由修改时间与大小生成；替换字节时若两者都保持不变，标签也可能不变。检查实际部署版本与覆盖配置，再让发布流程更新验证器依赖的输入，或采用基于内容的版本标识。

在发布清单中保留字节校验和，并测试未变化与已变化两种响应。校验和不会自动成为服务器的 ETag。304 还需要适用的缓存元数据，让缓存更新已存储的响应；它不只是一个空的成功状态。

来源

RFC 9110 — HTTP Semantics，第 8.8 与 13 节的验证器强度及前置条件，已核验 2026-10-15。
RFC 9111 — HTTP Caching，第 4.3 节的验证与已存储响应更新，已核验 2026-10-15。
MDN: HTTP 条件请求，条件请求概览，已核验 2026-10-15。
Caddy v2.10.2 文件服务器源码，calculateEtag 的输入与默认响应字段，已核验 2026-10-15。

压缩会改变所选中的 HTTP 表示

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

压缩节省传输字节，但也制造了资源的另一种表示。客户端用 Accept-Encoding 声明可接受的内容编码；服务器用 Content-Encoding 描述实际应用的编码。

压缩选择的是表示字节，协商、缓存匹配与验证器必须一致。编码后字节不同就需要不同强标签。下载正文解码后再与制品比较；编码后 Content-Length 不必等于解码文件大小。

让协商可见

当响应可能随 Accept-Encoding 变化时，把该请求字段写进 Vary。这告诉共享缓存：压缩响应与 identity 响应不是可互换的缓存条目。

不要只检查一个浏览器请求，而是比较两条路径：

curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' https://www.example.test/
curl -sS --compressed -D - -o /dev/null \
 https://www.example.test/

检查 Content-Encoding、Vary、Content-Length（如存在）与验证器。当内容编码改变表示字节时，强实体标签必须不同。语义等价的变体可以共享弱标签，但它不能用于强比较。条件请求必须针对同一个协商出的表示检查。

压缩合适的内容

HTML、CSS、JSON、XML、SVG 等文本格式通常适合压缩；已经压缩过的格式未必适合。Caddy 的 encode 指令会协商支持的编码，并且通常对没有合适内容类型或体积过小的响应不做压缩。

不要为了满足某个评分而加压缩。测量一个有代表性的响应，确认边缘返回预期的头，并核验可下载文件在传输解码后仍保留正确的内容类型与校验和。

使用 --compressed 时，curl 自动解码正文，但保存的响应头不会随之改写。若存在 Content-Length，它描述的是编码后内容，未必等于解码后下载文件的大小。应在内容解码后才把校验和与制品比较；HTTP 传输分帧属于另一层。此外，该选项不保证服务器一定压缩，应查看真实响应，尤其是小文件与已经压缩过的文件。

来源

RFC 9110 — HTTP Semantics，内容编码与 Vary，已核验 2026-10-15。
Caddy encode 指令，内容编码选择与协商，已核验 2026-10-15。
curl manual，--compressed，已核验 2026-10-15。

缓存头是两套时钟的契约

Thu, 25 Jun 2026 00:00:00 +0000

缓存不是一个单一开关。一个响应既有一个由缓存作出的新鲜度决策，也有与源站之间的校验对话。把这两种想法混在一起，会得到陈旧内容或多余请求。

存储、新鲜度与校验是不同问题。根据 URL 的变更方式选择策略，完整保留验证器，并检查共享缓存的变体。

先选变更模型

对于发布之后可能变化的 HTML 文档，Cache-Control: no-cache 通常比 no-store 更接近正确起点。no-cache 允许存储，但要求缓存复用前先校验；no-store 则要求缓存完全不存储。当你想要条件请求与廉价的 304 Not Modified 时，这个区别很关键。

对类似 app.4f2c.js 这种带指纹的资源，URL 在字节变化时也随之改变，此时一个较长的新鲜度生命周期是合理的：

Cache-Control: public, max-age=31536000, immutable

但对一个内容可能被原地替换的稳定 URL，该策略不安全。如果 URL 稳定，应优先使用较短的生命周期，并搭配实体标签（ETag）或有意义的 Last-Modified 值。

除了新鲜期，还要决定谁可以存储响应。如果共享缓存不能保存面向特定用户的内容，应使用不带参数的 private 指令；浏览器的私有缓存仍可存储。单独使用 no-cache 不提供这项限制。上面的 public 示例适用于可以在用户之间共享的资源，不是个性化响应的默认策略。

同时检查两条路径

发一次普通请求，再发一次条件请求。各服务器的具体标志可能不同，但你想要的证据是稳定的：

curl -sS -D - -o /dev/null https://www.example.test/
curl -sS -D - -o /dev/null \
 -H 'If-None-Match: "copy-a-real-etag-from-the-first-response"' \
 https://www.example.test/

不要在 runbook 里粘贴编造的验证器。从第一次响应里复制该值，或使用测试夹具。对这里的条件 GET，If-None-Match 匹配时可以通过弱比较返回 304：它允许语义等价，并不一定保证字节完全相同。验证器变化时通常返回新的 200 响应。保留 ETag 的双引号与可能存在的 W/ 前缀。

让中间层可见

Age、Vary 与 cache-control 指令说明了为什么两个客户端可能得到不同结果。如果响应随 Accept-Encoding、语言或其他请求字段变化，该维度应进入 Vary；否则共享缓存可能复用错误的表示。

有意义的发布检查不是"扫描器找到了缓存头"，而是"该头与替换策略匹配，且条件请求的行为符合文档说明"。

immutable 只在声明的新鲜期内生效，并非永久禁止重校验。版本化 URL 的内容应保持不变，只要旧 HTML 仍可能引用旧资源，就应让它们继续可访问。今天修改响应头不会追溯缩短既有缓存响应的寿命；缓存策略出错时，可能需要新 URL 或缓存系统明确支持的清除操作。

来源

RFC 9111 — HTTP Caching，第 4–5 节，已核验 2026-10-15。
RFC 9110 — HTTP Semantics，第 8 与 13 节，已核验 2026-10-15。
MDN: Cache-Control，指令语义与默认值，已核验 2026-10-15。
RFC 8246 — 不可变响应，immutable 仅在新鲜期内生效，已核验 2026-10-15。

HSTS 应带着恢复计划来灰度发布

Tue, 23 Jun 2026 00:00:00 +0000

HTTP Strict Transport Security 告诉支持的浏览器，在一个缓存周期内对该主机强制使用 HTTPS。这种持久性既是特性也是风险：移除响应头并不会立刻抹掉客户端已存储的策略。

观察后再增加 HSTS 时长，独立决定后代覆盖与预加载。恢复需要有效 HTTPS，也不能立刻抹除所有已存或预加载策略。

先验证 HTTPS 路径

在发送 HSTS 之前，确认规范主机名提供有效证书，并且 HTTP 在不依赖用户输入的情况下重定向到预期的 HTTPS URL：

curl -sS -D - -o /dev/null --max-redirs 0 http://www.example.test/
curl -sS -D - -o /dev/null https://www.example.test/

检查有代表性的深层路由与错误页。HSTS 无法修复证书错误，因为浏览器在接受该策略之前要求有效的 HTTPS 连接。

从一个短的 max-age 开始

分阶段发布能在配置还新的时候限制恢复窗口：

Strict-Transport-Security: max-age=300

观察站点与续期路径之后，再有意识地提高时长。记录日期、所选值与回滚条件。最终策略可能用一年，但这个数字是一种承诺，而不是扫描器分数。

把 includeSubDomains 当作独立的决定

includeSubDomains 把策略扩展到每个子域名。先盘点名称，包括旧服务、委派区，以及只在内部网络使用的主机名。即使只有一个仅 HTTP 的后代，也足以让该选项对收到父级策略的客户端产生破坏。

预加载不是普通的响应头配置

浏览器预加载程序可以在正常响应周期之外分发策略，其要求与移除延迟比设置一个响应头更严格。不要仅仅因为扫描器推荐就申请预加载；请先确认对域名及所有被覆盖名称的长期所有权。

验证公共响应

curl -sS -D - -o /dev/null https://www.example.test/ \
 | awk 'tolower($1) == "strict-transport-security:" { print }'

测试规范的公共边缘，而不只是某个源站端口。代理可能添加、移除或重复该响应头。

知道回滚能清除什么

通过有效 HTTPS 响应发送 max-age=0，只会让收到该响应的客户端清除该主机已学习的策略。移除响应头或通过 HTTP 发送它，都不能清除已缓存策略。子域无法退出父域仍有效的 includeSubDomains；清除父域策略，也不会删除客户端独立从子域学习到的策略。

作用域由发送响应头的主机决定：www.example.test 的策略覆盖自身，加上 includeSubDomains 后覆盖其后代，但不覆盖同级的 api.example.test 或父级 example.test。恢复期间必须保持 HTTPS 可用。移除预加载是独立的浏览器更新过程，不是响应头的即时回滚。

来源

RFC 6797 — HTTP Strict Transport Security，策略处理与作用域，已核验 2026-10-15。
MDN: Strict-Transport-Security，指令与部署注意事项，已核验 2026-10-15。
HSTS 预加载项目，提交要求与移除限制，已核验 2026-10-15。

HEAD 应描述与 GET 相同的表示

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

HEAD 方法请求服务器对 GET 会返回的响应，但不会传输响应内容。它适合需要状态、验证器、类型或长度的检查，但前提是元数据与真实的 GET 路径保持一致。

比较 HEAD 与 GET 之前，先对齐 URL、请求头、发布版本与内容编码。允许省略的字段不能自动判为失败。应保留小 GET 的正文或校验和检查，因为看似合理的元数据不能证明有效载荷完好。

比较规范化后的响应头集合

Date 这类动态响应头会随请求不同而变化。只比较描述所选表示的那些字段：

url=https://www.example.test/downloads/manual.pdf

curl -sS -I "$url" > head.headers
curl -sS -D get.headers -o /dev/null "$url"

for file in head.headers get.headers; do
 printf '== %s\n' "$file"
 awk '
 /^HTTP\// ||
 tolower($1) ~ /^(content-type:|content-length:|content-encoding:|cache-control:|etag:|last-modified:|vary:)$/ { print }
 ' "$file"
done

在可丢弃的工作目录运行，因为两个头部文件会被覆盖。对齐 URL、请求头与发布版本；压缩协商也应纳入比较，给两个请求发送相同的 Accept-Encoding 值。

HEAD 应描述对应的 GET，但 RFC 9110 允许省略只有在生成内容时才能确定的字段。单独缺少 Content-Length 不代表失败；如果 HEAD 携带它，其值必须是对应 GET 内容的长度，不能因为 HEAD 没有正文就填零。比较时应统一内容编码，调查变化的验证器与类型，而不是要求两份头部逐字节相同。

不要把 HEAD 当作唯一的发布检查

服务器可能在文件缺失、不可读或被截断时仍合成看似合理的响应头。在冒烟测试里保留一个小的 GET 并核验其正文或校验和。HEAD 降低了传输成本，但并不能证明有效载荷存在。

显式检查重定向

不使用 --location 时，curl -I 报告第一个响应，适合测试重定向策略；使用 --location 时，会打印跟随过程中的多个响应头块，包括中间重定向与最终目标。请记录这条命令回答的是哪个问题：

curl -sS -I --max-redirs 0 https://old.example.test/manual
curl -sS -I --location https://old.example.test/manual

把方法相关的失败视为配置缺陷

一个对 GET 返回 200、对 HEAD 返回 405 或 404 的静态页面，通常暴露出代理或路由的不一致。应当修复方法处理，而不是教监控系统忽略它——除非端点契约刻意不允许 HEAD。

来源

RFC 9110 — HTTP Semantics，HEAD 方法语义，已核验 2026-10-15。
curl manual，--head、--include 与重定向选项，已核验 2026-10-15。