静态站 · XB 现场笔记

Hugo 发布选项决定哪些页面进入产物

Sat, 18 Mar 2028 00:00:00 +0000

Hugo 在构建运行时判断哪些页面应当渲染。文章元数据提供发布时间与草稿状态，项目配置和命令参数提供包含规则，构建时钟提供判断所用的时间。生成目录一旦部署，在下次产物替换之前不会自行变化。因此，日期走到午夜不等于触发发布；没有写 draft: true 的文件，也不会自动被当成草稿。这两个边界决定了排期内容能否按预期上线。

元数据和构建选项分别起作用

在默认规则下，标记为 draft: true 的页面不进入产物；发布时间在未来的页面也会被排除，已经过了失效时间的页面同样如此。Hugo 根据 front matter 配置解析各类日期，显式的 publishDate 可以不同于页面显示的 date。对必须精确到某个边界的排期，应使用包含时区的完整时间戳，避免本机和构建服务器把同一个日期解释为不同时间。

--buildDrafts 包含草稿，--buildFuture 包含未来内容，--buildExpired 包含已失效内容，短选项分别是 -D、-F 和 -E。这些开关处理不同条件：一篇发布时间尚未到达的草稿，需要同时允许草稿和未来内容才能提前进入产物。项目配置或环境配置也能启用相同行为，所以只看文章里的标记不足以判断实际发布结果，还必须检查本次构建的有效选项。

本站明确设置了 buildFuture: true，用于保留包含未来日期文章的既有公开目录。因此，本站这些文章的日期不是保密截止时间，也不能用 Hugo 的默认排期规则推断它们尚未公开。修改发布策略之前，需要把配置和预期 URL 清单一起比较，否则关闭一个看似普通的开关，就可能让大量已经存在的地址消失。介绍默认机制与解释本站事实，应当采用各自对应的证据。

预览产物仍然可以被公开

预览开关只改变输出包含什么，不会给产物增加禁止部署的属性。如果流水线上传了用 -D -F 生成的目录，草稿和未来页面一样可以被访问。因此，预览应使用独立输出位置，正式发布则根据计划中的选项重新构建。Git 发布标签只是标识源码历史，既不会改变 Hugo 的包含规则，也不能证明某个生成目录已经经过审阅。交付记录需要关联源码版本、构建选项和实际产物。

按时发布还需要在发布时间之后执行新的构建与部署。反过来，把已经公开的页面重新标记为草稿，也不会撤回服务器上的旧 HTML 或缓存副本。需要重建、替换被服务的产物，再检查公共地址。Hugo 通常不会自动删除输出目录里的所有遗留文件，因此独立的新目录或合适的清洁构建，是证明被排除页面确实不存在的必要步骤。导航里不显示链接，远不足以证明内容已经下线。

坏掉的样子

把预览目录覆盖到发布目录，可能让一篇后来恢复为草稿的文章仍能通过直接地址打开，而索引里已经看不到它。排查应检查生成文件、订阅源、站点地图以及真正对外的页面，区分索引隐藏和文件移除。另一个容易遗漏的规则是：章节页面标记为草稿，并不会自动把所有子页面也变成草稿。若整个子树需要排除，应设置具体子页元数据，或依照文档使用级联配置。

时区差异则可能让两台构建机器从同一个提交生成不同页面。边界测试应固定 Hugo 版本和构建时钟，并记录生效参数。不要在尚未弄清日期解析规则、环境时区和参数来源之前，为了让页面出现而随意改动发布日期。那样可能掩盖配置错误，还会改变订阅顺序和页面展示时间。首先使输入和时钟可重现，才能判断差异真正来自哪里。

快速验证

安装 Python 3 和 Hugo 0.165.0 后，可运行下面的隔离实验。它在临时项目中创建五篇页面，分别构建到八个独立目录，不修改当前仓库，也不执行部署。

from pathlib import Path
from tempfile import TemporaryDirectory
import subprocess

with TemporaryDirectory(prefix="hugo-publication-") as directory:
 root = Path(directory)
 (root / "content/posts").mkdir(parents=True)
 (root / "layouts/_default").mkdir(parents=True)
 (root / "hugo.yaml").write_text("baseURL: https://example.org/\n")
 (root / "layouts/index.html").write_text("<h1>Publication test</h1>")
 (root / "layouts/_default/list.html").write_text("{{ .Title }}")
 (root / "layouts/_default/single.html").write_text("{{ .Title }}")
 for name, extra in {
 "visible": "",
 "draft": "draft: true\n",
 "future": "publishDate: 2030-01-01T00:00:00Z\n",
 "future-draft": "draft: true\npublishDate: 2030-01-01T00:00:00Z\n",
 "expired": "expiryDate: 2025-12-01T00:00:00Z\n",
 }.items():
 (root / f"content/posts/{name}.md").write_text(
 f"---\ntitle: {name}\ndate: 2025-01-01T00:00:00Z\n"
 + extra + "---\nPublication fixture.\n"
 )
 cases = [
 ("normal", "2026", [], {"visible"}),
 ("drafts", "2026", ["-D"], {"visible", "draft"}),
 ("future", "2026", ["-F"], {"visible", "future"}),
 ("preview", "2026", ["-D", "-F"], {"visible", "draft", "future", "future-draft"}),
 ("expired", "2026", ["-E"], {"visible", "expired"}),
 ("all", "2026", ["-D", "-F", "-E"], {"visible", "draft", "future", "future-draft", "expired"}),
 ("boundary", "2030", [], {"visible", "future"}),
 ("later", "2031", [], {"visible", "future"}),
 ]
 for name, year, flags, expected in cases:
 destination = root / f"output-{name}"
 subprocess.run(
 ["hugo", "--source", str(root), "--destination", str(destination),
 "--clock", year + "-01-01T00:00:00Z", *flags],
 check=True, capture_output=True, text=True,
 )
 actual = {p.parent.name for p in destination.glob("posts/*/index.html")}
 assert actual == expected, (name, actual, expected)
 print(name, sorted(actual))

断言依次检查默认排除、单独打开各个开关、组合预览，以及时间恰好到达和越过发布边界后的结果。后两次普通构建仍然不包含两篇草稿。未来草稿只有同时使用 -D 和 -F 才会提前出现；-E 则独立包含已过期页面。这证明的是受控条件下 Hugo 的渲染选择，没有覆盖部署调度、CDN 缓存失效，也没有套用本站主动包含未来页面的配置。正式发布时，还需要从本次产物和公共路由分别取得证据，确认生成结果与线上实际一致。

修改发布选项时，应保留普通、未来、草稿、未来草稿和过期五类用例，它们覆盖不同的包含条件。检查本次新生成的文件，不能因为导航里没有链接，就断言被排除的页面肯定不在产物里。

来源

Hugo：基本用法，草稿、未来和失效内容，以及输出目录行为，已核验 2026-09-06。
Hugo：Front matter，发布元数据和级联设置，已核验 2026-09-06。
Hugo 命令参考，内容包含开关和构建时钟，已核验 2026-09-06。

可读的证据优先于仪表盘

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

监控仪表盘很方便，但方便不等于证据。本文论证：对小型静态服务，“站点是否健康"最可审计的形式，是一组运维者能阅读、能重跑、能粘进报告里的纯文本事实——而不是一个聚合的面板。

区别很重要，因为两者回答的问题不同。仪表盘是众多样本之上的透镜，调教成让你看到趋势。探针是对公共边缘的一次单一、可复现的观察。当任务是证明一次发布或诊断一个具体请求时，探针是保真度更高的产物。

仪表盘的聚合正是风险所在

仪表盘把成千上万条原始观察折成一系列聚合面板：平均延迟、错误率、可用性百分比。聚合正是审计线索变薄的地方。一个"99.98% 可用"的数字不会告诉你哪个请求失败、哪个请求头错了、今天的发布是否有被服务。除非你在别处保留原始日志，否则它是一个抹掉了产生它的证据的摘要。

对"边缘服务的是我暂存的那棵树"这种信心属性，仪表盘用错了工具。响应体比较可以回答一个 URL、一种表示、一个网络观测点与一个时刻的这个问题。抓取首页头部不能确定整棵树或所有 CDN 节点的身份。

一条可以读的探针

仓库附带只读辅助脚本 static/downloads/check-http-headers.sh，也发布在 /downloads/check-http-headers.sh。它打印响应头、最终状态与 URL。下面是示意节选，不是新的生产测量：

HTTP/2 200
content-type: text/html; charset=utf-8
content-security-policy: default-src 'self'; …; script-src 'none'; …

人读这一行，立刻同时知道三件事：状态是 200、类型是 HTML、无脚本策略确实在服务。把它与说"边缘 OK"的面板对比——面板要求你信任生成它的东西；响应头这一行是该客户端收到什么的直接证据。两者仍依赖探针实现、TLS 验证、路由以及原始输出的留存。读取证书 notAfter 增加的是到期时间观察，不能证明主机名匹配或信任链有效。

用可核验的语句取代信号缺失

本站偏好的不是仪表盘，而是在构建期间强制的契约，和发布窗口内一组确定性的命令。大致是：

离线检查校验产物（每一条内部链接、每一个 SVG、无脚本边界、校验和）。
分别检查公共边缘的状态与响应头、响应字节、TLS 身份与到期时间。头部脚本不打印证书日期，也不会自动拒绝所有意外 HTTP 状态。
字节清单描述暂存树；抓取选定 URL 并比较正文，才能建立采样交付的一致性。完整论断需要检查所有发布映射及表示转换，而不是只对服务器磁盘做哈希。

每一处都是一个运维者能粘进 issue 或 changelog、未来的审计者能重跑的句子。它们都不需要面板才能被理解。

留下足以复查的上下文

记录 UTC 时间、请求与最终 URL、方法、所选编码、连接到的远端 IP、客户端版本、退出码、HTTP 状态、相关响应头及正文摘要。保留失败，也保留成功。共享日志前去除凭据、Cookie 与个人信息。一个返回 200 的代理错误页可以通过状态码检查；比较已知正文或发布标记能发现另一类故障。

有用的发布报告应区分“此响应在此时匹配”与“服务在一个月内满足可用性目标”。保留聚合指标背后的原始观察，可能时让仪表盘链接回它们。显示形式本身不能创造可信测量。

什么时候你确实需要仪表盘

这一切不是说观测无意义。如果你运维很多实例、聚合容量、或观察长期趋势，仪表盘是看清全局的正确视图。论断更窄：当问题只是"这一棵发布在公共边缘是否健康"时，可复现的终端读取是良好的起点。重复探针、多个观测点、错误预算与告警还能发现单次成功请求看不到的间歇或区域故障。设计良好的仪表盘可以展现这些观察，同时保留其来源。

决策启发式很简单：如果一条语句可以用一条命令检查、且其输出就是证明，就优先命令；只有在你真正需要聚合处才保留仪表盘。这能让站点自己的操作故事与站点的内容一样可审计。

来源

curl 文档，从单次调用读取响应头，已核验 2026-10-15。
十二要素方法：日志，把日志当作运维者可读的事件流，已核验 2026-10-15。
OpenTelemetry：可观测性基础，日志、指标与追踪的互补作用，已核验 2026-10-15。

两只钟模型中的缓存新鲜度与校验

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

缓存有两个独立决定：能否不联系服务器就复用已存响应，以及如何检查它是否仍代表当前资源。“两只钟”只是便于记忆的比喻。新鲜度确实是年龄计算；校验是比较，不是另一个计时器。缓存中的响应可能按策略仍然新鲜，却已经不同于刚发布的源站，这并不一定违反 HTTP。

新鲜度：多久可以不询问就复用

Cache-Control: max-age=60 给响应 60 秒的新鲜度寿命。缓存将寿命与当前年龄比较，年龄需要考虑 Date、Age、传输耗时与存储时间。恰好到 60 秒时已经陈旧，不会再多新鲜一秒。共享缓存有 s-maxage 时优先采用它；没有显式寿命时，某些响应也可以获得启发式新鲜度。

新鲜响应通常可以复用，但仍须匹配缓存键与 Vary 字段，并遵守请求及响应指令。即使按年龄仍新鲜，no-cache 也要求复用前成功校验。no-store 禁止存储，不是“每次重新验证”的同义词。public 允许共享缓存在原本受限制的某些情形下存储响应，它不指定缓存时长。

对于会变化的 HTML，较短的显式寿命加校验通常有用。这意味着新发布的内容可能要等到寿命结束才通过合规缓存可见，属于有意接受的代价。整树发布不会使浏览器或 CDN 中已有的条目失效。内容寻址的资源则可使用较长寿命，前提是字节变化时 URL 也变化。

校验：询问已存表示是否仍然匹配

ETag 是不透明校验器，不是供客户端解码的校验和。Last-Modified 是时间戳校验器。两者都不会单独确定新鲜度寿命，服务器也不一定同时提供它们。例如下面是分别表达寿命与校验器的示意头部：

Cache-Control: max-age=60, must-revalidate
ETag: "release-a"

过期后，GET 携带 If-None-Match: "release-a"，选中的表示仍匹配时可得到 304 Not Modified，变化时则得到带新正文的 200。缓存根据 304 更新适用的元数据，再复用已存正文。没有相应的已存表示，304 本身没有可用的正文。If-None-Match 使用弱比较，因此验证成功不一定证明字节完全相同；If-Range 及部分响应拼接有更严格的要求。

服务器可以用字节或其他可靠变化的元数据生成 ETag。强标签必须区分数据不同的表示，包括适用时的不同内容编码。给 gzip 与 identity 的不同字节发送相同强 ETag，不能靠缩短寿命修复。Vary: Accept-Encoding 还告诉缓存哪个请求头参与了表示选择。

用小练习分开两个决定

这个 Python 模型刻意不包含启发式寿命、网络延迟及变体选择。age 表示已经算好的当前年龄；条件请求面对的服务器校验器暂时没有变化。

lifetime = 60
stored_etag = '"release-a"'
server_etag = '"release-a"'
for age in (59, 60, 61):
 fresh = age < lifetime
 action = "reuse without validation" if fresh else (
 "validate: 304, reuse body" if stored_etag == server_etag
 else "validate: 200, replace body"
 )
 print(age, action)

第一行直接复用；后两行校验，并在 304 后复用正文。把 server_etag 改成 "release-b"：陈旧的两种情况变成 200，59 秒的情况仍然复用已有响应。这就是新鲜度策略用内容可见性延迟换取较低延迟与源站负载的含义。

值得断言的契约

应测试匹配和变化的校验器、新鲜度边界，以及所选编码。还要决定源站故障时怎么办。HTTP 在特定条件或扩展下允许复用陈旧响应；must-revalidate 则禁止在响应陈旧后未经成功校验就复用，即使客户端已经断网。它用可用性换取更严格的正确性约束。单有校验器没有这样的承诺。

因此，有用的发布记录应写明缓存策略、选中的表示、实际条件响应状态，以及可接受的更新延迟。强制要求两个校验器头部和一次 304，既不能证明每个缓存都有当前字节，也不能消除所有带宽浪费，更不能代替对真实中间层配置的测试。

来源

RFC 9111：HTTP Caching，第 4.1–4.3、5.2 节中的变体、年龄、校验与指令，已核验 2026-10-15。
RFC 9110：HTTP Semantics，第 8.8、13.1.2、13.1.5 节中的校验器与比较规则，已核验 2026-10-15。

零 JavaScript 静态站是可辩护的选择

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

静态站点不需要 JavaScript 才能站得住脚；<script> 标签的缺席本身就可能是重点。本文论证一个在线内容站点通过策略关闭脚本通道的工程依据，并说明如何在公共边缘验证策略。下方头部来自仓库预期配置，不是刚刚观测到的生产响应。

论证分三部分：你删掉的攻击面；让删除可被观察的契约；以及确实该放弃这一层的情况。

关闭脚本通道能缩小哪些威胁面

一个不执行自身或第三方脚本的页面，移除了原本需要修补与审查的客户端脚本依赖。有效的无脚本 CSP 会在合规浏览器中阻止注入脚本执行，但 HTML 注入仍可改变文字、链接与页面结构。跟踪还可能依赖图片、导航或服务器日志，无须 JavaScript。本站另有不依赖第三方浏览器资源的要求，这比删掉脚本标签更广。没有浏览器脚本包，就没有其依赖漂移；构建工具与服务器依赖仍然存在。每一类都是有限、可命名的表面——也就是"小系统"那种"选择你能说清的边界"的特性。

这不是声称站点"安全"，而是声称攻击面更窄，并且关键的是更容易推理，因为它是靠构造枚举的，而不是靠审计枚举的。

让边界可强制执行的响应头

口味不是策略。这里的区别是，服务器下发策略，由浏览器强制执行。仓库中的 Caddy 示例配置指定：

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' 指令是可强制执行的部分。在这个完整策略且没有更具体的脚本放行规则时，合规浏览器会拒绝页面脚本、内联事件处理器与 JavaScript URL。若使用的是 Content-Security-Policy-Report-Only，则只报告、不阻止。以后添加 script-src-elem 或 script-src-attr 时需要重新审查，因为它们可覆盖各自脚本类别的回退规则。

构建校验器检查生成产物中的可执行脚本、事件处理器与 URL，不能证明反向代理确实发送了预期 CSP。应分别抓取代表性 HTML、错误页与重定向目的页，检查实际强制策略，并测试浏览器行为。源码检查、响应检查与浏览器执行是三项不同的验证。

移除之后静态结构带来的好处

没有脚本之后，内容模型回归到更接近已发布文档的东西。缓存处理的是 HTTP 表示，不是页面后来发生的 DOM 变化。静态产物让表示更容易检查和版本化；ETag 与新鲜度策略仍然取决于服务器配置。在终端里读线上 HTML、用"查看源代码"、或索引整棵树都很直接，因为产物就是磁盘上的普通文件。这是这个站点接受的交换：没有脚本管理的状态、没有客户端渲染、没有依赖 JavaScript 视图模型的反馈。原生链接、键盘导航、CSS 行为以及 details 之类的元素仍然可以提供交互。对文档与运维站点而言，这是正确的取舍，值得写下来。

什么时候"零 JS"的论断是错的

这是一层功能，不是一张纯净的标签。一个真正需要客户端交互的站点——实时仪表盘、文档编辑器、支付流程——不应该为了迁就约束就扭曲成提供静态 HTML 再硬塞变通方案。错误的应用是削足适履地把产品切成适应约束的形状。正确的应用是认识到：用来阅读、检索、归档的内容，从"成为文档"中收益；只有在文档本身不足时才需要脚本。

实际响应头是所采样响应的有用证据，却不能证明所有浏览器都支持、或每条路由都具有相同策略。仍须安全地渲染内容、保护发布权限、维护生成器与服务器。只有说清这些限制，边界才真正可辩护。

来源

W3C：Content Security Policy Level 3，策略下发、脚本指令与回退规则（工作草案），已核验 2026-10-15。
MDN：内容安全策略（script-src），禁用脚本执行的指令，已核验 2026-10-15。
PortSwigger：什么是跨站脚本（XSS）？，脚本注入及其后果，已核验 2026-10-15。
OWASP：内容安全策略，CSP 作为纵深防御控件，已核验 2026-10-15。