这篇文章讲的是另一种顺序。服务继续跑在开发它的那台机器上，由 Cloudflare Tunnel 给它一个公开的 HTTPS 主机名。笔记本上没有任何东西对互联网监听：不做端口转发，不碰路由器设置，也不暴露 IP 地址。是机器主动连出去到 Cloudflare，Cloudflare 再把请求顺着这条连接送回来。Tunnel 本身免费，TLS 证书、DDoS 防护和缓存则随你多半已经有的 Cloudflare zone 一起附送。

例子是真实的。我的一个产品 跑在 Fly.io 上，它的移动应用从后端获取 JavaScript 的 OTA 更新（自托管的 Expo Updates）。我想在自己的 Mac 上再跑一份更新服务器，给开发构建用，生产环境原封不动。下面的输出都来自那个下午，包括没跑通的那部分。

Cloudflare Tunnel 到底是什么

#

普通的服务器是等别人连进来的。要从互联网访问一台笔记本，你得在路由器上开端口、转发到笔记本，还得指望运营商给你一个公网 IPv4 地址（很多地方都不给，我这里也是）。然后，那个端口上监听的所有东西，整天都暴露在互联网上每一个扫描器面前。

Tunnel 把方向反过来。cloudflared 跑在你的应用旁边，主动向 Cloudflare 的边缘建立出站连接，一共四条，连到附近的两个数据中心。你 zone 里的一条 DNS 记录把主机名指向这个 tunnel。当请求打到这个主机名时，Cloudflare 终止 TLS，把请求顺着其中一条连接转发下来，cloudflared 再按你配置里写的交给对应的本地服务。

从安全角度看，关键在于路由器上没有任何入站规则，你的 IP 地址也从不出现在 DNS 里。有人扫描你家的网络连接，什么也找不到，因为上面根本没有东西在监听。

从头到尾的搭建

#

你需要一个托管在 Cloudflare 上的域名（免费套餐就够），以及装好 cloudflared（Mac 上 brew install cloudflared）。

1. 登录一次。 这会打开浏览器，你选好 zone，它会保存一张证书，让这台机器可以在那个 zone 里创建 tunnel 和 DNS 记录：

cloudflared tunnel login

2. 创建 tunnel。 这个项目的所有东西我都放在单独的文件夹里，因为凭据文件就是 tunnel 的身份：谁拿到它，谁就能替你的主机名提供流量。

mkdir -p ~/.cloudflared/myapp && cd ~/.cloudflared/myapp
cloudflared tunnel create --credentials-file ./creds.json myapp-local
chmod 600 creds.json

Tunnel credentials written to ./creds.json. Keep this file secret. To revoke these credentials, delete the tunnel.
Created tunnel myapp-local with id 1ade030c-…

3. 把主机名指向它。 每个主机名一条命令，创建一条指向 <tunnel-id>.cfargotunnel.com 的代理 CNAME：

cloudflared tunnel route dns myapp-local ota.example.com
cloudflared tunnel route dns myapp-local checkin-local.example.com

4. 写 ingress 规则。 这是对安全最要紧的部分，所以下面单独一节来讲。

5. 跑起来。 我的应用本来就跑在 Docker Compose 下，所以 cloudflared 只是同一个网络里多出来的一个容器。它按服务名访问应用，应用根本不需要在宿主机上发布端口：

# compose.tunnel.yml, used alongside the project's docker-compose.yml
services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ${HOME}/.cloudflared/myapp:/etc/cloudflared:ro
    restart: unless-stopped
    depends_on: [api, edge]

docker compose -f docker-compose.yml -f ~/.cloudflared/myapp/compose.tunnel.yml up -d cloudflared

INF Registered tunnel connection connIndex=0 … location=icn06 protocol=quic
INF Registered tunnel connection connIndex=1 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=2 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=3 … location=icn06 protocol=quic

四条连接连到首尔，笔记本就从外向内地上了互联网。restart: unless-stopped 让它在重启后、Docker 一启动就自动恢复。

暴露路径，而不是服务器

#

这是我差点犯的错，我猜也是最常见的一个。最省事的配置只有一行：hostname → http://localhost:8000。这会把整个开发服务器都发布出去。

开发服务器不是为这个设计的。我的开着 DEBUG=True，任何错误都会显示完整的 traceback 和配置。它还关掉了认证（AUTH_MODE=disabled），任何 bearer token 都会让你以测试用户身份登录。这在 localhost 上完全合理，放到公网主机名上就是灾难。你的多半也有类似的东西：用默认密码的管理后台、灌测试数据的端点、debug toolbar，或者因为只有你自己在调用、所以信任调用方的 API。

所以 tunnel 配置是一份白名单。cloudflared 按顺序拿每个请求去匹配 ingress 规则，按主机名，也按路径上的正则表达式。第一条匹配的生效，最后一条兜住其余所有请求：

tunnel: myapp-local
credentials-file: /etc/cloudflared/creds.json

ingress:
  # OTA: the two read-only endpoints the phone calls, and the files they link.
  - hostname: ota.example.com
    path: ^/api/expo-updates/(manifest|status)/$
    service: http://api:8000
  - hostname: ota.example.com
    path: ^/media/
    service: http://api:8000
  # Device check-ins, authenticated by each device's own key.
  - hostname: checkin-local.example.com
    path: ^/c/$
    service: http://edge:8081
  # Everything else, including /admin/ and the publish endpoint: 404 at the edge.
  - service: http_status:404

发布端点就在同一台服务器上、同一个前缀下（/api/expo-updates/import-update/），但它不在列表里。管理后台和 API 的其余部分也不在。这些请求根本出不了 Cloudflare。

你不必盲信自己的正则；cloudflared 会告诉你一个 URL 匹配的是哪条规则：

cloudflared tunnel --config config.yml ingress rule https://ota.example.com/admin/

https://ota.example.com/api/expo-updates/manifest/        service: http://api:8000
https://ota.example.com/api/expo-updates/import-update/   service: http_status:404
https://ota.example.com/admin/                            service: http_status:404
https://ota.example.com/media/expo-updates/x.js           service: http://api:8000
https://checkin-local.example.com/c/                      service: http://edge:8081
https://checkin-local.example.com/health                  service: http_status:404

我会把这个检查写进脚本，每次改配置都跑一遍。只要几秒钟，而一条比你本意匹配得更多的正则，正是那种只会从别人那里得知的错误。

还有两条经验法则：

• 暴露出去的东西应该自己负责认证。 OTA 端点提供的是公开的只读数据。设备 check-in 用每台设备自己的密钥签名。两者的安全都不依赖网络。如果你想给别人看一个没有登录的页面，就在那个主机名前面放 Cloudflare Access（50 个用户以内免费），而不是自己去做登录。
• 别把 tunnel 当成开发流程里常驻后台的一部分。 有意识地启动它，只为你想要的那个主机名，用完就停。docker compose stop cloudflared 一条命令就把一切从互联网上撤下来。

吃掉我主机名的那个重定向

#

Tunnel 连上了，规则也验证过了，我从外部试了一下：

https://ota.example.com/api/expo-updates/status/?…   301
https://ota.example.com/api/expo-updates/manifest/   301
https://ota.example.com/admin/                       301
https://checkin-local.example.com/c/                 301

每条路径都返回同一个 301，包括那些 tunnel 本该回 404 的。这说明请求根本没到 cloudflared。Location 头写的是 https://www.example.com/，再加上 server: cloudflare 头，事情就清楚了：是 Cloudflare 自己在应答。

这是我自己挖的坑。几个月前我加了一条 zone 级的重定向规则，“其他任何子域名 → www”，用来当那些遍历编造出来的子域名的扫描器的黑洞。重定向规则在 Cloudflare 的请求流水线里执行，早于请求被发往源站，而 tunnel 不过是一个源站。同一条规则也拦住过我的预览环境，让 Workers 根本见不到请求。修法和上次一样：在规则表达式里再加一个例外。

… and not http.host in {"ota.example.com" "checkin-local.example.com"}

如果你的 tunnel 主机名返回的是 Cloudflare 的重定向或错误页面，而不是你的应用，那在调试 tunnel 之前，先检查这个 zone 的 Rules → Redirect Rules、Page Rules 和所有 WAF 自定义规则。cloudflared 会记录它转发的每个请求，所以日志为空就说明请求根本没走到那一步。

它做不到的事

#

• 来自公网的 UDP。 公开的 tunnel 主机名只承载 HTTP(S)（外加 WebSocket 和 gRPC）。我产品的设备平时通过 UDP 上的 CoAP 做 check-in，这走不了 tunnel；连本地副本的设备会退回到 HTTPS check-in，每次要多花几秒钟。如果你的想法是游戏服务器或 VoIP，tunnel 就不是合适的工具。
• 在线率。 这是你的笔记本。合上盖子，站点就挂了；Cloudflare 会显示一个 530 错误页。拿来做演示、十个人的内测或者一份 staging 副本都没问题，但不适合任何有人依赖的东西。
• 编译进构建里的东西。 移动应用的更新 URL 是原生配置，所以只有用 tunnel URL 构建出来的包才会用它。我的商店构建依然连着生产环境，这也正是这套方案敢拿来试的原因。

成本

#

免费套餐的 Cloudflare zone、tunnel、它的证书和 DNS 记录：0 美元。机器本来就开着。唯一真正的成本是，现在你自己就是运维值班团队。

它帮你省下的，是从“在我机器上能跑”到“值得花钱托管”之间的那个阶段。当天下午你就能把链接发给测试、设计师或者第一个客户。如果没人在意，你什么也没损失。如果有人在意，迁到真正的主机上也只是一处改动：把 CNAME 指到别处。

我第一次碰到它们是在 9 月，健康检查全绿、Cloudflare 面板上却有 22% 的请求在失败，我关掉了 Early Hints，就此作罢。11 月再看同一个 zone，Early Hints 又被打开了，一天之内又多出了 2,600 个 504。这一次我想弄清楚它们到底是什么，以及正确的做法是再关一次这个功能，还是让它真正发挥作用。这个 zone 前面挂着一个 Fly.io 源站，它同时提供一个 Django API、一个 Expo Web 应用和一个用 Hugo 搭的营销网站。

简短的答案

#

• 这些 504 是 Cloudflare 的 Early Hints 缓存写下的，不是你的访客。在 Cloudflare 日志里，它们的 ClientRequestSource = earlyHintsCache。
• 这里的 504 表示缓存未命中：Cloudflare 没有为这个 URL 存下任何提示。命中则记录为 2xx。
• 它们根本不会到达你的源站，OriginResponseStatus 为 0。
• Early Hints 依赖的是 Link HTTP 响应头，HTML 里的 <link rel="preload"> 标签喂不了它。
• 把这个响应头发出去，在那些有资源可预加载的页面上，这些未命中就会变成命中，并开始返回真正的 103 Early Hints 响应。

还有三件事值得先知道。只提示渲染关键的 CSS、脚本和字体，并且字体要保留 crossorigin。用 curl -sv --http2 验证，你应该在 200 之前看到 103。无论你做什么决定，都把 earlyHintsCache 排除在告警之外；如果你今后都不会发送这个响应头，就关掉 Early Hints，别用日志噪音为它买单。

如何分辨假的 Cloudflare 504 和真的 504

#

如果你用 Logpush 或 Instant Logs，先看两个字段。ClientRequestSource 对真实访客的请求是 eyeball，对 Early Hints 查询则是 earlyHintsCache。OriginResponseStatus 为 0 时，说明源站根本没有被联系过。

在 GraphQL Analytics API 里，同样的区分就是 requestSource 维度。现在每次 5xx 飙升，我在相信它之前都会先跑这个查询：

query ($zone: String!, $since: Time!) {
  viewer {
    zones(filter: { zoneTag: $zone }) {
      httpRequestsAdaptiveGroups(
        limit: 20
        filter: { datetime_geq: $since, edgeResponseStatus: 504 }
        orderBy: [count_DESC]
      ) {
        count
        dimensions { requestSource userAgent clientRequestPath }
      }
    }
  }
}

按 User-Agent 分组，结论也一样。9 月时，Early Hints 查询显示为 bastion early hints 和 nginx-ssl early hints；11 月则是 fl2 early hints 和 nginx-ssl early hints（FL2 是 Cloudflare 新一代的代理）。24 小时内，这个 zone 的 2,631 个 504 全部来自这些 User-Agent，没有一个来自浏览器、应用、curl 或搜索引擎爬虫。

访客真正看到的 504，几乎总是来自 Cloudflare 之外，也就是你这一侧：挡在应用前面的代理或负载均衡器等不及放弃了。可能是 nginx，可能是云负载均衡器，也可能是等待休眠机器启动的平台代理。Cloudflare 自己的超时用的是别的状态码：522 表示连不上源站，524 表示连上了，但在 125 秒内（Enterprise 以下套餐的默认值）没有收到响应。

所以，如果你是因为 504 想调大 Cloudflare 的超时时间而搜到这里：504 背后的那个超时几乎从来都不是 Cloudflare 的。去检查 nginx 的 proxy_read_timeout、负载均衡器的空闲超时，或者平台唤醒机器需要多久。有个很有用的线索：如果请求总在远低于 125 秒的整数时间点失败，比如 30 秒或 60 秒，那是你自己代理的上限，不是 Cloudflare 的。（只有 Enterprise 套餐能把 Cloudflare 的 125 秒上限提高到最多 6,000 秒，而 Cloudflare 自己也把这当作权宜之计。）

这些 504 到底是什么

#

在开启了 Early Hints 的 zone 上，每个指向 HTML 页面或无扩展名 URL 的请求（在以 API 为主的 zone 上，大多数 API 调用都算在内）都会附带一次内部查询：Cloudflare 查看自己的缓存里有没有可以发送的提示。这次查询会单独记成一行，ClientRequestSource = earlyHintsCache。它不是终端用户的请求，也永远不会被发往你的源站。

那一行的状态码是缓存查询的结果，而不是错误：

• 2xx 是命中。Cloudflare 存有这个 URL 的 Link 头，并把它作为 103 发给了浏览器。在我的 zone 上，命中同时以 200 和 204 出现。
• 504 是未命中。没有存下任何东西，所以没有什么可以提前发送。

如果源站从不发送 Early Hints 所依赖的那个响应头，每次查询都会未命中，每个请求都会写下一行 504。在我做任何改动之前的三个小时里，这个 zone 记录了 173 次 Early Hints 查询，173 次全部未命中。自从这个功能打开以来，它一次提示都没有发出过。

再更正一下我 9 月那篇文章：我当时把它们描述为"从 Fly 源站得不到响应"的探测请求。这并不准确。它们根本不会去源站。这个 504 记录的是缓存未命中，而不是超时。

Cloudflare 在它的 Early Hints 文档里简短地写明了这一点：记录为 ClientRequestSource: earlyHintsCache 的 Early Hints 查询是"expected and benign"（预期之内、无害的），200 是缓存命中，504 是未命中；在 Log Explorer 里可以用 ClientRequestSource != "earlyHintsCache" 把它们过滤掉。Cache Analytics 本来就不把它们算进去，但吓到我的那张 HTTP 流量图会。

假 504 让我白白升级了服务器

#

这就是区分它们的意义所在。11 月 3 日，也就是我动笔写这篇文章的前一天，Cloudflare 记录了 3,292 个 504，而访客请求大约只有 13,300 个：表面错误率 25%。这个 API 跑在 Fly.io 的 shared-cpu-1x 机器上，这类机器靠突发积分（burst credit）运行：保证给它的 CPU 份额很小，想跑得更快就要消耗积分。8 月的一次压力测试显示，在持续负载下它会被限流到每秒大约 20 到 30 个请求。“高峰时四分之一的请求超时"看起来正是这种限流，于是我把 API 换成了 shared-cpu-2x。

可这些 504 全都是 Early Hints 缓存未命中。按 requestSource 拆开，再回头看源站自己的日志：

• 10 月 28 日到 11 月 4 日，Cloudflare 的所有 5xx 都是 earlyHintsCache 查询，只有大约每天一个 525 例外（我追查的那个 525 来自一个安全扫描器）。
• 10 月 24 日到 11 月 4 日，源站的访问日志里一个 5xx 都没有，超过 10 秒的请求只有一个。
• Fly 的指标显示，最忙的时候也只有每秒约 7 个请求，机器用掉的 CPU 从未超过一个核心的五分之一，离限流上限还远得很。

换大机器什么也没修好，因为本来就没有坏。API 已经换回了 shared-cpu-1x。

不要根据一张没有按 request source 拆分的 5xx 图表来做容量决策。也要拿源站自己的日志对照一下：如果 Cloudflare 说四分之一的请求失败了，而你的服务器一条错误都没记，那在动服务器之前，先弄清楚 Cloudflare 到底在数什么。

2026 年 11 月 5 日更新：这一节的第一版说那一周 API 在 shared-cpu-1x 上真的垮了。其实并没有。上面的数字是我回头核查时发现的。

HTTP 103 是错误吗？

#

不是。1xx 范围的状态码属于信息性响应，是服务器在正式响应之前可以发送的临时响应。RFC 8297 定义的 103 Early Hints 携带 Link 头，让浏览器在服务器还在生成页面的时候，就开始获取关键的 CSS、JavaScript 和字体，或者提前与其他源建立连接。最终的 200 随后在同一个请求里到达。

各浏览器的支持程度不一，但很安全。基于 Chromium 的浏览器（Chrome 103 起，以及 Edge）和较新的 Firefox 同时支持 preload 和 preconnect 提示；Safari（17 及以上）只使用 preconnect。浏览器只在 HTTP/2 和 HTTP/3 上处理 103。不认识它的浏览器只会像往常一样等 200，所以 103 对大多数访客是抢先一步，对其余访客则毫无影响。

我的为什么是空的：Link 响应头与 <link rel=preload>

#

这是我花时间最多的地方，因为它看起来本该已经生效了。

Early Hints 只缓存一样东西：带有 rel=preload 或 rel=preconnect 关系的 Link HTTP 响应头。Cloudflare 从你平常的响应中（HTML 或无扩展名 URL 上的 200、301 或 302）读取它、存起来，然后在完整响应准备好之前，把它作为 103 重放给下一个访客。

我的页面其实已经有预加载了，只不过是写在 HTML <head> 里的标签：

<link rel="preload" href="/_expo/static/css/global-7d77bd.css" as="style">
<link rel="preload" href="/_expo/static/js/web/entry-fd7fa4.js" as="script">
<link rel="preload" href="/fonts/manrope-latin.woff2" as="font" type="font/woff2" crossorigin>

这些标签仍然有用，浏览器会按它们行事。但浏览器只有在收到 HTML 并开始解析之后才能看到它们，而这恰恰是 Early Hints 想要抢在前面的那一刻。Expo 导出和我用的 Hugo 主题都会自动写这些标签，却都不设置这个响应头。于是功能开着，预加载也声明了，两者却从未碰面。

解决办法：用你手上已有的数据发出这个响应头

#

最干净的办法，不是手工维护一份关键资源清单，每次打包哈希一变它就过时。每个页面已经用那些标签声明了自己想预加载什么。所以在返回页面时，把它们照抄进 Link 响应头就行。标准库的 html.parser 对带引号和不带引号的属性都能处理（Hugo 的压缩器会去掉引号），不用自己写正则：

from html.parser import HTMLParser


class PreloadLinks(HTMLParser):
    def __init__(self):
        super().__init__()
        self.hints = []

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag != "link" or "preload" not in (a.get("rel") or "").split() or not a.get("href"):
            return
        hint = f"<{a['href']}>; rel=preload"
        if a.get("as"):
            hint += f"; as={a['as']}"
        if a.get("as") == "font" or "crossorigin" in a:
            hint += "; crossorigin"
        self.hints.append(hint)


def link_header(html: str, limit: int = 12) -> str | None:
    parser = PreloadLinks()
    parser.feed(html)
    return ", ".join(list(dict.fromkeys(parser.hints))[:limit]) or None

然后在 Django 的 HTML 响应上加上它：

response = HttpResponse(html, content_type="text/html")
if (link := link_header(html)) and "Link" not in response:
    response["Link"] = link

有一个细节坑过我，值得记住：字体要保留 crossorigin。没有它的字体预加载会被当成另一个请求，字体会被下载两次，页面不但没变快，反而变慢了。

你不需要自己写 103，也不用在 ASGI、Granian 或 uvicorn 里添加任何临时响应的代码。Cloudflare 会根据你的响应头生成 103，你唯一要做的就是把响应头发出去。

在其他技术栈上

#

规则在哪里都一样：给 HTML 响应加上 Link 头，剩下的交给 Cloudflare。

• nginx，在返回 HTML 的 location 里：

  location = / {
      add_header Link "</css/app.css>; rel=preload; as=style" always;
      add_header Link "</fonts/inter.woff2>; rel=preload; as=font; crossorigin" always;
  }

• Laravel 配合 Vite 时已经有专门的中间件 AddLinkHeadersForPreloadedAssets，它会把 Vite 的预加载转换成 Link 头。针对它报告过的两个问题，正好就是上面那两个坑：它的 modulepreload 提示曾经不带 crossorigin 发出，导致浏览器可能丢弃它们并把脚本下载两次；在大页面上，这个响应头还曾超过 Apache 约 8 KB 的头部上限。请在你使用的版本上把这两点都确认一下。

• 其他任何环境：用一个 Link 头以逗号分隔，或者发多个 Link 头，两种方式都行。

大家最容易过度的，是提示哪些资源。只提示渲染关键的 CSS、入口脚本和首屏用到的一两个字体，不要把每个 chunk 都塞进去。清单太长，浏览器就会先去取暂时用不到的东西，反而耽误了真正需要的。我把上限设为 12 个，而且这还是因为 Expo 导出已经替我筛选过预加载清单。

如果你不在 Cloudflare 后面，或者你的 CDN 不支持 Early Hints，Link 头也能帮上一点忙：浏览器可以在响应头一到达、开始解析正文之前就开始获取这些资源。但除非你的服务器或 CDN 主动发送，否则不会有 103。

如何确认它在生效

#

用 curl 可以直接看到 103。用 HTTP/2 请求，只保留状态行和 Link 头：

$ curl -sv --http2 -o /dev/null https://example.com/register 2>&1 | grep -E '^< (HTTP|link)'
< HTTP/2 103
< link: </_expo/static/css/reset-f5d396.css>; as=style; rel=preload, …
< HTTP/2 200
< link: </_expo/static/css/reset-f5d396.css>; rel=preload; as=style, …

先到的是 103，然后才是 200。Cloudflare 会调整提示里属性的顺序，这没有影响。不要指望每个请求都能拿到 103，我最初的三次里有两次拿到了。改动之后的第一次访问只是把响应头存下来，而当最终响应的头部已经就绪时，Cloudflare 会跳过 103。

然后回到上面的分析查询，用 requestSource: "earlyHintsCache" 过滤，按状态码和路径分组。在你修好的页面上，命中应该会逐渐取代未命中。

改变了什么，还剩下什么

#

响应头上线几分钟后，这个 zone 第一次记录到了 Early Hints 命中，curl 也在网页上看到了真正的 103 响应。一个响应头同时解决了两个问题：功能开始生效，一部分"504"也随之消失。

剩下的问题是，JSON API 没有什么可预加载的。API 端点会继续未命中，继续写下 504 行；在以 API 为主的 zone 上，这些仍然占大多数。你有三个合理的选择。在有收益的页面上发送响应头，接受 API 路径继续记录未命中；功能生效，图表会安静下来，但不会完全安静。无论你做什么决定，都把 earlyHintsCache 从 5xx 告警和仪表盘中排除，因为内部的缓存查询永远不应该把人叫醒。或者，如果你今后都不会发送 Link 头，就关闭 Early Hints（在控制台的 Speed → Settings → Content Optimization，或者通过 API 修改 zone 的 early_hints 设置）；HTML 很小的单页应用可能本来就收益不大，关掉之后所有查询都会停止，噪音也会一起消失。

我选择保留它。现在网页能抢先一步，API 的未命中也已经从所有会触发告警的地方过滤掉了。这正是 9 月时我本该做的事，而不是把功能关掉。

如果你是来找「怎么在 GitHub Actions 里跑 Docker Compose」的：我这么干了两年，然后停了。现在 CI 把同样的 Postgres 和 Valkey 镜像声明为 services:，直接在 runner 上跑同样的 uv run … 和 npm run …；Compose 回归成开发者本地跑的东西。下面是原因，连同文件。

2024 年我写过一篇用 Docker Compose 做 CI/CD，别把逻辑写进平台专属的 YAML，意思是构建逻辑放进 Compose，CI 工具只负责调用它。两年后，我把自己真正用来发布的仓库全部翻了一遍。有工作流的仓库一共四个，提交者都只有我一个人，而这些工作流里，已经没有一个在调用 docker compose 了。原则留下来了，做法没有。下面是取而代之的东西：删减过的示例文件、GitHub 记录下的每一步耗时，以及那些没有 CI/CD 示意图期望的那么自动化的部分。

我跑的所有流水线，一张表

#

用教科书的话说，两个 Hugo 网站是持续部署；而那个应用（我做的一个集市兼社区应用）是持续集成加上一条命令就能完成的发布，也就是持续交付：检查会告诉我哪里不对，但不会拦着我部署。这是有意为之。一次 OTA 更新会送到所有装着目标二进制版本的手机上，所以发布它应该是一个决定，而不是合并的副作用；而 API 是数据库迁移运行的地方。我另外两个 Django 应用，压根没有工作流。

CI 这一半：一个工作流，两个 job

#

这个应用的 CI 只有一个文件，.github/workflows/checks.yml。10 月 11 日之前，连它都没有。下面是删减后的示例，看个大致样子：

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

两个 job 并行运行。到目前为止成功的 35 次运行里，应用 job 的中位数大约七分钟，Python job 大约十二分半。

services: 这一块，就是 Compose 文件搬去的地方，下一节细说。环境变量只有寥寥几个，外加一个开关；其余的一切，都会回落到开发者 docker compose up 时拿到的开发默认值，所以测试不需要任何密钥。为了确认真是这样，我只用这套环境、别的什么都不带，跑了一部分测试。

CI 用的解释器和我的笔记本、生产镜像是同一个，也就是 uv 自己构建的 Python 3.15.0，因为 uv sync 会读 .python-version，并下载正是那个版本。（我真实的文件里还给 setup-uv 传了一个 python-version-file 输入，其实什么都没做：setup-uv v6 没有这个输入，每次运行都带着一条这样说的警告。写这篇文章时我才发现。）

解释器一致的好处，在工作流上线八天后就显出来了。10 月 19 日我打开了 3.15 的 JIT 编译器，开启后的第一次运行就有一个测试失败：一句再普通不过的 yield from，在每次保存都会经过的代码路径上，抛出了 AttributeError: 'list' object has no attribute 'send'。同一个提交关掉 JIT 就能通过。我的 Mac 是 arm64，从没碰到过它；而 runner 是 x86_64，和生产机器一样。JIT 现在在 CI 和 Dockerfile 里都重新关掉了，这个 bug 从没到过生产环境。这就是 python/cpython#155823，上游在 10 月 13 日、也就是 3.15.0 发布之后修掉了它。

其实第一次运行也失败了，原因更无聊。Expo 在 expo start 时会生成 expo-env.d.ts，而这个文件被 gitignore 了，所以我用过的每个工作副本里都有它，全新的检出里却没有。TypeScript 报了五个本地从没出现过的错误。补上生成这个文件的那一步，就修好了。

concurrency 会在同一分支来了更新的推送时，取消之前的运行；到目前为止被取消的十二次运行，全都是这么结束的。另外还有一个提交前钩子（pre-commit），会跑代码检查，暂存了 Python 或 TypeScript 文件时再跑类型检查，所以大部分错误根本走不到推送那一步。

Docker Compose 文件去哪儿了

#

下面是这个应用的 docker-compose.yml 里 CI 关心的那部分，同样是示例。真实文件里服务更多，环境变量也多得多。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

把它和 checks.yml 里的 services: 放在一起看，是同样的两个镜像：Postgres 17（这里是 Alpine 版，CI 里是 Debian 版）和 valkey/valkey:8-alpine。现在两者的关系就是这样：Compose 文件是开发者跑的东西；CI 把同样的镜像声明为服务容器，然后直接在 runner 上跑开发者跑的那些命令，uv run … 和 npm run …。

和 2024 年那篇对照，我最在意的部分留了下来：CI 工具依然很薄，检查和部署都是我自己就能跑的命令。没留下来的，是让 CI 去调用 Compose。

这个应用的 CI 根本不构建 Docker 镜像；镜像在部署时由 Fly 的构建机构建一次，CI 只需要回答代码好不好，工具链有缓存的话，这只要六秒的安装。另外，Compose 文件会把工作副本 bind mount 进去、灌入种子数据，这些都不是一次测试运行该做的事。所以 CI 本来还得有一份自己的 Compose 文件，也就是同一组服务的第二份描述，靠手工保持同步。

还有，2024 年那个例子里有个我当时没发现的 bug。docker compose build 只构建镜像，从不运行服务的 command，所以那个文件里的 npm test 在 CI 里一次都没跑过，工作流不管测试过没过都是绿的。

那篇文章最担心的风险，也就是换 CI 供应商，始终没有发生。真正发生的迁移在另一头：这个博客和那个客户的网站换了托管，搬到了 Cloudflare Pages，博客这边只是新写了一个 45 行的工作流，因为构建本来就只是一条命令。至于我当年警告过的三百行工作流？我确实有一个，pyhtml2text 的。它之所以长，是因为 wheel 必须分别在 Linux、macOS 和 Windows 的 runner 上、为多种架构构建，也正因为如此，这是唯一一个平台专属 YAML 才是对的工具的活儿。

缓存：先看每一步的耗时

#

GitHub 记录了每一步的耗时，用 gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs 就能拿到。下面是这个应用最近一次成功的运行，10 月 20 日：

两个依赖缓存都开着，而且都是便宜的那部分。GitHub 为这个仓库保存的 uv 缓存只有 200 KB 左右，因为 setup-uv 会清掉 uv 重新下载就行的东西；npm 的接近 400 MB。时间花在测试上，而测试已经四路并行了。想让运行更快的话，我会去改测试套件，而不是缓存。

博客的情况正好相反。Hugo 处理过的图片放在被 gitignore 的 resources/_gen 里，所以每台新的 runner 都要把封面、正文图片和占位图全部重新编码一遍。下文的工作流用 actions/cache 把它们恢复回来，键是图片本身的哈希，对不上时退回到最新的旧缓存，因为 Hugo 只处理缺的部分。加缓存之前的最后八次运行，构建这一步要 33 到 76 秒；之后的 26 次是 6 到 20 秒，只有一次例外，94 秒。而且同一个提交还加了占位图和第二种卡片尺寸。

这个应用的镜像在 Fly 的构建机上构建，依赖文件先于代码复制进去，uv 的下载缓存放在 BuildKit 的缓存挂载里（RUN --mount=type=cache,target=/root/.cache/uv）。不过最大的改进并不是缓存。旧的 .dockerignore 是黑名单，漏掉了一个放额外 git worktree 的文件夹，每个 worktree 都带着自己的依赖和构建产物，结果每次部署都有 27.7 万个文件、7.7 GB 被传到构建机。改写成白名单之后，构建上下文大约 40 MB。这种写法的示例：

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

密钥，放在尽量少的地方

#

密钥放在三个地方。GitHub Actions 的密钥用于工作流要做的事，两个 Hugo 仓库各自只有一个，CLOUDFLARE_API_TOKEN。Fly 的密钥是应用运行时的配置，用 flyctl secrets set 设置，从不经过 Actions。最后，我笔记本上被 gitignore 的 .env 里，放着部署脚本清 Cloudflare 缓存用的令牌。

PyPI 完全不需要密钥。pyhtml2text 用的是可信发布（trusted publishing）：PyPI 接受 GitHub 签发给工作流的短期 OIDC 令牌，所以发布 job 只申请 id-token: write，仓库的密钥页面是空的。没有可泄露的，也没有要轮换的。

令牌只给它需要的权限。这个应用在 GitHub 上的 Fly 令牌，服务于一个只列出机器的定时检查，所以是用 fly tokens create readonly 创建的。Pages 部署只申请 contents: read 和 deployments: write，别无其他。

输入一律经过 env:，绝不直接塞进脚本。OTA 工作流接收自由填写的发布说明。如果在 run: 里写成 ${{ inputs.notes }}，文本会在 bash 读取之前原样贴进脚本，于是一条带引号和分号的说明就成了代码。作为环境变量传进去，它就始终只是数据。这种写法的示例：

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

有些密钥干脆不放在 GitHub 上。有一份定时报告需要一个对应用登录后端有管理员权限的密钥，所以它从定时工作流搬到了我 Mac 上的一个定时任务。工作流仍然留着作为手动备用，只是会略过需要那个密钥的部分。

部署：每次推送、靠脚本、按 tag

#

Hugo 网站每次推送都部署

#

这是博客工作流的示例版本，省掉了第一次运行时创建 Pages 项目的那一步：

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }} 让 main 成为生产，其他每个分支都得到预览 URL。那个客户网站的工作流和它是同一个结构，只是在构建前多了一行 rm -rf public，因为那边的 public/ 是提交进仓库的，不这样做的话，已删除的页面会一直留在上传内容里。

Hugo 的版本只在这里固定，别处都不固定。10 月份一次包管理器升级把我笔记本上的 Hugo 升到了 0.168，比主题支持的最新版本还高一个。部署一直停在 0.165，毫无察觉。

而构建本身就是测试。9 月 14 日，某个分支的预览部署连续失败了三次：那个分支上的一篇文章，用 Hugo 的 ref 链接到了一篇还是草稿的文章。CI 和生产一样，构建时不包含草稿，所以这个链接什么都指不到，Hugo 以 REF_NOT_FOUND 停了下来。在此期间，main 照常部署。

应用的 API 靠脚本部署

#

部署脚本的核心部分，示例如下：

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

以及 fly.toml 里对应的几行：

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

镜像只构建一次，以提交和时间组成的标签推到 Fly 的镜像仓库，再按这个标签部署，所以滚动上线的正是构建出来的那个东西。

让它做到零停机的，是先唤醒一台备用机器。max_unavailable = 1 只计算正在运行的机器，而这个应用空闲时一台运行中的机器都不留（挂起的机器大约一秒就能恢复）。所以以前那台唯一醒着的机器，会和睡着的机器在同一批里被替换掉，身后没有一台热着的机器。9 月 28 日，我用探针持续请求源站：直接 flyctl deploy 时出现了 7 次超时和一段 7.3 秒的空白；而用脚本部署时，先构建、在滚动开始前就有一台机器醒着，2,514 个请求一个都没失败。

脚本的其余部分，会在错误告警所在的团队聊天频道里留下部署标记，这样一阵错误涌来时，可以对照刚刚改了什么；然后清掉 Cloudflare 缓存，再把机器预热一遍。Web 前端完全不经过镜像，这部分我写在前后端分开部署：不重新部署 API 也能发布 Web 前端里。

迁移不是流水线的一个步骤。Fly 的 release_command 在我这里会卡住，所以由第一台用新镜像启动的机器拿锁并执行迁移，其他机器等着。因此每次迁移都必须兼容仍在运行的代码：一次部署里加列，下一次部署不再使用它，第三次再删掉。

这个脚本里没有哪一处非得在我的笔记本上不可，但有几个只在本地的文件把它留在了那里：Cloudflare 凭据，以及一份最后部署了什么的记录，全新的 runner 上不会有它们。它还会把未提交的改动也一起部署，并在聊天频道里说明这一点，而 Web 的发布脚本会拒绝不干净的工作区。

在每个分支一个预览环境里我写过，这些事手工来做，只有你一个人时没问题；从第二个开发者开始，它就必须因为 git 里发生了什么而发生。这个应用现在还是我一个开发者。那篇文章里的分支环境工作流，还留在我当初搭建它们的那个分支上。

OTA 工作流只能手动运行，因为发布应该是一个决定，也因为在有部分发布（partial rollout）进行中时，更新服务会拒绝新的发布，换成推送触发的话，每次金丝雀发布都会撞上。这个工作流一次都没跑过。到目前为止，每一次 OTA 更新都是从我的笔记本上，通过工作流调用的同一个脚本发出去的。保持工作流轻薄的理由，一句话就是这个：不管发布从哪里开始，跑的都是同一个脚本。

pyhtml2text 按 tag 发布

#

发布 job 如下，包名换成了通用的名字：

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

发布 job 会等所有构建 job 完成，只有 tag 才会真正发布；手动运行会构建并生成证明（attestation），但什么都不上传。actions/attest 记录每个 wheel 是由哪个工作流构建的，uv publish --trusted-publishing always 用 OIDC 令牌而不是密码来上传。这个包本身，我写在一个被关闭的 Pull Request、一个 fork 和一个 PyPI 包里。

定时工作流只是尽力而为

#

这个应用有一个定时工作流，检查 Fly 启动的机器有没有超过基线，不检查的话，第一次发现会是在账单上。它靠故意失败来报警，因为定时运行失败时 GitHub 会给仓库所有者发邮件。

它设的是 cron: '*/15 * * * *'，一天 96 次。可过去两周里，它每天只跑了三到八次，两次运行之间间隔的中位数大约三小时四十分。GitHub 文档给出的唯一解释是负载：Actions 忙的时候，定时运行可能会延迟，忙到一定程度还可能被丢掉。对持续的扩容来说，几个小时足够了。对于必须在几分钟内报警的东西，GitHub 的 cron 不是监控。

我会问一条流水线的几个问题

#

不管你是在搭新的，还是在审视现有的：

1. 如果 GitHub Actions 停摆一整天，你还能发布吗？不能的话，你的发布逻辑就在 YAML 里，2024 年那篇依然适用。
2. CI 跑的解释器、CPU 架构和数据库大版本，和生产一致吗？我的 CI 能抓到一个编译器 bug，只是因为 runner 和生产都是 x86_64，而我的笔记本不是。
3. 全新的检出能通过吗？通不过的话，通常是那些自动生成、又被 gitignore 的文件在作怪。
4. 一次运行的时间到底花在哪儿？加缓存之前，先看每一步的耗时。
5. 每个密钥放在几个地方？它真的需要放在 GitHub 上吗？

没有托管的 APM，生产环境没有链路追踪，也没有需要记着去打开的仪表板。唯一额外花钱的是日志归档，每月大约 2 美元。下面是完整清单，以及我弃用或不再信任的东西，其中一样让我追了好几天一个根本没有用户碰到过的故障。

我说的监控是什么，以及规模有多小

#

我说的 DevOps 监控指两件事：在别人告诉我之前就发现东西坏了，以及不靠猜就能查出原因。下面每个工具都按这两条来评价。

去年我写过一篇搭建开发者真正会用的监控，那时主要考虑的是团队：小团队用云厂商自带的监控，服务上百个了再上托管的 APM。这篇是同一个思路里最小的那一端。两个产品都是 Django，跑在 Fly 的 shared-cpu-1x 机器上，我当前的技术栈里写过，而且两边的开发者都只有我一个。如果说监控是一个产品、开发者是它的用户，那我这套监控的用户就只有一个人。九月我从 Fly 的指标里拉了一次基线，交易平台的 API 平均 CPU 占用是 1%。这不是企业级的技术栈，我也不打算把它包装成那样。

指标、日志、链路这三根支柱，我有两根。两个产品都没有分布式追踪：各自就是一套 Django 代码加一个数据库，没有服务边界让链路去跨。我平时看的链路只有一种，就是我工作站上反向代理的链路。

清单

#

表里没写“两个应用”的，都只说交易平台。估价应用的东西更少：Fly 的健康检查、日志和指标，iOS 上的应用分析，再加一个每天把数据库导出成 Parquet、我用 DuckDB 查询的任务。它没有崩溃报告，也没有告警频道，这是这篇里最大的缺口。（关于更新服务那一行要说明一下：做这个服务的公司付钱请我给他们的博客写文章。）

错误：把日志发到聊天频道的 logging handler

#

九月之前，未处理的 500、发送失败的推送通知、坏掉的 WebSocket 帧，唯一会出现的地方是 flyctl logs，而那条流没人会主动去读。现在由一个日志 handler 把 ERROR 及以上的每条记录都发到聊天频道，不管来自 API、WebSocket 服务器还是后台 worker。WARNING 故意不告警。

handler 在后台线程里发送，所以绝不会拖慢请求。它内部不写任何日志，所以不会递归。同一个错误最多每十分钟发一次，每小时上限 30 条，所以出故障时你读到的是一条消息，而不是一千条。

这个频道里还有我想拿来和错误对照着看的东西：部署在开始、上线成功和失败的地方都会发消息，带上 commit 和执行人，OTA 更新和 Web 发布也一样。某个账号短时间内集中输错登录验证码，也会记成 ERROR，所以有人在乱猜的话，会和故障出现在同一个地方。

十月来过一条告警，任何日志里都找不到对应的行。从那以后，每条告警都带上一个短的随机 id、主机名和进程的启动命令，同一行也写进那个进程自己的日志。找不到 id，就说明它来自一个不往那里写日志的进程，比如一个 SSH shell。频道里的所有消息也会进一条信息流，和我一起干活的编程 agent 可以读，所以在改代码的 agent 和我同时看到这些错误。

日志：用 Fly 的 log shipper 存到 S3，用 DuckDB 查询

#

Fly 自己的缓冲只有几分钟的输出，大概最后一百行，盯部署够用，查昨天的事就没用了。所以第三个 Fly 应用跑着 Fly 的日志转发器，就是订阅了组织日志流的 Vector，我只改了它的 S3 sink：

[sinks.aws_s3]
  type = "aws_s3"
  bucket = "myapp-logs"
  compression = "gzip"
  key_prefix = "logs/{{fly.app.name}}/%F/"   # one folder per app per day
  batch.timeout_secs = 300                  # a quiet app still lands its lines

交易平台各个应用的每一行日志，都以 gzip 压缩的 JSON 落进一个兼容 S3 的 bucket。转发器是一台 256 MB 的 shared-cpu-1x 机器，每月大约 2 美元，存储费可以忽略。DuckDB 用一个宏直接就地读取这些文件，一天的数据一秒左右就出来：

CREATE MACRO logs(app, day := '*') AS TABLE
  SELECT * FROM read_json_auto('s3://myapp-logs/logs/' || app || '/' || day || '/*.log.gz',
                               union_by_name := true);

SELECT timestamp, message FROM logs('myapp-api', '2026-09-06') WHERE message LIKE '% 500 %';

我在缩容到零那篇里测冷启动，用的就是这个宏：启动脚本每个阶段都会打一行，每行都带着机器 id，剩下的就是一个 GROUP BY。

所以同一条日志流按读者分成三层：归档保留 INFO 及以上（这也是生产环境的应用用 INFO 级别打日志的原因），实时查看脚本只显示警告和错误，聊天频道收 ERROR。不过三者都不知道是谁发的请求。访问日志里没有客户端 IP，也没有 user agent，这个得去 Cloudflare 查。

指标：Fly 自带的 Prometheus

#

Fly 给每个组织跑一个托管的 Prometheus，所以我自己不维护任何指标系统。有问题时直接查它的 API：每台机器的内存、CPU 和突发额度（共享 CPU 上 fly_instance_cpu_balance 很要紧），每个应用的响应数和并发数。有两件事我希望早点知道。用 fly tokens create 创建的 token 要以 Authorization: FlyV1 <token> 传入；Bearer 只对 flyctl auth token 给出的个人 token 有效，而只读 token 会返回 “something went wrong resolving organization”。另外数据大约只保留两周（Fly 的说法是 15 天左右）。

它在九月真正派上了用场。那时日志里一天好几次出现 “Could not open a database connection”，看上去完全就是应用的 bug。托管 Postgres 集群也在同一个 Prometheus 里，每次出现这个错误的那一分钟，主库的抓取耗时都从 80 毫秒左右跳到一到十秒，副本一切正常，Postgres 的启动时间也没变。Postgres 没重启过，是它底下的宿主机卡住了。我把时间戳发给了 Fly 的支持团队；十月初一次维护重启把主库挪到另一台宿主机之后，每天的卡顿就没了。

崩溃报告：指向我自己 API 的 Sentry SDK

#

以前应用在手机上崩了，我能看到的地方一点痕迹都没有。最直接的答案是 Sentry，我只用了它的一半：应用里装的是 Sentry 的开源 SDK，但 DSN 指向我自己 Django API 里的一个接口，这个接口接收 Sentry 的 envelope 格式，把崩溃归类，再通过同一个聊天 handler 告警。链路追踪、会话和回放都关掉了，只收错误。

没注册 sentry.io，是因为一天就几条报告，为此多一家掌握用户数据的厂商、隐私政策里多一行、再多一张账单，不值得。代价是符号化（symbolication），这块我还没补上。堆栈要么是压缩过的 JavaScript，要么是原始的 native 地址，所以一个 issue 能告诉我崩的是什么、哪个版本、哪台设备、用户崩之前做了什么，但说不出是源码的哪一行。

唯一的仪表板是一条消息

#

两个应用我都没做仪表板。去年那篇里写过一个检验标准：没人主动打开的仪表板，就是没证明自己的价值。自己送上门的消息不用打开，所以我最接近仪表板的东西，是每天早上发到团队聊天里的一条汇总。

开头是过去 24 小时的生产错误，从日志归档里读，而不是从聊天频道里读，因为告警限了频率，说不出一件事到底发生了多少次。数字、id 和地址先打码再归类，所以同一个失败出现一百次也只是一行加个计数，邮箱地址也不会流进频道。

接着是失败的健康检查、昨天的使用量和上周同一天的对比（周日永远不会像周一），最近一周的搜索流量、等着回复的聊天、任务看板，还有开销。哪一部分加载不出来就照实写，汇总照样发出去。

通过 API 读应用分析数据，会让你对这些数字多一点怀疑。八月份，阿塞拜疆来了 121 次 Android 首次打开，随后是 119 次卸载。那个月的 Android 总数，我是扣掉这些来看的。

发布有自己的界面。以前 OTA 更新从我自己的服务器发的时候，我看一次发布的方式就是后台里一个带 “is active” 复选框的列表，根本不知道有多少台手机真的装上了。现在这个服务的仪表板能看到设备实际在跑哪个版本、安装情况如何，坏掉的 bundle 崩溃、SDK 退回上一个版本时还会显示这次崩溃回滚。迁移到托管更新服务的经过我另外写过。

弃用的，或者不再相信的

#

这里面没有一样是付费工具。大多是我一直当成信号、其实不是信号的东西，还有一个放错了地方的任务。

按 user agent 分组之前的 Cloudflare 504 比例

#

九月，Cloudflare 面板上显示一天里有 22% 的请求以 504 失败，集中在应用每 30 秒轮询一次的那几个接口上，而健康检查全是绿的，应用自己的日志也说这些请求很快。我在上面花了好几天，发现机器冷启动要 25 到 33 秒、一天要冷启动 92 次，修好了，然后在缩容到零那篇里把它写成了原因。

第二天早上，我把同样的 504 按 user agent 分组。9 月 5 日到 9 日之间的 7,344 个 504，全部来自 Cloudflare 自家的 Early Hints 缓存查询（user agent 是 bastion early hints 和 nginx-ssl early hints），它们根本不会到达源站：这些行里的 504 记录的是一次缓存未命中，而不是超时。它们照搬真实请求的路径，所以都落在最忙的接口上，看起来和用户请求失败一模一样。应用、浏览器、curl 和搜索引擎爬虫一个 504 都没有。源站当时不发 Link 头，Early Hints 什么作用都没起，于是我先把它关了，后来才让它真正生效。

冷启动的优化并没有白做，部署和唤醒都因此变快了，但我以为自己在修的那个故障，从来没有落到任何用户身上。

所以我最想分享的一条规则是：相信 CDN 的错误率之前，先按 user agent 分组，确认那不是 CDN 自己的机制产生的。在 Cloudflare 的免费套餐上，就是对 httpRequestsAdaptiveGroups 发 GraphQL 查询，一次查一天。下一次虚惊也是靠同一个查询解决的：有个轮询接口从每天 70 到 260 次请求涨到了 2,880 次。不是爬虫，是我自己的 Mac，测试完把应用开在 iOS 模拟器里忘了关。

一路绿灯的健康检查

#

Fly 每 30 秒检查一次两个应用的 /api/health/，用结果决定哪些机器接流量，这件事它做得很好。但健康检查跑在已经起来的机器上，看不到机器起来之前发生的事：冷启动、代理前面的排队、根本没到达的请求。现在我只指望它做路由。

部署时改用探测脚本，它在整个部署过程中持续打源站，只要有一次失败就以退出码 1 结束。它抓到过一次普通的 flyctl deploy 留下了 7.3 秒的空档；换成先唤醒一台备用机器的部署脚本之后，2,514 个请求里一个失败都没有。

健康检查自己还造成过两次故障。七月，Django 的 SECURE_SSL_REDIRECT 给 Fly 的明文 HTTP 探测回了 301，所有机器检查失败，所有人都收到了 503。八月，我把健康检查视图里的 except Exception 收窄了，结果 “connection already closed” 错误以 500 漏了出去，Fly 把机器摘掉了，而视图里的重试恰恰就是为这种情况准备的。现在这个检查只问一件事：这个进程能不能处理请求。数据库卡住时，两个应用也不会再被一起摘出路由。

早间汇总在计数上也学到了同样的教训。交易平台会把空闲机器挂起，被请求唤醒的机器在启动后几百毫秒时第一次检查会失败，下一次就通过了。把这些都算上，每天早上的汇总读起来都像出了故障。所以现在一分钟内重新通过的失败会单独列出，标注为机器唤醒和部署。

CI 上的定时任务

#

早间汇总一开始是一个按 cron 定时跑的 CI workflow，不到一天就挪走了。它要读应用分析和搜索数据之后，需要的密钥就成了分析项目的服务账号密钥，这个密钥在那个项目里什么都能干，我不想把它放进 CI 的 secrets。现在由我 Mac 上的定时调度程序每 20 分钟运行一次，只在奥克兰时间早上八点以后、而且当天还没发过的时候才发，所以八点时在睡眠的 Mac 会在醒来时补发。workflow 留着当手动备用，只是不带应用分析和搜索那两部分。

如果从头再来

#

我会在第一个用户到来之前、而不是第一次故障之后，先搭好三样东西：把错误发到团队本来就在看的聊天频道，并且限流；一个能用 SQL 查询的对象存储日志归档；以及平台本来就在收集的指标。每月花几美元而已。应用上手机的那一周加上崩溃报告，不然手机上的崩溃谁也不会知道。等要查看的地方多到我干脆一个都不看了，再加早间汇总。

链路追踪，我会等到出现第二个服务、请求真的要跨服务时再上；托管的 APM，等到有一个需要共享仪表板、值班轮换、也有预算替别人付账单的团队时再说。去年那篇里提到的工具，是从那时候开始才回本的。在那之前，最有用的习惯不花钱：一个数字看起来很吓人时，先搞清楚是什么产生了它，再判断是什么坏了。这篇里的好几次虚惊，都出在监控本身，而不是产品。

我的工作环境是三台很少待在同一个地方的设备。一台 MacBook Air，我去哪它去哪。一台放在办公室、叫 devbox 的工作站，有块像样的 GPU，上面跑着 Ollama、几样微调工具、一个自带容器镜像仓库的小 Kubernetes 集群，还有我丢在那儿慢慢啃长任务的某个 agent。再就是我的手机：我做的应用真正被使用的地方就是它，而它一天里大部分时间连的是移动数据，不是 wifi。

很长一段时间里，这三台设备之间基本不通。笔记本在办公室局域网里能连上 devbox，出了办公室就不行。手机和笔记本连着同一个 wifi 时，能访问笔记本上的 dev server，前提是我记得绑定 0.0.0.0，还得手动敲进 DHCP 那天早上分给 Mac 的地址。工作站上所有有意思的东西，Ollama API、集群的仪表盘、链路追踪、镜像仓库，都绑在 localhost 或集群网络上，这是故意的，因为它们都不该出现在公网上。

这篇文章讲我怎么用 Cloudflare WARP 和两条 Cloudflare Tunnel 把它们连起来，这对我做 AI 功能和移动应用的方式带来了什么变化，还有那几个坏了却一声不吭的地方。

我真正想要的

#

写成需求的话，很短：

1. 笔记本应该是个瘦客户端。凡是需要 GPU、大量内存或者要跑几个小时的东西，都应该在 devbox 上跑，而笔记本无论在办公室、在家还是在咖啡馆，都用同一种方式连过去。
2. 手机应该能在任何地方、用移动数据访问我的 dev server 和 shell，而且不需要一个我得记着开关的 VPN。
3. 我用来观察系统运行状态的东西，仪表盘、链路追踪、docker info、模型列表，应该只有我能访问，而且永远不该有公网 URL。
4. 不开入站端口。办公室路由器不开，家里路由器不开，哪儿都不开。

第四条排除了老办法，也就是端口转发加动态 DNS。它也排除了很多取巧的方案：devbox 和笔记本都在我控制不了的 NAT 后面，而笔记本每隔几小时就换一个 NAT。

之前：一个装满 SSH 隧道的仓库

#

最早的版本是我自己写的一个小仓库，到现在它仍然是底层。它在笔记本上只解决一个问题：给通过 SSH 访问的东西起干净的名字，别的不管。dnsmasq 把 *.test 解析到 127.0.0.1，Caddy 按主机名路由到本地端口，用 tls internal 让浏览器满意，再由一组 autossh launch agent 保持 SSH 转发开着，断了就重连。主机名本身说明了东西在哪儿：

所以 https://devbox-ollama.ssh.test/api/tags 列出的是工作站上的模型，https://api.local.test 是我手上在做的那个应用的 API，跑在我自己的机器上。

用的是 .test 的子域名，而不是 .ssh、.cloud 这样新造的顶级域，也不是 .local。RFC 6761 把 .test 专门保留给这种用途，而 .local 归 mDNS 所有；占用它的话，Mac 上的 Bonjour 发现就会失效。dnsmasq 本来就通配了整个 *.test，所以多一级标签不花任何成本：一个指向 127.0.0.1 的 /etc/resolver/test 文件，此后再也不用改 DNS。

给不存在的域名上 HTTPS

#

这些名字全都走 HTTPS，证书浏览器也信任，对一个只存在于我笔记本上的主机名来说，这听起来不太可能。Caddy 靠它自带的内部证书颁发机构做到这一点。在某个站点上写 tls internal，Caddy 就会用本地 CA 给这个站点签证书，而不是去找 Let’s Encrypt；安装脚本会跑一次 caddy trust，把 CA 的根证书放进 macOS 的系统钥匙串（Chrome 和 Safari 读这里），以及 Firefox 自己的证书库。从此 https://anything.test 打开时都不会有证书警告，普通的 http:// 会重定向过去，而且没有任何东西离开这台机器。

这不只是为了好看。现在 Web 平台上有很多东西在纯 HTTP 下直接罢工：secure cookie、service worker、剪贴板 API、任何带 SameSite=None 的东西。在纯 http://localhost 上测 web 构建，会把那些到了真正 HTTPS 域名上才冒出来的 bug 藏起来。在 https://app.local.test 上测，它们就会在我的笔记本上现形。

一个站点块，每个服务除了端口都一样：

devbox-ollama.ssh.test, devbox-ollama.test {
	tls internal
	import cors
	reverse_proxy 127.0.0.1:11435 {
		import proxyhdr
		transport http {
			keepalive off
			dial_timeout 5s
		}
	}
}

麻烦的部分都在那两个 snippet 里。cors 把调用方的 Origin 原样回传，而不是发 *，因为一旦涉及凭据，* 就不被允许；它还自己用 204 应答 OPTIONS 预检请求，上游永远不用操心。proxyhdr 把 Host 头改写成实际连接的地址。有些挑剔的后端，包括路由器管理页面和 Chrome 的远程调试端点，会校验 Host，否则就会把 devbox-ollama.ssh.test 当成一个从没听说过的名字拒掉。Ollama 自己的 origin 检查接受任意端口的 loopback，所以把 Host 改成 127.0.0.1:11435 就能过。

keepalive off 是我原本肯定会搞错的那个。上游是 SSH 转发，网络一变，autossh 就会把它拆掉重建。开着 keep-alive 的话，Caddy 会一直攥着一条通往已经死掉的隧道的池化连接，在重载之前一直返回莫名其妙的 404。关掉之后每个请求都重新建连，在 loopback 上这点开销几乎测不出来。

每个服务也仍然响应它原来的扁平名字（devbox-ollama.test），所以启用后缀方案之前的书签还能用。

菜单栏

#

launchd 撑着十几条转发，我老在问的问题是"它还活着吗？"，而答案散在三个地方：launchctl list、lsof 和一次 curl。于是我写了个小小的菜单栏插件把它们归到一处，每个主机名前面有个圆点：

• 🟢 服务通过隧道响应了请求
• 🟡 隧道是通的，但后面的服务没反应
• 🔴 本地端口上没有任何东西在监听，也就是隧道本身断了

有用的是黄色这一档。只分绿和红的检查，区分不了"SSH 转发断了"和"远端的 Ollama 崩了"，而这两者的修法完全不同。插件不自己维护服务列表，而是读取和其他部分同一份代理配置和 SSH 配置，所以在那里加一个服务，菜单里也就有了。

第一版太贪了。它每十秒刷新一次，每个服务都要起好几个进程，一次运行大约七十个，macOS 立刻把它列进了"耗电量大的应用"。改成每次运行只取一次快照、每隔几分钟刷新之后，降到了大约一个核的 0.1%。一个状态灯要是费电，就帮了倒忙，所以开销最好一开始就算进去。

它有一个漏洞，恰恰是最要紧的那个。devbox 没有公网域名。它的 SSH 转发连的是一个 192.168.x 地址，所以只有笔记本在办公室局域网里时才管用。一离开办公室，菜单栏就变红，而且一直红着；我为了给笔记本减负而搬到工作站上的所有东西，恰好在我不坐在它旁边的时候全都够不着。

两条隧道，方向要对

#

解法分三部分，前两部分是 Cloudflare Tunnel。

Cloudflare Tunnel 就是 cloudflared 保持一条通往 Cloudflare 边缘的出站连接。Cloudflare 把请求沿着这条连接送回来，所以不管机器躲在多少层 NAT 后面，路由器上不用监听任何端口就能访问到它。笔记本连上酒店 wifi 它照样跟着走，CGNAT 也拦不住它。

我跑了两条，每台机器一条，原因值得说一句。显而易见的捷径是只在笔记本上跑一条隧道，再加一条 ingress 规则，指向办公室局域网里 devbox 的 SSH 端口。这样 devbox 上什么都不用装。可它也要经过笔记本，而笔记本正是那台会离开办公室的机器。它会恰好在它本该解决的那种情况下失效。devbox 不挪窝，所以由 devbox 自己保持通往边缘的连接。

# config.yml on devbox (runs as a systemd service)
protocol: auto        # prefer QUIC, fall back to HTTP/2 over TCP 443
ha-connections: 4     # mains-powered, its job is to stay reachable

warp-routing:
  connectTimeout: 5s

ingress:
  - hostname: ssh-devbox.example.com
    service: tcp://127.0.0.1:22
  - service: http_status:404

用 tcp:// 而不是 ssh://，是个很容易弄错的地方。ssh:// 选的是 Cloudflare 在浏览器里渲染的终端，它会把数据流包装成网页用的格式；普通的 ssh 客户端从这里过，能收到 banner，然后死在密钥交换那一步。tcp:// 才是 cloudflared access ssh 期待的那种纯字节管道，顺带还能承载 scp、rsync、走 SSH 的 git 和端口转发。

最后这一点，正好补上了 SSH 这一层的漏洞。现在 SSH 配置会按每次连接选路：

Match originalhost devbox !exec "nc -z -G 1 <office-lan-ip> 22 >/dev/null 2>&1"
    ProxyCommand cloudflared access ssh --hostname ssh-devbox.example.com ...

在办公室局域网里，探测成功，SSH 直连，一跳到位。在其他任何地方探测失败，SSH 就走 Cloudflare，用 Access service token 认证，中间不用在浏览器里登录。这里是 Match originalhost，不是 Match host：host 在 HostName 替换之后才匹配，那时名字已经变成 IP 了，这个块永远不会触发。结果就是 devbox-ollama.ssh.test 在办公室、在家、在火车上都能用，菜单栏上的圆点一直是绿的。

笔记本上那条隧道方向相反。它给 Mac 上的 dev server 分配真正的公网 HTTPS 主机名：我手上在做的每个应用，都有 API、WebSocket 服务和 web 构建这三个。它们每一个都挡在 Cloudflare Access 后面，这一点后面还会讲，因为正是它让这件事变得安全，而不是鲁莽。

菜单栏也学会了认这两条隧道，而且没法靠探测来做。入站隧道没有本地端口可查，两个 connector 里有一个根本不在笔记本上跑，而最直接的测试，curl 一下 ssh-devbox.example.com，不管有没有 connector 挂着，都会从 Cloudflare 边缘拿到响应，所以隧道死了它也会显示绿色。launchd 也好不到哪去：cloudflared 所有边缘连接都断了，它照样显示"loaded, exit 0"。所以隧道这部分改成去问 Cloudflare API 每条隧道有没有健康的 connector，因为决定一次 ssh 能不能落地的就是它。如果连不上 API，这一整部分就干脆不显示，而不是画成红色。菜单是扫一眼就看的东西，那里的一次误报，比少一行的代价更大。

第三部分：WARP 让它成为一个网络

#

带主机名的隧道对任何说 HTTPS 的东西都很好用，对能跑 cloudflared 的机器上的 SSH 也一样。手机不行。而且隧道主机名不是一个 TCP 端点：Cloudflare 边缘在上面只终结 HTTPS 和 WebSocket，所以 ssh.example.com 的 22 端口是关着的，在 Access 上怎么折腾都打不开。

这就是 WARP 的活了。Cloudflare One Agent（企业版 WARP 客户端，不是面向普通用户的"1.1.1.1"应用，那个加入不了组织）装在笔记本和手机上，注册进我的 Zero Trust 组织。每条隧道通告私有路由，运行 WARP 的设备就能直接对这些地址开一个普通 socket，落到正确的机器上。它不再是"按名字访问这个服务"，而是"这几台机器和我在同一个网络里"：

这些地址是每台机器上的 loopback 别名，开机时创建，所以跟 DHCP 或者我身后是哪台路由器都没关系。198.18.42.2 就是 devbox，在办公室是，在家是，从连着 5G 的手机上也是。Mac 真正的局域网地址我每换一个地方就变一次；这个永远不变。

split tunnel 用的是 include 模式，里面只有这些路由（外加 WARP 自身需要的 Cloudflare 网段）。正是这一点让这个客户端能长期开着。默认是 exclude 模式，WARP 承载除一串私有网段之外的所有流量，于是手机发出的每个字节都要绕道 Cloudflare。这对电量和延迟有实打实的代价，大到我最后只会在需要时才打开它，那就失去意义了。在 include 模式下，发往我这三台机器的流量走 WARP，其他一切照常走原来的路径，完全不受影响。所以客户端就一直开着。笔记本上的 warp-cli status 整天都是 Connected，我根本不用去想它。

传输方式我选的是 MASQUE，也就是跑在 UDP 443 上的 HTTP/3，带 HTTP/2 回退，而不是跑在 UDP 2408 上的 WireGuard。有些运营商和访客网络会封 2408；几乎没人封 443。我组织的策略还给 MASQUE 打开了后量子密钥协商，这不是我特意去找的，但也没理由拒绝。

为什么是 198.18，为什么还有 IPv6 地址

#

这些地址看着有点怪，而我最初挑的那几个错得很有教育意义。

我第一次用的是 10.10.0.1，因为大家顺手就会选它。它在两种 split tunnel 模式下都不行。在 exclude 模式下，WARP 的默认列表排除了所有 RFC 1918 网段外加 100.64.0.0/10，所以客户端会在流量离开设备之前就把它丢掉。在 include 模式下，它会和我碰巧接入的任何真实 10.x 网络冲突；咖啡馆、联合办公空间和不少办公室用的正是这个网段。198.18.0.0/15 是 RFC 2544 的基准测试网段。它是保留地址，从不在公网上路由，不在 WARP 的排除列表里，普通网络也不会用它。IPv6 地址用 ULA（fd00::/8），理由相同。

为什么要有 IPv6，这个故事更有意思。v4 地址通了以后，我在手机上连着 wifi 测了一下，没问题，就当完事了。换到 5G 上，不通了。Agent 显示 connected ，隧道健康，Access 也没问题；wifi 上的测试已经证明了这些。问题在于现在的移动网络大多是纯 IPv6。手机根本没有原生 IPv4，是通过运营商的 464XLAT 转换器去访问那个 v4 字面地址的，而当 include 列表里只有一个 v4 前缀时，这个转换器位于隧道 之外 。流量就这么出了公网，而 198.18.0.0/15 在公网上不路由，于是被悄无声息地丢掉了。手机上没有报错，connector 的日志里什么也没有。

解法是给每台机器再配一个手机能原生通过 IPv6 访问的地址，并把它加进路由和 include 列表。现在我手机上的 SSH 客户端在移动数据下真正用的，就是 fd12:3456:789a:: 这组地址。

卸载：把笔记本当终端用

#

整套配置就是为这一部分存在的。

模型和微调。 Ollama 跑在 devbox 上，绑定 127.0.0.1:11434。办公室局域网里的其他机器都看不见它，更别说公网了。在笔记本上，它出现在 https://devbox-ollama.ssh.test，或者给需要端口的工具一个裸端口：

OLLAMA_HOST=127.0.0.1:11435 ollama list

用 11435 而不是 11434 是故意的：11434 是 Ollama 自己的默认端口，要是笔记本哪天也跑了个本地 Ollama，两者就会抢这个端口，而我会根据谁先启动，悄悄地从"本地"那个拿到 devbox 的回答。

实际效果是，我做 AI 功能时，它调用的模型跑在工作站的 GPU 上，而不是笔记本上，不管我人在哪儿。评估跑批、给一大堆文档做 embedding、跑一次微调：都在 devbox 上跑，笔记本的风扇一声不响。做 agent 原型时，可以让它指向工作站上的本地模型，反复跑工具调用也不产生 API 账单，等循环调顺了再换成托管模型。

长时间运行的 agent。 一个要跑一小时的 agent 会话，不该取决于我的笔记本盖子是不是一直开着。改在 devbox 上跑，笔记本就只是一扇看它的窗口：合上盖子，过会儿不管在哪儿 ssh devbox，或者从手机上连，它都还在。有隧道之前，这只在办公室里管用，而办公室恰恰是我最不需要它的地方。

构建和集群。 devbox 上的集群有自己的镜像仓库，所以镜像可以在工作站上构建和推送，就在它们运行的地方旁边，而不是用笔记本通过酒店 wifi 上传。集群仪表盘、ingress 仪表盘和镜像仓库的 UI，在笔记本上都是 *.ssh.test 主机名。

移动端的开发循环。 手机和笔记本在同一个私有网络里，笔记本的 dev server 还有挂在 Access 后面的公网主机名。所以我可以带着应用的原生构建走出大楼，连着 5G，它照样和我桌上跑着的 API 通信。或者和 devbox 上那个通信，如果我把它留在那儿的话。在真机、真实移动网络上的反馈循环，以前意味着部署到共享的 staging 服务器。现在意味着保存一个文件。

这里有个坑，最好在你把它当成应用 bug 去调之前就知道。Access 也保护着 WebSocket 主机名，而原生的 WebSocket 客户端不是浏览器。它不带 CF_Authorization cookie，所以原生构建连到 WebSocket 服务的连接会在边缘被一个 403 拒掉，看起来跟你自己服务器报的错完全不像。浏览器标签页没问题，因为登录后它们已经有了那个 cookie。对任何不是浏览器的东西（原生应用、脚本、调用 dev API 的 agent），答案是 Access 的 service token，以两个请求头的形式发送：

CF-Access-Client-Id:     <client_id>
CF-Access-Client-Secret: <client_secret>

这个 token 本身什么权限都不给。Access 只在策略里点了它名的应用上认它，所以它能触及的范围恰好就是那串 dev 主机名，一点不多。我把它的策略归在 non_identity 决策下，而不是 allow，这样在审计日志里它始终显示为一个持有者凭据，而不是某个登录进来的人。

公网永远看不到的数据

#

我想要的另一半是可观测性。能告诉你系统运行状况的东西，大多数本就不该公开，这没错。在 devbox 上，这些东西是：

• ingress 代理的仪表盘，以及装着它的链路追踪的追踪界面
• 管 Kubernetes 集群的仪表盘
• 容器镜像仓库的 UI（只读）
• Ollama 的模型列表和当前加载了哪些模型
• docker info 和容器统计数据

这些都没有公网主机名，以后也不会有。它们绑定在 loopback 或集群的 service IP 上，通过 SSH 转发访问，而这条转发本身又跑在隧道上。我手机上有个监控应用，经 WARP 通过 SSH 读取 docker info --format '{{json .}}'，所以不管在哪儿，我都能看到容器是不是都在跑，或者有没有什么东西把内存吃光了。

也正是这个应用让我发现了一个值得一提的小 bug。Mac 上那个隧道用的 sshd，还停留在我调试时设的 LogLevel DEBUG2。带 -e 时 sshd 把日志写到 stderr，而对一个会话来说，这个 stderr 就是 SSH 通道的 stderr。每条命令的输出后面都多了一行 debug2: do_setup_env: set TMPDIR，而手机应用会把两个流合并，于是拿到的是合法 JSON 后面跟着一行日志，解析失败，把整段显示成错误。改成 LogLevel INFO 就好了。调试完记得把日志级别改回去。

同样是刻意为之的，是我 不 放进这个网络的东西。旧的 autossh 隧道还能连到几台别人网络里的路由器，我帮忙照看着。它们没有公网主机名，也没有 WARP 路由。路由器管理页面挂在公网上，哪怕有登录挡着也是个隐患，而且那不是我的网络，轮不到我去扩大它的暴露面。

Access 不是可选项

#

Cloudflare Tunnel 的主机名，DNS 记录一建好就在公网上了。它前面没有防火墙；不开端口的全部意义就在这里。保护必须来自 Cloudflare 边缘，而这正是 Access 做的事。在访问者证明自己是谁之前，它根本不转发请求，所以没认证的扫描器永远到不了笔记本。这很重要，因为这些是 dev server：带着 settings 的调试模式报错页，一个敞开的 JavaScript bundler。这些主机名后面的东西，没有一样是为面对公网而做的。

策略只放行我自己的几个邮箱地址，别的一概不放，证明身份的方式有两种：邮件一次性 PIN 码和 SSO 单点登录。会话持续八小时，因为现实中的威胁是一台在咖啡馆里开着、带着一整天有效 cookie 的笔记本，而不是有人暴力破解 PIN 码。

SSH 被认证了两次，由两个互不知情的系统分别负责。Access 决定一条 TCP 流能不能到达 sshd；sshd 照样要我的密钥。丢了其中任何一个，机器都不会因此敞开。Mac 上的隧道 sshd 还信任 Cloudflare 的 SSH CA，所以 Access 可以用从我的 SSO 会话签发的短期证书让我登录，同时 authorized_keys 也照样能用，这样一份坏掉的 Access 配置也不会把我锁在自己的笔记本外面。

我最满意的是一个很小的部分。暴露发生在三件事同时成立的时候：一条 DNS 记录、一个在跑的 connector、一个已激活的 zone。它们在不同时间变为真，顺序也不由我控制；zone 会在 nameserver 改完之后过一阵子自己变成 active，那时 Mac 很可能正睡着。所以 launch agent 不直接跑 cloudflared。它先跑一个预检：从隧道自己的配置里读出主机名，问 Access API 哪些已经被覆盖，只要有一个没被覆盖就拒绝启动：

HOSTNAMES=$(grep -E '^\s*-\s*hostname:' "$CONFIG" | sed -E 's/.*hostname:\s*//' | sort -u)
PROTECTED=$(curl -fsS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps?per_page=100" \
    | python3 -c 'import sys,json; print("\n".join(a.get("domain","") for a in json.load(sys.stdin)["result"]))') \
    || { echo "could not reach the Access API. refusing (fail closed)."; exit 1; }

for h in $HOSTNAMES; do
    grep -qxF "$h" <<<"$PROTECTED" || { echo "NOT starting: $h has no Access app"; exit 1; }
done
exec cloudflared tunnel --config "$CONFIG" run

launch agent 设了 KeepAlive，所以被拒之后它每 30 秒自己重试一次，Access 应用一建好，隧道就自己起来了。失败时关闭，代价是一次宕机。失败时敞开，代价是一次暴露。我很清楚这两件事里我更愿意解释哪一件。

踩过的四个坑

#

上面这些现在都能用了。一路走来，四个坑里有三个是同一个模式：坏掉的那个东西在任何地方都不报错，而我能看到的部分全都显示健康。

路由和 include 列表是两份不同的列表。 隧道路由让 Cloudflare 愿意 把某个地址的流量送到正确的 connector。WARP 的 include 列表才决定客户端一开始会不会 发送 它。devbox 从手机上连不通，就是因为它的路由已经存在，但 include 列表里还只有 Mac 的地址。手机在本地就把包丢了，connector 从没见到过任何流量，所有仪表盘都是绿的。每加一台新机器，都要把它的地址同时加进这两处。

纯 IPv6 移动网络上的 IPv4 字面地址。 上面讲过了：wifi 上能用，5G 上失败，没有报错。如果一条 WARP 路由在 wifi 上能用、移动数据上不行，而 Agent 显示已连接，那是路由的问题，不是隧道的问题。

cloudflared 后面的 macOS sshd。 macOS 用 launchd 的 socket activation 启动 sshd，每个连接一个短命的 sshd -i。放在 cloudflared 后面时，banner 能到达客户端，但在客户端的标识字符串传回来之前，数据流就被拆掉了，所以每次登录都死在 kex_exchange_identification。我从两端都确认过，还用一个普通的 TCP 中继复现了出来，排除了 Cloudflare 的嫌疑。解法是另起一个独立的 sshd -D，监听 127.0.0.1:2222 和 WARP 的 loopback 地址，以我的用户身份运行，唯一的用途就是充当隧道的源站。系统设置里的远程登录原封不动。devbox 是 Linux，跑的是正常的常驻 sshd，从来没有这个问题。

不复存在的配置字段。 旧的示例在隧道配置里写着 warp-routing: enabled: true。cloudflared 2026.8 会直接拒绝这个字段。只要这个块存在、且有路由指向这条隧道，WARP 路由就是开着的。至少这个报了错，跟前面三个比起来，简直称得上厚道。

它改变了什么

#

老实说，总结起来就是：我不再根据硬件在哪儿来决定在哪儿干活。笔记本是一副好键盘、一块好屏幕，续航很长，它不需要比这更多。工作站不管我在哪儿都替我扛重活。手机是在真实网络上的真实测试设备，而不是拴在办公室 wifi 上的东西。而我用来观察系统在干什么的那些部分，对我来说一点就开，对别人来说根本不存在。

这个规模下，它在 Cloudflare 免费的 Zero Trust 套餐以内。花掉的是时间，外加一份我很庆幸写了的 README，因为上面那些故障，每一个第二次遇到时都会是一个全新的谜。

如果你在考虑搭类似的东西，下面是我会拿来问你的配置的几个问题：

1. 有哪些东西跑在你的笔记本上，只是因为笔记本是你唯一随时能连上的机器？
2. 你的手机能用移动数据访问你的 dev server 吗，而不只是在办公室 wifi 上？用 5G 测，别用 wifi。
3. 你的仪表盘里，有哪些是公开的，只因为那是从外面看它们最省事的办法？每一个都可以改成私有路由。
4. 如果明天某个隧道主机名起来了却没有对应的 Access 应用，什么会拦住它？如果答案是"我会记得"，那就把预检写出来。
5. 你的私有地址所在的网段，是你去过的那些网络永远不会用的吗？

想象一个小团队在做同一个应用。两个开发者也好，五个也好；不是分工不同的专家，而是各自在自己的分支上把一个功能从数据库迁移、经过 API、一直做到移动端界面，端到端地负责的人。这是运转团队的好方式，而从第二个开发者加入起，它就有一个反复出现的故障：“现在有人在用 staging 吗？“这条消息。

消息背后是一个做完了功能、想给测试或设计看、却看不了的开发者：staging 上跑着第二个开发者的分支，dev 上跑着第三个的，而那个分支两天前把登录搞坏了，之后就再没重新部署过。几个人，两个共享环境，一条聊天线程在负责排班。

这不是人的问题，是拓扑问题。每个开发者都把环境当作"我的分支变成真的"的地方，于是环境在替 merge 干活，一次一个分支，其他所有人排队等着。

我的技术栈在生产中的样子写在 My Current Stack 里：Fly.io 最便宜的机器上跑的 Django，连接池后面的 Postgres，给缓存和 Channels 层用的 Redis，独立的 WebSocket 应用，一个后台 worker，放文件的兼容 S3 的 bucket，一个托管的认证服务，前面挡着 Cloudflare，还有一个和这一切通信的移动应用。这篇文章讲的是我怎么把这套栈变成这样一种东西：任何分支，开发者往 PR 上打一个标签，几分钟后就拿到一份带 HTTPS 的、公开可访问的完整副本，不用求别人，也没人替他开通，而且不需要第二个 Postgres 集群、第二个 Redis 或第二个 bucket。基础设施保持共享。变化的是每一种共享资源都学会了按名字切片，而名字来自分支。这里面没有任何东西预设团队规模：两个开发者和二十个开发者用的是同一套设计，会增长的只有应用列表，而那由清扫器来处理。我在一个下午里把它搭起来，同时跑了三个分支，在两个没预料到的地方把它弄坏，又拆掉了；下面的输出都来自那次运行。

为什么一个共享环境撑不过一个开发者

#

共享的 dev 环境里烙着一个假设：所有人想看的"当前代码版本"只有一个。对单个开发者，或者对齐步推进同一条变更流的团队来说，这是对的。第二个开发者按另一个时间表开始做功能的那一刻，它就不对了；而在端到端负责制下，每个功能都是这样。从那以后，环境里的一切都成了争抢对象：

• 部署的代码。 最后部署的人赢。其他人的工作在重新部署前都看不见，而重新部署又会抹掉前一个人的。
• 数据库 schema。 当每个开发者都拥有自己功能的数据模型时，咬得最狠的就是这一条。第一个分支加了一列。一小时后部署的第二个分支不知道有这列，ORM 开始在 insert 上报错。或者两个分支都有一个 0042_* 迁移，共享数据库落到一个和谁的迁移历史都对不上的状态，然后有人把它重置，顺手删掉了第三个开发者花一下午准备的测试数据。
• 缓存。 一个分支改了序列化器，结果缓存到了另一个分支代码读取的同一个 Redis 键下。由此产生的 bug 报告莫名其妙，每个都要耗掉一上午。
• 第三方集成。 一个 OAuth 回调，一个 webhook URL，一个推送证书。谁的分支部署着，谁就收到事件。
• 测试人员。 他们只能测已经部署的东西，所以是按环境碰巧被谁占用的顺序、而不是功能就绪的顺序，一次测一个。

团队的应对是预约制：一条聊天线程、一条置顶消息、一个 /claim staging 机器人。那是一把锁，而锁在唯一能展示你工作的地方上，就是锁在交付速度上。两个开发者的话，只是烦人。三个的话，顺利的一周还能忍。加一个第四人，或者某个功能因为要和设计师来回三天而一直霸着 staging，就忍不了了。

人们最先想到的办法是再加一个共享环境，“dev2” 或者 “uat”。这能争取几周。队伍只是变成了两条道。

真正的解法是意识到 dev 和 staging 从来就不是环境。它们是某人分支的当前状态，附带一个 URL。如果它们是这样的东西，那它们的正确数量就是团队此刻在意的分支数，正确寿命就是分支的寿命。

模型：分支就是环境

#

目标状态是这样。

再看一遍表里谁创建、谁销毁：每一项要么是 git 事件，要么是时钟。git 就是控制平面。应该存在的环境集合直接由存在的分支集合决定，自动化唯一的工作就是让现实和它保持一致：PR 上的标签创建，之后每次 push 更新，关闭或合并 PR 销毁，每晚一个任务把前三者漏掉的收拾干净。也不是每个分支都会有环境：标签就是闸门，开发者点一下，所以备份用的 push 或机器人的依赖升级不花一分钱。没有人在开通环境。不是拿着工单的 DevOps 工程师，不是你在聊天里喊的机器人，也不是你每次都要提示一遍的 AI agent。第十个开发者的第一个分支拿到环境的方式，和第一个开发者的一模一样：PR 被打上了标签。如果还得去找一个人，那就没有扩展，只是队伍换了个地方排。

让它成立的规则只有一条：环境触及的每一种资源都按分支命名，且是确定性的。 不按开发者，不按工单，也不按那个没人开 PR 之前根本不存在的 PR 号。按分支，因为分支才是开发者实际打交道的东西，也因为名字确定，就意味着在同一分支上第二次运行 ./scripts/env up 会找到已经建好的环境，而不是再建一个。

名字是给人看的 slug 加上保证唯一的短哈希：

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c 就是环境。这个字符串会成为 Fly 应用名、Postgres 数据库名（连字符换成下划线）、Redis 键前缀、bucket 的对象前缀、错误追踪工具里的 environment，以及主机名最左边的标签。知道分支名的任何人都能算出来。什么都不用查。

最后那句话就是设计本身。没有环境注册表，没有协调者。env up、env down、负责路由主机名的 Cloudflare Worker，以及每晚的清扫器，各自独立地从分支重新算出名字，靠构造保证一致。尤其是 Cloudflare，它什么都不协调：Worker 是一个从主机名到 Fly 应用的纯函数，它永远不知道某个环境被创建或销毁了。应用存在，请求就落地；不存在，Fly 用自己的错误来回答。

由此得出三件事。

第一，“谁在用 staging"不再是个问题。有 feature-payments-retr-3f9a1c-dev.example.com，有 fix-login-redirect-8b21e0-dev.example.com，各归在那个分支上的人所有。

第二，staging 从垃圾场变成了对生产的诚实彩排。它用即将上生产的那个镜像构建，对着几分钟前从生产形态快照克隆出来的数据库跑。那里能跑通，生产里剩下的唯一变量就是生产数据。

第三，每个开发者获得了权力，却不需要任何共享资源的 root。分支环境的爆炸半径就是那个分支环境。第四个新人入职第一天想往自己分支上部署什么都行，最坏的结果是自己的分支坏了。

fly.io/dashboard/my-org

物理上共享，逻辑上隔离

#

“每个分支一个环境"的诱人版本是整套复制：每人一个 Postgres 集群、一个 Redis、一个 bucket。干净，但是笔坏买卖。一个 Fly Postgres 集群是一台机器加一个卷加一次恢复；一个 Redis 又是一台机器；你会为每个环境等上几分钟，并为十来个闲置数据库付钱。清扫器要清理的东西也从一种变成四种。

取而代之的是，每种共享服务为整个预览组织只配置一次，按小号生产的规格来，每个环境以 $ENV 为键分到一片。这是我想贴在墙上的表：

其中两行值得多说一句。

Postgres：用数据库，不用 schema。 切分单个集群的另一种做法是每个环境一个 schema，按连接设置 search_path。把 -c search_path=... 塞进连接的 options 里，Django 是能做到的，但事务模式下的连接池会丢弃启动参数，除非你专门告诉它别丢，而即便如此，池里的每个连接也终究只能属于一个环境。这是"为什么我的查询打到了别的表"这类 bug 的源头，而每个环境一个数据库根本不存在这个问题。数据库是硬边界，CREATE DATABASE ... TEMPLATE 几秒钟建一个，DROP DATABASE 把它删得一干二净。分支环境不走连接池，直接连 Postgres 的 5433 端口，和生产里的后台 worker 一样；连接池是在生产级并发下才值回票价的，而分支环境永远见不到那种并发。

密钥：生成，不共享。 弄一套 dev 密钥复制到每个环境里当然省事。别这么干。env up 脚本为每个环境生成新的 SECRET_KEY（会话签名）、ENCRYPTION_KEY（所有静态加密的东西）和 ENV_TOKEN（移动端出示的 bearer 令牌，下文详述），只存在那个 Fly 应用的密钥存储里。这意味着一个分支的会话 cookie 在另一个分支上一文不值，泄露的预览令牌只能打开一个预览，开发者不特意去找就永远看不到这些值。如果你把密钥放在单独的密钥管理工具里而不只是 Fly 里，规则一样：路径是 myapp/preview/$ENV/，清扫器会连同环境一起删掉这条路径。真正跨环境共享的密钥只有共享基础设施本身的凭据（Postgres 管理员 URL、Redis URL、bucket 密钥），而这些放在 CI 里，不在任何环境里。

Redis 那一行最容易让人怀疑，所以做了测试。从一个环境里面设一个缓存键，从另一个读，再列出共享 Redis 里的所有键：

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

同一个 Redis，同一个键名，另一个环境什么都看不到。

这篇文章剩下的部分，就是把 $ENV 盖到那八行上的脚本，以及让它保持诚实的规则。

./scripts/env up

#

这就是整个思路——一个开发者在自己分支上运行的脚本。CI 运行的是同一个脚本；没有会各自漂移的 CI 专用路径。笔记本上只需要 fly 和 git，别的都不要：SQL 通过 fly ssh 送到 Postgres 应用，环境的 Redis 键和 bucket 对象在销毁前由环境自己的机器删除，所以笔记本除了一个被 gitignore 的 env 文件之外，不持有任何共享 Redis 或 bucket 的凭据。下面只留了要紧的几行：

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

演示时我是从笔记本上直接跑的，而不是 push，因为这三个分支是一次性的，我不想让它们留在仓库历史里，也想盯着输出一行行出来。团队里用的时候没人会敲这条命令：下文的标签工作流跑的就是这个脚本，接下来的输出就是会落在 Actions 日志里的那些。这是它第一次在承载这套工具本身的分支上运行时打印的内容：

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

从命令到 URL 大约两分半，大部分是镜像构建。再提交一次后在同一分支上第二次 up，没有打印 “New app created”，也没有 “CREATE DATABASE”，暂存了同样的密钥名而没有重新生成已生成的那些，然后重新构建：同一个 URL，新的提交。

里面的几个选择各值得一句话。

fly.preview.toml 不是 fly.toml。 生产把 API、WebSocket 服务器和后台 worker 作为独立的 Fly 应用和进程组来跑，各按自己的指标伸缩，那正是技术栈那篇的全部论点。分支环境不需要伸缩；它需要的是一台机器。所以预览配置只有一个进程：容器的入口脚本多了一个预览模式，先跑迁移，再启动一个开着 WebSocket 的 ASGI 服务器。Channels 本来就在同一个 ASGI 应用里同时路由 HTTP 和 WebSocket 流量，所以一个进程就能服务整个应用。那个模式下同步视图按 thread-sensitive 方式运行，差不多一次一个请求——正是我在生产里放弃的那笔交易，而在这里恰恰合适，因为测试分支的人不会察觉。

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend"，min_machines_running = 0。 午饭后没人打开过的分支环境应该一分钱不花。用 suspend 而不是 stop，得到的是我追查 504之后落到的约 3 秒恢复，而不是 30 秒冷启动，而在这里就算 30 秒也能接受。三个演示环境里有两个在部署完成一分钟后就已经在 fly apps list 里显示 suspended 了。

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False，和生产同一个 settings 模块。 分支环境是一个公开 URL。在所有对测试重要的方面（真 HTTPS、真 cookie、同样的健康检查）它都应该像生产，在所有可能伤到人的方面它都应该不像生产。差异不靠单独的预览 settings 文件，而是由 env up 设置的密钥承载：沙箱支付密钥、没有认证服务的管理员凭据，以及打开下面所有前缀的 ENV_NAME。

一个设置切分一切。 ENV_NAME 是 settings 里唯一新增的旋钮，应用在四个地方：

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

漏掉 channels 那一处，两个分支的 WebSocket 服务器就会共用组名，一个环境里发的消息会出现在另一个环境里。那是要耗掉一天的那种 bug。

第五处是事后读共享 Redis 才发现的。504 那篇里的启动锁——让每个镜像只有一台机器跑迁移、其他机器等待的机制——原本是以镜像引用为键的。从同一个提交构建的两个分支环境有同一个镜像。第二个会找到第一个的 “done” 标记，然后跳过它自己对自己那个尚未迁移的数据库的迁移。现在环境名是键的一部分，键也住在前缀下面。这是共享基础设施设计会不断产出的那类问题：所有隐含地"按部署"的东西都得显式地变成按环境，而在你去看之前，你不知道什么是隐含的。

数据库是克隆的，不是从空库迁移的。 下一节。

数据库：几秒克隆出来的模板

#

分支环境的数据库有三种可能。和所有人共享——这正是把我们带到这里的东西。空库，从零迁移再用 fixture 填充：确定性强，但 fixture 从来比不上真实形态的数据，而且永远陈旧十八个月。或者克隆一份生产形态的快照：真实的行数，fixture 假定总是有值的那些列里真实的 null，在空表上瞬间完成、在真表上要跑四十分钟的迁移会现出原形。

选第三种，第二种保留为只在 CI 跑的检查。而让第三种快到可以每个分支都做一次的，是一个大多数人忘了存在的 Postgres 功能：

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE 是集群内的文件级复制。几个 GB 只要几秒，而不是 pg_restore 的几分钟。被克隆时模板不能有打开的连接，datallowconn = false 强制了这一点，这也是为什么夜间任务往 seed_raw 里构建、最后再改名，而不是直接往活着的模板上恢复。

演示里模板是手工建的，而不是来自生产 dump：用 fly proxy 打一条通向预览集群的隧道，manage.py migrate，然后用仓库自带的填充命令生成一份不大但贴近真实的数据。十九兆。三个分支起来时，集群里出现了它的三个克隆，每个 19 MB，每个不到一秒：

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

预览集群是一个非托管的 Fly Postgres 节点，shared-cpu-1x 带 1 GB 卷，每月大约两美元。分支环境通过私有网络的 .flycast 连它；没有任何东西是公开的。

匿名化不是可选项。生产数据在 -dev 主机名上可达的那一刻，它就必须不再是生产数据：姓名、邮箱、电话、地址、自由文本、支付引用、令牌，全部在改名之前覆盖掉。匿名化失败，前一晚的模板保留，有人会收到消息。这是件小活，也正是让整个方案能被回答隐私问卷的那个人接受的那件活。

入口脚本在每个镜像首次启动时运行 migrate，所以分支自己的迁移会叠加在模板之上。这是"我的迁移在生产形态的数据上能不能跑"的第一次诚实测试，而且发生在任何人打开 URL 之前。

主机名：一个通配符、一个 Worker，以及文档没告诉我的两件事

#

每个环境都需要一个公开的 HTTPS 主机名，而"公开"正是重点：拿着手机的测试、另一个网络里的设计师、不肯装 VPN 的产品经理。Fly 免费给每个应用一个 myapp-$ENV.fly.dev，光靠它也能用。但 *.fly.dev 主机名有三个问题：发出去难看，前面没有 Cloudflare 所以你在生产上的所有防护都不生效，而如果想放到自己的域名下，就得每个环境一条 DNS 记录加一张证书，清扫器又多一样要清的东西。

把这些都去掉的版本，是一个通配符加一个 Cloudflare Worker。我原计划用 *.dev.example.com。两件事挡住了它，而且在你做同样的计划之前，两件都值得知道。

Universal SSL 只覆盖一层通配符。 Cloudflare 的免费证书签发给 example.com 和 *.example.com。它不覆盖 *.dev.example.com；二级通配符需要每月 10 美元的 Advanced Certificate Manager。对 feature-branch-envir-c65cb4.dev.example.com 的第一个请求在我的任何东西运行之前就死于 SSL 握手失败。解法是把环境留在第一层标签里：feature-branch-envir-c65cb4-dev.example.com。它被已经存在的证书覆盖，也被已经存在的、已代理的 *.example.com 记录覆盖——就是我为扫描杜撰子域名的爬虫设的那个黑洞记录。所以一个环境完全不需要 DNS。

Redirect Rules 在 Workers 之前执行。 路由配好之后，每个 -dev 主机名都在 Worker 没有运行的情况下 301 到了 www 首页。黑洞是一条区域级的重定向规则，“其他任何子域名 → www”，而 Cloudflare 的重定向阶段在 Workers 阶段之前执行。规则需要加一个子句：and not ends_with(http.host, "-dev.example.com")。部署脚本在 up 时加上、down 时去掉，因为手工改过的规则正是会被遗忘的东西。

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

DNS 这边就是那条本来就在的记录：

dash.cloudflare.com/…/example.com/dns/records

这两件事解决后，路由就是 *-dev.example.com/* 上的一个 Worker：

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare 在通配符上终结 TLS，Worker 从标签算出 Fly 主机名，到机器那一跳由 Fly 自己的 *.fly.dev 证书覆盖。WebSocket 升级原样穿过 fetch。而由于路由在区域上，Cloudflare 为生产做的一切在这里都可用：WAF 规则、限速、bot 防护模式，以及 Access。

dash.cloudflare.com/…/example.com/workers

三个分支同时在线，一个 Worker，以及每个主机名的应答：

每个 200 都带着 Worker 加上的 X-Robots-Tag: noindex, nofollow 和 X-Dev-Environment: <env>。那个 404 是 Worker 自己给的，根本没问过 Fly。

Cloudflare Access 是把"公开"变成"该到的人到得了"的东西。在 *-dev.example.com 上建一个应用，策略是"任何 @example.com 邮箱”，浏览器访客看一次登录页，之后就再也不用想它。设计师、PM 和用笔记本的测试就都覆盖了。演示里我没加；那些环境带着 noindex 在线了一小时，上面除了种子数据什么都没有。

它覆盖不了移动端，因为原生应用完不成 Access 的登录跳转。两条路。Access 支持服务令牌（一对 CF-Access-Client-Id / CF-Access-Client-Secret 请求头）绕过登录，移动应用的开发菜单可以为 dev 主机名带上一对。或者更简单，为 /api/ 加一条 Access 放行，让 Django 拒绝任何既没有已登录用户、也没有该环境 ENV_TOKEN——就是 env up 专门为这个环境生成的那个——的请求。无论哪种，移动端这边都是一个带两个字段的开发菜单页，基础 URL 和令牌，测试人员已经装好的应用现在就和那个分支通信了。不需要新构建。空中更新（OTA）通道继续指向应用构建时的那个；API 基础 URL 是运行时设置，不是构建时设置，本来就该如此。

认证是唯一有意共享的共享服务。身份不分环境；测试人员希望在每个分支上都用同一个账号登录。认证服务上一个授权域名里有 example.com 的 dev 项目覆盖所有 -dev 主机名，每个环境都对着它验证 ID 令牌。每个环境数据库里的用户表都是模板用户的副本，所以模板里有的账号，测试人员在哪儿都有。

用 GitHub Actions 自动化预览环境：事件进来，环境出去

#

上面的一切手工来做，只有你一个人时没问题。一旦有了第二个开发者，它就必须因为 git 里发生了什么而发生，而不是因为有人记得。整套自动化是四个工作流、一个仓库设置、一个规则集和一个 GitHub environment，其中每一个都把某个 git 事件映射到对开发者手工运行的同一个 scripts/env 的调用。没有会漂移的 CI 专用路径。

标签、push 与 delete 工作流

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

闸门是 env 标签，这也是我最想据理力争的部分。没有闸门，每个分支都要花掉一个应用和一份数据库克隆：某人为了备份笔记本而 push 的分支、明天就会被 squash 的 spike、机器人凌晨三点开的依赖升级。所以光 push 什么都不发生，光开 PR 也什么都不发生。给 PR 加上 env，环境就起来；标签在的时候每次 push 都更新它；移除标签、关闭 PR 或合并，它就下线。选择加入仍然是一个 GitHub 事件，而不是向某个人提请求，而且这一下点击是由唯一知道有没有人要看的那个人做的。置顶评论就是用户界面：给 PR 打标签，一条带 URL 的评论出现，可以发给任何人，而且每次 push 都在原地更新，不会堆叠。还没有 PR 就想拉起来的分支交给 workflow_dispatch，其余的交给笔记本上的 ./scripts/env up。

还有两种闸门值得知道。分支名过滤（branches: ['feature/**', 'fix/**']）不需要 PR，但每个功能分支都要付钱。“所有非草稿 PR"最自动，如果你的团队开 PR 开得晚、只在准备好时才开，那是正确的选择。我选标签，是因为它把花不花钱的决定交给了有上下文的人，也因为它可以收回而不用关掉任何东西。一个我喜欢的副作用：来自 fork 的 pull_request 运行拿不到 secrets，所以 fork 拉不起环境。

concurrency 比看起来更重要。对同一分支的一连串快速 push 会取消之前的部署而不是让它们赛跑；对同一应用同时跑两个 fly deploy，结局是其中一个输掉。

有过 PR 的东西，不管合没合并，拆除都由 closed 负责。delete 事件是给用 workflow_dispatch 拉起来、最终也没开 PR 的分支兜底的，而它只在分支真的被删除时才触发。那是一个仓库设置，Automatically delete head branches，默认关闭。打开之后，点 Merge 会关闭 PR 并删除分支，两个事件中的任何一个单独都会跑 env down。合并按钮就是拆除。

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN 是这个文件里危险的一行。它能创建和销毁应用，如果 $APP 变成了分支环境之外的任何东西，它就能销毁生产。两道防护，我两道都留着：令牌限定在一个单独的 Fly 组织里，从字面上就看不到生产组织（演示里为了省去给新组织绑定账单的步骤，我用了生产组织，只靠第二道防护）；以及 down() 拒绝任何不匹配 slug-hash 模式的应用名。

分支环境无法替自己做的检查

#

一个分支只看得见自己的迁移，所以真正要紧的检查跑在 pull request 上，针对合入 main 之后的状态，也是 main 要求的唯一状态检查：

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

三十秒。正是它把 0042 / 0042 的碰撞从发布日的意外变成了第二个开发者 PR 上的一个红叉；下面的迁移一节会展示它真的触发。

main 上的规则

#

如果分支能活一个月，或者有人直接往 main 上 push，上面的一切都撑不住。这些规则与其说是保护，不如说是为了让环境保持小、让迁移保持新：

• main 受保护且随时可部署。 只通过 PR 合并，且 migrations 检查针对当前的 main 是绿的（严格状态检查，所以上周绿过的 PR 在 main 前进后要重跑）。线性历史，禁止 force-push，禁止删除。
• 功能分支要短。 开了两周的分支，环境落后 main 两周，迁移和别人碰撞的概率也多了两周。一个月的功能藏在开关后面分块合入 main。长寿的是开关，不是分支。
• 一个分支，一个环境，一个数据库。 命名已经强制了。
• 只有发布标签能上生产。 镜像从标签构建一次；staging 和生产跑的是那个镜像，不重新构建。
• 动了 migrations/ 的 PR 由另外两人之一评审。 见下文。

写成规则集，用 gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json 应用一次：

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

一个诚实的褶皱。这个仓库是 GitHub Free 计划下的私有仓库，而在 Free 上，分支保护和规则集只对公开仓库可用；API 的回答是 403 Upgrade to GitHub Pro or make this repository public。delete_branch_on_merge 设置、environment 和工作流在 Free 上都能用。所以对于私有 Free 仓库上的小团队，上面的规则集是一种约定：migrations 工作流照样跑、照样变红，但没有东西会把合并按钮变灰。这是一个每月 4 美元的决定，我会在第二个人能合并的那一刻就做。

没有 develop 分支，没有 release/* 分支。Git-flow 的设计前提是集成昂贵、必须成批做。分支环境让集成变得便宜，成批的必要就消失了。

Staging 是标签的环境，生产是一次晋升

#

Staging 复用整套机制。main 上的一个 v* 标签用分支名 staging/v1.42.0 运行 scripts/env up，命名把它变成 staging-v1-42-0-<hash>：同样从模板克隆的数据库，同样闲置即 suspend 的机器，同样的主机名方案。区别在于之后发生的事：

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

production 作业等待一个设有必要评审人的 GitHub environment。有人看过 staging，点 Approve，生产就按引用收到 staging 跑过的同一个镜像，不是重新构建。最后一步销毁 staging，因为它的任务完成了。如果没人批准，发布候选就是被否了，而当它的"分支”（staging/v1.42.0 从未在 origin 上存在过）通不过存活检查时，清扫器会把 staging 清掉。没有清扫器能核实的理由，任何东西都不许存在。

每晚的清扫器

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0 是因为清扫器需要每个远程分支及其最后提交日期，而不是 Actions 默认检出的那一个提交。workflow_dispatch 是为了事故之后能手工跑一次。

开发者实际要做的事

#

push 一个分支，开 PR，想让人看的时候打上 env 标签。清单就这么长。三分钟内 PR 上出现一个 URL，每次 push 更新，PR 合并或关闭后消失。如果和队友撞了，迁移检查会比任何人都先告诉他们。没人去抢 staging，因为没有 staging 可抢；没人去拆任何东西，因为合并就是拆除。

而搭起这套东西的人，之后要为每个分支做什么？什么都不用。共享的 Postgres、Redis 和 bucket 开通一次，密钥放进 Actions 一次，此后反复要做的事只剩周一看一眼清扫器的日志。没有工单队列，没有要喊的机器人，没有要提示的对象。

不信任拆除的拆除

#

env down 是常规情况，有意思的地方在于谁来清理。Redis 键和 bucket 对象属于共享服务，而跑 down 的笔记本两者的凭据都不需要，因为环境自己的机器已经有了，也已经知道自己的前缀。所以 down 先把 suspend 的机器唤醒，在上面跑一条小小的清理命令，然后才销毁应用、删除数据库。环境自己收拾自己：

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

那个 530 再次印证了关于协调的那一点：Worker 仍在路由这个主机名，Fly 那边什么都没有，而没有人需要通知 Cloudflare。

这条清理命令没有 ENV_NAME 就拒绝运行，因为前缀为空时它会把整个共享 bucket 清空。它之所以做成应用里的一条命令、而不是 shell 脚本里的三行，全部理由就是这道防护。

环境照样会泄漏。GitHub Actions 故障期间有分支被删除。开发者为了做个试验在笔记本上跑了 env up，从来没 push。fly apps destroy 偶发失败，被 || true 吞掉。三个月后有四十个应用，和一张让人问"发生了什么"的账单。

所以有第二道机制，它不信任第一道：上表里那个每晚的清扫器。它列出所有 myapp-* 应用，弄清每个属于哪个分支，销毁分支已不存在或七天没有 push 的那些。闲置一周的分支不需要一个活着的 URL；下一次 push 两分钟就把它重建出来。哈希不可逆，所以清扫器为每个活着的分支算出环境名，销毁不在这个集合里的所有应用，再删掉后面没有应用的任何 env_* 数据库：

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

演示的分支从来没 push 过（就是上面那次笔记本上的运行），所以在清扫器看来它们全都不存在了；有人从笔记本上拉起来、之后再也没 push 的 spike，一周后正是这个状态。它把剩下的两个拆了，包括 tagline 环境写下的 Redis 键：

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

（一件小事咬了我一口：macOS 自带的是 bash 3，没有关联数组。清扫器的第一版用了关联数组，在我的笔记本上死在 declare -A 上。上面这版用换行分隔的列表，在哪儿都能跑。）

费用是令人愉快的部分。suspend 的机器只付 rootfs，每月几美分。数据库是已经付过钱的卷上的 19 MB。Redis 用的是按量付费的套餐，每十万条命令 20 美分，在分支测试的量级上四舍五入等于零。bucket 前缀按存了多少付。共享 Postgres 节点是唯一的固定项，每月约两美元。二十个活跃分支的花费大致等于一台常开的 shared-cpu-1x，而清扫器把它维持在二十而不是两百。整个演示——三个环境一小时，加上共享部件——比我期间喝的咖啡还便宜。

跨分支的迁移，没有共享数据库来预警

#

当每个开发者端到端负责一个功能时，每个分支里都有一个迁移。这让本节成为重要的一节。

离开共享环境世界时，人们会漏掉一件事。所有人都往同一个 dev 数据库部署时，迁移冲突会立刻、痛苦地浮现，但它们浮现了。一个迁移跑了，下一次部署失败了，有人当天下午修好。每个分支一个数据库之后，每个迁移在自己的环境里都完美运行，两个迁移第一次相遇是在第二个合入 main 的时候。做得不小心，冲突就从便宜的 dev 挪到了不便宜的发布。

四条规则，全都能由 CI 强制，所以没人需要记住它们。

1. 针对合入 main 后的状态，迁移图有两个叶子时 CI 失败。 makemigrations --check 能抓到模型和迁移不一致，但要紧的冲突是两个分支都加了 0042_*。要对着合入 main 的分支检查，而不是分支本身：

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

这一个是我故意让它发生的。三个演示分支里有两个，feature/profile-tagline 和 feature/profile-website，各用一个迁移给用户资料模型加了一个字段，每个环境在启动时应用了自己的。新列只出现在该出现的地方：

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

两个迁移都是 0042_*。两个分支互相看不见对方的，所以两个环境都不会告诉你有问题。把一个合入另一个，检查就会说：

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

第二位作者在自己的分支上、自己的环境里、不打扰任何人地运行那个 --merge，下一次 env up 就把 0043 叠加到他们的克隆上。（这个例子里 git 还先报了文本冲突，因为两个字段加在了模型文件的同一行。很真实，而且值得知道：文本冲突在解决之前会遮住迁移冲突。）

2. 迁移要向后兼容上一个发布的代码。 部署过程中有一个新 schema 与旧代码共存的窗口，机器回滚时则反过来。加列要可空或带默认值，绝不一步改名，绝不删掉当前发布仍在读的东西：先加，部署，回填，切代码，在后续发布里再删。expand and contract。它在这里更重要的原因是，一次性环境让部署更频繁，你待在那个窗口里的时间更多。按标签的 staging 就是彩排它的地方。

3. CI 还会往空数据库里从零迁移。 模板克隆测试的是"我的迁移能不能应用在真实数据上”。空库运行测试的是"整条链从零还能不能跑通”，能抓到那种假定前一个数据迁移已经填了什么的迁移。三十秒，抓住一类否则要等到下一台新笔记本才暴露的 bug。

4. schema 变更要有第二双眼睛。 小团队不需要 CODEOWNERS 文件，但需要一条规则：动了 migrations/ 的 PR 合并前由一位队友评审，而评审人的工作不是检查 SQL。是知道自己或团队里的其他人这两周是否在动同一张表，并把它说出来。超过十来个开发者，这份知识就装不进一个人的脑袋了，那时给 migrations/ 加一条 CODEOWNERS 才算物有所值。没有任何工具能替代这一点。机械性的东西工具都抓了，这就是件两分钟的活，也是旧共享环境世界里唯一值得保留的部分：两个人发现自己即将相撞的那一刻。

版本标识，让 URL 说出它在跑什么

#

只有一个共享环境时，“staging 上是什么"是个在聊天里问的问题。有很多个时，它必须是环境的属性，否则每个 bug 报告都从考古开始。

• 每个镜像携带提交 SHA，应用把它暴露出来。 fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=... 把它们作为环境变量烙进镜像，/api/version/ 连同环境名和区域一起返回（见上面的输出）。听到"feature-profile-tagl-fa8832 上坏了”，任何人第一件事就是确认它跑的是自己以为的那个提交。第一个演示环境是在工具提交之前一个提交的工作树上部署的，端点如实说了：它报的是上一个提交，不是我预期的 SHA。
• ENVIRONMENT=$ENV 在每一行日志里，也是错误追踪工具的 environment 标签。 分支的错误不会污染生产的错误追踪，一键就能过滤。
• 分支有 SHA，发布有标签。 feature-payments-retr-3f9a1c 永远没有版本号；它有提交。staging 和生产有 v1.42.0。
• 移动端携带的是最低 API 版本，不是 URL。 开发菜单里的 URL 字段是测试人员把真机指向某个分支的方式，带有 API schema 版本的版本端点则是应用判断对方是否可理解的方式。

这解决不了什么

#

它解决不了只有放在一起才有意义的两个功能。分支环境展示一个分支。答案是把两者都藏在开关后面合入 main，然后看 main，可以用一个跟随 main 的常驻环境（main-dev.example.com，每次合并重新部署）来做。这是我唯一会保留的长期非生产环境，没人往它上部署；它是用来看下一个发布会是什么样的。

它解决不了那些要求注册回调、又不接受通配符的提供商。我用的认证服务接受父域名，所以 example.com 覆盖所有 -dev 分支主机名。有些 OAuth 和支付提供商不接受，那就保留一个共享主机名，由 Worker 路由到最后认领它的那个环境。那是一把小锁，锁在一件小事上，比把一切都锁住好得多。

它解决不了迁移的人的一面。工具抓的是机械性冲突。它抓不到你们两个在同一个两周里以互不兼容的方式建模同一个概念，唯一的补救是那次有人注意到的迁移评审。

我会在你的环境里检查什么

#

如果你有共享的 dev 或 staging，还有一条预约它的聊天线程：

1. 一个做完的分支，要等多久才能让作者以外的人看到它在运行？超过一小时，你就在用交付时间为这把锁付费，而在小团队里，那是团队里很大一部分人在等。
2. 共享数据库多久重置一次，重置时谁丢了工作？
3. 一个新开发者在第一天，能不能不向任何人要任何东西，就拿到一个跑着自己分支的公开 URL？无论他们得要的是什么，那就是最先该自动化的东西。
4. 新环境是从真实数据开始的吗？如果从空库开始，它第一个抓不到的 bug 就是那个在空表上没事、在真表上要跑四十分钟的迁移。
5. 你的非生产托管里，有没有什么东西在所有人都忘了它一个月后还会存在？有的话，先于一切写清扫器。泄漏从第一天就开始了。

那个聊天里的问题消失，不是因为人们不再问，而是因为答案永远是"在用啊，用我自己的。"

这个博客的搜索流量已经平了两三年，我也不指望它再动了。所以我转而去看访客都是从哪来的，AI 助手在不在其中。在，勉强算在。截至 2026 年 9 月 16 日的十二个月里，访问统计记到这里有 5,372 个会话。其中 27 个来自 AI 助手：12 个来自 chatgpt.com，9 个来自 gemini.google.com，6 个来自 Perplexity，来自 claude.ai 的是零。半个百分点。不过从 ChatGPT 来的访客是好的那种。他们平均停留五分钟，直接访问是 27 秒，Google 来的是三分钟，因为他们已经读过答案，想看的是细节。

所以我花了些时间琢磨，一个小博客怎么才能被选中当这些回答的来源。这篇写的是我在这个站上做了什么，以及日志对此怎么说。有数字的地方我给数字，靠猜的地方我说明是猜。初稿里有三句话，一查之下发现是错的，我把改正留在了文里。

两种 bot，只有一种会引用你

#

第一件要弄清楚的事：“AI bot” 其实是两种不同的活，用的是不同的 user agent，拦住一种对另一种毫无影响。

训练爬虫成批地抓页面，用来训练下一个模型。OpenAI 的叫 GPTBot，Anthropic 的叫 ClaudeBot，Google 的由 Google-Extended 这个 token 控制，Apple 的是 Applebot-Extended，Common Crawl 的 CCBot 则喂着大多数开放数据集。它们拿走的东西最后变成权重，不会有任何链接指回你。拦掉这些是有道理的，我不觉得这想法傻。

检索 bot 是另一种。有人问 ChatGPT、Claude 或 Perplexity 一个问题时，助手会跑一次搜索，当场抓几个页面，读一遍，然后写出带引用的回答。这些抓取来自 OAI-SearchBot 和 ChatGPT-User、Claude-SearchBot 和 Claude-User、PerplexityBot 和 Perplexity-User。Google 的 AI Overviews 用的就是普通的 Googlebot，所以根本没有单独的开关。会把访客送回来的是这些 bot。如果目标是被引用，你要优化的就是它们，而且值得知道的是，拦不拦 GPTBot，ChatGPT 的搜索结果都不会因此变好或变坏。

这个站的 robots.txt 是 Hugo 的默认，也就是全部放行：

User-agent: *
Allow: /
Sitemap: https://jared.lynskey.co.nz/sitemap.xml

我想过把它拆开，放检索 bot 进来，把训练爬虫挡在外面，最后觉得对一个存在意义就是被人读的博客来说不值得。真要那么做的话，写出来就是下面这样。把它放出来是因为和Cloudflare 给 Googlebot 发了一个空页面里的教训一样：列表里写的得是 bot 的名字，不是厂商。没有哪一行能写成"OpenAI"。

User-agent: GPTBot
User-agent: ClaudeBot
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: CCBot
Disallow: /

User-agent: *
Allow: /

站在 Cloudflare 后面的话，有一件事要查一下。从 2025 年年中起，那里新建的 zone 默认拦 AI 爬虫，bot 设置里还有一个一键开关，能对已有的 zone 做同样的事。它两种都拦。这个博客上周刚搬到 Cloudflare Pages，所以这件事在我的清单上。如果你因为"AI bot"听起来像该挡的东西就把它打开了，那你也把引用一起关掉了。Cloudflare 后来开始在它托管的 robots.txt 里写一行 Content-Signal，带 search、ai-input 和 ai-train 三个独立的标志。没人有义务遵守它，但这套词是对的：和上面一样的划分，只是表达成一种偏好，而不是一堵墙。

真正来敲门的是谁

#

搬到 Cloudflare 有个副作用：我头一次能按 user agent 看到每一个请求。下面是 2026 年 9 月 13 日到 16 日这四天进来的东西，假冒的已经剔掉了，那部分后面再说。

有两点很显眼。训练爬虫把整个站读了两遍，用的时间只够检索 bot 读几十个页面。而检索 bot 抓的不是随机页面：ChatGPT-User 和 Claude-User 都奔着更新服务器那篇去了，那是站上最具体的一篇，日语的冷启动那篇被抓的也正是日语版。

再说假冒的。自称 GPTBot 的 20 个请求里，有 18 个来自 OpenAI 公布的地址段之外，要的是 /.env、/.git/HEAD 和 /firebase-adminsdk.json。36 个 “ChatGPT-User” 请求里有 15 个是同一路货色。“PerplexityBot” 的流量大多想要 /id_ed25519。user agent 就是一个谁都能发的字符串，漏洞扫描器已经发现 AI bot 的名字会被放行。OpenAI、Anthropic 和 Perplexity 都公布了自己的 IP 段。如果你打算对某个 bot 特殊对待，不管是放还是拦，查地址，别查名字。上面的 20、59 和 8，是从正确地址来的那些请求。

页面不用浏览器也得能读

#

检索 bot 在回答的那一刻抓取，有超时，而且大多数不跑 JavaScript。一个在 bundle 加载完之前只是一个空 div 的页面，就是它们读不到的页面。Hugo 输出的是完整的 HTML，所以这个博客白得了这一点，这也是我从没动过心思把它搬到什么更聪明的东西上的主要原因。我做的市场应用是反面例子，一个 React Native 的 Web 应用，为了让爬虫拿到一份真正的文档，先做了一条动态渲染分支，然后又被一个缓存 bug 悄悄抵消了。上面那篇 Cloudflare 的文章讲的就是这事。

速度也是同样的道理，而这里日志纠正了我。我原本以为，静态站放在 Cloudflare 后面，就是从最近的边缘节点出去的。不是。这个博客放在 Cloudflare Pages 上，HTML 是不经缓存发出去的，从首尔发请求，响应从洛杉矶回来，大约要半秒。对一个超时有好几秒的 bot 来说这仍然够用，但它不是我原本会张口就说的几十毫秒，而且我知道这一点只是因为我测了。一个正从六个页面里拼答案的助手，会把那个要花三秒的丢掉，而且不会告诉你它丢了。

写得让一段话能单独被摘出来

#

这些系统用页面的方式和读者不一样。它们把页面切成块，给每块按问题打分，引用得分高的那些。一篇用八百字铺垫到结论的文章，每一块的分都低。一篇每一节第一句就亮出观点、后面再论证的文章，会在匹配的那一节得分。

这件事对我在这里写东西的影响，比任何技术上的事都大。front matter 里的 description 现在是对文章内容的概括，不是勾你点进来的钩子，因为 description 往往是助手唯一展示的部分。小节标题说的是这一节的结论。数字连同单位写进句子，而不是放在图表里。日期写全，因为"上周"对一年后读这页的模型来说什么都不是。还有，一篇文章只讲一件事。

另一半是要有值得引用的东西，而这里的数据是掺杂的。日志里，回答时的 bot 抓的都是具体的那些页面：冷启动、更新服务器、iOS 调试。Naver 的爬虫叫 Yeti，Daum 的叫 Daumoa，我用的托管平台上机器重启是一个 30 秒的 504 窗口，Cloudflare 在线做的 Brotli 在我的 bundle 上测出来比 gzip 还差。这些事实没几个地方写过，所以需要其中某一条的问题就会落到这里。可是从助手那边点进来的人，大多落在 2023 年和 2024 年那些讲管理的文章上，每篇一两个会话。具体的文章被机器读，泛泛的文章拿到点击。这我给不出一个利落的解释，宁可照实报出来，也不想编一个。杠杆要是有的话，仍然是把你这周弄明白的、当初搜也搜不到的那件具体的事写下来，因为机器明摆着读的就是这些。

说清楚是谁写的，而且每次都说一样的

#

一个助手在决定要不要引用一个页面时，做的事和一个认真的读者差不多：这是谁写的，什么时候写的，和我找到的其他东西对得上吗？这个站上这部分的机制大多是主题的功劳。每篇文章都带 Article 结构化数据，有作者、发布日期和修改日期，作者是一个 Person，链接到同一组公开主页。这在模板里只是几行，却是"一个页面"和"一个有来历的、署了名的人写的页面"之间的区别。

不是主题功劳的那部分是一致性。关于页、llms.txt、各个公开主页和每篇文章顶上的那一行，描述的都是同一个人，同一段工作经历。有东西变了，就全都要改，不然忘掉的那个就成了错的那个。听起来挺较真，但一个页面说我是工程经理、另一个说我是自由职业，正是那种会让模型含糊其辞、或者干脆换个人引用的矛盾。

修改日期也得老实。内容变了它才变，否则我不碰它。为了显得新鲜而去改它，是那种管用一次、然后整个域名都被打折扣的事。

llms.txt 是什么，以及没人读它这件事

#

llms.txt 是 2024 年 9 月提出的一个方案：在站点根目录放一个 Markdown 文件，给语言模型一段站点概述和一份精选的链接列表。我今年 2 月加了一份。开头一段讲我是谁，然后按管理、基础设施、移动和社区分节，每篇文章一行：标题、URL，加一句话说这篇文章的结论。读起来像一份写给赶时间的人的目录。

要说明的是，没人读它。在我手上这四天的日志里，请求过 /llms.txt 的只有我自己。Common Crawl 在 2026 年 8 月那一轮抓取里收了这个站的 76 个页面，从来没收过这个文件。没有哪家主要的助手说过它会读它。所以这里有什么被引用都不是因为它，我也不会以此为由推荐给任何人。留着它有两个原因。它只花了一个小时，而且给每篇文章写一句"这篇到底得出了什么结论"，比文件本身更值，因为它让我看到了哪些文章什么结论都没有。它也是站上唯一一个告诉机器这个站是干什么的页面，我宁愿有它而用不上。之后它已经跑偏了，因为我是手写的，会忘，这也是应该改成用 Hugo 的输出格式从 front matter 生成它的理由。这事在清单上。

Feed、sitemap 和五种语言

#

无聊的管道照样算数。sitemap 是爬虫在新文章上线当天找到它的方式。RSS 是它得知一篇文章改过的方式。两个都是 Hugo 的默认，我从没需要操心。ClaudeBot 两天里读了 36 次 sitemap，它就是这样那么快找到 1,380 个页面的。

语言是我没料到会有影响的部分。这里的所有内容都有英语、日语、韩语、简体中文和越南语版本，带 alternate 链接，让爬虫知道它们是同一篇文章。爬虫把它们当成五个站：ClaudeBot 的抓取几乎是在五种语言之间平分的，Common Crawl 8 月收走的 73 个文章页面里，只有四个是英语的。助手用被提问的语言回答，也偏向那种语言的来源，所以一个关于冷启动的韩语问题，可以直接从韩语页面回答，而不是现场把英语页面翻一遍，而 ChatGPT 实际抓走的正是日语那一页。条件是译文读起来得像用那种语言写的。今年早些时候我请母语者帮着检查做的那一遍修订，本来是为了人类读者，但也正是它让越南语页面成了一个来源，而不是一个稀奇玩意儿。

我能测量什么

#

比我以为的多，只要别再靠猜。Cloudflare 的免费套餐给的是按 user agent 和路径分的请求日志，一次查询一天，上面那张 bot 表就是从这来的；referrer 要付费套餐才有。访问统计工具里有 referrer，通过它的报表 API 把数据拉出来，而不是眯着眼看仪表盘，开头那些数字就是这么来的。两边合起来能看出个大致轮廓。四天里，检索 bot 从 OpenAI 和 Anthropic 的地址抓了大约九十个页面。上一个月，有两个人从 ChatGPT 过来。读得多，偶尔引，很少点。据我所知，还是没有办法看到那些用了某个页面却没被点击的回答。最有用的检查依然是手动的那种：拿你文章回答的那个问题去问助手，看它引的是谁的页面。

如果这一切里只能留一样，我留写作那条规则。robots.txt、结构化数据和 llms.txt 是一个下午的活，做完就完了。让每一节先说观点，写具体的事而不是泛泛的事，是一种习惯，而正是这个习惯决定了一个页面到底值不值得引用。第二样是：先测了再说。被机器信任，结果看起来和被人信任很像：说你是谁，说你知道什么，而且每次都用同一种说法。

直到不久前，我做的一个集市应用在 Web 端的每一次改动，走的都是和 Django API 一样的路：构建 Docker 镜像，推上去，在 Fly.io 的每台机器上滚动部署。Web 前端（移动应用的 Web 导出，加上静态站点生成器构建的营销页面）和 API 一起被复制进了镜像，所以没有别的办法把它发出去。改一个 CSS 大约要七分钟，重启 11 台机器。八月有一天我这么干了六次。

这篇按顺序过一遍我用什么替换了它：一个部署脚本构建两棵前端树，按版本前缀上传到对象存储，改一个指针对象，等到每台机器都在提供新版本，再通过 API 清掉 Cloudflare 的缓存。另一侧，Django 在每个请求里读指针，提供它指向的那个版本。API 完全不用重启。

老办法的问题在哪

#

最大的成本是重启。11 台机器滚动就是 11 次冷启动，在共享 CPU 上 Django 起来大约要 13 秒，其中 7 秒只是在 import Django。我在部署脚本末尾加了一步预热，把每台机器都请求一遍，免得让真实访客来付这笔账，结果就是每次 Web 发布都以等最慢那台机器收尾。 这些冷启动在 Fly.io 上有多贵，我在缩容到零，于是每次重启都是一次 30 秒的故障里写过。简单说，每次重启都是一个访客可能拿到 504 的窗口，所以一条什么都不重启的部署路径，就把 Web 发布的这个窗口整个关掉了。

第二个问题是静态站点的输出是拆开的。HTML 进了镜像，但 RSS feed 和搜索索引直接上了存储桶。它们来自同一份源码，只是不在同一时刻构建，所以可能互相对不上，而且对不上之前没人会发现。

第三个更像是习惯问题。当一次发布要七分钟外加一次重启，你就不做小发布了。我会攒三四个修复再一起发，而不是一个一个发，而这正是一行改动和某个坏掉的东西一起上线的原因。

存储桶里的布局

#

所有东西都在一个兼容 S3 的存储桶里，web/ 前缀之下：

web/current                              ← a text file containing one version string
web/a1b2c3d-20260914021500/manifest.json ← every file in this version
web/a1b2c3d-20260914021500/app/...       ← the app's web export
web/a1b2c3d-20260914021500/site/...      ← the static site's output
web/9f8e7d6-20260912093012/...           ← the previous version, still there

版本是短 git SHA 加一个 UTC 时间戳，一眼就能看出是哪个提交、什么时候传上去的。发布上线时唯一变化的东西就是 web/current。

部署脚本做什么

#

整件事就是一个脚本，在仓库根目录运行。按顺序：

1. 拒绝不干净的工作树。 它做的第一件事是 git status --porcelain，有任何输出就退出。磁盘上是什么就上传什么，以前营销站的部署脚本就这样发过一次未提交的文案。有个跳过检查的标志给知道自己在干什么的人用，我还没用过。然后它用 git rev-parse --short HEAD 和当前时间算出版本字符串。

2. 构建两棵树。 应用这边跑 Web 导出，把生产环境的 API 和 WebSocket 地址写死进去，后面接一遍 Brotli 预压缩。预压缩值得解释一下：Cloudflare 会在线做 Brotli 压缩，但质量等级很低，在这个 bundle 上测出来比 gzip 还差（2.04MB 对 1.66MB）。构建时用质量 11 压一次，能压到 1.28MB，所以脚本给每个超过 1KB 的 JS、CSS 和 JSON 文件旁边都写一个 .br 孪生文件。营销站这边跑静态站点生成器，开着压缩（minify）。

3. 上传。 它遍历两个构建目录，用 16 个线程把每个文件上传到 web/<version>/app/... 和 web/<version>/site/...。每个对象的 Content-Type 根据文件名猜（先去掉 .br），Brotli 孪生文件再加上 Content-Encoding: br。等所有文件都传完，才写 manifest.json，一个带两个相对路径列表的 JSON 对象。顺序很重要：Django 那一侧把没有清单的版本当作不存在，所以传到一半的版本永远不可能被设为当前版本。现在是几百个文件，上传大约六秒。

4. 改指针。 一次 put_object 把版本字符串写进 web/current。这就是发布。

5. 等机器。 每台 API 机器把指针缓存五秒，所以改完之后的一小会儿，有些机器还在旧版本上。脚本每半秒轮询一次 API 上的版本接口，数带着新版本的连续回答。Fly 会在所有机器之间做负载均衡，所以连续 16 次匹配的回答（比机器数多）就说明每台都重新读过指针了。一个旧回答就把计数清零。90 秒后放弃，让你手动检查；第一次真正的切换花了 30 秒出头，所以上限没定得更低。

6. 清 Cloudflare 缓存。 一次 API 调用，下面讲。失败的话脚本打条警告继续走。

7. 发到团队聊天。 用运行时错误告警的同一个 webhook 发一行，带版本和是谁跑的，这样一波错误可以对照着刚才改了什么来看。回滚用琥珀色发。

从头到尾一次发布一分钟出头，大部分时间是 Web 导出。

Django 这一侧

#

提供前端的本来就是 Django。所有非 API 的 URL 返回的都是 Web 导出里对应该路由的预渲染页面；营销、隐私政策和支持页面则来自静态站点的输出。这些视图以前是直接打开磁盘上的文件。现在它们都通过一层知道存储桶存在的小封装来读。

每个请求它解析三样东西：当前版本（从 web/current 读，缓存五秒）、该版本的清单（在该版本为当前版本期间一直缓存）、以及文件本身（一个放文件内容的小型内存 LRU，所以页面的 HTML 和主 bundle 会留在内存里）。清单是 404 便宜的原因：路径不在列表里，就直接答没有，不用去问存储桶。如果客户端接受 Brotli，它会改读 .br 的孪生文件并设置编码头。静态资源带着一年的 immutable 缓存头发出去，因为文件名里有内容哈希。凡是从文件列表推出来的东西，比如把路由映射到预渲染页面的那张表，也按版本缓存，所以新部署之后会在第一个请求时重建，之前不会。

然后是部署脚本轮询的那个接口：

def web_version(request):
    # bundle: the layer that reads web/current and the manifest
    response = JsonResponse({"source": bundle.source(), "version": bundle.version()})
    response["Cache-Control"] = "no-store"
    return response

它在生产环境返回 bucket:<version>，从镜像提供时返回 filesystem。每台 Fly 机器只回答自己的情况，所以打十几次就知道整个集群有没有收敛。当哪里看着不对劲时，这也是查某台机器认为线上是什么最快的办法。

通过 API 清 Cloudflare 缓存

#

站点的 HTML 在 Cloudflare 边缘缓存五分钟。不清的话，部署已经在机器上生效，但大多数访客最长五分钟内拿到的还是旧页面，这就失去意义了。

清缓存就是一次 API 调用：

urllib.request.Request(
    f"https://api.cloudflare.com/client/v4/zones/{zone}/purge_cache",
    data=json.dumps({"hosts": ["example.com", "www.example.com"]}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

我按主机而不是按 URL 清，这样就不用把每个页面列一遍。静态资源根本不需要清：文件名带内容哈希，新构建指向新文件名，旧的只是不再被引用。需要刷新的只有引用这些文件名的 HTML。

脚本在清缓存之前等机器，是有意的。如果先清，Cloudflare 可能从一台还在旧版本的机器上把缓存填回去，那个页面就会在边缘再待五分钟。

如果清缓存失败，脚本打一条警告然后照样结束。缓存五分钟内会自己过期，所以最坏情况是发布慢一点，而不是发布坏了。我宁愿这样，也不要部署在最后一步中止。

上线前先检查一个构建

#

有个不切换的模式，做到第 3 步就停。版本在存储桶里，但没有任何东西在提供它。要看的话，我在一台机器上设一个环境变量，不管 web/current 说什么，那台机器就固定在那个构建上。看着没问题，再用回滚命令把它设为当前版本。它叫回滚，其实就是"把 current 指向这个版本"，往前走和往回退是同一个操作。

回滚

#

旧版本留在存储桶里，所以回滚就是拿一个更早的版本跑同一条命令，还有个列表命令按从新到旧列出有哪些。它和往前部署一样会等机器、清缓存。我还没用到过。目前没有任何东西会清理旧版本；它们很小，我宁愿留着。

没变的部分

#

API 仍然按老办法、用它自己的部署脚本发布，也应该如此：它有状态，迁移就跑在它上面。Dockerfile 也仍然把两份前端构建复制进镜像。这是有意的。没有配置存储桶时（本地开发、测试套件）或者存储桶读不了时，提供文件的那一层会退回到磁盘上的那些目录，所以存储故障时访客拿到的是随上一个镜像发出的前端，而不是错误页。如果哪天需要把存储桶从链路里摘掉，一个环境变量就可以在生产环境强制这个行为。

前端的改动比 API 频繁得多，现在每次发布大约一分钟，而不是七分钟。我没刻意去改，攒着发的习惯就没了。

我做的这个集市应用是用 React Native Web 写的单页应用。在 JavaScript 跑起来之前，每一个商品页都只是一个 script 标签加一个空 div。这对人没问题，对搜索却是致命的：Google 有时能执行那段 JS，Bing 不会，而对一个商品几乎全是韩语的站点最要紧的 Naver 爬虫，肯定不会。

这篇讲的是我怎么让这些页面被看见，以及之后那条以我没预料到的方式把成果抵消掉的缓存规则。

动态渲染，不是伪装

#

办法很老，而且 Google 认可：识别爬虫，给它返回一份服务端渲染的 HTML，内容和 SPA 本该画出来的一样。不是不同的内容，是同样的内容，只是更早。

于是像 /listings/view?id=... 这样的商品 URL 分叉了。浏览器拿到 SPA 外壳。爬虫拿到一份真正的文档：一个标题，商品的关键信息，每张照片一张带 alt 的图，一段正文摘录，以及通往几个相关商品的链接，好让这页不至于成为孤儿。

最后那点比我预想的重要得多。在这些内链存在之前，大约一千个商品页没有任何东西指向它们，Search Console 里能看到抓取一路沉到每天 7 到 11 次请求。找不到你页面的爬虫，不会在乎那些页面有多好。

陷阱：厂商的名字不是它家爬虫的名字

#

爬虫识别是 user-agent 匹配，问题就出在这里。

韩国平台用的爬虫名字和公司名一点都不像。Naver 的爬虫叫 Yeti，Daum 的叫 Daumoa，Kakao 的链接抓取器叫 kakaotalk-scrap。三个都不是厂商名。

与此同时，同样这几家还发布带内嵌浏览器的 App，那些浏览器发送的是真实浏览器 UA，后面缀上 App 的名字。KakaoTalk 的内置浏览器说自己是 KAKAOTALK/10.5.1，Kakao 的抓取器说自己是 kakaotalk-scrap/1.0。

用 kakao 去匹配，两个都会中。我当初正是这么干的，结果每一个打开链接的 KakaoTalk、Naver App、Daum App 用户，拿到的都是爬虫页：没有 JavaScript，没有导航，没有登录。一份挑不出毛病的文档，对人却毫无用处。

修复靠的是判断顺序，这一点值得明确写成规则：

import re

# 内嵌浏览器会在普通浏览器 UA 后面附上应用名。
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# 认机器人名，不认厂商名：Naver 用 Yeti，Daum 用 Daumoa，
# Kakao 的链接预览抓取器用 kakaotalk-scrap。
CRAWLER_RE = re.compile(r"googlebot|bingbot|yeti/|daumoa|kakaotalk-scrap", re.I)


def is_crawler(user_agent: str) -> bool:
    # 内嵌浏览器永远不是爬虫，所以这个判断放在最前面。
    if not user_agent or INAPP_BROWSER_RE.search(user_agent):
        return False
    return bool(CRAWLER_RE.search(user_agent))

内嵌浏览器先判断，而且它赢。并且每一个爬虫匹配词都必须指向一个机器人，而不是一个厂商。

然后我在前面放了 Cloudflare

#

源站是悉尼的一台共享 CPU 机器，能撑住每秒二三十个请求。Googlebot 要走大约 995 个 URL，而它们全都打到了悉尼，因为每一个 URL 的 cf-cache-status 都是 DYNAMIC：除非有规则明说，Cloudflare 不缓存 HTML。 整个站点大约 16% 的内容被缓存，而真正要紧的那部分一个也不在里面。

那就给爬虫页加一条缓存规则。很简单。除了一点：一个商品 URL 并不只有一个响应体，它有三个。

• 要 HTML 的爬虫拿到服务端渲染页。
• 人拿到 SPA 外壳。
• 发送 Accept: text/markdown 的 agent 拿到 Markdown，从数据库拼出来的，因为把一个空的 HTML 外壳转换一遍只会得到一份空文档。

源站会发 Vary: Accept，而对 user-agent 做 Vary 本来也没什么指望。然后就是我不知道的这件事：

Cloudflare 在 HTML 上忽略 Vary。 三个响应体共用一个缓存键。

哪个先到，哪个就占住这个 URL，对该边缘节点之后的所有访客生效，持续源站 s-maxage 允许的一小时，再加上一天的 stale-while-revalidate。

我在生产环境两个方向都亲眼见到了：

• 一个 Naver App 用户用爬虫页预热了某个商品 URL，随后普通的 iPhone Safari 就在一次 HIT 上拿到了那个页面。一个人盯着一份没有 JavaScript 的文档。
• 一个人用 SPA 外壳预热了某个 URL，Googlebot 拿到了空外壳。整套 SEO 工作要防的正是这个失败，如今它更快了，还是从边缘发出来的。

靠收窄来修复的规则

#

你没法让 Cloudflare 在 HTML 上尊重 Vary。你能做的，是确保三个响应体里只有一个有资格进缓存：

(starts_with(http.request.uri.path, "/listings/")
 and not any(http.request.headers["accept"][*] contains "text/markdown")
 and (lower(http.user_agent) contains "googlebot" or ...)
 and not (lower(http.user_agent) contains "kakaotalk/" or ...))

只匹配爬虫 UA，并排除 Markdown 请求。现在人的请求不匹配任何规则，于是读到 DYNAMIC 并像以前一样回源。只有爬虫请求读写缓存，而能进到缓存里的响应体只有爬虫那一个。

边缘 TTL 用 respect_origin，于是有效期仍归渲染这个页面的代码所有，而不是被钉死在控制台里。

一个容易漏掉的运维细节：收窄规则并不会驱逐已经在缓存里的东西。 得手动清一次缓存，否则那些刚刚已不再生成的污染条目还会继续被发出去。

两份清单，以及它们的错误为何不对称

#

这条规则需要一份爬虫 UA 清单，而 Django 里已经有一份。同一份知识在两个系统里存两份通常是坏味道，但这里有意思的是它们漂移时会发生什么，因为并不对称：

• Cloudflare 里的机器人清单必须始终是 Django 那份的子集。 一个 Cloudflare 认为是机器人而 Django 不认的匹配词，会把 SPA 外壳缓存到爬虫专用键下，然后发给真正的爬虫。
• 内嵌浏览器的排除清单必须是 Django 那份的超集。 排除得太多，代价只是少几次缓存命中。

任何一边朝安全方向错，你只是少缓存一点。第一条朝另一个方向错，你就又在给 Googlebot 发空页面了。顺带一提，这种不对称也正是这些清单用 contains 而不是正则的原因：matches 需要 Business 套餐，而对一份允许在已知安全方向上粗糙的清单，contains 够用了。

一条让构建失败、而不是让页面失败的不变式

#

爬虫页里嵌着有效期七天的预签名图片 URL。页面本身在边缘缓存一小时，外加一天的 stale-while-revalidate。

这两个数字是相关的，一旦缓存寿命超过图片寿命，边缘就会开始发出每张照片都 403 的页面。不会有任何告警，因为 HTML 本身没问题。

所以定义这些数值的代码，在关系被破坏时会拒绝导入：

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # 预签名图片 URL
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# 边缘缓存可能比图片 URL 活得更久时，在 import 时就失败。
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

两个分处不同文件的常量之间的约束，在代码评审里看不见，在进程启动时却一目了然。把它放在进程启动的地方。

Cloudflare 做的两件、我不得不撤销的事

#

Vary: Origin 把打包产物挡在了缓存之外。 django-cors-headers 会在它经手的每个响应上打 Vary: Origin，而 Cloudflare 拒绝缓存任何在 Accept-Encoding 之外还有 vary 的响应。这就悄悄把关键路径上最大的那个 1.6 MB JavaScript 包整个排除在边缘之外。修法是把一个中间件放在列表最前面，让它在出站方向最后执行，重写静态资源路径上的 Vary。

边缘压缩比源站压缩更差。 让 Cloudflare 现场做 Brotli 得到 2,041,742 字节，而源站自己的 gzip 是 1,658,115 字节。为了不用动脑，代价是大了 23%。即时压缩优化的是 CPU，不是压缩率；源站预压缩的资源会赢。

不等抓取就告诉搜索引擎

#

两个协议，加在一起覆盖面也令人失望。

IndexNow 接受一次 ping，覆盖 Bing、Yandex 和 Seznam。Google 和 Naver 不参与。每次保存商品时，我在后台带着很短的超时发一次 ping，已售出和已关闭的条目直接跳过。网络失败只记一条警告，绝不让触发它的那次保存失败——这是一个尽力而为的旁路通道唯一可以接受的行为。

Google 的 Indexing API 只接受两种结构化数据类型，其中之一正是我有的 JobPosting。在招的职位发 URL_UPDATED，关闭的发 URL_DELETED。那条删除通知之所以诚实，是因为关闭的条目同时输出了 noindex，代码里也这么写着——好让日后拿掉 noindex 的人知道自己还顺手破坏了什么。

这里有两处让我耗了不少时间。配额是每天 200 个 URL，而批量导入一次商品就会触发几百次，所以导入进来的条目会被跳过，否则一次导入就把当天预算全花光。另外端点是带冒号的 urlNotifications:publish。用斜杠的话，Google 返回一个普通的 HTML 404，看起来和 API 没启用一模一样。

结构化数据教给我的

#

三条规则，每一条都是被 Search Console 数落出来的：

1. 解析不了的就别输出。 薪资是自由文本。我以前把原始字符串当作 baseSalary.value 输出，那是无效的，还让每一条职位都被标记缺少单位。现在解析不了的薪资干脆不出现。
2. 别为了满足结构化数据的要求而编造字段。 招聘广告很少带街道地址。人会很想给 PostalAddress 填个看着像样的东西。招聘广告上编造的地址比不完整的地址更糟，所以只放城市和国家。
3. 有效期不是可选项。 Google 会丢掉没有 validThrough 的 JobPosting，所以要推导一个，并加上下限，免得一条旧条目声称自己昨天就过期了。

还有关于站点地图的第四条：别给所有条目都声称 changefreq: daily。 要求 Googlebot 每天重新抓取一千个条目，会被读成一台过载的主机，而它的回应是降低整站的抓取速率。从这东西实际上多久变一次来推导。

站点地图还有一道质量下限：标题加正文合计四十个字符。Search Console 曾把大约一千条报成"已抓取 – 尚未编入索引"，其中某个二手页面的全部独有内容，是一个单词的标题加一个电话号码。四十这个数字是故意定低的，因为 484 条里有 471 条是韩语，而韩语单位字符承载的信息更多；按英语调的阈值会砍掉这个市场的一半。内容单薄的条目仍然通过索引页保持可抓取，一旦有人编辑就会自动重新进入站点地图。

我会从中带走的

#

• 在一个 URL 上返回不同的响应体，首先是一个缓存键问题。 弄清楚你的 CDN 用什么做键，并且在你于那个确切的内容类型上验证之前，就假定它忽略 Vary。
• 当两个系统必须就一份清单达成一致时，先弄清哪个方向的错误是安全的，然后把它写在两份副本旁边。“它们可以漂移，而且只允许朝这个方向漂”，胜过假装它们不会漂。
• 按机器人名字匹配机器人，永远别按厂商名字。 尤其在英语世界之外，那个厂商同时还做着你用户手里的那个浏览器。
• 把相距遥远的常量之间的不变式，放在会大声失败的地方。 import 时机是免费的，而且没人能跳过。

更新（2026 年 11 月 4 日）：再更正一点。这些 504 并不是源站没能响应的探测请求，而是 Cloudflare 自己的 Early Hints 缓存查询，根本不会到达源站；这里的 504 只表示这个 URL 没有缓存任何内容。关掉 Early Hints 也不是最好的办法：发送 Link 响应头之后，这个功能开始生效，这些未命中也变成了命中。完整经过见《Cloudflare 504 错误其实不是故障：Early Hints 与 HTTP 103 详解》。

先说结论：开启 auto_stop_machines 后，落到已停止的 Fly.io 机器上的请求要等整台机器启动完。我的机器冷启动要 25 到 33 秒，因为每次机器启动，entrypoint 都会跑一遍 Django 迁移和 collectstatic，而字节码从来没人缓存过。把这些发布相关的工作改成每个镜像只做一次（用以 FLY_IMAGE_REF 为键的 Redis 锁），再在构建时加上 compileall，冷启动降到了 9 秒左右。最后把 auto_stop_machines 从 'stop' 改成 'suspend'（为此得先去掉 swap，Fly 不允许挂起带 swap 的机器），唤醒只要 3 秒左右。

我本来只是去 Cloudflare 面板上看一个流量尖峰，结果在它下面发现了严重得多的东西：一天之内，应用处理的请求有 22% 是失败的。没有任何告警触发，健康检查全是绿的，日志看起来也完全正常。因为那些失败的请求，根本没有到达应用。

原因是我自己写的容器启动脚本，在完全错误的时机做着完全合理的事。

尖峰是个幌子

#

我最初想解释的是这样一个小时：约 4,900 个请求，而中位数是每小时 121 个。独立访客 42 个。也就是每人 110 个请求，人类不是这么浏览网页的。

是扫描器。一个机器人在编造子域名，挨个向它们索要密钥文件：

api-stage-asia.example.com/.env.local
api-us-east-1-demo.example.com/.env
api-eu-uat.example.com/wp-config.php~
app-test-us-east-1.example.com/actuator/configprops
prod-api-use2.example.com/.env.local
relay.example.com/.env.production

三十来个主机名，你能想到的每一种 .env 变体，外加冲着 Django 应用要的某个 Java 框架的 actuator 端点。它们全部拿到了指向规范主机的 301，什么也没被返回。乏味，而且确实无害。

不过既然分析页面开着，我顺手把同一天按状态码分组了。真正的问题在那里。

22%。而且不是均匀散布在整个站点，而是精确地压在最疼的地方：

这些都是移动端每 30 秒轮询一次的端点。所以这不是一个抽象的错误率数字，而是用户的手机整天、大概持续了好几周，都在悄悄加载不出未读角标。

日志为什么看起来正常

#

我的第一反应是应用变慢了。并没有。我从日志归档里翻出最糟糕那个小时里应用自己的请求日志：

[2026-09-08 01:00:29] "GET /api/notifications/unread/" 304 61.615
[2026-09-08 01:00:29] "GET /api/notifications/"        304 63.568
[2026-09-08 01:00:59] "GET /api/notifications/unread/" 304 58.742
[2026-09-08 01:00:59] "GET /api/notifications/"        304 105.438

44 到 105 毫秒，清一色 304。源站很快。

这是关键线索，值得写成一条规则：如果边缘报告的错误是源站从没听说过的，那么请求是在到达之前就死掉了。 别再读应用日志，去看它前面的那一层。

在我这里就是 Fly.io 的代理，答案藏在机器的调度方式里。

缩容到零是关于成本的承诺，不是关于延迟的

#

我的配置是这样，乍看之下相当合理：

[http_service]
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 1

空闲的机器停掉，来流量再启动，用多少付多少。对于流量有峰谷的小应用，这正是你想要的，也正因如此我定义了十台机器，平时却只有一台在跑。

它藏起来的账单是延迟。当一个请求打到一台已停止的机器上，总得有人等它启动完。如果启动比代理的耐心更久，这个人就会拿到 504。

那么我的机器启动要多久？我从来没量过。日志归档知道，因为启动脚本会打印每个阶段，而且每一行都带着机器 ID：

WITH s AS (
  SELECT instance, timestamp,
         CASE WHEN message ILIKE '%Starting app server%' THEN 'begin'
              WHEN message ILIKE '%Migrations complete%' THEN 'migrated'
              WHEN message LIKE  '%"GET /healthz%'       THEN 'serving' END AS phase
  FROM logs
  WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
)
SELECT instance,
       min(timestamp) FILTER (WHERE phase = 'begin')    AS started,
       min(timestamp) FILTER (WHERE phase = 'migrated') AS migrated,
       min(timestamp) FILTER (WHERE phase = 'serving')  AS first_serve
FROM s GROUP BY instance

在每一台机器上，答案都一致：

然后我数了数这件事发生的频率：

SELECT count(*) AS starts, count(DISTINCT instance) AS machines
FROM logs
WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
  AND message ILIKE '%Starting app server%'
-- starts: 92, machines: 10

一天 92 次冷启动。每一次都打开一个半分钟的窗口，任何被路由到那台机器的请求都会超时。22% 不再神秘了。

原因就在我自己的 entrypoint 里

#

这是每一台机器在响应任何请求之前都要跑的东西：

# entrypoint.sh, run on every machine start
echo "Running migrations..."
python manage.py migrate --noinput

echo "Running collectstatic in background..."
python manage.py collectstatic --noinput &

exec "$@"    # then start the app server

带着「一天 92 次」再读一遍。

migrate 是一次完整的 Django 启动：导入所有模型、连上 Postgres、查询迁移表，然后判定无事可做。在共享 CPU 上，为了什么也不做花掉十秒。collectstatic 是第二次完整的 Django 启动，之后还要把静态文件上传到对象存储，同时和正在启动的 Web 服务器抢同一个核心。应用服务器是第三次启动。

三个 Python 解释器，其中两个在重复已经做过的事，机器每醒来一次就来一遍。

当初这么写的理由是站得住脚的，你的代码大概也长得差不多：迁移总得在某处执行，Fly 的 release_command 曾经卡住过，而 entrypoint 是唯一保证会在部署时执行的地方。把部署工作放在这里是对的，只是把它放在每次机器启动时不对。而一旦你的机器开始自己停自己起，这两件事就不再是同一个事件了。

整个 bug 就是这一句，我认为它相当常见：

属于发布的工作，被按机器启动执行了。缩容到零把一个事件变成了九十二个。

解法：把发布只认领一次

#

某个镜像的第八台机器不需要跑迁移。这个镜像只需要跑一次，其他机器只需要知道已经跑过了。

这就是一把每次部署都换名字的锁。Fly 用 FLY_IMAGE_REF 白送了这个名字，而 Redis 我本来就有。整个东西是一个在 Django 存在之前就运行的小脚本，所以常见情况下的答案是毫秒级，而不是一次框架启动：

# release_gate.py: runs before Django exists. Exit code 0 means "prepare this release".
import os, time

PREPARE, SKIP = 0, 1
LOCK_TTL, WAIT, POLL = 300, 240, 2
_sleep, _monotonic = time.sleep, time.monotonic    # aliases, so tests can replace them


def release_id() -> str:
    """Something that changes exactly when the deployed image does."""
    return os.getenv("FLY_IMAGE_REF") or os.getenv("FLY_MACHINE_VERSION") or ""


def claim(client, release: str) -> int:
    if client is None or not release:   # no Redis, or no idea which release: behave as before
        return PREPARE
    done_key, lock_key = f"release:{release}:done", f"release:{release}:lock"
    if client.get(done_key):            # somebody already did it for this image
        return SKIP

    owner = os.getenv("FLY_MACHINE_ID", "unknown")
    if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
        return PREPARE                  # we won the race; we do the work

    # Someone else is preparing. Wait for them, because serving requests
    # against a half-migrated schema is worse than starting slowly.
    deadline = _monotonic() + WAIT
    while _monotonic() < deadline:
        _sleep(POLL)
        if client.get(done_key):
            return SKIP
        if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
            return PREPARE              # the owner died and its lock expired; take over
    return PREPARE                      # waited long enough; do it ourselves

# ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE