Deployment · XB 现场笔记

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。

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

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

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

TTL 随每个应答传播。切换前做好准备，让两侧持续有效，并结合旧端点流量与余量决定下线和回滚。

在事件前降低 TTL

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

单独记录权威服务器的应答。下面两条探针比较系统配置的解析器与公共递归解析器，并不天然属于权威查询：

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

要取得权威证据，应向该区域实际的名称服务器发起非递归查询，并检查 AA 标志、状态、答案与权威部分。递归解析器的剩余 TTL 反映其当前缓存状态，不同解析器可以合理地不同。还应检查服务使用的 AAAA 与 CNAME 链，不能只检查 A。

让两侧都保持有效

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

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

观察后恢复 TTL

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

TTL 不是所有客户端统一的下线期限。解析器在解析失败时可能提供过期数据，长连接与应用缓存也可能超过 DNS 新鲜期。应观察旧端点流量并预留余量；把 DNS 改回去同样有缓存窗口。对否定应答，应检查由 SOA 决定的否定 TTL，不能假设新 A 记录的 TTL 适用。

来源

RFC 1034 — Domain Names: Concepts and Facilities，缓存模型，已核验 2026-10-15。
RFC 1035 — Domain Names: Implementation and Specification，TTL 字段，已核验 2026-10-15。
RFC 2308 — Negative Caching of DNS Queries，否定缓存模型与保留的错误 TTL，已核验 2026-10-15。
RFC 8767 — 提供过期数据，DNS 解析失败时提供过期应答，已核验 2026-10-15。
BIND 9 dig 手册，服务器选择与递归控制，已核验 2026-10-15。

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

Thu, 04 Jun 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
}

主机名与路径都是占位值；www.example.test 不是可签发公开可信证书的生产名称。生产环境应使用自己控制且可解析的主机名，测试环境的本地 TLS 信任则另行安排。发布命令应发布一个完整目录、核验它，然后才把这个目录设为配置里的根。在新目录通过冒烟测试之前，保留旧的已知良好目录。

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

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

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

根目录是发布边界，不是沙箱

把版本控制元数据、备份、凭据与私有配置留在发布树之外。Caddy 会跟随根目录中的符号链接，因此链接可能暴露根目录外的文件。既要检查制品内容，也要检查服务用户的读取与目录穿越权限。此外，仅把 404.html 放进目录并不会配置自定义错误处理；应核验缺失路由的状态码与预期错误页行为。

来源

Caddy file_server 指令，静态文件服务与根目录选择，已核验 2026-10-15。
Caddy header 指令，响应头配置，已核验 2026-10-15。
Caddy Automatic HTTPS，证书签发与 HTTPS 重定向，已核验 2026-10-15。
MDN: X-Frame-Options，防止被嵌套的选项，已核验 2026-10-15。
RFC 7034 — X-Frame-Options，DENY 嵌入策略，已核验 2026-10-15。
静态网站发布检查清单，本地配套资源。
RFC 6761 — Special-Use Domain Names，保留的 .test 名称，已核验 2026-10-15。

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

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。