这类技术统称测试影响分析（test impact analysis），而 testmon 是在 Python 里免费、开源地用上它的一种办法。它完全不依赖 git：它对比的是上次运行时看到的代码，提交没提交都一样。

这周我把它加进了我那个集市应用的 Python 测试里，原因并不是为了快而快。

为什么要加它

#

一个功能需求通常很小：一个界面、一个接口、一条要换个做法的规则。跑整个测试套件，让每个需求都变得比它本身更大。这个套件有 2,248 个 Django 测试，四个进程跑大约三分半，单进程要 11 分钟，而每次编辑都会把它整个跑一遍，尽管其中几乎全部检查的都是这个需求根本没碰过的东西。只要有不相干的测试失败，或者运行单纯慢了点，功能就得等着。拖住它的，是功能需求之外的情况，而那个拖住它的东西，正是我自己的测试套件。

另一条路也好不到哪儿去：不跑全量，猜哪个测试文件覆盖了这次改动，偶尔猜错。这样是快，但不精确，而我发出去的每一个未经测试的改动，都是一个要做两遍的功能需求。

我等的测试应该恰好是这次改动能触及的那些，不多也不少。testmon 给我的这组测试来自记录，而不是猜测。全量套件照样在跑，只不过是在 CI 里，不会拖住我接下来手上的任何事。

它怎么决定跑什么

#

testmon 把每个 Python 文件切成代码块：模块的顶层、每个类、每个函数，嵌套函数的函数体会从外层代码块里切出去。它为每个代码块存一个校验和，从不存代码本身。测试运行时，coverage.py 记录它执行的代码行，testmon 记下这些行属于哪些代码块。没有静态分析，也不靠 import 去猜。一个测试依赖的，恰好就是它跑过的那些代码块。

拿这样一个模块来说：

# pricing.py
def subtotal(items):
    return sum(item.price * item.quantity for item in items)

def discount(total, code):
    if code == "WELCOME10":
        return total * 0.9
    return total

一个只调用 subtotal() 的测试，依赖的是模块顶层和 subtotal 的函数体。discount() 随你怎么改写，testmon 都不会重跑这个测试，因为它从没执行过 discount 里的任何一行。而在 subtotal 里哪怕只改一个字符，它就会再跑一次，即使这个改动根本不可能改变结果。testmon 不会在副作用上耍聪明：你执行过的代码块变了，你就得跑。

它还会追踪代码周围的东西。记录里包括 Python 版本，以及已安装的包及其版本。它不看环境变量：同一份代码要在两个 settings 模块下跑的话，得用 --testmon-env（第 8 步）给它们起名字，否则它们共用一份记录。升级一下 Django，所有碰过 Django 的东西都会再次受影响，而在一个 Django 应用里，那就是全部。

它看不到什么

#

testmon 追踪的是测试执行的 Python 代码。测试读取的其他文件它不追踪：模板、JSON、文本，磁盘上的任何别的东西。经网络访问的服务它也不追踪。而在测试开始前只跑一次的东西，它没法归到某个具体测试头上。

放在 Django 项目里，首先是迁移：它们只在创建测试数据库时跑一次，所以没有哪个测试的记录里包含它们（有新迁移时，下面的包装脚本会重建测试数据库）。其次是设置和启动代码，它们在 pytest 启动时运行，不属于任何一个测试。再就是模板和数据文件：模板不是 Python，所以改了模板，渲染它的测试一个都不会重跑。

我的测试套件还有几样自己特有的。有些测试读取一个 JSON fixture 文件，移动应用的测试也共用它。有些检查构建出来的 Web bundle，还有些检查同一个仓库里生成的静态网站的输出。改了其中任何一个，testmon 都会高高兴兴地告诉你什么都不用跑。所以下面的教程会用一个脚本把 testmon 包起来，这个脚本会留意这些文件，只要其中一个改了，就全部跑一遍。

怎么把它加进 Django 项目

#

以下步骤假定你用 pytest 和 pytest-django，依赖用 uv 管理。用 pip 的话，把 uv add --dev 换成 pip install，去掉 uv run。

1. 安装。

uv add --dev pytest-testmon

2. 确保 pytest 能跑这套测试。 testmon 是 pytest 插件，所以在 python manage.py test 下它什么都不做。pytest-django 需要知道设置模块，以及你的测试所用的文件命名模式：

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
python_classes = Test* *Tests *TestCase

如果这套测试一直只在 Django 自带的 runner 下跑过，先在 pytest 下跑一遍，把不一致的地方修好，再加 testmon。不然你就得同时调试两件事。

3. 别把记录放进 git。 testmon 会在 pytest 根目录写入 .testmondata。它是一个 SQLite 数据库，所以旁边还会出现 -shm 和 -wal 文件，下面的脚本还会再加一个时间戳文件。一个模式就能把它们全部覆盖：

# .gitignore
.testmondata*

4. 先把整套测试记录一遍。 testmon 在看过每个测试运行之前，什么都选不出来：

uv run pytest --testmon

在全新的检出里，第一次运行就是单进程跑完整个套件。在我这里，2,248 个测试大约要 12 分钟。从那以后，同一条命令就只跑受影响的测试。什么都没改的话，它什么都不跑。

有两个坑。在 testmon 2.2.0 及更早版本上，它需要 pytest 的 cache 插件：我第一次尝试时带着 -p no:cacheprovider，结果以 KeyError: 'lf' 崩掉了（2.3.0 会把缺失的 --lf 当作未设置）。另外，在 Python 3.14 或更高版本上，记录之前要先设置 COVERAGE_CORE=ctrace。原因在后面的“看起来全绿的那个 bug”一节里解释。这是下面脚本里最重要的一行。

更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 会自己强制使用 coverage 的 C tracer，所以在这个版本上，这行 export 只是多一道保险。如果你用的是 2.2.0 或更早的版本，就留着它。而故意弄坏点什么来验证的那一步，不管哪个版本都要做。

5. 为它看不到的文件包一层。 正是这一步，让它可以放心地天天用。脚本保留一个时间戳文件，记的是上次运行开始的时间。只要有任何 testmon 追踪不到的文件比这个时间戳新，就全部跑一遍并重新记录。新的迁移只会让它重建测试数据库。其余情况就让 testmon 来选。删减后的示例：

#!/usr/bin/env bash
# scripts/test-changed.sh: the tests a change can affect, or all when in doubt.
#   scripts/test-changed.sh            # affected tests
#   scripts/test-changed.sh --all      # everything, re-recorded
#   scripts/test-changed.sh -k orders  # anything else goes to pytest
set -euo pipefail
cd "$(dirname "$0")/.."

# coverage's C tracer: from Python 3.14 coverage defaults to sys.monitoring,
# which reports a line only the first time a process runs it, so testmon
# would credit each line to one test. Changing this means --all.
export COVERAGE_CORE=ctrace

STAMP=.testmondata.started
full=false
rebuild=false
if [ "${1:-}" = "--all" ]; then
    full=true; shift
elif [ ! -f .testmondata ] || [ ! -f "$STAMP" ]; then
    echo "No record yet: running everything once."
    full=true
else
    # Changed since the last run started, and not traceable per test:
    # anything that isn't Python, plus settings and conftest.
    newer="$(find myapp myproject fixtures pytest.ini \
        -type f -newer "$STAMP" ! -path '*/migrations/*' \
        \( ! -name '*.py' -o -path 'myproject/settings*' -o -name 'conftest.py' \) \
        ! -path '*/__pycache__/*' | head -5)"
    if [ -n "$newer" ]; then
        echo "Changed, and not traceable per test:"; printf '  %s\n' $newer
        full=true
    fi
    # A new migration needs a fresh test database, not a full run.
    [ -n "$(find myapp -path '*/migrations/*.py' -newer "$STAMP" | head -1)" ] && rebuild=true
fi

# Stamp the start, so an edit made while the tests run counts next time.
started="$(mktemp .testmondata.run.XXXXXX)"
args=(--testmon --reuse-db)
# --create-db alone deletes the database when the run ends; with
# --reuse-db as well, the rebuilt one is kept for next time.
[ "$rebuild" = true ] && args=(--testmon --reuse-db --create-db)
[ "$full" = true ] && args=(--testmon-noselect --reuse-db --create-db)

status=0
uv run pytest "${args[@]}" -q "$@" || status=$?
# 0: passed, or nothing selected. 1: some failed (still recorded).
# 5: nothing collected at all.
case "$status" in 0|1|5) mv "$started" "$STAMP" ;; *) rm -f "$started" ;; esac
[ "$status" = 5 ] && exit 0
exit "$status"

这里面有两个细节值得解释。--reuse-db 是 pytest-django 的参数，用来在两次运行之间保留测试数据库。一旦一次运行只要几秒，这一点就很要紧：每次重新创建数据库，花的时间可能比测试本身还长。全量运行，或者有新迁移之后的那次运行，会再加上 --create-db，让数据库用上当前的 schema。--reuse-db 要和它一起留着：单独用 --create-db 时，pytest-django 会在运行结束时删掉数据库，下一次运行就得从头再建一遍。

还有，当 testmon 把所有测试都取消选中时，运行的退出码是 0，所以“什么都没改”算作通过。退出码 5 是 pytest 的 “no tests collected”（没有收集到测试），脚本把它也当作没问题。

注意清单里没有什么：pyproject.toml 和 lock 文件。我的第一版只要 lock 文件一变就全部跑一遍，结果这个慢吞吞的兜底大多数日子都会触发，整件事比以前还糟。testmon 本身就会追踪已安装包的版本，用不着帮这个忙。

6. 给它单独的数据库和缓存。 如果同一台机器上还有别的东西在跑测试，比如第二个终端、一个编程 agent 或者 manage.py test，就让脚本指向它自己的测试数据库和它自己的缓存编号，这样保留下来的数据库永远不会撞上别人的运行：

export DATABASE_URL="postgresql://myapp:myapp@localhost:5432/myapp_changed"
export REDIS_URL="redis://localhost:6379/8"

7. 每次运行前清空那个缓存。 这一条我是吃了亏才学到的。子集运行开始出现 KeyError，全量运行却没有。有些分类标签的缓存没有过期时间，于是一次运行保留下来的测试数据库，碰上了更早一次运行留下、还热着的缓存。在脚本开头清掉缓存，问题就解决了：

uv run python -c "import os, redis; redis.Redis.from_url(os.environ['REDIS_URL']).flushdb()"

这正是 testmon 在做它文档里说过会做的事：每次跑不同的子集，会暴露出那些只是因为之前跑过什么才通过的测试。修复应该放在测试的 setup 里，而不是 testmon 里。

8. 记住选择出错时用的参数。

• --testmon-noselect 跑所有测试，但把可能失败的排在前面。当你同时传了 -k、-m、--lf 或某个测试的 node ID 时，testmon 会自动切换到这个模式。
• --testmon-forceselect 只跑既受影响、又匹配你的 -k 或 -m 的测试。
• --testmon-nocollect 使用已有的记录，但不往里添加。在调试器下，或者 coverage 已经在运行时，会强制使用这个模式。
• --no-testmon 在它写进了 addopts 时，用来关掉一次运行。
• --testmon-env=<name> 在一个文件里保存多份独立的记录，适合要在两个设置模块下跑的测试套件。

如果项目还有 JavaScript 那一侧，Jest 自带了同类功能。jest --changedSince=main 会跑那些 import 了自 main 以来改动过的任何东西的测试，它跟的是 import，而不是覆盖率。我把它加进了应用的 package.json，叫 npm run test:changed，这样两边是同一个习惯。改了一个工具模块，它从应用的 121 个测试文件里选中了 7 个。

它能省下多少

#

包装脚本就位、并修好下一节说的那个 bug 之后，我计了一下时，包括启动时间：

日常的一次编辑，比并行跑整个套件快大约 25 倍；什么都没改的时候，快大约两百倍。

这份记录从更宽的角度说明了同一件事。在测试套件跑的 307 个非测试 Python 文件中，改动中位数的那个文件会波及 22 个测试，测试时间大约 8 秒。另一头是几个核心模块：几乎每个测试都会跑到它们，所以改了那里会波及 1,500 个左右的测试，testmon 会重跑套件的大部分。这才是正确的答案，不是失败。这些数字是按文件算的上限：testmon 按代码块工作，所以改了一个函数，只会选中跑过那个函数的测试。

代价出现在包装脚本退回全量运行的时候。一次全量运行和第一次一样，是单进程的记录，大约 12 分钟，比它取代的那个并行套件还慢。之所以是单进程，只是因为我还没试过把 testmon 和 pytest-xdist 一起用；它从 1.4 起就支持 xdist，下一个该量的就是这个。所以触发全量运行的文件清单，应该在不自欺的前提下尽量短。

看起来全绿的那个 bug

#

我最早的数字比这些好看：改一处，6 个测试，3.3 秒。它们是错的，而屏幕上没有任何东西提示这一点。

从 Python 3.14 开始，coverage.py 默认使用一个新的核心，建立在解释器的 sys.monitoring 之上。这个核心只在一个进程第一次运行某一行时报告它。testmon 关于哪个测试跑了哪一行的记录，是从 coverage 得来的，所以每一行都只记在碰巧第一个跑到它的测试头上，别的测试一概没有。改一行八个测试共用的代码，testmon 只会选中其中一个。

发现它，是在我另一个更小的项目上，那个项目照搬了这套配置。在那里引入它的步骤之一，就是故意弄坏一行代码、对比结果，而数字对不上。回到这个套件，我做了同样的检查。我弄坏了首页横幅代码里的一行，也就是一张幻灯片的标题。直接跑 pytest，报告了 8 个失败的测试。testmon 选中了 4 个。另外 4 个坏掉的测试根本没跑，输出里也没有任何地方说它们被漏掉了。

修复只要一行，export COVERAGE_CORE=ctrace，让 coverage 回到经典的 C tracer。换了 tracer，记录也就不一样了，所以我重新记录了一遍：2,248 个测试，12 分 3 秒。之后，同样那种弄坏代码的改动，把它弄坏的 11 个测试全都跑了。

更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 现在会自己设置 C tracer，进程内和子进程里都会，所以新装的话不再需要这行 export。下一段里的检查仍然需要。

这是我最想先传下去的一条教训。一个选得太少的测试选择器，看起来和成功一模一样：测试更少，跑得更快，全是绿的。所以搭一个这样的东西时，要故意弄坏某个共用的东西，分别跑原本的完整套件和选择器，确认它们失败的是同一批测试。之后每当 Python 或 coverage.py 升级版本，再做一遍。

编程 agent 在哪里用得上

#

那个仓库里的改动，已经不全是我自己做的了。一个编程 agent，我用的是 Claude Code，做了很多小改动，而一个好的 agent 每次编辑后都会跑测试。面对一个 11 分钟的测试套件，它的两个坏选择和我当初一样：等，或者猜哪个测试文件要紧。

所以仓库里给 agent 的说明现在写着：工作时跑测试，默认就用这个包装脚本，要全量运行就加 --all。每次编辑后，agent 都能在几秒内拿到和我一样精确的那组测试。这也是第 6 步要给脚本单独的数据库和缓存的原因：忙的时候，同一台机器上不止一个会话在跑测试，而保留下来的数据库绝不能撞上别人的运行。

这些都不需要 testmon 提供任何 AI 专属的东西。还是同一份记录、同一套选择。只不过，当做改动的那一方改得非常多时，它就更重要了。

为什么 CI 用的是更粗的版本

#

testmon 没有 CI 模式。它在 runner 上和在笔记本上表现一样，而它的作者写道，在 CI runner 之间共享或缓存 .testmondata，效果远不如他们的托管服务 testmon.net。缓存下来的记录还会带着上面说的所有盲区，再加上我的 CI 是用 Django 自带的 runner、四个进程跑这套测试的，所以我没在 CI 里用 testmon。

CI 拿到的，是同一个思路的文件级版本。检查工作流现在先跑一个小 job，对这次推送做 diff，判断它碰到了仓库的哪一半：Python API、移动应用、两者都有，或者都没有。在这之前，每次推送 CI 都会把 Python 和应用两个 job 都跑一遍，只改文档的推送也不例外。现在只改文档的推送什么都不跑，只改应用的推送会跳过 Django 测试套件。我拿五个真实的提交试跑了这个 job：只改文档的那个什么都没跑，只改应用的那个跳过了 Python job，只改后端的那个跳过了应用 job。删减后的示例：

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.diff.outputs.python }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        env:
          BEFORE: ${{ github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          FILES="$(git diff --name-only "$BEFORE" "$HEAD")"
          # Python's inputs include the non-Python files its tests read.
          PY='^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)'
          if printf '%s\n' "$FILES" | grep -qE "$PY"; then
            echo "python=true" >> "$GITHUB_OUTPUT"
          else
            echo "python=false" >> "$GITHUB_OUTPUT"
          fi

  python:
    needs: changes
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: uv run python manage.py test --parallel 4 --noinput

真实的版本在没有可比较的范围时，也会全部跑一遍：新分支、强制推送（force push），或者手动运行。

盲区还是同一个，只是换了个形式。testmon 看不到 JSON 文件，路径过滤器也看不到，除非你把它列出来。所以这个模式里明确写出了共享的 fixture、构建出来的 bundle 和生成的网站，还加了一条注释，请改它的人让这份清单保持如实。文件级的版本更粗糙，但它出错时偏向安全的一边：Python 那边只要有任何改动，就跑整个套件。

值得吗？

#

对一个要跑好几分钟的测试套件来说，值得。真正的代价在于它看不到的东西，而那正是包装脚本的用处。即便如此，testmon 该待的地方是笔记本上的开发循环。只要 Python 那边有改动，CI 照样跑整个套件，部署前我信任的是那一次运行。

如果你是来找「怎么在 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 上吗？

想象一个小团队在做同一个应用。两个开发者也好，五个也好；不是分工不同的专家，而是各自在自己的分支上把一个功能从数据库迁移、经过 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. 你的非生产托管里，有没有什么东西在所有人都忘了它一个月后还会存在？有的话，先于一切写清扫器。泄漏从第一天就开始了。

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

声明。 这次迁移和这篇文章是 Codemagic 付费委托的。他们只对事实准确性做了一轮审阅，不涉及语气，文中没有任何内容是应他们要求修改的。凡是我遇到问题并反馈了的地方，我都会说明；如果你读到这里时问题已经修复，文中会写成已修复。

2026 年 9 月 23 日更新。 我反馈的问题，Codemagic 的开发者都逐一处理了。大部分已经修复，包括 iOS 版本检测的 bug、重复计数的安装、首次运行时的静默，以及那条吵闹的调试命令；文档现在也写到了已提交的原生工程和崩溃回滚的额度。下文中每个问题出现的地方我都标注了，仍未解决的那几个保持原样。

2026 年 10 月 16 日更新。 迁到 Patch 之后的第一次原生升级（Expo SDK 58）构建出了一个完全不含 Patch 配置的 Android release，而且没有任何地方报错。来龙去脉和只改一个文件的修复写在 第一次原生升级。

二月我写过一篇自己搭 Expo 更新服务器的文章。它现在还在跑。我运营的社区应用 maru 从那以后每一次 OTA 修复都走它，两个平台都是，每月大约一美元。

这也意味着每一块都归我管：几张数据库表、一个 API 接口、一条管理命令、一个发布脚本、一个共享密钥，还有一堆坑，每个坑都是靠一次坏掉的更新学来的。坐下来做规划时我才发现，那个脚本从我写它的第一天起，每次生产发布之后都会打印 “Sent 0 push notifications”，读的是一个这台服务器从未返回过的字段。没人注意到，最没注意到的就是我。自己维护一套东西，大概就会变成这样。

所以当 Codemagic 问我要不要试试 Patch，他们那套开源、可自托管的 CodePush 替代品，我答应了，只有一个条件：要用真实的应用，而不是 demo。真实的签名、真实的发布流程、已经提交进仓库并且手改过的原生工程，全套。大多数打算离开 EAS Update 的人，要迁的都是这样的应用，不是刚生成的模板。

下面就是整个过程，毛边都留着。

Patch 是什么

#

Patch 是一台你自己跑的服务器，加一个放进应用里的 SDK。服务端包括一个 API、一个后台 worker、Postgres、S3 兼容的对象存储和一个 Web 面板，打包成一套 Docker Compose 栈。客户端是 @codemagic/react-native-patch，一个支持 iOS 和 Android 的 TurboModule，附带 Expo 配置插件，再加一个 CLI，cmpatch，负责打包 JavaScript 并发布。

读完源码之后，有两个设计决定让我印象深刻。

第一，应用从不向 API 询问有没有更新。发布一个 release 时，worker 会把纯 JSON 的清单写进对象存储，应用只是去取那些文件。一次更新检查就是对存储或 CDN 的两个静态 GET，API 只接收指标。我原来的接口站在每一次应用启动的请求路径上；这一套想站也站不上去。

第二，每个 release 都精确地写明它面向哪个二进制版本，CLI 会对你的原生工程算一个指纹，拒绝把 JavaScript 发到原生代码对不上的二进制上。我的服务器只有一个版本字符串，剩下的全靠祈祷。

先在自己笔记本上试

#

文档一上来让你搭的是本地评估栈，从这里开始是对的。

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

CLI 两秒就装好了。整套栈第一次起来花了 3 分 14 秒，大部分时间在本地构建服务器和面板的镜像，而且在非交互模式下，这期间它什么都不打印，看起来和挂死一模一样。（现已修复：它现在每一步会打印一行进度。）然后四个健康的容器就出现了，全部绑定在 localhost：面板在 8080，API 在 3000，Postgres，还有 MinIO 在 9100。它很懂事地避开了我自己那套栈已经占用的端口。

这个模式下登录是关掉的，每个页面上都有一条警告，叫你别把它暴露出去。

localhost:8080

栈自带一个叫 Example Data 的种子应用，在你发布任何东西之前值得先看一眼，因为它展示了面板是用来干什么的。接下来两张截图里的数字都是种子数据，不是真实用户。

localhost:8080

localhost:8080

作为对比，我的面板就是后台里的一张更新列表，带一个“启用”复选框。到底有多少台手机真的装了更新，我完全不知道。

CLI 登录是一套正经的浏览器流程，带 PKCE 和 localhost 回调，批准页面会告诉你是哪个账号在请求，以及授权码大约一分钟后过期。

localhost:8080

对准一个真实应用

#

Patch 要求每个平台一个应用，每个应用会自动建好 Staging 和 Production 两个 deployment。我在面板里建了 maru-ios，又用 cmpatch app create 建了 maru-android，主要是两种方式都看看。建完应用后弹出的对话框是整个产品里对迁移最有用的一屏：两个 deployment key、SDK 需要的两个 URL，还有一句说明：deployment key 不是机密。

localhost:8080

两件小事。cmpatch init 当时是把项目关联到已经存在的应用上，所以不管迁移指南怎么暗示，它都不可能是第一条命令。这一点后来修好了：在交互模式下，它现在会自己给每个平台建一个应用。另外，对话框给的 API URL 是 http://localhost:8080，而文档和 CLI 说的是 3000。两个都能用，因为两个端口都同时提供这两种服务，但你会犯嘀咕。

接着我对着还没动过的应用跑了 cmpatch doctor，三秒钟它就找出了一个真问题。它报告 iOS 二进制版本是 2.0.0。应用其实是 2.5.1。

CLI 会找出 ios/ 下所有的 Info.plist，如果没有一个路径里带 “test”，就按字母顺序取第一个。maru 有一个 WidgetKit 扩展，它的目录按字母排在应用本身的目录前面，于是 CLI 拿到的是扩展的 Info.plist。这个 plist 还停在 2.0.0，这是我的 bug，但后果很难看：自动检测会把每一个 iOS release 都对准一个没有任何手机在跑的版本，而且不会报任何错。更新只是永远不会到，正是我在自建服务器那篇里警告过的那种故障。Android 读 versionName 是对的。绕过的办法是传 --target-binary-version 或 --plist-file，我的发布脚本现在会先检查 app.config.js 和两个原生工程的版本一致，然后显式传入版本。后来同一个 bug 又让 doctor 自己的清单检查在一个运行正常的 deployment 上失败，因为它跑去找 2.0.0 版本的清单了。修好过期的 plist 之后，doctor 的 24 项检查全部通过。

Codemagic 后来修复了这个问题。CLI 现在读取的是应用 target 的 Info.plist，而不是扩展的；如果有不止一个 target 可能是应用，cmpatch 会问你是哪一个。

JavaScript 这一侧

#

去掉 expo-updates、加上 SDK，是两行的改动。把应用原来围绕更新做的那些事换过来，要多想一想。

maru 在启动时和每次回到前台时检查更新，最多每十五分钟一次。发现更新就下载，然后提议重启；你说不，它就在下一次冷启动时应用。设置页里还有一个手动检查，显示当前跑的是哪个 bundle，错误上报器也会给每份报告打上它来自哪个更新的标签。

从 SDK 源码里学到的第一件事是，它在 import 时就用 TurboModuleRegistry.getEnforcing 查找原生模块，模块不存在就直接抛错。maru 还有一个 Web 构建，顶层 import 会把 Web 应用整个搞挂。所以一切都走一个懒加载 SDK 的小模块，配一个什么都不返回的 .web.ts 孪生文件，这样还能把 SDK 彻底挡在 Web bundle 之外。

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

自动检查本身主要就是 sync()，它从不抛错，而是 resolve 成一个状态：

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

SDK 对强制 release 的默认值是 IMMEDIATE，不管用户正在干什么都会直接重载 JavaScript。我改成了下次从后台回来时再应用，因为弄丢一篇写了一半的帖子，这个 bug 比大多数修复带来的好处都要糟。当时 InstallMode 是字符串联合类型，不是文档示例里暗示的那种枚举对象；现在它导出为一个常量对象，所以 InstallMode.ON_NEXT_RESTART 可以照文档那样用了。

原生这一侧，当 ios/ 和 android/ 已经提交进仓库

#

迁移指南说，加完配置插件后跑 npx expo prebuild --clean。我在另一个 checkout 里跑了，它删掉了随包的图片、我的 Android 网络安全配置、iOS 隐私清单和 Podfile.lock，还把 build.gradle 里一个给测试工具做的修复连同 Info.plist 里的几百行一起回退了。不加 --clean，Expo 照样把两个目录清空。

这不怪 Patch。maru 一开始是托管的 Expo 应用，后来长出了原生定制，所以 ios/ 和 android/ 是提交进仓库的，EAS 拿它们原样构建。但长这样的应用多得很，指南当时没有提醒。现在有了：Expo 迁移指南分成两条路径，生成原生工程的走 prebuild，已提交原生工程的则列出需要手动应用的具体改动。

插件实际改的东西，其实少到可以手动完成。iOS 上，AppDelegate.swift 里一个 import 加一行：

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

Android 上，MainApplication.kt 里一个 import 加一个参数（这是 React Native 0.82+ 的写法；更早的版本是改写 getJSBundleFile()）：

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

再加上每个平台三个配置值，以及删掉旧的 expo-updates 设置：两个工程加起来新增 13 行、删除 20 行。

插件会在 prebuild 时把那些配置值写成字面量，对于提交了原生工程的项目，这意味着每次构建都只能有一个写死的 deployment。我想让 preview 构建走 Staging、商店构建走 Production，用的还是同一个工程，所以这些值改成从构建环境来。Info.plist 里，Xcode 会展开构建设置：

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

android/app/build.gradle 里：

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

这些 key 于是和 EXPO_PUBLIC_ 那些值一起放在 eas.json 的各个构建 profile 里。值为空时 SDK 会安静地什么都不做，本地构建没关系，商店构建就是灾难，所以 app.config.js 现在会在 preview 或 production 的 EAS 构建缺了这些值、或者还指向 localhost 时直接抛错。

第一次更新

#

第一个 release 我改的是引导页的大标题，不用登录就能看到，然后发布：

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

耗时 30 秒，大部分是 Metro 和 Hermes。上传完成 0.6 秒后，服务器的 worker 就发布了清单。这个更新是一个 7.3 MB 的压缩 tarball，而我旧的导出流程产出的是 11 MB 的 Hermes bundle 加资源。

这里有一件事要做对：JavaScript bundle 在构建时会把 EXPO_PUBLIC_ 那些值内联进去，所以一次更新必须用和它要落上去的那个二进制相同的值来构建，否则你发出去的 JavaScript 会连到错误的后端。我的脚本从构建那个二进制的同一个 eas.json profile 里加载它们。Patch 的 CI 文档现在也把这一点写清楚了，还说明了 release-react 本身不会读取 EAS profile。

然后我重新启动应用。设备日志显示整个更新检查就是对对象存储的两次请求，meta.json 和 2.5.1/manifest.json。启动三秒后 SDK 写下了一条 Downloaded 事件，把更新暂存好，应用弹出了重启提示。

bug 是我的

#

然后我看了看面板。一台模拟器装了 release v1，面板却显示两次成功安装、两个活跃用户。

localhost:8080

SDK 把自己的状态和待发送的指标事件以文件形式存在应用容器里，追起来很方便。里面有两条 Success 事件，时间戳完全相同，id 不同。我的 hook 在挂载时用 notifyAppReady() 确认当前 bundle，紧接着就调用 sync()，而 sync() 自己也会调用 notifyAppReady()。两次调用重叠了，各自都看到这个 release 处于待确认状态，各自都记了事件。服务器按事件 id 去重，但这两条 id 不同，所以都算数了，而且这些重复是永久的。

我这边的修复是每次启动只做一次共享的确认，其他所有东西都等它。SDK 自己也可以防一下重叠调用，这一点我提了建议。现在它确实这么做了：重叠的 notifyAppReady() 调用，包括 sync() 内部那一次，会共用同一次确认，所以每次安装只记一次。SDK 参考文档现在也写明了 sync() 会自己确认就绪，用它的应用不需要再单独调用 notifyAppReady()。

舒服的地方在于发修复。这是纯 JavaScript 的改动，所以作为 release v2 发了出去，而且因为可以给 v1 上的设备发二进制差分，v2 下载下来是一个 543 KB 的 patch，而不是 7.3 MB 的 bundle，大约是原来的 7%。重启之后：一次下载、一次安装、一次成功、一台活跃设备。

localhost:8080

故意弄坏它

#

回滚是我最在意的功能，因为旧方案在设备端什么都没有。一个坏更新会让每次启动都崩溃，直到我注意到并把复选框取消勾选。

所以我发了一个 v3，在第一次渲染之前就抛错，也就是它永远没机会调用 notifyAppReady()。应用下载了它，提示重启，然后死回了主屏幕。

下一次启动又跑了 v3，又崩了，这让我很意外，因为文档说在 notifyAppReady() 之前崩溃的 bundle 会被回滚。源码解释了原因：SDK 允许三次未确认的启动，之后才判定为崩溃，因为一次未确认的启动也可能只是 iOS 在任何 JavaScript 跑起来之前就杀掉了一个健康的进程。第四次启动回到了 v2。

然后设备自己上报了这次失败，类型是 crash_rollback，面板把它记在了 v3 名下。这个设计合理，但有必要把它的含义说白：一个坏 release 会让每个用户崩三次启动才能恢复，而当时文档没有提这个数字。现在提了，而且这个额度可以配置，原生侧用 CodemagicPatchMaxLaunchAttempts，或者用 Expo 插件的 maxLaunchAttempts。这正是先发 Staging、再小比例发 Production 的理由。

替其他所有人叫停一个坏 release 是一条命令，不到一秒：

cmpatch release rollback --app maru-ios --deployment Staging

它不改写历史。它把上一个 release 重新发布成一个新的（v4，标记为 v2 的回滚），所以崩溃的那个 release 连同它的失败计数一起留在列表里，这是诚实的记录。面板上通过一个对话框做同样的事。

localhost:8080

Android

#

Android 有两个意外，都不是 Patch 的问题。我给 SDK 加的 R8 keep 规则放在 app.config.js 里，而它只能通过 prebuild 才能到达原生工程，所以我第一个 release 构建等于无意中测试了 SDK 在没有 keep 规则的情况下能不能扛住 R8。能：R8 把它所有的类都重命名了，更新照样下载、安装、回滚，一切正常。另外，刚冷启动的模拟器加上还占着内存的 Gradle，慢到我的第一次测试在 SDK 完成那个早已开始的下载之前 45 秒就放弃了。

Release v1 应用成功，一次成功、一台活跃设备，一个会崩的 v2 在同样的三次启动额度之后回滚了。

顺利路径之外

#

更新能到、能回滚是核心，但一个团队天天用的是其他那些功能，所以我一个一个过了一遍。

灰度发布是确定性的，这点我喜欢。md5(deviceId + "-" + releaseLabel) 的前八位十六进制数字对 100 取模，小于灰度百分比的设备就在圈内，所以同一台手机对某个 release 要么一直在、要么一直不在。我算出模拟器在下一个 release 里落在 91 号桶，按 25% 发布，模拟器果然什么都没收到。用 cmpatch release patch 提到 95%，不到一秒，下次启动它就更新了。

接着我的下一个 release 失败了，返回 409：“deployment has an active rollout below 100 percent”。每个 deployment 同时只允许一个部分灰度，所以你得先把金丝雀发完、禁用或者回滚，才能发别的。这合理，也有文档，但一条每次合并都发布的流水线会在金丝雀进行到一半时撞上它。我反馈之后，CLI 在这里会把话说清楚了：如果是一个进行中的部分灰度挡住了你，它会告诉你等也没用，以及怎么把灰度发完或禁用；如果是另一个发布任务还在跑，它会让你用 release inspect --wait 等着。文档现在也有一节专门讲按顺序进行的发布变更。

强制 release 用的是 SDK 的 mandatoryInstallMode。我设的是下次回到前台时应用，应用下载了更新并弹出提示，我无视提示，把应用切到后台再切回来，新版本就直接在那里了。

禁用一个 release 做的不只是停止提供它。我一禁用最新的那个，清单就立刻指向了仍然启用的最新 release，禁用版本上的设备会被推一个回到它的 patch。把某个二进制版本的 release 全部禁用，清单的目标就变成 null，SDK 会把应用退回到它随二进制自带的 bundle。我的更新 hook 起初没有对这种情况弹提示，现在有了。

从 Staging 提升到 Production 不到一秒，而且复用的正是测试过的那个包，同样的哈希和备注，不会重新构建。它还接受一个灰度百分比，所以“提升到 Production 的 10%”就是一条命令。

构建和发布也可以拆成两步。cmpatch bundle 产出一个 .cmpatch 产物，面板的 “Bundle upload” 选项会在上传前读取它：平台、目标版本、指纹、签名状态、大小和打包器。这适合 CI 构建产物、再由别人决定什么时候发布的场景。

也是在这里，我真正撞上了指纹保护。修好过期的 widget plist 之后，服务器以 409 拒绝了我的下一个 release，因为原生工程的指纹和它为 2.5.1 记录的那个对不上了。Android 上，改一下 app.config.js 里的注释就够触发了，因为 Expo 把应用配置也算进指纹。面板把同样的检查显示成一条警告，带两个指纹和一个 “Upload anyway” 按钮。这两次已安装的二进制上都没有任何原生的东西变过，所以覆盖是对的。但在真实使用里，诚实的答案几乎总是升版本号、重新做一次商店构建，我的发布脚本现在遇到这种情况就会这么说。

代码签名用的是 RS256：CLI 用 RSA 私钥给包的哈希签名，SDK 用编译进二进制的公钥校验。公钥以一行 base64 的形式放进去，正好契合我走构建设置的做法，两个平台我都测了。应用里带了公钥之后，未签名的 release 在下载前就被拒了。给应用打开 “require code signing” 后，服务器拒绝了未签名的发布，错误信息里写明了修法并链接到指南。签名的 release 正常安装，SDK 记录签名为已验证。当我禁用签名的那个 release、服务器退回到一个更早的未签名 release 时，SDK 也把它拒了。要注意的是，公钥必须在你发出的第一个二进制里就带上，因为更新没法把它加进去。

localhost:8080

团队和 CI 也都覆盖到了。成员会拿到四种团队级角色之一（owner、admin、developer、viewer），邀请会一直等到对方第一次登录。个人访问 token 在空的 home 目录下也能用，通过 --token 或环境变量传入都行，token 列表会显示每一个上次使用的时间。我还写了一个手动触发的 CI workflow，在 Linux runner 上跑同一个发布脚本，签名密钥来自 secret，不过还没跑过，因为它需要托管的服务器。

有一个工具当时我会跳过，cmpatch debug ios。它按 “OTA” 不区分大小写过滤系统日志流，而这会匹配到 “Rotation”，于是一次二十秒的应用启动产出了满屏的 SpringBoard 消息，应用自己的一条都没有。这已经修好了：它现在只显示带 SDK 标记的行。SDK 本身日志不多，主要是错误和开发构建下的警告，所以输出会很安静。你可能看到的那条 getpwuid_r 警告来自 xcrun simctl，不是 Patch。

到底有多难

#

Codemagic 想听我的看法，那就尽量说得直白。

试用很容易。两条命令、几分钟，你就有了真正的服务器、一个带演示数据的面板，和一个可以对准自己应用的 CLI。我会说这是头一个小时里最好的部分。

集成 SDK 是中等工作量，而且难点大多在你自己的项目里，不在 Patch。在一个原生目录是生成出来的新 Expo 应用上，确实就是插件加几行替换 expo-updates 调用的代码。在 maru 这样的应用上，原生工程已提交、有 widget 扩展、有 Web 构建、有 R8 和构建 profile，活儿都在边边角角。我得手动应用原生改动来避开 prebuild，把配置改成构建时注入好让 Staging 和 Production 构建能不一样，还要把 SDK 挡在 Web 之外。我还得保证更新里的 JavaScript 和二进制用同样的环境构建。搞明白之后没有一件是难的。我做的时候，这些大多不在文档里，不过已提交原生工程的路径和 bundle 构建时的环境，现在都写进去了。

日常使用很好。发布是一条命令，半分钟左右。灰度、提升、禁用和回滚，从 CLI 或面板操作都不到一秒，错误信息会说出了什么问题、该怎么办。服务器的那些保护（指纹检查、同时只能一个金丝雀、签名）严格得不止一次拦住我做错事。

在生产环境跑它是更大的承诺。它是一套带 Postgres 和对象存储的 Docker Compose 栈，你得托管、备份、升级，还需要两个域名和一个 OAuth 应用。对已经在跑服务器的团队，这是一个安静的下午。对那些正因为不想碰服务器才用 EAS 的团队，这才是切换的真实成本，比 SDK 那部分工作更大。

按挂钟时间算，我 12:29 装好 CLI，13:34 第一个更新在模拟器上应用成功，其中半小时是一次 Xcode 构建卡住了，原因和 Patch 无关。这篇文章里的所有东西，两个平台，都在下午过半之前做完了，托管服务器不算在内。

最耗我时间的几件事，按顺序：expo prebuild --clean 抹掉了我提交的原生工程，然后是研究怎么手动接好一切；iOS 版本检测的 bug，它会把更新发给一个没人在跑的版本；重复计数的安装，虽然是我自己造成的，但任何人都很容易重蹈，因为 sync() 自己会调 notifyAppReady()；还有没写进文档的三次启动崩溃额度，在一次测试进行到一半时把我吓了一跳。再往后是一些本身正确、但需要规划的事：无害的原生相关改动触发指纹保护，每个 deployment 同时只能一个金丝雀，以及不能重叠的生命周期任务，一旦脚本要连着做几件事，这就很要紧。剩下的都是小事：首次运行时静默的搭建过程、一条吵闹的调试命令，还有几个当时和代码对不上的文档示例。

这些我都连同细节一起写给了 Codemagic，到 9 月 23 日，大部分已经修复：版本检测、重叠的确认、prebuild 的提醒、崩溃额度、静默的搭建过程、调试命令、InstallMode 的示例，以及发布任务或金丝雀挡路时给出的报错。还没解决的都是小事：面板显示 API 在 :8080，而其他地方都说 :3000；SDK 在 Web 和 Jest 里一 import 就抛错；以及文档里的几处空白。

上生产

#

上面的一切都是在评估栈上跑的。生产就是同一个应用、同一套脚本对准一台真实的服务器，下面是 maru 的计划。

官方支持的服务器部署方式是 Docker Compose 安装：一台开放 80 和 443 端口的 Linux 机器、两个域名（一个给 API 和面板，一个给下载），以及一个用于登录的 GitHub OAuth 应用，没有它服务器不会启动。安装器负责剩下的事，包括 TLS：

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

它会写一个 .env.selfhost，里面是数据库和存储的密钥，应该放进你的密码管理器。

不过你不一定要用自带的数据库和存储，这正是它能嵌进我这种栈的原因。maru 的 API 已经跑在 Fly.io 上，文件放在 Tigris，Patch 在两者上都能工作。Compose 文件底下，服务器就是一个以 MODE=all（API 和 release worker 一起）运行的容器，需要一个 Postgres 数据库、S3 兼容存储，和一个供文件访问的公开 HTTPS URL。也就是一个用仓库的 Dockerfile 构建的 Fly 应用（目前还没有发布的镜像，所以由 fly deploy 来构建）、一个 Fly Postgres 数据库，和一个 Tigris 桶：

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

两点提醒。在 Compose 之外运行，仓库里的文档把它定位为参考材料，而不是这个首个开源版本里受支持的路径，所以在 Fly 上，升级和备份得靠你自己。我也还没这样部署过；这是计划，不是报告。另外，如果你读过我写 Fly 缩容到零的那篇，记得至少留一台机器在跑。手机做更新检查时从不等 API，因为清单直接来自存储，但不然的话，每一次指标上传和每一个 release 任务都会从一次冷启动开始。

Tigris 是我最期待的部分。maru 的文件本来就在那儿，而且它在每次应用启动都要访问的那个 URL 前面放了一层 CDN。这么做的话要留意清单的缓存：用普通的 base-URL 分发适配器时，Patch 会把清单以 no-cache 提供，因为它没法清 CDN，而一份按自己 TTL 缓存的清单会一直提供你刚刚回滚掉的那个 release。配置参考现在在 MANIFEST_CACHE_CONTROL 下写明了这一点，文档站也讲到了 S3 兼容存储。

在托管服务器上，重新建一遍应用，把新的 key 放进 eas.json 的 preview 和 production profile（分别是 Staging 的 key 和 Production 的 key），再创建一个用于发布的 token：

cmpatch token create --name ci

想要代码签名的话，现在就定：生成生产环境的密钥对，私钥作为 CI secret 保管，公钥放进构建 profile，然后给两个应用都打开 “require code signing”。第一个 Patch 二进制还需要一个新版本号，因为商店里已有的二进制跑的是 expo-updates。先用 preview profile 构建给 TestFlight 和 Play 内部测试，交给任何人之前，先确认 key 真的进了构建出来的 Info.plist 和 Android 资源。这是我本地测试唯一没有覆盖到的一环，因为环境变量是我手动导出的。然后发到 Staging，确认每个测试者一次下载、一次成功，之后才构建商店版本。

生产 release 从小开始，逐步放大：

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

旧服务器这期间继续开着。所有还没更新的 2.5.1 副本仍然在向它检查，给它们的热修复也仍然走旧脚本。等日志显示那些请求停了，旧服务器连同它的发布脚本和密钥就可以全部删掉。

第一次原生升级

#

2026 年 10 月 16 日补充。

从 10 月初开始，maru 的生产更新就交给 Patch 来发了。那之后的第一次原生发布是升级到 Expo SDK 58：React Native 0.88，Android 上还有 Gradle 插件的一个新大版本。原生改动没法 OTA，所以这是一个新的二进制 2.6.0，而我的发布脚本在这个二进制存在之前会拒绝发 2.6.0 的更新。两个平台第一次就都干净地构建成功了。

上面的生产部分说过，交给任何人之前，先确认 key 真的进了构建出来的 Info.plist 和 Android 资源。这次我真的查了，而这一节正是因为这次检查才有的。iOS 构建里四个 Patch 设置都在。Android 构建里一个都没有：

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

这条命令对 2.5.11 的构建打印出四个 key，对 2.6.0 什么都没打印。问题不在环境变量：Gradle 的 generateReleaseResValues 四个都写了。它们是之后被 release 构建的资源缩减器（resource shrinker）删掉的，而它在 Android Gradle Plugin 9 里激进了很多。同一个应用的资源从 9,240 个降到了 7,116 个。SDK 用 getIdentifier 按名字读取配置，缩减器看不到这种用法，于是把这四个字符串当成没用的删掉了。缺失的字符串读出来是空的，而空意味着"没有更新"。什么都不会失败。Android 2.6.0 会正常安装、正常运行，却永远收不到更新，唯一的迹象是面板上一台 Android 2.6.0 设备都没有。

修复是一个资源文件，告诉缩减器保留这四个字符串：

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

别把它叫做 keep.xml：React Native 的 bundle 任务已经会为你的 JavaScript 资源生成一个 raw/keep.xml（图片和字体能幸存就是因为它），两个文件会冲突。这条规则更合适的位置是 SDK 本身，因为库的 keep 文件会自动合并进应用；而 release 构建在没有 deployment key 的情况下启动时，只要有一条警告，就能把这种悄无声息的情况变成看得见的。这和前面 iOS 版本检测的 bug 是同一类失败：什么都不报错，更新就是永远不来。

同一次检查还发现了第二个问题，跟 Patch 无关，但出于另一个原因值得知道。Android 的 release 构建一启动就崩溃，而且崩了两次，原因是 Expo 自己模块里的两个不同问题。第一个是 Expo 的 widget 模块没能注册它的原生类，所以应用在任何 JavaScript 运行之前就挂了。修好之后，应用能走到启动 JavaScript 这一步，然后就停住了，因为有三个已经迁到 Expo 新模块系统的模块从来没被注册。这两种情况 Patch 的崩溃回滚都帮不上忙，因为根本没有可以回滚的更新。它保护你不受坏更新的影响，而不是坏二进制。不管用不用 Patch，原生升级在上商店之前都得在真机或模拟器上装好、打开一次。

同一轮测试还带出了一件小事。sync() 失败时会返回 "error"，除非应用跑在开发模式下，否则不会告诉你原因，所以 release 构建只能在日志里记一句出错了。现在我的 hook 在 sync 失败后会调用一次 checkForUpdate()，把它抛出的错误记下来，我就是这样发现问题不是服务器坏了，而是一个本地模拟器构建的 Patch URL 是空的（unsupported URL）。如果最后一次的错误在 release 构建里也能读到，会有帮助。

我的原生发布检查清单现在多了以前没有的三行：从构建出来的 .ipa 和 .aab 里导出 Patch 设置，把 deployment key 和构建 profile 对一遍，以及在提交前启动 release 构建本身，而不是 debug 构建。

想对正在付 Expo 账单的人说的话

#

如果你付费用 EAS Update 是因为搭服务器看起来太费事，Patch 是一个实在的答案：你确实要跑一台服务器，但那是一套 Compose 栈和一个安装器，不是你要维护的代码。和我自己搭的那套相比，你会得到灰度发布、每个 release 的安装和失败数字、二进制 patch、指纹保护、代码签名、设备端的崩溃回滚，和一个回滚按钮。这些我一个都没做过。

代价是：在任何人收到 Patch 更新之前先要发一个新二进制，因为 SDK 得进到应用里；一台要持续升级和备份的服务器；release 坏得够彻底时每个用户三次崩溃启动（默认值）；以及原生工程已提交的话，一些手工活。它也还年轻。这是 0.3.0 版本，我碰到了一个版本检测 bug、一条吵闹的调试命令和文档里的几处空白，还自己造了一个 SDK 本可以防住的 bug。版本检测和调试命令后来都修好了，文档的空白大多补上了，SDK 现在也能防住我犯的那个错。这些都没有挡住迁移，而且全都看得见，在 CLI 里、在面板里、或者在设备上 SDK 自己的文件里，这一点我的旧方案可说不上。

2026 年 9 月 13 日更新。 这篇发出之后，Codemagic 发布了 Patch，一个 CodePush 路线的开源、可自托管 OTA 服务器。如果你是因为不想自己写服务器才找到这里的，它现在是一个实在的选项：我已经把一个应用从下面这套方案迁到了 Patch，并把过程写了下来，写在最后一节里也有一段简短说明。声明：那次迁移和那篇文章是 Codemagic 付费委托的，他们也希望在这里提一句。正文里的代码后来已精简为简短的示例。

我做的报价应用，bug 修复都是通过 OTA 推送的：JavaScript 改动不用等 App Store 审核，直接下发到用户手机上。Expo 官方的 EAS Update 本来就能做这件事，但我还是用 Django REST Framework 和 Tigris S3 自己搭了一套。从那以后，iOS 和 Android 的更新全都走这台服务器。

Expo 的 OTA 更新（也就是大家常说的热更新）是这样运作的：应用里的 expo-updates 库向更新服务器请求一份清单，请求头里带着自己的平台和运行时版本。服务器返回最新的兼容更新，以及这次更新的 JavaScript bundle 和资源文件的地址，应用把它们下载下来，下次启动时就跑新的 bundle。EAS Update 是 Expo 官方托管的一种实现，但任何实现了这套协议的服务器都能用，我自己搭的就是这样一台。

这篇文章把整个方案过一遍：数据模型、清单（manifest）接口、发布流水线，还有那些只有真正跑起来才会踩到的坑。

为什么要自己搭

#

对我来说主要是钱的问题。EAS Update 按用量计费，用户多了、更新频繁了，账单就跟着涨；而 Tigris 这类 S3 兼容存储几乎不要钱。当然还有别的理由：有些行业要求应用资产必须留在自己的基础设施里；服务器在自己手上，整个更新流程就都可控，想按用户群灰度、想做 bundle 的 A/B 测试都行。另外，更新链路也不再受 Expo 服务可用性或下一次调价的影响。

整体架构

#

一共四个部分：Django 后端负责下发更新清单、保存元数据；Tigris 存放 bundle 和资源文件本体；一个发布脚本负责导出、上传、登记更新；再加上移动应用本身，把更新地址指向我的服务器而不是 Expo 的。

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

具体实现

#

两个模型

#

一切都建立在 ExpoUpdate 和 ExpoUpdateAsset 之上。前者保存每次更新的元数据：

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

这里有几个刻意的设计。runtime_version 对应 app.json 里的 runtimeVersion，客户端只会下载和自己运行时版本一致的更新，所以这个字段很关键。iOS 和 Android 的 bundle 不一样，所以分开存。is_active 是回滚开关：把有问题的更新停用，客户端就会退回上一个版本。manifest_data 直接把完整的 Expo Updates v1 协议清单存成 JSON，下发的时候取出来就行。

ExpoUpdateAsset 记录每个文件：

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

资源用 SHA-256 哈希来引用，天然不可变、好缓存，同一个资源可以被多次更新复用。

清单接口

#

应用和服务器真正打交道的地方是 /api/expo-updates/manifest/，实现的是 Expo Updates v1 协议：

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

有三个细节值得注意。没有更新时返回 204，应用会继续用内置的 bundle。清单里的资源地址是预签名 URL，应用直接从 Tigris 的 CDN 下载，不用整个流经 Django。响应头里的 expo-protocol-version 不能省，客户端真的会检查。

发布更新

#

发布靠一条 Django 管理命令，外面再包一层 shell 脚本。管理命令负责读取 expo export 的输出、给每个资源算 SHA-256 哈希、把 bundle 和资源并行传到 Tigris、写数据库记录，需要的话还会往桶里放一份用于生产同步的导入 JSON。精简到关键部分大致是这样：

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

平时真正敲的是外面这层脚本：

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

它会在导出前加载生产环境变量，平台可以只发一个也可以两个都发，还顺带处理下一节要讲的生产同步。

同步到生产环境

#

我不想把生产环境的凭证放在自己笔记本上，所以生产发布分两步：先在本地发布（资源传到 Tigris，同时生成一份元数据的 JSON 快照），再带着 S3 路径调用生产环境的 API，让服务器自己把元数据导进去：

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

让应用指向自己的服务器

#

在 app.json 里配置更新地址和运行时版本：

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

runtimeVersion 必须在应用和服务器之间严格对齐。改了原生代码或者升级了 Expo SDK，就把运行时版本加一，然后针对新版本重新发布更新。

Tigris 存储

#

Tigris 是 S3 兼容的对象存储，比 AWS S3 便宜得多，还自带全球边缘缓存。考虑到用户要下载好几 MB 的 bundle，这一点很实在。Django 侧的配置：

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

客户端就是普通的 boto3：

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

下载走预签名 URL，应用直接从 CDN 拉取：

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

安全

#

清单接口是故意不做鉴权的，因为应用在用户登录之前就需要拿更新。导入接口则完全不同：它能写生产数据库，所以要求共享密钥，并用常数时间比较来防时序攻击：

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

资源完整性是这套设计白送的：所有资源都按 SHA-256 哈希校验，被篡改的资源直接失败。预签名 URL 一小时过期，bundle 也就不会被长期盗链。

性能

#

(runtime_version, platform, is_active, -created_at) 这个联合索引保证清单查询不会随着更新数量增长变慢：

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

发布脚本用线程池并行上传资源：

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

以一次 50 个资源左右的典型更新为例，发布时间从大约 2 分钟缩到了 15 秒。分发这边什么都不用做，Tigris 会自动把资源缓存到离用户近的边缘节点。

日常流程

#

开发时

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

发布到生产

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

回滚

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

成本

#

这个应用大约有 500 个活跃用户。Tigris 上，约 200 MB 的历史更新每月大概 0.02 美元，更新下载带来的每月约 50 GB 流出流量大概 1 美元。Django 这边跑在原本就承载 API 的服务器上，没有额外成本。加起来每月一美元左右。同样的用量放到 EAS Update 上，一年大概要 300 到 500 美元，所以这套东西基本上立刻就回本了。

监控与调试

#

没什么花哨的。ViewSet 会把每个清单请求记进日志：

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

Django admin 就是事实上的控制台，把模型注册进去，查看、筛选都很方便：

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

客户端这边，expo-updates 会告诉你它看到了什么：

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

踩过的坑

#

运行时版本不匹配

#

最常见的故障也最安静：客户端只下载和自己运行时版本一致的更新。装机版本还在 1.0.0，你却按 1.0.1 发布，那就什么都收不到，也没有任何报错。运行时版本要和构建保持同步，只在原生代码变化时才递增。

createdAt 时间戳

#

expo-updates 客户端会拿清单的 createdAt 和内置 bundle 的 commitTime 比较，只有 createdAt 更新的才会被应用。ViewSet 里用数据库时间戳覆盖它：

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

本地开发时，如果你在发布 OTA 之后又构建了二进制包，就重新发布一次 OTA，保证时间戳更新。

清单里的资源 key

#

清单中每个资源的 key 字段是 expo-updates 用来做缓存的，它必须是确定性哈希（比如文件名的 MD5），不能是随机 UUID 或随便一个字符串。搞错了，客户端可能无法正确缓存和读取资源，更新会在第一次成功加载之后悄悄失效。感谢读者 Raphael Mutschler 指出这个问题。在找到原因之前，他的更新恰好只成功过一次。

expoClient 里的应用配置

#

如果应用用到 Linking、Constants 或其他在运行时读取应用配置的东西，清单的 extra.expoClient 字段里就必须带上应用配置。少了它，应用第一次可能启动正常，关掉之后再打开就崩溃或干脆打不开。原因是 expo-updates 会用 OTA 的清单替换内置清单，expoClient 一缺，这些 API 依赖的配置就没了。这个坑也是 Raphael Mutschler 发现的。

清理旧资源

#

旧更新会在 Tigris 里越积越多。目前我还是手动清理：

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

按理说应该放进定时任务，我还没顾上。

接下来想加的

#

（2026 年 9 月：这三样 Patch 现在都有了，还不止，见迁移记录。）

灰度发布

#

加一个 rollout_percentage 字段，就能先放量给一部分用户：

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update