决策 · XB 现场笔记

站点以静态树提供服务，而非动态应用服务器

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

预期架构：构建工具在服务前执行，Caddy 仍是 Web 服务器。浏览器 CSP 是另一项策略。只发布生成文件；服务根并不是符号链接沙箱。

Context

本站是文档与运维内容：用来阅读、检索、归档的页面。动态应用服务器可以渲染模板、管理会话或提供交互组件，但这些是可选能力，不是当前需求。内容本身对服务器端状态、按用户的认证逻辑或客户端渲染都没有要求。

Decision

用 Caddy 将一个预构建的静态树作为站点提供服务，通过受控的发布切换选择一个不可变发布目录。目录发布 ADR 解释了切换方式及其跨请求限制。边缘后面没有应用服务器、没有脚本通道、没有数据库。

浏览器 ──HTTPS──► Caddy ──文件系统读取──► public/ 发布树

预期的浏览器无脚本契约由响应头（script-src 'none'）下发，并由拒绝可执行脚本与残缺产物的构建检查支持。CSP 由浏览器执行，不能证明没有应用服务器。构建输出是 public/，其中包括生成的页面和从源 static/ 目录复制的文件。

后果

发布更简单： 内容产物没有应用状态或数据库 schema 要迁移。发布切换、缓存行为与回滚仍须验证。
威胁面更窄： 请求路径没有应用模板求值器或数据库查询层。Caddy 和浏览器仍会解析不可信输入，生成器与依赖仍在构建时执行。
缓存可检查： 不可变发布文件有稳定字节。校验器、压缩变体与新鲜度指令仍需正确服务器配置。
接受的取舍： 没有脚本驱动的交互、认证个性化或每用户 HTML。原生文档交互仍然可用。若确实需要，应作为独立的服务来组合，而不是并进这棵树。

仍然存在的边界

只发布生成树，不发布仓库根、构建凭据或私有内容。Caddy 的 root 不是文件系统沙箱：根内的符号链接可能暴露根外目标。发布前应检查产物符号链接、权限与错误路由。无脚本 CSP 不会让 HTML 注入无害，也不能保护被公开的机密文件。

持续更新服务器，验证实际公共响应，并保留经过测试的上一版。这些运维责任不会随应用层的移除而消失。仓库记录的是预期架构与示例配置，不是证明当前生产主机没有其他服务的资产清单。

为什么它胜过替代方案

动态层带来一个运行时、一个状态边界和一条更慢的编辑路径。对价值在文档本身的内容，这笔成本买来了内容用不到的能力。静态服务没有牺牲站点需要的任何东西，同时移除了只会让发布与安全边界变复杂的部分。

来源

Caddy 文档：file_server，在没有应用层的情况下提供静态根目录，已核验 2026-10-15。
MDN：内容安全策略，浏览器资源与执行策略，已核验 2026-10-15。

钉住 vendored 主题与生成器版本

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

固定版本缩小漂移范围。比较受控构建并留存输入；历史四次构建一致的结论有明确边界。

Context

本站用 Hugo 生成器与 PaperMod 主题构建。两者任一未跟踪的升级都可能静默改变输出：主题的模板、生成器的渲染规则，或两者都可能改变两次"相同"重建之间的 HTML 字节。发布清单标识一份产物。复现它是更强的论断：源码、环境与步骤必须受到足够控制，才能再次产生相同字节。

Decision

把主题纳入仓库，并把确切的生成器版本与主题版本记录在钉住文件 data/upstream-pins.toml。make build 用 .hugo_version 检查安装的 Hugo 版本；CI 另外调用的 make check-upstream 将它与 TOML 中的版本及 THIRD_PARTY_NOTICES.md 记录的 PaperMod 发布版交叉核对。后者检查记录一致性，不是重新逐文件比对 vendored 内容与上游。

Hugo 0.165.0
PaperMod v8.0
data/upstream-pins.toml （钉住）

被纳管的主题放在 themes/ 目录下，作为提交的一部分，因此也成为一次发布字节身份的一部分。

后果

输入受控： 固定版本去除了两个漂移来源，但本身不能证明输出字节一致。
升级可见： 更新生成器版本或 vendored 主题字节，是显式可审查的变化。即使发布标签未变，主题修改仍然能在 Git 中看见。
来源可审计： 任何一次发布的读者都能看到是哪个生成器与主题产生了这些字节。
接受的取舍： 仓库带上 vendored 主题与钉住簿记；相比静默的输出漂移，这个代价很小。

可复现性仍需要测试

当前 Makefile 每次构建都把当前 UTC 时间写入 data/buildinfo.toml。时间会被渲染到站点，因此不同时间的两次普通构建有意不保持字节一致。提交标签也不能描述未提交修改。应把干净源码版本和准确构建元数据与产物一起保存。

要测试渲染的确定性，可在隔离检出中固定相同的构建元数据、工具链、配置、环境和资源输入，再让 Hugo 分别输出到两个空目录。为两份输出生成按路径排序的 SHA-256 清单并比较，把选定输入与结果一起留存。不要声称这个 Makefile 会采用 SOURCE_DATE_EPOCH，因为它明确调用了 date。

较早的完整站点两次构建检查在固定构建元数据后，两份产物各含 4,695 个文件，但有 165 条路径的字节不同，其中包括 HTTP 与 Http 等分类显示大小写。这个失败结果仍保留在历史记录中；仅固定版本并未建立输出确定性。

原报告记载了一次后续隔离 Linux 检查：固定相同构建元数据与 Hugo 时钟，在一项仅涉及内容的分类修改前后各比较四次完整构建。修改为 28 个语言/分类大小写冲突组添加显式分类元数据，把中文 nginx 标签改为漏桶，并保留其历史 /zh/tags/令牌桶/ URL。修改后的四份产物各含 4,695 个文件，按路径排序的 SHA-256 清单完全相同；所有发布路径、标签成员顺序、分页目标和 XML 路由均保留，构建没有警告。报告中的结论仅涉及所记录源码快照、Hugo 0.165.0 Extended、vendored 主题和 Linux 环境下的重复一致性，不是跨平台、跨年份、未来版本或未来内容的可复现保证。改变这些输入后应重新比较，也不能用两次普通 make build 代替固定元数据测试。

恢复后的文章与配图保留了这项历史报告，但恢复材料不包含后续四次构建结果的原始运行日志或比较清单。本轮审查没有独立复现该结果。后来进行的分类标题元数据恢复是另一项工作，不能补足原实验缺失的证据。

固定版本不代表永远批准运行旧软件。应审查上游修复、判断其影响，适当同步更新版本记录与 vendored 字节，然后执行完整验证并检查生成差异。

为什么它胜出

输入未钉住的构建，今天可能给正确的答案，明天却给出不同的树，而 diff 与清单都无法告诉你为什么。固定版本缩小了构建变化时的调查范围；时间戳、内容、配置与环境仍可能造成差异。这个边界有用，但不应被夸大为可复现性的证明。

来源

Reproducible Builds：定义，受控输入与逐字节比较，已核验 2026-10-15。
Hugo 命令参考，显式构建目的目录与配置选项，已核验 2026-10-15。
Hugo 文档：版本，报告并匹配生成器发布版，已核验 2026-10-15。
语义化版本规范，版本标签约定，而非可复现保证，已核验 2026-10-15。

通过原子指针选择完整发布树

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

同一文件系统上的符号链接替换选择完整发布树。旧资源 URL 必须继续可访问。本地示例不证明生产迁移、浏览器跨请求事务、自动回滚或断电持久性。

Context

将变更文件直接覆盖在线上树中，会暴露部分发布，也让上一版难以命名。完整暂存解决了复制中途的问题，但“把新目录重命名覆盖旧目录”并不是足够的发布过程。mv new existing-directory 通常把 new 移入目的目录。普通 POSIX rename 不能替换已有的非空目录。先移走旧目录、再把新目录移入，则在两次操作之间留下空窗。

Decision

保留不可变、带版本名的发布目录，用 current 符号链接选择其中一版。让文件服务器服务这个稳定路径。校验新树后，在 current 旁创建临时符号链接，再通过同一文件系统上的 rename 原子替换符号链接本身。旧发布目录以原有版本名保留，不受修改。

这是完整树决策的实现模式，不是生产主机已经迁移到此布局的证据。若当前服务根是真实目录，需要单独规划迁移，不能对那个路径直接执行示例并假设符号链接会安全替换它。

在本地演练切换与回滚

下列 Python 3 练习只创建一次性本地文件，在 POSIX 文件系统上展示指针操作，不启动 Caddy，也不改变部署。

from pathlib import Path
from tempfile import TemporaryDirectory
import os

with TemporaryDirectory() as tmp:
 root = Path(tmp)
 for version in ("v1", "v2"):
 release = root / "releases" / version
 release.mkdir(parents=True)
 (release / "index.html").write_text(version, encoding="utf-8")
 current = root / "current"
 current.symlink_to("releases/v1", target_is_directory=True)
 previous = os.readlink(current)
 with (current / "index.html").open() as in_flight:
 pending = root / "current.next"
 pending.symlink_to("releases/v2", target_is_directory=True)
 os.replace(pending, current)
 print("new open:", (current / "index.html").read_text())
 print("already open:", in_flight.read())
 pending.symlink_to(previous, target_is_directory=True)
 os.replace(pending, current)
 print("rollback:", (current / "index.html").read_text())

预期输出为 new open: v2、already open: v1、rollback: v1。成功的 rename 使目录项替换具有原子性，却不会改变已经打开旧文件的描述符，也没有测试断电持久性或 HTTP 路由。

后果

线上没有复制到一半的树： 选中前每个发布都已完整。不要修改已选中或留存的发布目录。
可命名的回滚： 创建指向已记录上一版目标的新临时链接，再替换 current。回滚需要执行和验证，冒烟测试失败不会自动完成它。
切换前证据： 检查暂存清单、所有权、可读权限与剩余空间。清单放在被哈希树之外。
发布串行化： 同时只允许一个发布者。固定临时链接名适用于此隔离练习；生产环境需要协调与防碰撞的临时名称。
存储取舍： 为回滚与进行中的客户端保留旧版，经过留存窗口和检查后才清理。

原子指针替换不是覆盖一个浏览器页面及其所有资源请求的事务。浏览器可能在切换前取得旧 HTML、切换后才请求资源。带内容指纹的资源 URL 只有在新服务树或独立留存资源库仍能通过旧 URL 提供旧字节时才有用。只是把旧发布目录留在磁盘别处并不够。发布和回滚后，缓存也可能继续持有旧响应。

临时链接与 current 必须位于同一文件系统，共用父目录是方便的保证方式。还须检查文件系统及服务器真实的符号链接行为。rename 的原子性描述并发可见性，不等于突然断电后的持久性；更强的持久性需要与文件系统匹配的文件和目录同步。服务根不是沙箱，应拒绝发布内容中意外出现的符号链接。

为什么它胜过就地同步

发布可以命名、在暴露前验证、通过一次指针操作选中，并从已知目标恢复。这些保证有实际价值，无须承诺全球瞬时更新、跨请求快照隔离，或每次失败后的自动恢复。

来源

Linux man-pages：rename(2)，原子替换、非空目录、符号链接与已打开描述符，已核验 2026-10-15。
Python os.replace，成功替换的原子性及非空目录、跨文件系统限制，已核验 2026-10-15。
Caddy file_server，根解析与符号链接安全边界，已核验 2026-10-15。