https://www.xbcatm.com/zh/decisions/基于 HTTP、DNS、TLS、Caddy、SSH、发布与恢复的可复现运维现场笔记。Hugozh-CNhttps://www.xbcatm.com/zh/decisions/adr-static-not-dynamic-server/Tue, 25 Aug 2026 00:00:00 +0000https://www.xbcatm.com/zh/decisions/adr-static-not-dynamic-server/决策记录：选择在 Caddy 之后提供构建好的静态树，而非动态应用，并说明接受的取舍。<h2 id="context">Context</h2> <p>本站是文档与运维内容：用来阅读、检索、归档的页面。早期构想考虑过用动态应用服务器来渲染模板、管理会话或提供交互组件。内容本身对服务器端状态、按用户的认证逻辑或客户端渲染都没有要求。</p> <h2 id="decision">Decision</h2> <p>用 Caddy 将一个预构建的静态树作为站点提供服务，发布时整棵目录一次性交换。边缘后面没有应用服务器、没有脚本通道、没有数据库。</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Caddy（公共边缘）──HTTPS──► 静态/ 树（资源、HTML、SVG） </span></span></code></pre></div><p>服务的契约由响应头（<code>script-src 'none'</code>）与构建期检查强制，后者拒绝脚本与残缺产物。</p> <h2 id="后果">后果</h2> <ul> <li><strong>发布平淡：</strong> 发布是一次完整目录交换，因此没有状态迁移、没有 schema。</li> <li><strong>威胁面窄：</strong> 没有运行时执行用户输入，关闭了整类注入。</li> <li><strong>缓存诚实：</strong> 每个文件有稳定的字节身份与校验器。</li> <li><strong>接受的取舍：</strong> 没有交互、没有认证个性化、没有每用户 HTML。若确实需要，应作为独立的服务来组合，而不是并进这棵树。</li> </ul> <h2 id="为什么它胜过替代方案">为什么它胜过替代方案</h2> <p>动态层带来一个运行时、一个状态边界和一条更慢的编辑路径。对价值在文档本身的内容，这笔成本买来了内容用不到的能力。静态服务没有牺牲站点需要的任何东西，同时移除了只会让发布与安全边界变复杂的部分。</p> <h2 id="来源">来源</h2> <ul> <li><a href="https://caddyserver.com/docs/caddyfile/directives/file_server">Caddy 文档：<code>file_server</code></a>，在没有应用层的情况下提供静态根目录，已核验 2026-08-25。</li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy">MDN：内容安全策略</a>，限制边缘会执行什么，已核验 2026-08-25。</li> </ul>https://www.xbcatm.com/zh/decisions/adr-pin-vendored-theme-and-generator/Fri, 21 Aug 2026 00:00:00 +0000https://www.xbcatm.com/zh/decisions/adr-pin-vendored-theme-and-generator/决策记录：选择把主题纳入版本库并钉住 Hugo 版本，使重新构建能复现相同输出。<h2 id="context">Context</h2> <p>本站用 Hugo 生成器与 PaperMod 主题构建。两者任一未跟踪的升级都可能静默改变输出：主题的模板、生成器的渲染规则，或两者都可能改变两次&quot;相同&quot;重建之间的 HTML 字节。当发布用字节清单证明时，可复现不是可有可无；同一份源码的两次构建必须产生同一棵树。</p> <h2 id="decision">Decision</h2> <p>把主题纳入仓库，并把确切的生成器版本与主题版本记录在钉住文件 <code>data/upstream-pins.toml</code>。构建流水线读取该文件，若安装的生成器与钉住版本不符则失败。</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Hugo 0.165.0 </span></span><span class="line"><span class="cl">PaperMod v8.0 </span></span><span class="line"><span class="cl">data/upstream-pins.toml （钉住） </span></span></code></pre></div><p>被纳管的主题放在 <code>themes/</code> 目录下，作为提交的一部分，因此也成为一次发布字节身份的一部分。</p> <h2 id="后果">后果</h2> <ul> <li><strong>可复现输出：</strong> 相同源码加上钉住的生成器得到相同树，使清单有意义。</li> <li><strong>升级可见：</strong> 升主题或生成器是对钉钉文件的显式、可审的改变，而非意外漂移。</li> <li><strong>来源可审计：</strong> 任何一次发布的读者都能看到是哪个生成器与主题产生了这些字节。</li> <li><strong>接受的取舍：</strong> 仓库带上 vendored 主题与钉住簿记；相比静默的输出漂移，这个代价很小。</li> </ul> <h2 id="为什么它胜出">为什么它胜出</h2> <p>输入未钉住的构建，今天可能给正确的答案，明天却给出不同的树，而 diff 与清单都无法告诉你为什么。钉住把&quot;构建变了&quot;变成&quot;钉住变了&quot;，而这是一个 changelog 真正能回答的问题。</p> <h2 id="来源">来源</h2> <ul> <li><a href="https://gohugo.io/getting-started/usage/">Hugo 文档：版本</a>，报告并匹配生成器发布版，已核验 2026-08-21。</li> <li><a href="https://semver.org/">语义化版本规范</a>，为什么版本边界让可复现有意义，已核验 2026-08-21。</li> </ul>https://www.xbcatm.com/zh/decisions/adr-complete-directory-release/Thu, 20 Aug 2026 00:00:00 +0000https://www.xbcatm.com/zh/decisions/adr-complete-directory-release/决策记录：发布作为单一目录名之后的一次整树交换，保留旧树以便回滚。<h2 id="context">Context</h2> <p>通过把变更文件覆盖到线上树上来部署，会有访问者看到部分发布的窗口风险：某些文件是新的、另一些是旧的，相关联的资源彼此不一致。单个损坏文件也可能弄坏一个本来完好的线上站点。任何原地编辑被服务目录的发布路径，都让&quot;上一个发布&quot;难以命名和恢复。</p> <h2 id="decision">Decision</h2> <p>发布时在线上树旁边暂存一棵完整的新树，然后重命名 Caddy 服务的单一目录指向它。旧树保留在磁盘上，用其先前的名字。</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">rsync -a public/ /srv/www/example-site.new/ </span></span><span class="line"><span class="cl">mv /srv/www/example-site.new /srv/www/example-site </span></span></code></pre></div><p>因为服务根是一个目录名，交换从客户端角度看是原子的：每个请求要么解析到旧的完整树，要么解析到新的完整树，绝不会是一个混合。</p> <h2 id="后果">后果</h2> <ul> <li><strong>无部分状态：</strong> 访问者总是看到一个连贯的发布。</li> <li><strong>回滚廉价：</strong> 旧树仍然存在；恢复是一次反向重命名。</li> <li><strong>交换前可验证：</strong> 暂存的树在被服务之前可以被检查和哈希。</li> <li><strong>存储取舍：</strong> 服务器持有当前树外加一棵暂存树；额外磁盘是原子性的代价。</li> </ul> <h2 id="为什么它胜过就地同步">为什么它胜过就地同步</h2> <p>就地同步承诺在线调整一棵树，但它无法原子地回答&quot;此刻正在被服务的字节是哪些&quot;，并且让回滚复杂化为&quot;回到昨天&quot;。完整目录交换用一个持久事实——被服务的目录名——来回答发布问题，让前进与后退都是单次重命名。</p> <h2 id="来源">来源</h2> <ul> <li><a href="https://www.martinfowler.com/bliki/BlueGreenDeployment.html">Martin Fowler：蓝绿部署</a>，完整树与蓝绿/暂存交换模型，已核验 2026-08-20。</li> <li><a href="https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html">POSIX <code>rename()</code></a>，支撑交换的原子重命名语义，已核验 2026-08-20。</li> </ul>