Caddy · XB 现场笔记

Caddy 自动管理 HTTPS 证书的签发与续期

Thu, 21 Jan 2027 00:00:00 +0000

Caddy 可以自动获取并续签受管理的证书，不需要运维人员手工实现 ACME 协议。自动化省去了重复操作，却没有取消签发前提，也不能代替对失败的监控。今天证书有效，不证明下次续期仍能完成，更不证明整条链路中的每一跳都使用同一张证书。应先明确服务名称、验证路径、持久存储和 TLS 终止位置，再判断自动化覆盖到哪里。

先让自动 HTTPS 知道服务名称

当配置让 Caddy 知道符合条件的主机名或地址时，自动 HTTPS 才会按规则启用，同时还要考虑文档列出的例外与显式覆盖。Caddyfile 中的站点地址包含主机名，是常见触发方式。file_server 指令负责提供文件，本身并不等于为某个尚未指定的域名申请公开证书，不能把文件服务功能与证书管理的启用条件混在一起。

命令行区别很明确：不带参数的 caddy file-server 默认监听八十端口；提供 --domain 后，才会尝试为指定主机名启用 HTTPS，并将默认监听端口改为四百四十三。无论命令怎样拼写，都不能单独证明 DNS、端口转发或证书授权已经正确。显式 HTTP 配置、手动加载的证书等条件，也可能改变自动行为，应该检查实际生效配置。

本地开发还有不同的信任边界。对于内部名称，Caddy 可以使用自己的本地证书机构。客户端需要通过适当流程信任该机构；某台机器能够正常访问，不代表这张证书已经获得公网客户端的普遍信任。更不能为了修复客户端信任问题，把私有 CA 的签名密钥发给所有客户端。信任根分发与私钥保管是两项不同工作。

让挑战方式与真实路径匹配

Caddy 默认同时启用 HTTP-01 与 TLS-ALPN-01。前者通过公网八十端口验证，后者通过四百四十三端口上的特殊 TLS 握手验证；Caddy 可以在可用方式之间选择。某次 HTTP 挑战失败，并不说明 DNS 验证就是唯一替代方案。应先从日志确认实际失败的是哪种挑战，再检查该方式的入口、转发和防火墙规则。

代理或 CDN 可能干扰这些路径，但它们的存在不会自动使签发变得不可能。即使普通 HTTPS 在 CDN 终止，HTTP 挑战请求也可能被正确转发。DNS-01 则通过 TXT 记录证明控制权，不要求申请证书的服务器接收入站验证流量，但需要受支持的服务商集成和范围适当的 DNS 凭据。选择方式应依据真实路由和权限，而不是凭拓扑名称猜测。

坏掉的样子

陈旧的 A 或 AAAA 记录、端口阻断、错误转发或 CDN 规则变化，都可能让首次签发成功之后的验证失败。应同时检查两个地址族，并读取日志中的具体挑战错误。反复清空存储再重试，不是有效诊断：这样会丢掉本可复用的证书状态，还可能增加不必要的签发尝试，消耗正常业务需要的配额。

实例替换时应保留 Caddy 的数据存储，并保护其中的敏感密钥材料。多个实例需要符合 Caddy 协调语义的存储安排；几台机器上恰好有同名目录，并不表示它们共享了状态。应验证这套配置如何恢复，同时避免把私钥打印到日志、复制进报告或提交到版本库。自动管理证书并不会免除持久化与访问控制责任。

现有证书仍然可用时，续期自动化就可能已经失败。应监控续期错误，以及客户端实际收到的证书到期时间，为处置留下足够提前量。源站续签成功，不能证明 CDN 对外证书已经更新；CDN 对访客启用 TLS，也不会取消对另一条 HTTPS 源站连接的安全和身份检查。这两个终止位置需要分别验收。

签发实验应使用预发签发者，避免把不受公开信任的测试证书带到生产。DNS 凭据轮换后，也需要受控的验证检查。告警提前量应按响应能力与证书寿命选择，不能把一个固定三十天的算术示例当成 Caddy 的续期调度规范，更不能因脚本输出正常就断言真实证书一定会自动更新。

Caddy 证书生命周期：机制与证据边界。

快速验证

保存为 expiry_alert.py 并运行 python3 expiry_alert.py，须启用断言，不使用 -O 或 PYTHONOPTIMIZE；只需要 Python 标准库。程序使用固定 UTC 观察时刻，三十天阈值是本例运维告警的自主选择，不是 Caddy 内部策略。它不会联系域名或证书机构，不启动监听器，不创建密钥，也不修改系统信任设置，适合单独验证日期边界。

from datetime import datetime, timedelta, timezone

# An operator-chosen alert threshold, not Caddy's renewal scheduler.
ALERT_BEFORE = timedelta(days=30)
NOW = datetime(2026, 10, 15, 12, tzinfo=timezone.utc)


def expiry_alert(not_after, now):
 for value in (not_after, now):
 if value.tzinfo is None or value.utcoffset() is None:
 raise ValueError("timezone-aware timestamps required")
 remaining = not_after - now
 if remaining <= timedelta(0):
 return "expired"
 if remaining <= ALERT_BEFORE:
 return "warning"
 return "ok"


for name, days, expected in [
 ("fresh", 80, "ok"), ("due", 20, "warning"),
 ("boundary", 30, "warning"), ("expired", -1, "expired"),
]:
 not_after = NOW + timedelta(days=days)
 actual = expiry_alert(not_after, NOW)
 assert actual == expected
 print(f"{name}: remaining={days}d alert={actual}")
assert expiry_alert(NOW, NOW) == "expired"
try:
 expiry_alert(NOW.replace(tzinfo=None), NOW)
except ValueError:
 print("naive timestamp rejected")
else:
 raise AssertionError("missing timezone accepted")
print("PASS: expiry alert boundaries; no certificate issuance tested")

四个打印案例依次得到正常、警告、警告和过期。恰好剩余三十天也进入警告范围，到期瞬间则单独归为过期。负例传入的是缺少时区的到期时间；函数也检查观察时刻，但本例没有单独测试第二个参数缺少时区的分支。断言验证的是这套明确的告警规则，不依赖执行当天，也不假设所有证书都拥有相同总寿命。

保留的精确记录覆盖这份未变的算术夹具；本轮源码复核没有重跑。该实验没有运行 Caddy、获取证书或观察真实续期。部署验收仍需要检查客户端实际收到的证书、已经配置的挑战路径，并在预期持久存储条件下观察续期成功。应把这些运行证据与这份可重复的小型日期算术检查分开记录，才能知道哪一部分已经证明，哪一部分仍需要实际环境验证。

来源

Python assert statement，优化模式省略断言及其内部调用，已核验 2026-10-18。
Caddy 自动 HTTPS，启用条件、本地信任、挑战选择及存储，已核验 2026-10-15。
Caddy file-server 命令，默认监听端口与 domain 参数，已核验 2026-10-15。
Let’s Encrypt 挑战类型，验证端口、DNS 自动化及受限凭据，已核验 2026-10-15。
Let’s Encrypt 速率限制，实验使用预发环境与签发失败，已核验 2026-10-15。

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

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, 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。

压缩会改变所选中的 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。

证书过期是一个日期，而不是仪表盘上的颜色

Wed, 10 Jun 2026 00:00:00 +0000

HTTPS 进程可能是健康的，而公共证书却临近过期、为错误的名字签发，或在另一条边缘上被不同地提供。一条有用的检查，是向公共端点索取它会给真实客户端的那张证书。

先检视真实客户端看到的证书，再独立验证。到期告警应使用服务自己的响应阈值，配合握手检查、续期失败告警，以及相关边缘和地址族抽查。

包含主机名

TLS 虚拟主机依赖服务器名称。把主机名作为 SNI 传入，并检视对端证书：

host=www.example.test
openssl s_client -connect "$host:443" -servername "$host" </dev/null 2>/dev/null \
 | openssl x509 -noout -subject -issuer -dates -fingerprint -sha256

这条命令是只读的。它不会续签任何东西，也不能证明每个中间证书都被每个客户端接受。但它确实给出为该主机名呈现的证书的 not-before、not-after、subject、issuer 与指纹。

在阈值上告警

选择能留出续期失败、DNS 问题与人工响应时间的阈值。确切数字属于服务的恢复目标；并非普通的"30 天"规则就能替代这个决定。配套的TLS 过期检查会打印过期时间，并在剩余区间低于你传入的阈值时以非零退出。

尽可能从主机外部运行检查。本地进程看到的监听器、证书文件或代理路径，可能与公共网络上的访问者不同。

把观察与验证分开

SNI 用于选择虚拟主机，并不验证证书是否匹配该名称。即使 s_client 报告验证问题，这条管道也可能打印证书，而且它隐藏了标准错误。另做主机名与证书链验证，保留诊断信息并使用已知信任库。不要把这条检视管道最后一个命令的退出码当成 TLS 健康结论。

配套脚本以 OpenSSL -checkend 检查 notAfter，并不能证明主机名匹配、信任关系、吊销状态或 notBefore 已经到来。把到期告警与握手检查、续期失败告警配合使用。阈值应小于证书正常寿命，短期证书尤其如此；还应抽查相关边缘与地址族。

来源

Caddy Automatic HTTPS，自动 TLS 证书管理，已核验 2026-10-15。
OpenSSL s_client 文档，SNI 与证书检查选项，已核验 2026-10-15。
OpenSSL x509 文档，证书解析、日期与指纹，已核验 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。