小系统的优势

Mon, 27 Jul 2026 00:00:00 +0000

小不等于未完成。它意味着每个组件职责清晰、依赖经过斟酌，并且从请求到结果之间始终可见。

明确每个请求边界、相关证据与负责人。组件更少只会减少需要理解的路径；恢复承诺仍靠备份与恢复演练支撑。

可见性是一种特性

当运维人员能说出每个边界时，他们也能指出缺少哪份证据。日志变得更有用，告警更具体，例行维护风险更低。

对静态网站而言，重要的边界通常很容易列出：

DNS 把主机名指向预期的边缘。
TLS 在预期的代理处终结。
代理只服务一个已知的输出目录。
输出只包含站点需要的文件。
404 响应由站点本身处理，而不是意外的上游。

把这些写下来，比加上一块回答不了任何上述问题的仪表盘更有价值。

复杂性要用实力取得位置

当新的一层消除的不确定性多于它引入的，它才值得。缓存重要时，给资源加指纹的构建步骤会有用；内容需要事务时，数据库才有用。但对一个小而多为静态的站点，这两者都不必然是改进。

对客户端 JavaScript 也适用同一规则。如果页面确实需要客户端脚本，应选择满足需求的最小实现，并有意识地审查内容安全策略。对本站而言，这首先需要重新评估已接受的零脚本架构及其验证契约，并不是当前策略的例外。如果页面是一份文档，纯 HTML 往往更容易检视、更有韧性。

让所有权明确

每个文件都应有存在的理由与明确的更新方式。vendored 主题应记录其上游版本与许可。生成目录应标记为生成物。资源下载应说明它包含什么、何时更新、校验和如何产生。

这些简短声明能防止未来的运维者把偶然产生的制品当作受支持的接口。

为下一次变更留出空间

最好的小系统不是行数最少的那个，而是下一次变更看得见去处的那一个。笔记站可以从 Markdown、静态生成器与一个 Web 服务器起步；如果以后需要搜索或评论，可以独立评估这个新需求，而不是一开始就假设它存在。

规模小并不自动带来容错。一个边缘、磁盘或运维者仍可能成为单点故障。明确可接受的恢复时间与数据损失，保留独立备份并演练恢复。组件更少的好处是需要理解的故障路径更少，而不是不会停机。

来源

Hugo directory structure，内容与资源的目录约定，已核验 2026-07-27。
Caddy file_server 指令，设计中引用的静态文件服务默认值，已核验 2026-07-27。

为什么小型站点可以保持静态

Mon, 08 Jun 2026 00:00:00 +0000

静态站点在请求到来之前准备好文档。判断是否适用，关键是不同访问者是否需要服务器即时生成不同表示，而不是站点到底有多少页面。几百篇文章也可以共享一条发布流程：编辑源文件、构建 HTML 和资源、检查生成结果，再通过服务器或 CDN 对外提供这些文件。页面数量本身不是引入动态运行时的充分理由。

把文档生成放在合适边界

一篇文章对每位读者含义相同，逐次请求重新拼装通常不会增加多少价值。模板、导航、翻译关系和索引都可以提前生成。对外服务此时依赖的是发布产物，而不是作者使用的内容数据库或生成器。请求仍然需要加密、日志、缓存和必要的访问控制；静态交付只改变文档生成时机，并没有消除托管层的这些职责。

静态 HTML 完全可以包含 JavaScript 和交互控件。规模适中的公开文集可以使用客户端搜索索引，私有搜索或个性化结果则需要能执行权限检查的服务。表单、评论、支付和需要登录的写入，同样要由合适的处理端负责。应逐个识别这些边界：文章静态化，并不意味着浏览器能够成为权限判断或持久状态的权威来源。

提前生成是转移工作，而不是消灭工作。大型文集可能重建缓慢，构建依赖可能失败，内容新鲜度也受到发布流水线限制。源文件刚刚保存，并不代表读者已经看到更新。对于有时效的内容，需要观察从编辑到发布的延迟、明确暴露构建失败，并直接验证发布后的页面，而不能以编辑器保存成功代替上线证据。

坏掉的样子

常见错误是把整个仓库根目录当成网站根目录。这样即使没有导航链接，源数据、构建脚本和私有草稿也可能被直接下载。应使用专门的输出目录，其中只放准备公开的产物。从文章索引隐藏一项，与从发布文件中排除它，是两件不同的事。检查必须覆盖真实文件清单，包括复制进来的附件以及生成的客户端搜索数据。

另一个问题是请求到来时逐个覆盖文件。新 HTML 可能先引用尚未上传的脚本，旧页面也可能在清理过程中失去依赖。应先准备完整发布集，保留必要的旧资源，再使用托管平台支持的切换机制。仅仅恢复旧源码提交，不会自动恢复当时的依赖、构建产物、缓存状态或外部服务，因此回退能力必须按真实交付链验证。

静态输出同样可能存在注入问题。来自不可信输入的文字需要按所在上下文转义，直接插进 HTML 可能把普通字段变成可执行标记。文本转义也不是万能的：它不负责判断任意链接是否安全，不负责清洗有意允许的富文本，更不能直接用于 JavaScript 上下文。应审阅实际模板位置和源数据的信任边界，而不是因为没有请求时渲染就默认安全。

修改源码不会自动发布。依据原文与明确限制静态绘制；未为本图重跑原文夹具。

快速验证

将下面程序保存为 static-build.py，用 Python 3 执行 python3 static-build.py。它先在临时目录创建内容源，并把源码放在 public 目录之外，再构建一个 HTML 文件。回环服务器只提供 public 内的文件。所有关键结果都通过实际 HTTP 请求确认；服务器关闭之后，实验创建的临时文件也会移除，不会修改现有站点。

from functools import partial
from hashlib import sha256
from html import escape
from http.client import HTTPConnection
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Thread
import json
import os


class Handler(SimpleHTTPRequestHandler):
 def log_message(self, *args):
 pass


with TemporaryDirectory() as directory:
 root = Path(directory)
 public = root / 'public'
 public.mkdir()
 source = root / 'source.json'
 source.write_text(json.dumps({'title': 'Version one', 'text': 'Published content'}))

 def build():
 content = json.loads(source.read_text())
 document = f'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>{escape(content["title"])}</title></head><body><h1>{escape(content["title"])}</h1><p>{escape(content["text"])}</p></body></html>'
 pending = root / 'next.html'
 pending.write_text(document)
 os.replace(pending, public / 'index.html')
 return document.encode()

 first = build()
 server = ThreadingHTTPServer(('127.0.0.1', 0), partial(Handler, directory=str(public)))
 thread = Thread(target=server.serve_forever)
 thread.start()
 try:
 def fetch(path='/'):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 return response.status, response.read()
 finally:
 connection.close()

 source.unlink()
 assert fetch() == (200, first)
 source.write_text(json.dumps({'title': 'Version two', 'text': '<b>literal text</b>'}))
 assert fetch() == (200, first)
 second = build()
 assert fetch() == (200, second) and second != first
 assert b'&lt;b&gt;literal text&lt;/b&gt;' in second
 assert fetch('/source.json')[0] == 404
 print(json.dumps({'serves_without_source': True, 'edit_requires_rebuild': True,
 'published_sha256': [sha256(first).hexdigest(), sha256(second).hexdigest()],
 'source_not_published': True, 'text_escaped': True}))
 finally:
 server.shutdown()
 thread.join()
 server.server_close()

首先，程序删除可编辑的内容源，仍然能够读取已经发布的页面字节。随后重新创建有改动的源文件，但在再次执行 build 之前，HTTP 请求仍返回第一版。第二次构建后，页面摘要发生变化，响应变为第二版。作为普通文字的 <b>literal text</b> 被转义，而不是成为真正的加粗标签；访问 /source.json 则收到 404。预期四个行为标志都为真，同时打印两个不同的发布摘要。

这些断言已经在 Python 3.14.4 下运行通过。程序通过同一文件系统上的 os.replace 替换一个完整文件，因此没有展示整个多资源站点的原子发布，也没有验证掉电持久性、自动回滚或某家托管平台的部署机制。实验的重点是证明源码与发布产物之间存在明确边界，不能把单文件行为推广成未经验证的整站承诺。

实际发布仍需检查全部生成文件，覆盖代表性链接及不存在的路径，并把缓存策略和资源可用性放在一起验证。静态交付适合生成边界与产品需求相符的场景；采用之后，也应分别观察构建层和服务层的健康状态，确保源文件中的正确修改确实能够成为用户收到的正确文档。

来源

GitHub Docs: About GitHub Pages，从已发布的 HTML、CSS 与 JavaScript 文件提供静态托管，已核验 2026-09-13。
MDN: Introduction to the server side，静态与动态响应的生成边界，已核验 2026-09-13。

Architecture · XB 现场笔记