<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Performance · 仁才德</title>
    <link>https://jared.lynskey.co.nz/zh-cn/tags/performance/</link>
    <description>关于软件工程与研发团队领导力的短文——绩效评估、招聘与团队扩张、CI/CD、DevOps 监控、智能体 AI。写于首尔。</description>
    <generator>Hugo</generator>
    <language>zh-CN</language>
    <copyright>© 2026 仁才德</copyright>
    <lastBuildDate>Sat, 21 Nov 2026 17:52:23 +0900</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/zh-cn/tags/performance/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>一个被关闭的 Pull Request、一个 fork 和一个 PyPI 包：给 Python 用的快速 HTML 转 Markdown</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-18-pyhtml2text/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-18-pyhtml2text/</guid>
      <pubDate>Sun, 18 Oct 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Python</category>
      <category>Rust</category>
      <category>PyPI</category>
      <category>Open Source</category>
      <category>Markdown</category>
      <category>LLM</category>
      <category>PyO3</category>
      <category>Performance</category>
      <description>为了给 AI agent 把 HTML 转成 Markdown，我需要把相对链接解析成绝对链接。上游的 Rust crate 没法接受我的 pull request，因为它是用 LLM 写的，于是我 fork 了它，发布了 pyhtml2text：带 base_url 的 Python 绑定、新的 html2markdown、用 profile-guided 优化构建的 wheel，以及一个打过补丁、能在线性时间内解析深层嵌套 HTML 的解析器。本文讲它为什么存在、里面有什么，以及我怎么检查输出是否正确。</description>
      <content:encoded><![CDATA[<p>10 月 15 日，我在 PyPI 上发布了 <a href="https://pypi.org/project/pyhtml2text/"  target="_blank" rel="noreferrer">pyhtml2text</a>。它把 HTML 转成纯文本或 Markdown，底层是 Chris Emerson 写的 Rust crate <a href="https://github.com/jugglerchris/rust-html2text"  target="_blank" rel="noreferrer">rust-html2text</a>。在我测过的页面上，转 Markdown 的速度是常见 Python 转换器的 3 到 21 倍。它还能根据页面的 URL 解析相对链接，这样输出里的链接离开原页面后依然能用。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pip install pyhtml2text</span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">pyhtml2text</span> <span class="kn">import</span> <span class="n">html2markdown</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html</span> <span class="o">=</span> <span class="s2">&#34;&#34;&#34;&lt;h2&gt;Before you start&lt;/h2&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;p&gt;Read the &lt;a href=&#34;setup.html&#34;&gt;setup guide&lt;/a&gt; and &lt;b&gt;back up&lt;/b&gt; your data.&lt;/p&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;img src=&#34;https://jared.lynskey.co.nz/img/diagram.png&#34; alt=&#34;How it fits together&#34;&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;table&gt;&lt;tr&gt;&lt;th&gt;Plan&lt;/th&gt;&lt;th&gt;Price&lt;/th&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Basic&lt;/td&gt;&lt;td&gt;Free&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">html2markdown</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/intro.html&#34;</span><span class="p">))</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gu">## Before you start
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Read the [<span class="nt">setup guide</span>](<span class="na">https://example.com/docs/setup.html</span>) and <span class="gs">**back up**</span> your data.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">![<span class="nt">How it fits together</span>](<span class="na">https://example.com/img/diagram.png</span>)
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">| Plan | Price |
</span></span><span class="line"><span class="cl">| --- | --- |
</span></span><span class="line"><span class="cl">| Basic | Free |</span></span></code></pre></div></div>
<p>它最初是给 rust-html2text 提的一个 pull request。维护者因为它是用 LLM 写的而关闭了它，所以 pyhtml2text 改为基于一个 fork 运行。这篇文章讲事情的经过、fork 和这个包里有什么，以及我怎么确认生成的 Markdown 是对的。</p>

<h2 class="relative group">为什么需要它
    <div id="为什么需要它" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e9%9c%80%e8%a6%81%e5%ae%83" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我做的一个集市兼社区应用，收到 <code>Accept: text/markdown</code> 的请求时会返回 Markdown 而不是 HTML，给那些不想在导航栏和页脚里翻找内容的 AI agent 和 LLM 客户端用。边缘那一侧的做法我在<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-09-cloudflare-crawlers-cache/" >关于爬虫和缓存的文章</a>里写过。由应用数据生成的页面，HTML 只是一个空的 JavaScript 外壳，所以直接生成 Markdown。其余都是静态 HTML（营销页、法律条款和博客），这部分要经过转换。</p>
<p>转换的麻烦在于链接。静态站点的页面里到处都是 <code>/en/posts/...</code> 和 <code>../setup/</code> 这样的链接。在浏览器里没问题，因为浏览器知道它们来自哪个页面。读 Markdown 的 agent 没有这个上下文，所以它没法打开 <code>/login</code>，它需要的是 <code>https://example.com/login</code>。</p>
<p>纯 Python 的 <a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a> 有一个 <code>baseurl</code> 选项专门做这件事，我一开始用的就是它。但它很慢，生成的 Markdown 也有一些问题，后面会讲到。rust-html2text 速度快、测试充分，但它没有办法解析链接。</p>

<h2 class="relative group">先问上游
    <div id="先问上游" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%85%88%e9%97%ae%e4%b8%8a%e6%b8%b8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>8 月 29 日，我提了 <a href="https://github.com/jugglerchris/rust-html2text/issues/287"  target="_blank" rel="noreferrer">issue #287</a>，写明了使用场景和我想要的行为：按 RFC 3986 解析，绝对 URL 以及 <code>mailto:</code>、<code>data:</code> 和 <code>#fragment</code> 链接保持不变。几分钟后，我提了 <a href="https://github.com/jugglerchris/rust-html2text/pull/288"  target="_blank" rel="noreferrer">pull request #288</a>。它加了一个 <code>Config::base_url(...)</code> 选项，我在 issue 里说明这只是一个起点，如果维护者想换一种做法，我完全理解。</p>
<p>10 月 11 日，维护者关闭了这个 PR：</p>
<blockquote><p>Thanks for the contribution, but I&rsquo;m unable to accept this as it appears to be LLM generated. (I have now added a brief policy to the README.md - it wasn&rsquo;t previously stated)</p>
</blockquote><p>（大意：感谢贡献，但我无法接受，因为它看起来是 LLM 生成的。我已经在 README.md 里加了一条简短的政策，之前没有写明。）</p>
<p>并在 issue 里回复：</p>
<blockquote><p>Hi - this is a reasonable feature request, thanks! I have closed the PR as it appears to be LLM-written which I can&rsquo;t accept, but thanks for the attempt.</p>
<p>A short HTML sample and expected output would definitely help get the feature implemented!</p>
</blockquote><p>（大意：这是个合理的功能请求，谢谢！PR 看起来是 LLM 写的，我无法接受，所以关闭了，但感谢你的尝试。如果能提供一小段 HTML 示例和期望的输出，肯定有助于实现这个功能！）</p>
<p>现在 README 里有这样一条政策：</p>
<blockquote><p>At this time, this project is not able to accept code contributions produced with generative AI/LLMs due to the uncertain copyright status.</p>
</blockquote><p>（大意：由于版权状态尚不明确，本项目目前无法接受由生成式 AI/LLM 产出的代码贡献。）</p>
<p>维护者的判断没错：那段代码确实是我用 AI 编程助手写的。我也不觉得这条政策不合理。LLM 输出的版权归属还没有定论，而把它合进一个许多项目都依赖的 MIT crate，风险是由维护者来承担的。这是对方的项目，而且回复也很客气。那个功能请求现在仍然开着。</p>
<p>不过我还是需要这个功能，而跟维护者争论对方自己定的贡献政策，并不是拿到它的好办法。所以我把改动留在一个 fork 上，在它之上构建了 Python 包，两者都清楚写明了自己不是上游。</p>

<h2 class="relative group">fork 里有什么
    <div id="fork-里有什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#fork-%e9%87%8c%e6%9c%89%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>fork 是我那个 rust-html2text fork 里的 <code>pyhtml2text-perf</code> 分支。为了能干净地 rebase 到上游，我只保留了三个小提交。最主要的是 PR 里那个 <code>Config::base_url</code> 选项：按 <a href="https://www.rfc-editor.org/rfc/rfc3986#section-5.3"  target="_blank" rel="noreferrer">RFC 3986 §5.3</a> 解析相对链接，不传 base URL 时输出完全不变。另一个提交让 crate 不再每次调用都重建样式规则，短片段的耗时从 7.3 µs 降到 5.6 µs。大页面上这点差别可以忽略，但调用几千次就积少成多了。第三个只是把下文 Markdown 转换器需要的部分从 crate 里导出来。</p>

<h2 class="relative group">Python 包
    <div id="python-包" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#python-%e5%8c%85" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><a href="https://github.com/jaredlynskey/pyhtml2text"  target="_blank" rel="noreferrer">pyhtml2text</a> 用 PyO3 和 maturin 构建，提供两个函数：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">pyhtml2text</span> <span class="kn">import</span> <span class="n">html2text</span><span class="p">,</span> <span class="n">html2markdown</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html2text</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">80</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">decorate</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">link_footnotes</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">          <span class="n">table_borders</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">wrap_links</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">max_wrap_width</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html2markdown</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></span></span></code></pre></div></div>
<p><code>html2text</code> 就是 rust-html2text 的纯文本渲染器，它是为终端和电子邮件的 <code>text/plain</code> 部分设计的：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">html2text</span><span class="p">(</span><span class="s1">&#39;&lt;p&gt;Please &lt;a href=&#34;https://jared.lynskey.co.nz/login&#34;&gt;sign in&lt;/a&gt; first.&lt;/p&gt;&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">                <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/page.html&#34;</span><span class="p">))</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Please [sign in][1] first.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">[1]: https://example.com/login</span></span></code></pre></div></div>
<p>关于这些绑定，有几点可能不那么显而易见：</p>
<ul>
<li><strong>两个函数都接受 <code>str</code> 或 UTF-8 的 <code>bytes</code></strong>，所以可以直接传 <code>response.content</code>，不用先解码。输入是借用的，不会复制。</li>
<li><strong>转换期间会释放 GIL。</strong> 从头到尾都是纯 Rust，所以多线程能用满多个核。模块还声明了自己不需要 GIL，因此在 free-threaded 的 Python 3.14t 上，导入它时不会把 GIL 重新打开。</li>
<li><strong>panic 会变成 <code>ValueError</code>。</strong> PyO3 默认抛出的是 <code>PanicException</code>，而 <code>except Exception</code> 捕获不到它。一个以为自己已经处理好转换错误的 web worker 会因此崩掉，所以绑定层把它捕获下来，重新抛成 <code>ValueError</code>。</li>
<li><strong>一共有 30 个 wheel：</strong> CPython 3.10 及以上的 abi3 wheel，加上 free-threaded 3.14t 的 wheel，覆盖 Linux（glibc 和 musl）、macOS 和 Windows 上 maturin 的 CI 能构建的所有架构。所以安装时谁都不需要 Rust 工具链。</li>
</ul>

<h2 class="relative group">让它变快
    <div id="让它变快" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%ae%a9%e5%ae%83%e5%8f%98%e5%bf%ab" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>0.2.0 在真实页面上比 0.1.0 快 1.5 到 1.7 倍，短片段上快一倍，输出逐字节一致。大部分提升来自配置文件引导优化（PGO）：CI 先构建一个插桩版 wheel，在一组由文档页面和 RFC 组成的训练集上跑一遍，再用得到的 profile 构建正式的 wheel。在训练集以外的页面上大约快 25%，只在 CI 能原生运行插桩构建的平台上启用。剩下的来自换用 mimalloc 分配器（大量小块分配时它比系统分配器强得多），以及 fork 里那个样式规则的改动。</p>
<p>为了确认提速没有改变任何输出，我把一批真实页面用每一组选项都转换一遍，记录输出的哈希，还加上了空输入、极深嵌套之类的边界情况。每个改动都必须让所有哈希保持不变。</p>
<p>下面是在 Apple Silicon Mac 上转 Markdown 的中位耗时：</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>在线百科条目（1 MB）</th>
					<th>新闻网站首页（370 KB）</th>
					<th>Python 文档页（245 KB）</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><a href="https://pypi.org/project/markdownify/"  target="_blank" rel="noreferrer">markdownify</a></td>
					<td>184 ms</td>
					<td>28 ms</td>
					<td>97 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a>（纯 Python）</td>
					<td>73 ms</td>
					<td>13 ms</td>
					<td>37 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html-to-markdown/"  target="_blank" rel="noreferrer">html-to-markdown</a></td>
					<td>44 ms</td>
					<td>5.6 ms</td>
					<td>15 ms</td>
			</tr>
			<tr>
					<td><strong>pyhtml2text</strong></td>
					<td><strong>14 ms</strong></td>
					<td><strong>1.7 ms</strong></td>
					<td><strong>4.5 ms</strong></td>
			</tr>
	</tbody>
</table>
<p>转纯文本：</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>在线百科条目（780 KB）</th>
					<th>新闻网站首页（370 KB）</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a>（纯 Python）</td>
					<td>71.5 ms</td>
					<td>14.9 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html2text-rs/"  target="_blank" rel="noreferrer">html2text-rs</a></td>
					<td>15.2 ms</td>
					<td>2.5 ms</td>
			</tr>
			<tr>
					<td><strong>pyhtml2text</strong></td>
					<td><strong>10.9 ms</strong></td>
					<td><strong>1.6 ms</strong></td>
			</tr>
	</tbody>
</table>

<h2 class="relative group">深层嵌套的 HTML，以及给 html5ever 打的补丁
    <div id="深层嵌套的-html以及给-html5ever-打的补丁" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b7%b1%e5%b1%82%e5%b5%8c%e5%a5%97%e7%9a%84-html%e4%bb%a5%e5%8f%8a%e7%bb%99-html5ever-%e6%89%93%e7%9a%84%e8%a1%a5%e4%b8%81" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>没人会手写 40,000 层嵌套的列表。但如果你要转换不是自己写的页面，迟早会碰到某个恶意的或者坏掉的页面给你来这么一下。用原版解析器，解析 40,000 层嵌套的 <code>&lt;ul&gt;&lt;li&gt;</code> 要 <strong>6 秒</strong>，也就是一个 worker 被一个请求卡住 6 秒。</p>
<p>原因在 rust-html2text 使用的 HTML5 解析器 <a href="https://github.com/servo/html5ever"  target="_blank" rel="noreferrer">html5ever</a>。大多数块级开始标签都要检查是否有一个打开的 <code>&lt;p&gt;</code> 元素处于 &ldquo;button scope&rdquo; 之内，而 html5ever 每次都要把打开元素的栈从头到尾走一遍。嵌套越深，每个标签花的时间越长，总时间随深度的平方增长。</p>
<p>这个包附带了打过一个补丁的 html5ever 0.39.0。补丁让这个答案在元素打开和关闭时随时更新，所以检查的耗时不再取决于嵌套深度。同一个文档现在 <strong>0.14 秒</strong>就解析完了。为了确保补丁没有改变别的行为，我在 html5lib 的全部树构建测试、约 20 个真实页面和 30 万个随机标签汤文档上，对比了原版和补丁版解析器生成的 DOM，结果完全一致。</p>
<p>出于同样的原因，Markdown 转换器也设了上限：任何输入都不会撑爆线程栈；引用块和列表超过 32 层就不再缩进，免得输出按平方膨胀；展开后网格超过 100,000 个单元格的表格，只输出单元格内容。</p>

<h2 class="relative group">html2markdown
    <div id="html2markdown" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#html2markdown" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>0.3.0 版加入了 <code>html2markdown</code>，这个包的大部分工作都花在它上面。rust-html2text 的渲染器输出的文本看起来像 Markdown，但它是按终端宽度折行的，并不打算被解析。所以 <code>html2markdown</code> 只借用它的解析器，输出则自己来写：<a href="https://commonmark.org/"  target="_blank" rel="noreferrer">CommonMark</a>，外加 GitHub 风格的管道表格和 <code>~~删除线~~</code>：</p>
<ul>
<li><code>#</code> 标题、<code>-</code> 列表、<code>_强调_</code> 和 <code>**加粗**</code>。</li>
<li>行内链接和图片，给了 <code>base_url</code> 时转成绝对地址。如果一个链接里只有图标，就用它的 <code>aria-label</code> 或 <code>title</code> 作为链接文字。</li>
<li>围栏代码块，页面标明了语言时（<code>class=&quot;language-python&quot;</code>）会带上语言标记。</li>
<li>管道表格。跨行或跨列的单元格变成空单元格，没有表头行的表格会补一个空表头，用来做页面布局的表格则写成普通段落。</li>
<li>不折行。隐藏内容（<code>hidden</code>、<code>aria-hidden</code>、<code>display: none</code>）、脚本、样式和表单控件都会被去掉。</li>
</ul>

<h3 class="relative group">只转义需要转义的
    <div id="只转义需要转义的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8f%aa%e8%bd%ac%e4%b9%89%e9%9c%80%e8%a6%81%e8%bd%ac%e4%b9%89%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>有些 HTML 转 Markdown 的工具会把所有可能是 Markdown 语法的字符都转义掉。比如 markdownify 默认会转义每一个 <code>_</code> 和 <code>*</code>。这样的输出是正确的，但满篇都是 <code>snake\_case</code> 和 <code>5 \* 3</code>，人读起来费劲，对模型来说也是浪费 token。pyhtml2text 只在 CommonMark 解析器会把某个字符当成语法的地方才转义它：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">html2markdown</span><span class="p">(</span><span class="s1">&#39;&lt;p&gt;Use &lt;code&gt;snake_case&lt;/code&gt;, 5 * 3, $5 and &#39;</span>
</span></span><span class="line"><span class="cl">              <span class="s1">&#39;&lt;a href=&#34;../setup.html&#34;&gt;setup&lt;/a&gt;&lt;/p&gt;&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">              <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/intro.html&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">Use <span class="sb">`snake_case`</span>, 5 * 3, $5 and [<span class="nt">setup</span>](<span class="na">https://example.com/setup.html</span>)</span></span></code></pre></div></div>

<h3 class="relative group">韩语助词前的加粗
    <div id="韩语助词前的加粗" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%9f%a9%e8%af%ad%e5%8a%a9%e8%af%8d%e5%89%8d%e7%9a%84%e5%8a%a0%e7%b2%97" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>这个问题来自我那个应用自己的页面。韩语的助词紧跟在名词后面，中间没有空格，所以一个带括号的加粗词语是这样的：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;&lt;</span><span class="nt">b</span><span class="p">&gt;</span>타이타닉(Titanic)<span class="p">&lt;/</span><span class="nt">b</span><span class="p">&gt;</span>의 감독<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span></span></span></code></pre></div></div>
<p>最直接的 Markdown 写法是 <code>**타이타닉(Titanic)**의</code>，markdownify 输出的就是这个，但它不起作用。CommonMark 的 flanking 规则规定，<code>**</code> 跟在标点后面时，只有后面紧接空格或另一个标点才能闭合，而 <code>의</code> 是一个字母，所以这些星号会原样留在文本里。纯 Python 的 html2text 的办法是加一个空格：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">**타이타닉(Titanic)** 의 감독</span></span></code></pre></div></div>
<p>这样能渲染出加粗，但改动了韩语原文。助词变成了一个单独的词，在韩语里这是拼写错误。pyhtml2text 的做法是把标点移到标记外面：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">**타이타닉(Titanic**)의 감독</span></span></code></pre></div></div>
<p>括号不再是粗体，但强调依然能正确解析，原文的每个字符也都保留了下来。日语和中文也是同样的道理：中文词与词之间没有空格，一段以括号结尾的加粗文字后面如果直接跟着&quot;的&quot;之类的字，也会碰到同样的问题。任何不在后续文字前加空格的语言都一样。</p>

<h3 class="relative group">读回来检查输出
    <div id="读回来检查输出" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%af%bb%e5%9b%9e%e6%9d%a5%e6%a3%80%e6%9f%a5%e8%be%93%e5%87%ba" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>我不会因为一个转换器的单元测试都通过了就相信它，因为 Markdown 输出里的 bug 往往藏在没人想到要写测试的组合里。所以输出要读回来检查。</p>
<p>转换时，每个段落都会按 CommonMark 重新解析一次，确认强调读回来符合预期。如果不符合，就换另一种强调写法重写（用 <code>*</code> 代替 <code>_</code>，或者反过来）；两种都不行，就保留文字、链接和代码，去掉格式，保证一个字都不丢。测试套件则用另一个 Markdown 解析器做往返检查，把每一个可见的词、链接地址和图片地址同原始 HTML 逐一比较。因为没转义而被语法吞掉的文字、没解析出来的链接、多出来的 <code>*</code>，都会作为差异显示出来。它在真实页面和成千上万个随机文档上运行，出错时还会把文档缩减成最小的复现用例。</p>

<h2 class="relative group">上线
    <div id="上线" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8a%e7%ba%bf" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>0.3.0 发布当天，我那个应用的 Markdown 内容协商就从纯 Python 的 html2text 换成了 pyhtml2text。在其中一个指南页面上，转换时间从 4.2 ms 降到了 0.36 ms，快了大约 12 倍。链接都是绝对地址，表格是真正的管道表格，韩语的加粗也不会再把助词分开。abi3 wheel 本来就覆盖了 x86_64 和 arm64 上的 Python 3.14，所以容器镜像不需要加任何新东西就能装上它。</p>

<h2 class="relative group">致谢，以及在哪里报告 bug
    <div id="致谢以及在哪里报告-bug" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%87%b4%e8%b0%a2%e4%bb%a5%e5%8f%8a%e5%9c%a8%e5%93%aa%e9%87%8c%e6%8a%a5%e5%91%8a-bug" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>纯文本渲染来自 Chris Emerson 的 rust-html2text，采用 MIT 许可证。pyhtml2text 在此之上加了它的一个 fork、一份打过补丁的 html5ever（MIT/Apache-2.0）以及 Markdown 转换器。这个包与这两个项目都没有关联，也没有得到它们的认可，所以<strong>有问题请报到 <a href="https://github.com/jaredlynskey/pyhtml2text/issues"  target="_blank" rel="noreferrer">pyhtml2text 的 issue 页面</a></strong>，不要报到上游。这些代码里的 bug 由我来修，上游维护者不应该收到关于他们拒绝接受的代码的报告。</p>
<p>如果你在用 Python 转换 HTML，特别是要给模型读的，不妨试试：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pip install pyhtml2text</span></span></code></pre></div></div>
<p>源码在 <a href="https://github.com/jaredlynskey/pyhtml2text"  target="_blank" rel="noreferrer">GitHub</a> 上，changelog 里列出了 0.1.0 到 0.3.0 的所有改动。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-18-pyhtml2text/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Fly.io 冷启动为什么慢：缩容到零后，从 33 秒降到 3 秒</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-09-scale-to-zero-504s/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-09-scale-to-zero-504s/</guid>
      <pubDate>Wed, 09 Sep 2026 00:00:00 +1200</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Fly.io</category>
      <category>Django</category>
      <category>DevOps</category>
      <category>Cloudflare</category>
      <category>Performance</category>
      <category>Cold Starts</category>
      <category>Redis</category>
      <category>Debugging</category>
      <description>在 Fly.io 上用 auto_stop_machines 缩容到零，请求落到已停止的机器上就得等它启动。我的冷启动要 25 到 33 秒，这篇讲我怎么把它降到 3 秒左右。</description>
      <content:encoded><![CDATA[<p><strong>更新（2026 年 10 月 22 日）</strong>：这篇文章最核心的数字是错的。发布当天，我把这个 zone 的 504 按 user agent 分组，发现 9 月 5 日到 9 日的 7,344 个 504 全部来自 Cloudflare 自己的 Early Hints 探测请求（<code>bastion early hints</code> 和 <code>nginx-ssl early hints</code>）。这些请求从 Fly 源站拿不到任何响应，被记成 504，而且沿用真实请求的路径，看起来和用户侧故障一模一样。同一时期，真实客户端（应用、浏览器、curl、搜索引擎爬虫）一个 504 都没收到。源站本来就不发 preload 头，Early Hints 什么忙也没帮上，所以我当天就把它关了。下面的冷启动是真的，解决办法也依然有效，但 22% 从来不是我的用户遇到的数字。在把 Cloudflare 的 5xx 比例当成故障之前，先看看是哪些 user agent 在收到这些错误。</p>
<p><strong>更新（2026 年 11 月 4 日）</strong>：再更正一点。这些 504 并不是源站没能响应的探测请求，而是 Cloudflare 自己的 Early Hints 缓存查询，根本不会到达源站；这里的 504 只表示这个 URL 没有缓存任何内容。关掉 Early Hints 也不是最好的办法：发送 <code>Link</code> 响应头之后，这个功能开始生效，这些未命中也变成了命中。完整经过见《<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/cloudflare-504-early-hints/" >Cloudflare 504 错误其实不是故障：Early Hints 与 HTTP 103 详解</a>》。</p>
<p>先说结论：开启 <code>auto_stop_machines</code> 后，落到已停止的 Fly.io 机器上的请求要等整台机器启动完。我的机器冷启动要 25 到 33 秒，因为每次机器启动，entrypoint 都会跑一遍 Django 迁移和 <code>collectstatic</code>，而字节码从来没人缓存过。把这些发布相关的工作改成每个镜像只做一次（用以 <code>FLY_IMAGE_REF</code> 为键的 Redis 锁），再在构建时加上 <code>compileall</code>，冷启动降到了 9 秒左右。最后把 <code>auto_stop_machines</code> 从 <code>'stop'</code> 改成 <code>'suspend'</code>（为此得先去掉 swap，Fly 不允许挂起带 swap 的机器），唤醒只要 3 秒左右。</p>
<p>我本来只是去 Cloudflare 面板上看一个流量尖峰，结果在它下面发现了严重得多的东西：一天之内，应用处理的请求有 22% 是失败的。没有任何告警触发，健康检查全是绿的，日志看起来也完全正常。因为那些失败的请求，根本没有到达应用。</p>
<p>原因是我自己写的容器启动脚本，在完全错误的时机做着完全合理的事。</p>

<h2 class="relative group">尖峰是个幌子
    <div id="尖峰是个幌子" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%b0%96%e5%b3%b0%e6%98%af%e4%b8%aa%e5%b9%8c%e5%ad%90" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我最初想解释的是这样一个小时：约 4,900 个请求，而中位数是每小时 121 个。独立访客 42 个。也就是每人 110 个请求，人类不是这么浏览网页的。</p>
<p>是扫描器。一个机器人在编造子域名，挨个向它们索要密钥文件：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">api-stage-asia.example.com/.env.local
</span></span><span class="line"><span class="cl">api-us-east-1-demo.example.com/.env
</span></span><span class="line"><span class="cl">api-eu-uat.example.com/wp-config.php~
</span></span><span class="line"><span class="cl">app-test-us-east-1.example.com/actuator/configprops
</span></span><span class="line"><span class="cl">prod-api-use2.example.com/.env.local
</span></span><span class="line"><span class="cl">relay.example.com/.env.production</span></span></code></pre></div></div>
<p>三十来个主机名，你能想到的每一种 <code>.env</code> 变体，外加冲着 Django 应用要的某个 Java 框架的 actuator 端点。它们全部拿到了指向规范主机的 301，什么也没被返回。乏味，而且确实无害。</p>
<p>不过既然分析页面开着，我顺手把同一天按状态码分组了。真正的问题在那里。</p>
<table>
	<thead>
			<tr>
					<th>状态码</th>
					<th>24 小时请求数</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>总计</td>
					<td>11,350</td>
			</tr>
			<tr>
					<td>504 Gateway Timeout</td>
					<td>2,474</td>
			</tr>
	</tbody>
</table>
<p>22%。而且不是均匀散布在整个站点，而是精确地压在最疼的地方：</p>
<table>
	<thead>
			<tr>
					<th>端点</th>
					<th>504</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>通知未读数</td>
					<td>621</td>
			</tr>
			<tr>
					<td>通知列表</td>
					<td>614</td>
			</tr>
			<tr>
					<td>消息未读数</td>
					<td>469</td>
			</tr>
			<tr>
					<td>信息流游标</td>
					<td>210</td>
			</tr>
	</tbody>
</table>
<p>这些都是移动端每 30 秒轮询一次的端点。所以这不是一个抽象的错误率数字，而是用户的手机整天、大概持续了好几周，都在悄悄加载不出未读角标。</p>

<h2 class="relative group">日志为什么看起来正常
    <div id="日志为什么看起来正常" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%97%a5%e5%bf%97%e4%b8%ba%e4%bb%80%e4%b9%88%e7%9c%8b%e8%b5%b7%e6%9d%a5%e6%ad%a3%e5%b8%b8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我的第一反应是应用变慢了。并没有。我从日志归档里翻出最糟糕那个小时里应用自己的请求日志：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">[2026-09-08 01:00:29] &#34;GET /api/notifications/unread/&#34; 304 61.615
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:29] &#34;GET /api/notifications/&#34;        304 63.568
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:59] &#34;GET /api/notifications/unread/&#34; 304 58.742
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:59] &#34;GET /api/notifications/&#34;        304 105.438</span></span></code></pre></div></div>
<p>44 到 105 毫秒，清一色 304。源站很快。</p>
<p>这是关键线索，值得写成一条规则：<strong>如果边缘报告的错误是源站从没听说过的，那么请求是在到达之前就死掉了。</strong> 别再读应用日志，去看它前面的那一层。</p>
<p>在我这里就是 Fly.io 的代理，答案藏在机器的调度方式里。</p>

<h2 class="relative group">缩容到零是关于成本的承诺，不是关于延迟的
    <div id="缩容到零是关于成本的承诺不是关于延迟的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%bc%a9%e5%ae%b9%e5%88%b0%e9%9b%b6%e6%98%af%e5%85%b3%e4%ba%8e%e6%88%90%e6%9c%ac%e7%9a%84%e6%89%bf%e8%af%ba%e4%b8%8d%e6%98%af%e5%85%b3%e4%ba%8e%e5%bb%b6%e8%bf%9f%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我的配置是这样，乍看之下相当合理：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;stop&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_start_machines</span> <span class="p">=</span> <span class="kc">true</span>
</span></span><span class="line"><span class="cl">  <span class="nx">min_machines_running</span> <span class="p">=</span> <span class="mi">1</span></span></span></code></pre></div></div>
<p>空闲的机器停掉，来流量再启动，用多少付多少。对于流量有峰谷的小应用，这正是你想要的，也正因如此我定义了十台机器，平时却只有一台在跑。</p>
<p>它藏起来的账单是延迟。当一个请求打到一台已停止的机器上，总得有人等它启动完。如果启动比代理的耐心更久，这个人就会拿到 504。</p>
<p>那么我的机器启动要多久？我从来没量过。日志归档知道，因为启动脚本会打印每个阶段，而且每一行都带着机器 ID：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">WITH</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">SELECT</span><span class="w"> </span><span class="n">instance</span><span class="p">,</span><span class="w"> </span><span class="k">timestamp</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">         </span><span class="k">CASE</span><span class="w"> </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Starting app server%&#39;</span><span class="w"> </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;begin&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Migrations complete%&#39;</span><span class="w"> </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;migrated&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">LIKE</span><span class="w">  </span><span class="s1">&#39;%&#34;GET /healthz%&#39;</span><span class="w">       </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;serving&#39;</span><span class="w"> </span><span class="k">END</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">phase</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">FROM</span><span class="w"> </span><span class="n">logs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">WHERE</span><span class="w"> </span><span class="n">app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;myapp&#39;</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="k">timestamp</span><span class="p">::</span><span class="nb">date</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;2026-09-08&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="n">instance</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;begin&#39;</span><span class="p">)</span><span class="w">    </span><span class="k">AS</span><span class="w"> </span><span class="n">started</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;migrated&#39;</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">migrated</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;serving&#39;</span><span class="p">)</span><span class="w">  </span><span class="k">AS</span><span class="w"> </span><span class="n">first_serve</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="k">GROUP</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="n">instance</span></span></span></code></pre></div></div>
<p>在每一台机器上，答案都一致：</p>
<table>
	<thead>
			<tr>
					<th>阶段</th>
					<th>耗时</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>启动到迁移完成</td>
					<td>10 到 13 秒</td>
			</tr>
			<tr>
					<td>迁移到处理第一个请求</td>
					<td>8 到 19 秒</td>
			</tr>
			<tr>
					<td><strong>合计</strong></td>
					<td><strong>25 到 33 秒</strong></td>
			</tr>
	</tbody>
</table>
<p>然后我数了数这件事发生的频率：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="k">count</span><span class="p">(</span><span class="o">*</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">starts</span><span class="p">,</span><span class="w"> </span><span class="k">count</span><span class="p">(</span><span class="k">DISTINCT</span><span class="w"> </span><span class="n">instance</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">machines</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">logs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="n">app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;myapp&#39;</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="k">timestamp</span><span class="p">::</span><span class="nb">date</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;2026-09-08&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">AND</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Starting app server%&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1">-- starts: 92, machines: 10</span></span></span></code></pre></div></div>
<p>一天 92 次冷启动。每一次都打开一个半分钟的窗口，任何被路由到那台机器的请求都会超时。22% 不再神秘了。</p>

<h2 class="relative group">原因就在我自己的 entrypoint 里
    <div id="原因就在我自己的-entrypoint-里" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8e%9f%e5%9b%a0%e5%b0%b1%e5%9c%a8%e6%88%91%e8%87%aa%e5%b7%b1%e7%9a%84-entrypoint-%e9%87%8c" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>这是每一台机器在响应任何请求之前都要跑的东西：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># entrypoint.sh, run on every machine start</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Running migrations...&#34;</span>
</span></span><span class="line"><span class="cl">python manage.py migrate --noinput
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Running collectstatic in background...&#34;</span>
</span></span><span class="line"><span class="cl">python manage.py collectstatic --noinput <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span>    <span class="c1"># then start the app server</span></span></span></code></pre></div></div>
<p>带着「一天 92 次」再读一遍。</p>
<p><code>migrate</code> 是一次完整的 Django 启动：导入所有模型、连上 Postgres、查询迁移表，然后判定无事可做。在共享 CPU 上，为了什么也不做花掉十秒。<code>collectstatic</code> 是第二次完整的 Django 启动，之后还要把静态文件上传到对象存储，同时和正在启动的 Web 服务器抢同一个核心。应用服务器是第三次启动。</p>
<p>三个 Python 解释器，其中两个在重复已经做过的事，机器每醒来一次就来一遍。</p>
<p>当初这么写的理由是站得住脚的，你的代码大概也长得差不多：迁移总得在某处执行，Fly 的 <code>release_command</code> 曾经卡住过，而 entrypoint 是唯一保证会在部署时执行的地方。把部署工作放在这里是对的，只是把它放在<strong>每次机器启动</strong>时不对。而一旦你的机器开始自己停自己起，这两件事就不再是同一个事件了。</p>
<p>整个 bug 就是这一句，我认为它相当常见：</p>
<blockquote><p>属于<strong>发布</strong>的工作，被按<strong>机器启动</strong>执行了。缩容到零把一个事件变成了九十二个。</p>
</blockquote>
<h2 class="relative group">解法：把发布只认领一次
    <div id="解法把发布只认领一次" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%a7%a3%e6%b3%95%e6%8a%8a%e5%8f%91%e5%b8%83%e5%8f%aa%e8%ae%a4%e9%a2%86%e4%b8%80%e6%ac%a1" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>某个镜像的第八台机器不需要跑迁移。这个镜像只需要跑一次，其他机器只需要知道已经跑过了。</p>
<p>这就是一把每次部署都换名字的锁。Fly 用 <code>FLY_IMAGE_REF</code> 白送了这个名字，而 Redis 我本来就有。整个东西是一个在 Django 存在之前就运行的小脚本，所以常见情况下的答案是毫秒级，而不是一次框架启动：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># release_gate.py: runs before Django exists. Exit code 0 means &#34;prepare this release&#34;.</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">time</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">PREPARE</span><span class="p">,</span> <span class="n">SKIP</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>
</span></span><span class="line"><span class="cl"><span class="n">LOCK_TTL</span><span class="p">,</span> <span class="n">WAIT</span><span class="p">,</span> <span class="n">POLL</span> <span class="o">=</span> <span class="mi">300</span><span class="p">,</span> <span class="mi">240</span><span class="p">,</span> <span class="mi">2</span>
</span></span><span class="line"><span class="cl"><span class="n">_sleep</span><span class="p">,</span> <span class="n">_monotonic</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">,</span> <span class="n">time</span><span class="o">.</span><span class="n">monotonic</span>    <span class="c1"># aliases, so tests can replace them</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">release_id</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;&#34;&#34;Something that changes exactly when the deployed image does.&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_IMAGE_REF&#34;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_MACHINE_VERSION&#34;</span><span class="p">)</span> <span class="ow">or</span> <span class="s2">&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">claim</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">release</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">release</span><span class="p">:</span>   <span class="c1"># no Redis, or no idea which release: behave as before</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">PREPARE</span>
</span></span><span class="line"><span class="cl">    <span class="n">done_key</span><span class="p">,</span> <span class="n">lock_key</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;release:</span><span class="si">{</span><span class="n">release</span><span class="si">}</span><span class="s2">:done&#34;</span><span class="p">,</span> <span class="sa">f</span><span class="s2">&#34;release:</span><span class="si">{</span><span class="n">release</span><span class="si">}</span><span class="s2">:lock&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">done_key</span><span class="p">):</span>            <span class="c1"># somebody already did it for this image</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">SKIP</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="n">owner</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_MACHINE_ID&#34;</span><span class="p">,</span> <span class="s2">&#34;unknown&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">lock_key</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="n">LOCK_TTL</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">PREPARE</span>                  <span class="c1"># we won the race; we do the work</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Someone else is preparing. Wait for them, because serving requests</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># against a half-migrated schema is worse than starting slowly.</span>
</span></span><span class="line"><span class="cl">    <span class="n">deadline</span> <span class="o">=</span> <span class="n">_monotonic</span><span class="p">()</span> <span class="o">+</span> <span class="n">WAIT</span>
</span></span><span class="line"><span class="cl">    <span class="k">while</span> <span class="n">_monotonic</span><span class="p">()</span> <span class="o">&lt;</span> <span class="n">deadline</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">_sleep</span><span class="p">(</span><span class="n">POLL</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">done_key</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="n">SKIP</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">lock_key</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="n">LOCK_TTL</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="n">PREPARE</span>              <span class="c1"># the owner died and its lock expired; take over</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">PREPARE</span>                      <span class="c1"># waited long enough; do it ourselves</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE</span></span></span></code></pre></div></div>
<p>entrypoint 变成一个 <code>if</code>：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="k">if</span> python3 release_gate.py claim<span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    python manage.py migrate --noinput
</span></span><span class="line"><span class="cl">    python manage.py collectstatic --noinput <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">    python3 release_gate.py <span class="k">done</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span></span></span></code></pre></div></div>

<h2 class="relative group">每一种失败都必须落在「那就准备」上
    <div id="每一种失败都必须落在那就准备上" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%af%8f%e4%b8%80%e7%a7%8d%e5%a4%b1%e8%b4%a5%e9%83%bd%e5%bf%85%e9%a1%bb%e8%90%bd%e5%9c%a8%e9%82%a3%e5%b0%b1%e5%87%86%e5%a4%87%e4%b8%8a" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>比起代码，这一节更值得抄走。</p>
<p>这样一个门闩，站在你的用户和一次库迁移之间。如果它朝<strong>跳过</strong>的方向出错，你就会对着一个没迁移的数据库提供服务，那是真正的故障。如果它朝<strong>准备</strong>的方向出错，你只是把一次幂等的空迁移跑了两遍，浪费十秒。</p>
<p>这两个结果并不对称，所以代码也不能对称地对待它们。每一条不确定的路径都返回 <code>PREPARE</code>：</p>
<ul>
<li><strong>没有 Redis，或者 Redis 不可达。</strong> 准备。这正是旧行为，于是缓存故障退化成「慢」，而不是「坏」。</li>
<li><strong>环境里没有镜像引用。</strong> 准备。我不知道这是哪个发布，也就无从知道它是否就绪。</li>
<li><strong>锁的持有者在迁移途中死了。</strong> 它的锁过期，下一个等待者接管并准备。</li>
<li><strong>等待超过了超时时间。</strong> 还是准备。一台永远不提供服务的机器，比一次重复迁移更糟。</li>
</ul>
<p>反方向上我故意留了一处不对称：发现另一台机器确实握着锁的机器会<strong>等待</strong>，而不是开始服务。部署期间启动慢一点没关系，对着只迁移了一半的表结构接受查询则不行。</p>
<p>如果你把它建在一个会吞掉连接错误的缓存包装器上（我一开始就是这么做的），有一个陷阱。这种包装器在 Redis 不可达时让 <code>add()</code> 返回 <code>False</code>，而这读起来和「别人正持有锁」一模一样，那会让每台机器都跳过迁移——恰好是危险的那个方向。用回读锁来区分：一把没有任何人持有的锁，意味着缓存坏了，而不是你输掉了竞争。</p>

<h2 class="relative group">不用 Redis 也能测
    <div id="不用-redis-也能测" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8d%e7%94%a8-redis-%e4%b9%9f%e8%83%bd%e6%b5%8b" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>这段逻辑值得写单元测试，因为真正有意思的路径恰恰是你没法手工复现的。一个两方法的假对象就够了：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">FakeRedis</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;&#34;&#34;Enough of a Redis client for the gate: get, and set with nx/ex.&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">nx</span> <span class="ow">and</span> <span class="n">key</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">None</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="kc">True</span></span></span></code></pre></div></div>
<p>然后按自己的节奏推动时间，去跑那些别扭的分支。这也是门闩调用模块级的 <code>_sleep</code> 和 <code>_monotonic</code> 别名，而不直接调用 <code>time.sleep</code> 的原因，这样测试替换它们时不会波及同进程里的其他线程：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">test_a_waiter_takes_over_when_the_owner_disappears</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">redis</span> <span class="o">=</span> <span class="n">FakeRedis</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">release_gate</span><span class="o">.</span><span class="n">claim</span><span class="p">(</span><span class="n">redis</span><span class="p">,</span> <span class="s2">&#34;img-1&#34;</span><span class="p">),</span> <span class="n">release_gate</span><span class="o">.</span><span class="n">PREPARE</span><span class="p">)</span>   <span class="c1"># the owner takes the lock</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">owner_dies</span><span class="p">(</span><span class="n">_seconds</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="n">redis</span><span class="o">.</span><span class="n">store</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s2">&#34;release:img-1:lock&#34;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>                              <span class="c1"># its lock expired</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">release_gate</span><span class="p">,</span> <span class="s2">&#34;_sleep&#34;</span><span class="p">,</span> <span class="n">owner_dies</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">release_gate</span><span class="o">.</span><span class="n">claim</span><span class="p">(</span><span class="n">redis</span><span class="p">,</span> <span class="s2">&#34;img-1&#34;</span><span class="p">),</span> <span class="n">release_gate</span><span class="o">.</span><span class="n">PREPARE</span><span class="p">)</span></span></span></code></pre></div></div>

<h2 class="relative group">有效果吗，一半
    <div id="有效果吗一半" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%9c%89%e6%95%88%e6%9e%9c%e5%90%97%e4%b8%80%e5%8d%8a" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>部署之后，停掉一台机器再启动，同时看着表。现在启动过程会说出自己的判断，然后立刻让路：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">15:23:34  Starting app server...
</span></span><span class="line"><span class="cl">15:23:36  release gate: this release is already prepared, starting straight away
</span></span><span class="line"><span class="cl">15:23:44  &#34;GET /healthz HTTP/1.1&#34; 200</span></span></code></pre></div></div>
<p>十秒，第二台量到十一秒。对比之前的 25 到 33 秒，这个窗口消失了三分之二，而门闩本身只花两秒，因为它从不导入 Django。</p>
<p>但十秒还是十秒。落在这十秒最开头的请求依然会失败。于是我去找剩下的部分。</p>

<h2 class="relative group">没有人在缓存字节码
    <div id="没有人在缓存字节码" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b2%a1%e6%9c%89%e4%ba%ba%e5%9c%a8%e7%bc%93%e5%ad%98%e5%ad%97%e8%8a%82%e7%a0%81" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>镜像里有一行，几乎每一个 Python Dockerfile 都写着它：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">ENV</span> <span class="nv">PYTHONDONTWRITEBYTECODE</span><span class="o">=</span><span class="m">1</span></span></span></code></pre></div></div>
<p>这是好建议。容器不该在运行时把 <code>.pyc</code> 涂进镜像层里。我没有想透的是这笔交易的另一半：如果运行时从不写字节码，而构建时也不写，那就没有任何东西被缓存，于是每一次进程启动都要把整棵依赖树从源码编译一遍。</p>
<p>我数了数：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">site-packages .py  files : 5,707
</span></span><span class="line"><span class="cl">site-packages .pyc files : 0</span></span></code></pre></div></div>
<p>Django、REST 框架、每一个库，在那 92 次日常启动里每次都重新编译。在生产机器上实测：</p>
<table>
	<thead>
			<tr>
					<th><code>django.setup()</code></th>
					<th>耗时</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>出厂状态</td>
					<td>5.15 秒</td>
			</tr>
			<tr>
					<td><code>compileall</code> 之后</td>
					<td>3.17 秒</td>
			</tr>
	</tbody>
</table>
<p>修复是一行，而且 <code>compileall</code> 是显式写入，所以那个环境变量拦不住它：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">RUN</span> python -m compileall -q /app/.venv/lib /app/myapp <span class="o">||</span> true</span></span></code></pre></div></div>
<p>十六秒的构建时间，只此一次，还在一个可缓存的层里。</p>
<p>顺手还发现了一个更安静的问题。<code>.dockerignore</code> 里写着：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">__pycache__/
</span></span><span class="line"><span class="cl">*.pyc</span></span></code></pre></div></div>
<p>Docker 是拿它们去匹配<strong>整条</strong>相对路径，而不是路径的每一段，所以没有锚定的模式只会在构建上下文的根目录生效。所有嵌套的 <code>__pycache__</code> 都被打进了镜像。里面有 218 个由笔记本上的 Python 3.15 编译出来的 <code>.pyc</code>，躺在一个解释器是 3.14 的镜像里，被安静地全部忽略。正确的写法是 <code>**/__pycache__/</code> 和 <code>**/*.pyc</code>。</p>
<p>诚实的结果：端到端只换来大约一秒，而不是两秒。十秒变成九秒。孤立的基准测试总是这样高估自己。</p>

<h2 class="relative group">挂起，以及挡住它的那一行
    <div id="挂起以及挡住它的那一行" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8c%82%e8%b5%b7%e4%bb%a5%e5%8f%8a%e6%8c%a1%e4%bd%8f%e5%ae%83%e7%9a%84%e9%82%a3%e4%b8%80%e8%a1%8c" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>到了九秒，我已经没有可以再删的工作了。剩下的是一次无法避免的启动：Python 起来、Django 导入、WSGI 应用在一个共享核心上立起来。</p>
<p>那就别启动。Fly 可以给机器的内存做快照，而不是把它关掉：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;suspend&#39;</span>   <span class="c"># was &#39;stop&#39;</span></span></span></code></pre></div></div>
<p>我去测试，Fly 拒绝了我，并给出了整件事里最有用的一条错误信息：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">failed to suspend VM: failed_precondition:
</span></span><span class="line"><span class="cl">Machines with swap cannot be suspended</span></span></code></pre></div></div>
<p>我的配置顶部有这么一段，注释是我自己写的，我也一直相信它：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="c"># Swap cushion so a memory spike swaps to disk instead of getting OOM-killed.</span>
</span></span><span class="line"><span class="cl"><span class="nx">swap_size_mb</span> <span class="p">=</span> <span class="mi">2048</span></span></span></code></pre></div></div>
<p>听起来是合理的预防。它真的在干活吗？每一台机器的回答都是：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">MemTotal:   985220 kB
</span></span><span class="line"><span class="cl">SwapTotal: 2097148 kB
</span></span><span class="line"><span class="cl">SwapFree:  2097148 kB</span></span></code></pre></div></div>
<p>一页都没有换出过。当天的日志里也没有 OOM kill——那 11 行匹配到 &ldquo;oom&rdquo; 的记录，是对一个内容哈希里恰好含有这三个字母的 JavaScript 包的请求。而真正的内存护栏在完全不同的地方，在应用服务器自己的配置里：任何 worker 一旦超过 800MB 就会被重启，远在触到 1GB 天花板之前。</p>
<p>所以这层缓冲是一份针对从未发生过的事件的保险，而且已经被另一套机制覆盖，它的保费是挂起能力。删掉。</p>
<table>
	<thead>
			<tr>
					<th>唤醒路径</th>
					<th>到能响应</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>今天早上的冷启动</td>
					<td>25 到 33 秒</td>
			</tr>
			<tr>
					<td>加了门闩和字节码之后的冷启动</td>
					<td>9 到 10 秒</td>
			</tr>
			<tr>
					<td><strong>从挂起恢复</strong></td>
					<td><strong>2.5 到 3.1 秒</strong></td>
			</tr>
	</tbody>
</table>
<p>测了三次，波动不超过半秒。唤醒之后每个端点都在 250 到 435 毫秒内返回 200。</p>

<h2 class="relative group">机器睡着时，你的套接字会怎样
    <div id="机器睡着时你的套接字会怎样" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%9c%ba%e5%99%a8%e7%9d%a1%e7%9d%80%e6%97%b6%e4%bd%a0%e7%9a%84%e5%a5%97%e6%8e%a5%e5%ad%97%e4%bc%9a%e6%80%8e%e6%a0%b7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>不会有好事，而且没有钩子可以补救。Fly 冻结整个虚拟机：进程收不到信号，下坠途中什么也关不掉。它握着的连接在醒来时仍然留在内存里，指向对端几分钟前就已经丢弃的套接字。</p>
<p>这个问题不在下去的时候解，而在上来的时候解，而且多半取决于你之前是否已经做对了选择：</p>
<ul>
<li><strong>数据库连接按请求打开</strong>（<code>conn_max_age = 0</code>），没有活得够久、够得着变质的连接。</li>
<li><strong>Redis 缓存是降级而不是抛异常。</strong> 包装器捕获连接错误并返回一次未命中。</li>
</ul>
<p>我亲眼看到第二条挣到了它的位置。某次恢复时，日志里出现了完全在预料之中的失败：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">redis.exceptions.ConnectionError: Error while reading from fly-...</span></span></code></pre></div></div>
<p>而它所在的那个请求，用 3.6 秒返回了 200——死掉的缓存意味着慢一点的页面，而不是错误页面。之后的恢复什么都没记。</p>
<p>如果你的缓存客户端在连接死掉时会抛异常，挂起就会把每一次唤醒变成一串 500。在打开这个开关<strong>之前</strong>确认，而不是之后。</p>

<h2 class="relative group">那个骗了我的测试
    <div id="那个骗了我的测试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%82%a3%e4%b8%aa%e9%aa%97%e4%ba%86%e6%88%91%e7%9a%84%e6%b5%8b%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我第一次测挂起，结论是这功能糟透了：502，30 秒之后，而且连着两次。</p>
<p>我用 <code>fly-force-instance-id</code> 把请求钉在了某一台机器上。用来压测单个实例时这是个好头部，用在这里则糟糕透顶：强制指定实例会绕过本该把它唤醒的代理逻辑。Fly 其实早就告诉我了，只要我把它当成答案而不是错误来读：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">machine was recently stopped and is unavailable to service request</span></span></code></pre></div></div>
<p>有意义的数字来自真实流量走的那条路。经由边缘发出 40 个并发请求，远超 12 的软上限，逼得代理必须扩容到挂起的机器上：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">status codes:  40 × 200
</span></span><span class="line"><span class="cl">slowest:       2.1s</span></span></code></pre></div></div>
<p>两个教训，贵的是第二个。去测量用户走的那条路，而不是方便插桩的那条路。以及，当你的工具拒绝你的时候，去读那句拒绝——&ldquo;Machines with swap cannot be suspended&rdquo; 这一句，打开了整个下午。</p>

<h2 class="relative group">我建议你在自己的应用里检查什么
    <div id="我建议你在自己的应用里检查什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e5%bb%ba%e8%ae%ae%e4%bd%a0%e5%9c%a8%e8%87%aa%e5%b7%b1%e7%9a%84%e5%ba%94%e7%94%a8%e9%87%8c%e6%a3%80%e6%9f%a5%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>如果你跑在任何会停掉空闲实例的平台上，下面这些问题我花了半天，本可以省下好几周的静默失败：</p>
<ol>
<li><strong>冷启动要多久？</strong> 不是容器跑起来要多久，而是到它能响应一个真实请求要多久。如果你没法用秒数直接回答，就在需要它之前先量出来。</li>
<li><strong>你的 entrypoint 里，哪些按启动执行的事其实属于部署？</strong> 迁移、静态文件收集、缓存预热、索引构建。做一次都没问题，做九十二次都很贵。</li>
<li><strong>有东西在缓存你的字节码吗？</strong> 只有 <code>PYTHONDONTWRITEBYTECODE</code> 而构建里没有 <code>compileall</code>，答案就是没有。</li>
<li><strong>你能用挂起代替停止吗？</strong> 如果不能，是什么挡着？我这边是一个从未被碰过的 swap。</li>
<li><strong>边缘看得见、源站看不见的错误存在吗？</strong> 把两边比一比。那个差值不是统计口径的怪癖，而是死在中间的请求，你的应用日志永远不会显示它们。</li>
</ol>
<p>顺带一提，这段时间里健康检查一直是绿的。它总是绿的：健康检查跑在一台已经起来的机器上，它没法报告这台机器存在之前的那三十秒。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-09-09-scale-to-zero-504s/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Fly.io 上的 Django 自动扩缩容：先压测出一台小机器的极限</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-07-22-my-current-stack/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-07-22-my-current-stack/</guid>
      <pubDate>Wed, 22 Jul 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Django</category>
      <category>Python</category>
      <category>React Native</category>
      <category>Expo</category>
      <category>Fly.io</category>
      <category>PostgreSQL</category>
      <category>WebSockets</category>
      <category>Scaling</category>
      <category>Load Testing</category>
      <category>Performance</category>
      <category>Tech Stack</category>
      <description>我的两个 Django 应用都跑在 Fly.io 的 shared-cpu-1x 机器上：先把一台做快，用压测找到延迟崩掉的并发点，再把自动扩缩容的阈值设在它前面。</description>
      <content:encoded><![CDATA[<p>想在 Fly.io 上便宜地跑 Django，我的做法是：把一台 shared-cpu-1x 小机器尽量做快，压测到延迟崩掉为止，然后让 Fly 的自动扩缩容在这个点之前启动第二台机器。压测用的是按阶梯加压的 Locust（另一个应用用一个按并发档位逐级跑的小 Python 脚本），盯着 p95 延迟和错误率看。流量回落后 Fly 会自动停掉空闲机器，所以平时的成本就是每个应用一台小虚拟机。</p>
<p>我目前以独立开发者的身份运营着两个产品：一个是面向上门报价的手艺人的<strong>现场估价应用</strong>，另一个是带有信息发布和实时消息的<strong>集市兼社区应用</strong>。</p>
<p>产品完全不同，用户完全不同，但技术栈几乎一模一样——而且两者都只跑在 Fly.io 最便宜的档位 <strong>shared-cpu-1x 机器</strong>上。这个约束是刻意为之的。与其按峰值负载来配置服务器，我选择把一台小机器的性能榨到极限，精确测出它在哪里崩溃，然后让 Fly 的自动扩缩容器围绕这个实测极限来增减机器。这篇文章讲的就是让这一切成为可能的优化、阈值背后的压测数据，以及 Fly.io 上扩容和缩容到底是怎么运作的。</p>

<h2 class="relative group">理念：先测准一台机器，再做乘法
    <div id="理念先测准一台机器再做乘法" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%90%86%e5%bf%b5%e5%85%88%e6%b5%8b%e5%87%86%e4%b8%80%e5%8f%b0%e6%9c%ba%e5%99%a8%e5%86%8d%e5%81%9a%e4%b9%98%e6%b3%95" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>两个应用的扩缩容策略都是同样的三步：</p>
<ol>
<li>把一台小机器在合理范围内做到尽可能快。</li>
<li>压测到它崩溃为止，记下延迟塌陷时的并发水平。</li>
<li>配置 Fly 的自动扩缩容器，在临界点之前启动第二台机器，并在流量回落时停掉空闲机器。</li>
</ol>
<p>这样容量就随机器数量近似线性增长，而基线成本是每个应用一台小虚拟机。下面的所有内容，都是为这三步中的某一步服务的。</p>

<h2 class="relative group">让一台小机器变快
    <div id="让一台小机器变快" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%ae%a9%e4%b8%80%e5%8f%b0%e5%b0%8f%e6%9c%ba%e5%99%a8%e5%8f%98%e5%bf%ab" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">Granian：API 走 WSGI，WebSocket 走 uvloop ASGI
    <div id="granianapi-走-wsgiwebsocket-走-uvloop-asgi" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#granianapi-%e8%b5%b0-wsgiwebsocket-%e8%b5%b0-uvloop-asgi" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>两个后端都是 Django 6 + Django REST Framework。API 由基于 Rust 的服务器 <strong>Granian</strong> 提供服务，但跑的是 <strong>带阻塞线程池的 WSGI</strong>，而不是 ASGI：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">granian --interface wsgi myapp.wsgi:application <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers <span class="m">1</span> --blocking-threads <span class="m">16</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers-max-rss <span class="m">1400</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers-kill-timeout <span class="m">15</span> --respawn-failed-workers</span></span></code></pre></div></div>
<p>我最初用的是 <code>--interface asgi --loop uvloop</code>，事后看是选错了。这些应用里的每个 HTTP 视图都是同步（sync）的，而 Django 的 ASGI 处理器会以 <code>thread_sensitive</code> 方式跑同步视图——每个 worker（工作进程）一次只跑一个。于是 ASGI 把每个 worker 的并发请求实质压到约 1 个，却还把整套 asyncio/uvloop/Channels 栈白白装进内存。带 <code>--blocking-threads</code> 的 WSGI 则把这些同步视图放进一个真正的线程池：1 个 worker × 16 个线程 = 16 个并发的 I/O 密集型请求（数据库读取、S3 预签名），而常驻内存比异步栈更低。</p>
<p>为什么只用一个 worker？因为这台 VM 是 <code>shared-cpu-1x</code>——只有一个核。第二个 worker 在单核上没法并行跑 Python（GIL + 单核），却要白白多占一整个常驻的 Django 进程；Granian 会直接就此发出警告。一个 worker 配 16 个线程，就是单 vCPU 机器在 I/O 密集型工作上诚实的上限。<code>--workers-max-rss 1400</code> 会在 worker 越过内存上限时重启它，于是失控的 PDF 或图片任务会被回收，而不是把机器一路拖向 OOM。</p>
<p>WebSocket 被拆到了它自己的 Granian 进程里——一个用 uvloop 和 <code>--ws</code> 的 <strong>ASGI</strong> 应用，为长连接跑 1 个 worker。同步 API 完全不需要 ASGI 路径：当某个视图想往 socket 推送时，它会经由 Redis 调用 <code>async_to_sync(channel_layer.group_send)</code>，消息照样会跨进程送到 WebSocket 应用。两台服务器，各自跑自己真正擅长的接口。本地 Docker 也跑同样的 WSGI 线程池，因此测试时我的笔记本约等于一台生产机器。</p>

<h3 class="relative group">热路径交给 Rust
    <div id="热路径交给-rust" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%83%ad%e8%b7%af%e5%be%84%e4%ba%a4%e7%bb%99-rust" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>只要 Python 热路径上存在 Rust 实现的替代品，我就用它：</p>
<ul>
<li><strong>orjson</strong>（通过 <code>drf-orjson-renderer</code>）——所有 API 响应都经由 Rust 序列化，而不是标准库的 JSON 编码器。</li>
<li><strong>blurhash-rs</strong>——在上传时计算图片占位符。</li>
<li><strong>uuid-utils</strong>——Rust 实现的 UUID 生成。</li>
<li><strong>psycopg 3 (binary)</strong>——C 加速的 Postgres 驱动。</li>
</ul>
<p>这些都不改变架构，只是抬高了一颗 vCPU 在需要第二台机器之前所能承受的上限。</p>

<h3 class="relative group">消灭隐藏的延迟税
    <div id="消灭隐藏的延迟税" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b6%88%e7%81%ad%e9%9a%90%e8%97%8f%e7%9a%84%e5%bb%b6%e8%bf%9f%e7%a8%8e" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>两个代码库里最大的一次性能提升不是算法，而是连接复用。在 Granian 的线程池下，每个新线程都会重新构建一个 boto3 的 S3 客户端，而每个返回照片或 PDF 的接口都在支付这笔开销。我写了一个小小的自定义存储类，改为按进程缓存客户端之后：</p>
<blockquote><p>新线程上生成签名 URL 的耗时从 <strong>约 150ms 降到约 1ms</strong>。</p>
</blockquote><p>同样的教训也适用于数据库：Fly 的 Postgres 位于 PgBouncer 之后，所以应用设置 <code>conn_max_age=0</code>，把连接复用交给连接池，并用 5 秒的 <code>connect_timeout</code> 快速失败，避免 worker 挂在失效的 SSL 连接上。</p>

<h3 class="relative group">把缓存放在真正的瓶颈前面
    <div id="把缓存放在真正的瓶颈前面" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8a%8a%e7%bc%93%e5%ad%98%e6%94%be%e5%9c%a8%e7%9c%9f%e6%ad%a3%e7%9a%84%e7%93%b6%e9%a2%88%e5%89%8d%e9%9d%a2" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>压测社区市集时发现了一个值得记住的事实：<strong>天花板是 Postgres 连接数，而不是 CPU</strong>。浏览流量绝大多数是匿名的、用户之间完全相同，而在高负载下，这些相同的列表查询会在 CPU 闲置的同时把连接池打满。</p>
<p>解决办法是给匿名列表页加一层 Redis 缓存，用按命名空间的版本计数器做失效——一次写操作只需把一个计数器加一（O(1)，无需管理任何键），该资源的所有缓存页面立即失效。再用一个短 TTL 兜底。让浏览页面直接从 Redis 出去，真正的瓶颈就消失了，小机器可以把连接留给已登录的流量。</p>

<h3 class="relative group">不要消息代理的后台任务
    <div id="不要消息代理的后台任务" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8d%e8%a6%81%e6%b6%88%e6%81%af%e4%bb%a3%e7%90%86%e7%9a%84%e5%90%8e%e5%8f%b0%e4%bb%bb%e5%8a%a1" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>两个应用都用 <strong>django-tasks-db</strong>——Django 的数据库后端任务框架——而不是 Celery。一个独立的 <code>db_worker</code> 进程轮询数据库来处理任务：图片处理、PDF 生成、机器翻译、提醒推送。没有消息代理，没有需要额外估算容量和监控的服务，API 进程也永远不会被重活阻塞。这个 worker 甚至绕过 PgBouncer 直连 Postgres，因为长时间运行的任务和事务级连接池合不来。</p>

<h3 class="relative group">内存：jemalloc 和交换空间缓冲
    <div id="内存jemalloc-和交换空间缓冲" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%86%85%e5%ad%98jemalloc-%e5%92%8c%e4%ba%a4%e6%8d%a2%e7%a9%ba%e9%97%b4%e7%bc%93%e5%86%b2" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>图片和 PDF 处理造成的内存尖峰，是按稳态估算内存时无法预测的。两个便宜的缓解手段：在 Docker 镜像里预加载 <strong>jemalloc</strong> 来减少内存碎片，以及<strong>给每台机器都配交换空间</strong>（API 机器 2GB，WebSocket 机器 1GB），这样尖峰来临时进程会把内存换出到磁盘，而不是被 OOM 杀掉。交换空间不是性能特性——它是一份保险，让我能把内存配置一直保持在小规格。</p>

<h2 class="relative group">Django 压力测试：找到拐点
    <div id="django-压力测试找到拐点" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#django-%e5%8e%8b%e5%8a%9b%e6%b5%8b%e8%af%95%e6%89%be%e5%88%b0%e6%8b%90%e7%82%b9" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>阈值只有在被实测过之后才站得住脚。每个项目都有自己的压测工具：</p>
<ul>
<li>估价应用有一个小的 Python 压测脚本，扫描各个并发级别并报告 RPS、p50/p95/p99 和错误率；它跑在预先生成的几百条样例数据上，让列表接口在接近真实的数据量下被查询。</li>
<li>社区市集用 <strong>Locust</strong> 以 30 秒为步长从 50 爬升到 500 用户来寻找饱和点，接口权重按真实的浏览为主的流量设定；另有一套更小的独立测试，以 p95 &lt; 2 秒为阈值，对生产环境从 5 爬升到 50 个虚拟用户。</li>
</ul>
<p>估价应用扫描的代表性数据（1 个 Granian worker × 16 个阻塞线程，开发机上的 Docker）：</p>
<table>
	<thead>
			<tr>
					<th>接口</th>
					<th>并发</th>
					<th>RPS</th>
					<th>p95</th>
					<th>错误率</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>health</td>
					<td>25</td>
					<td>602</td>
					<td>52ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>重型列表</td>
					<td>25</td>
					<td>309</td>
					<td>260ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>轻型列表</td>
					<td>25</td>
					<td>357</td>
					<td>61ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>重型列表</td>
					<td>50</td>
					<td>309</td>
					<td>347ms</td>
					<td>0%</td>
			</tr>
	</tbody>
</table>
<p>而决定其他一切的那个数字，来自在<strong>单台 shared-cpu-1x 机器</strong>上对社区市集的压测。在旧的 ASGI 构建里，这曾是一堵硬墙：同步视图被实质串行化到大约<strong>3 个可用槽位</strong>，于是 p95 在约 5 个并发请求以内保持在 300ms 以下，随后当一切都排在 thread_sensitive 锁后面时，超过约 8–10 个并发就塌陷。把拐点往外推的，正是把 API 迁到 WSGI 线程池这件事——每台机器的真实并发槽位从约 3 个变成了 <strong>16 个</strong>，而这个新的上限就是整个自动扩缩容配置的依据。</p>

<h2 class="relative group">Fly.io 上的扩缩容是怎么运作的
    <div id="flyio-上的扩缩容是怎么运作的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#flyio-%e4%b8%8a%e7%9a%84%e6%89%a9%e7%bc%a9%e5%ae%b9%e6%98%af%e6%80%8e%e4%b9%88%e8%bf%90%e4%bd%9c%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Fly 的模型很简单：你的应用是代理后面的一组相同机器，代理统计每台机器的负载。你只需要声明两个数字：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">.</span><span class="nx">concurrency</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">type</span> <span class="p">=</span> <span class="s1">&#39;requests&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">soft_limit</span> <span class="p">=</span> <span class="mi">12</span>   <span class="c"># 超过就启动另一台机器</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hard_limit</span> <span class="p">=</span> <span class="mi">24</span>   <span class="c"># 超过就直接卸载负载而不是排队</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;stop&#39;</span>
</span></span><span class="line"><span class="cl"><span class="nx">auto_start_machines</span> <span class="p">=</span> <span class="kc">true</span>
</span></span><span class="line"><span class="cl"><span class="nx">min_machines_running</span> <span class="p">=</span> <span class="mi">1</span></span></span></code></pre></div></div>
<p>**扩容：**当一台机器上的在途（in-flight）请求超过软上限（soft limit），代理会启动一台停止中的机器，并把新流量路由过去。WSGI 线程池让每台机器有 16 个真实并发槽位，所以软上限设为 12——约为池子的 75%，于是第二台机器会在线程还有余量时启动，而不是等用户已经在承受数秒延迟之后。硬上限 24（池子的 1.5 倍）是熔断器：短促的突发会在线程上排队，超过它，代理宁可卸载负载，也不让一台机器被压垮。（旧的 ASGI 构建只有约 3 个真实槽位，用的是 8/20；正是把池子拓宽，才让这两个数字都能往上调。）</p>
<p>**缩容：**流量回落时，Fly 自动停掉空闲机器，最低降到 <code>min_machines_running = 1</code>。停止的机器不产生计算费用，只收 rootfs 存储费，所以每个应用的基线成本就是字面意义上的一台小虚拟机，而突发容量随时待命。</p>
<p>我原本在这里写着，停止的机器&quot;冷启动不到一秒&quot;。这是错的，而且错得很贵。当我不再假设、真正去测量之后，一次冷启动要 <strong>25 到 33 秒</strong>，落到一台还在启动的机器上的请求，就得把这段时间整个等完。我一开始把 CDN 面板上 22% 的失败率归咎于这些冷启动，当时健康检查一直是绿的。后来才发现，那个数字是 CDN 自己的 Early Hints 探测请求在源站失败造成的，真实客户端一个 504 都没收到。不过冷启动本身确实存在。</p>
<p>解法不在上面的伸缩数字里，那些数字没问题。解法在于机器启动过程中做了什么，以及让 Fly 挂起机器而不是停止它们——那样唤醒就变成大约 3 秒的内存恢复。我单独写了一篇：<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-09-scale-to-zero-504s/" >缩容到零，于是每次重启都是一次 30 秒的故障</a> 讲了诊断过程和该改什么。如果你在 Fly 上跑着任何用了 <code>auto_stop_machines</code> 的东西，先读那篇，再来相信这一段。</p>
<p>一个微妙之处：并发类型是 <code>requests</code> 而不是 <code>connections</code>。现代客户端会一直保持 keep-alive 连接，所以按连接数统计时数字在真实负载下几乎不动，自动扩缩容永远不会触发。统计在途请求，才能追踪真实的工作量。</p>

<h3 class="relative group">WebSocket 在另一条轴上扩缩
    <div id="websocket-在另一条轴上扩缩" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#websocket-%e5%9c%a8%e5%8f%a6%e4%b8%80%e6%9d%a1%e8%bd%b4%e4%b8%8a%e6%89%a9%e7%bc%a9" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>社区市集把 WebSocket 服务器拆成了<strong>第二个 Fly 应用</strong>，与 API 共享同一个 Docker 镜像。API 应用用 WSGI 跑 1 个 worker × 16 个阻塞线程，按<em>请求</em>计数（软上限 12）；WebSocket 应用在一台 <strong>512MB</strong> 的机器上用 ASGI 配 uvloop 跑 1 个 worker，按<em>连接</em>计数：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">.</span><span class="nx">concurrency</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">type</span> <span class="p">=</span> <span class="s1">&#39;connections&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">soft_limit</span> <span class="p">=</span> <span class="mi">1500</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hard_limit</span> <span class="p">=</span> <span class="mi">2000</span></span></span></code></pre></div></div>
<p>一条长连接维持起来几乎零成本，却会占用一个槽位好几个小时；而一个 HTTP 请求只占用槽位几毫秒——同一个扩缩容信号无法同时服务两者。拆开之后，每个机群都按对自己诚实的指标扩缩，而空闲的 WebSocket 容量只花 512MB，不是 2GB。在 Channels 这一侧，Redis 层以 <code>capacity: 1500</code>、消息 60 秒过期运行，并每 30 秒发送 socket keepalive——因为 Fly 的 Redis 代理会把 Channels 赖以工作的长时间 BRPOP 连接当作空闲连接掐掉。</p>

<h2 class="relative group">把计算卸载到边缘和客户端
    <div id="把计算卸载到边缘和客户端" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8a%8a%e8%ae%a1%e7%ae%97%e5%8d%b8%e8%bd%bd%e5%88%b0%e8%be%b9%e7%bc%98%e5%92%8c%e5%ae%a2%e6%88%b7%e7%ab%af" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>最便宜的服务器工作，是服务器根本不用做的工作：</p>
<ul>
<li><strong>静态文件和媒体</strong>放在 Fly 的 S3 兼容对象存储上，私有媒体通过签名 URL 走 CDN 分发——图片的每一个字节都不经过 Django 机器。</li>
<li>**AI 推理跑在用户的手机上。**两个应用都内嵌了一个小型本地 LLM（量化的 4B 模型，约 2.7GB），直接在设备上运行。服务端推理成本为零，而且离线也能用。</li>
<li><strong>离线优先的移动端</strong>（设备上的 SQLite 加带重试的同步队列）意味着应用会把写操作攒批、容忍信号盲区，而不是每敲一个键就向 API 发一次琐碎请求。</li>
</ul>

<h2 class="relative group">其余的技术栈，简单说
    <div id="其余的技术栈简单说" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%85%b6%e4%bd%99%e7%9a%84%e6%8a%80%e6%9c%af%e6%a0%88%e7%ae%80%e5%8d%95%e8%af%b4" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>认证用托管的身份服务加 WebAuthn 通行密钥（passkey），WebSocket 连接在协议升级完成前就完成认证。生产用 Postgres，开发用 SQLite。后台管理和审计记录用了几个现成的 Django 包。移动端是基于 Expo 的 React Native 和 TypeScript，配 Expo Router 和 Tailwind，OTA 更新由自托管的 Expo Updates 服务器下发，应用内订阅交给一个订阅管理服务。质量关卡：后端 pytest 和 mypy，客户端单元测试和端到端测试。</p>

<h2 class="relative group">值得你拿走的东西
    <div id="值得你拿走的东西" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%80%bc%e5%be%97%e4%bd%a0%e6%8b%bf%e8%b5%b0%e7%9a%84%e4%b8%9c%e8%a5%bf" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>可迁移的想法不是某个具体的库，而是这个循环本身：把一台便宜机器做到真正的快（Rust 热路径、连接复用、在真正的瓶颈前面加缓存、能卸给 CDN 和客户端的都卸掉）；压测到找出它到底在哪个并发数崩溃；把自动扩缩容的软上限设在那个拐点上，让空闲机器停机，把最小机群保持在 1。两个生产应用、实时功能、AI 助手——而平时的账单，只是这个平台上最便宜的几台虚拟机。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-07-22-my-current-stack/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
