这两个我每天都在用。Ollama 跑在我的笔记本和办公室那台 GPU 工作站上，用来开发，也用来跑我自己的工具。vLLM 在一块 96 GB 的 GPU 上为我做自由职业时接的一个项目提供聊天模型，最早用 Docker Compose 跑，现在跑在一个小型 Kubernetes 集群里。

vLLM 与 Ollama 的区别一览

#

Ollama 是什么

#

Ollama 是我知道的、在自己机器上让模型开口回答最省事的办法。它建立在 llama.cpp 之上，跑的是量化过的 GGUF 模型，所以一个 8B 模型大约 5 GB 就装得下，在 MacBook 上也跑得挺欢。按名字拉取模型，第一次调用时加载，闲置五分钟没事干就从内存里退出，所以它能和你机器上跑着的其他东西客客气气地共处。

这份客气就是代价。Ollama 是围绕"一次一个人"来设计的。默认它一次只处理一个请求，OLLAMA_NUM_PARALLEL 可以加槽位，但每个槽位都要占一整个上下文的内存，而且它从来就不是为了把几十个用户批到一块 GPU 上而做的。

vLLM 是什么

#

vLLM 是一个推理服务引擎，正是为这种批处理而做的。撑起它的主要是两个设计。PagedAttention 把每个请求的 KV cache（模型在读写 token 的过程中积累下来的 attention 状态）存放在固定大小的小块里，显存就不会浪费在 padding 和碎片上。连续批处理让新请求在两个生成步骤之间加入批次，而不必等当前这一批跑完。两者加在一起，同一块 GPU 跑 vLLM 能服务的并发用户，远多于它一个接一个处理请求的时候。我没有亲自把两者放在一起测过，所以这篇文章没有自己的吞吐量数字。实测版本可以看 Red Hat 的 Ollama vs. vLLM 基准测试：一块 A100 跑 Llama 3.1 8B，并发用户从 1 到 256，即便把 OLLAMA_NUM_PARALLEL 提到 32，vLLM 的峰值也有每秒约 793 个输出 token，而 Ollama 是 41。

代价是 vLLM 表现得好像整块卡都归它。它在启动时就申领自己那份显存，权重用不完的部分全部填上 KV cache，不管有没有人在调用都一直占着。它还要完整的 Hugging Face 权重，或者 FP8、AWQ 这类适合 GPU 的量化格式。GGUF 文件它也能加载，但 vLLM 自己的文档把这项支持称为"highly experimental and under-optimized"，所以别指望复用 Ollama 下载好的文件。

需要多少显存

#

只算权重的大致大小：

也就是 16-bit 下每个参数约 2 字节，8-bit 下 1 字节，Q4_K_M 下略多于半个字节。权重之外还要加上 KV cache，它随上下文长度和同时在处理的请求数增长。正是这第二部分，让同一个模型在 vLLM 上服务五十个用户时，比在 Ollama 上只服务你一个人时需要多得多的显存。

一套 API，两个服务端

#

因为两者都提供 OpenAI 的 chat completions API，我的代码并不知道自己在跟哪一个说话。URL 和模型名都从环境变量里读：

import os
from openai import OpenAI

# Laptop:     LLM_URL=http://localhost:11434/v1  LLM_MODEL=qwen3:8b
# GPU server: LLM_URL=http://localhost:8000/v1   LLM_MODEL=qwen3-8b
client = OpenAI(base_url=os.environ["LLM_URL"], api_key="not-needed")

reply = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "Say hello in Korean."}],
)
print(reply.choices[0].message.content)

我的笔记本没有大显卡，在上面应用就指向 Ollama。到了服务器上，它指向 vLLM。别的什么都不用改，开发这个应用时，那台 GPU 机器甚至可以不开机。vLLM 这边，--served-model-name 给模型起一个短名字，客户端就不用发完整的 Hugging Face 路径。

有一点要提醒一下，因为很容易忘：同一个模型，两边给出的回答并不一样。Ollama 的 qwen3:8b 是 4-bit 量化，而在 vLLM 上你通常跑的是 16-bit 或 FP8 权重。对着其中一个调好的 prompt，换到另一个上可能表现不同，所以凡是你在衡量的东西，不管是回答质量、拒答，还是 JSON 能不能解析，都得在生产环境真正要用的那个服务上验证。

如何安装 Ollama

#

在 Mac 或 Windows 上，从 ollama.com 下载应用。在 Linux 上：

curl -fsSL https://ollama.com/install.sh | sh
ollama run qwen3:8b

就这么多。API 现在在 http://localhost:11434 上，除非你设置了 OLLAMA_HOST，否则它只监听 localhost，这正是你想要的。我的那个跑在办公室工作站上，绑定 127.0.0.1，我在任何地方都通过一条隧道连过去（我是怎么用 Cloudflare WARP 搭起来的）。

vLLM 部署教程：安装与运行

#

在装有 NVIDIA GPU、驱动也比较新的 Linux 上，用 vLLM 部署 Qwen3-8B：

python -m venv .venv && source .venv/bin/activate
pip install vllm
vllm serve Qwen/Qwen3-8B --served-model-name qwen3-8b --max-model-len 16384

第一次运行会从 Hugging Face 下载权重。等日志里出现 Application startup complete，curl localhost:8000/v1/models 就能列出这个模型，上面那段 Python 也能直接对着它用。

用 Docker 部署 vLLM

#

凡是需要一直在线的，我都用官方镜像而不是 pip 安装，主要是为了让 CUDA、PyTorch 和 vLLM 的版本绑在一起。一个通用的 Compose 服务：

services:
  vllm:
    image: vllm/vllm-openai:v0.30.0   # the tag I ran; pin whatever is current. About 30 GB
    restart: unless-stopped
    ipc: host                          # PyTorch needs shared memory
    command: >
      --model Qwen/Qwen3-8B
      --served-model-name qwen3-8b
      --gpu-memory-utilization 0.85
      --max-model-len 16384
    volumes:
      - ${HOME}/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "127.0.0.1:8000:8000"          # reach it over ssh -L, not the LAN
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 10s
      timeout: 5s
      retries: 90
      start_period: 120s

tag 一定要固定。vLLM 迭代很快，flag 和默认值在版本之间会变，什么时候跟着变，应该由你自己说了算。ipc: host（或者给足 shm_size）写在 vLLM 自己的 Docker 文档里。那个很长的 start_period，就是下面要讲的第一件事。

跑 vLLM 踩过的坑

#

启动要好几分钟

#

加载权重、编译、捕获 CUDA graph，在我的服务器上花了 190 秒，大模型要三到五分钟很正常。照着 Web 应用写的健康检查，会在它准备好之前就把它杀掉。在 Compose 里，这意味着要设一个很长的 start_period；在 Kubernetes 里，意味着要配 startup probe。这也意味着每次重启都有几分钟没有模型可用，所以重启不能随手就来。

你给它多少显存，它启动时就拿走多少

#

--gpu-memory-utilization 是 vLLM 可以使用的显卡占比，较新的版本默认 0.92，权重用不完的部分都会变成 KV cache。vLLM 独占显卡时这没什么问题。我的不是，旁边还跑着几个小模型，所以我在这块 96 GB 的卡上设成了 0.70。模型是一个 FP8 的 35B 混合专家模型（MoE），加载后占 47.7 GiB，给 KV cache 留了 15 GiB，在 16k 上下文下绰绰有余。如果 vLLM 因为最大序列长度放不进 KV cache 而拒绝启动，先调低 --max-model-len，再去考虑换更大的 GPU。

LoRA 槽位要提前占显存

#

vLLM 可以在一个基座模型上挂多个 LoRA adapter，每个请求按模型名切换，这一点 Ollama 基本做不到。但它在启动时就会为 --max-loras 个 adapter 按 --max-lora-rank 预留空间，而在混合专家模型上，这份预留连专家部分也要算进去，所以涨得很快。在 0.70 下，四个 rank 64 的 adapter 放不下。两个可以。

默认的序列数上限不适合混合架构的模型

#

我跑的这个模型在 attention 层之间夹着 Mamba 风格的层，每个序列都需要为这些层单独准备一个缓存块。vLLM 的 --max-num-seqs 默认值在 70 GB 以上的卡上是 1024（更小的卡是 256），所以在那块卡上它启动失败；改成 --max-num-seqs 256 就好了。如果某个较新的架构起不来，先查这个 flag，再去想更偏门的原因。

一个叫 vllm 的 Kubernetes Service 会让 vLLM 崩溃

#

这是我最喜欢的一个。Kubernetes 会为命名空间里的每个 Service 注入环境变量，变量名取自 Service 的名字，所以一个叫 vllm 的 Service 会给每个 pod 塞进一个 VLLM_PORT=tcp://<cluster-ip>:8000。vLLM 会把 VLLM_PORT 当成自己的配置项来读，它解析不了那里的 URL，于是挂了。当然是在把整个模型加载完之后才挂的，所以每试一次就搭进去三分钟。vLLM 的文档其实对此有警告，这是我事后才看到的。解决办法是在 pod 上设 enableServiceLinks: false，或者给 Service 换个名字。

下面是一个能正常工作的 Deployment 的大致样子，只保留了要紧的部分：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm
spec:
  replicas: 1
  strategy:
    type: Recreate               # the old pod has to free the GPU first
  selector:
    matchLabels: {app: vllm}
  template:
    metadata:
      labels: {app: vllm}
    spec:
      enableServiceLinks: false  # no VLLM_PORT=tcp://... from the Service
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.30.0
          args: ["--model=Qwen/Qwen3-8B", "--served-model-name=qwen3-8b"]
          resources:
            limits:
              nvidia.com/gpu: "1"
              memory: 32Gi       # loading needs far more host RAM than serving
          volumeMounts:
            - {name: shm, mountPath: /dev/shm}
          startupProbe:          # don't judge it until the model is loaded
            httpGet: {path: /health, port: 8000}
            initialDelaySeconds: 120
            periodSeconds: 10
            failureThreshold: 90
          livenessProbe:         # a restart costs a full reload, so be patient
            httpGet: {path: /health, port: 8000}
            periodSeconds: 30
            timeoutSeconds: 5
            failureThreshold: 10
      volumes:
        - name: shm
          emptyDir: {medium: Memory, sizeLimit: 16Gi}

值得照抄的是 probe 这部分。startup probe 先等两分钟，然后再给模型十五分钟时间起来，过了这个时间 Kubernetes 才判定它挂了。liveness probe 要连续失败大约五分钟才会重启它，因为引擎忙的时候 /health 可能响应很慢，而且重启反正要完整重新加载一遍。在单 GPU 上 Recreate 很关键：滚动更新会先启动新 pod，而它只能干等着那块还被旧 pod 占着的 GPU。内存限制看起来给得很宽，确实很宽；权重进了 GPU 之后，我这边稳定在大约 7 GiB 主机内存，但加载过程本身要多得多。

Ollama 要注意的地方

#

意外少一些，主要是因为它做的事本来就少。

安静一阵之后的第一个请求会很慢，因为模型已经被卸载，得重新加载。OLLAMA_KEEP_ALIVE 决定模型在最后一个请求之后在内存里留多久；如果这个停顿让你烦，就把它调大，或者在一台不干别的事的机器上设成 -1。

上下文窗口取决于你有多少显存。显存不到 24 GiB 时，Ollama 默认只给 4k token，远少于大多数模型支持的长度，而放不下的 prompt 会被悄悄截掉，不会报错拒绝。如果回答好像无视了长 prompt 的开头，就把 OLLAMA_CONTEXT_LENGTH（或者每个请求的 num_ctx）设成你真正需要的长度。

如果你把远程的 Ollama 转发到笔记本上，别用 11434。那是 Ollama 的默认端口，要是本地哪天也起了一个 Ollama，两者就会抢这个端口，你可能在不知不觉中连到了错的那一个。我的转发到 11435。

还有，它不是多用户服务器。拿来做几个人用的内部工具没问题；一旦真正的并发来了，就到了该换 vLLM 的时候。

该用哪一个

#

如果你只是想在自己的机器上跑个模型，装 Ollama 就够了，到此为止；十分钟内就能让它回答问题。如果你有一台 GPU 服务器，还有用户或者应用整天都要调用它，那就用 vLLM，接受它启动慢、占显存，把 probe 配好。不少部署最后两个都用，我的也是：写代码的地方用 Ollama，请求落地的地方用 vLLM。

当然还有别的选择。SGLang 是 vLLM 常见的替代方案，但我没在生产环境跑过它，与其瞎猜，不如不写。如果模型得跑在手机上，那就又回到 llama.cpp 了，我在用 React Native 在手机上端侧运行 LLM 里写过。

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

很多团队把构建和测试步骤直接写进 GitHub Actions 的 YAML 里。平时用着没问题，直到某天你想在自己的笔记本上跑一遍同样的构建，或者有人提议迁去 GitLab，才发现整条流水线已经焊死在某家供应商的配置格式上了。我现在的做法很朴素：真正的逻辑放进 Docker Compose，CI 工具只负责调用它。

为什么我不把构建逻辑写进 Actions YAML

#

最明显的问题是绑定。Actions 的工作流对 GitLab、Bitbucket、Jenkins 来说毫无意义，构建步骤要是写在工作流文件里，换平台就得全部重写。我还没见过哪个团队真会给这种事排期。

更隐蔽的问题是流水线没法在本地跑。如果验证构建改动的唯一办法是推一个提交、盯着 Actions 页面等结果，git 历史很快就会塞满 “fix ci”“fix ci again” 这样的提交。Compose 文件在我的笔记本上和在 runner 上跑起来一模一样，“在我机器上是好的” 这类争论基本也就消失了。

还有，YAML 会一直长。一开始是整洁的二十行，加上缓存技巧和条件判断后很快变成三百行，开发者除了 Git 还得学一门 CI 方言。一个脚本本该只做一件事，而庞大的工作流文件往往什么都揽。

用 Compose 之后分工就清楚了：构建和测试归 Compose 文件管，CI 平台只是在每次推送时把它跑一遍的角色。

具体做法

#

1. 先写一个 Dockerfile，让镜像的构建方式只有一个出处：

# 使用官方Node.js运行时作为基础镜像
FROM node:14

# 设置容器中的工作目录
WORKDIR /app

# 将package.json和package-lock.json文件复制到容器
COPY package*.json ./

# 安装依赖
RUN npm install

# 将其余应用程序代码复制到容器
COPY . .

# 暴露应用程序运行的端口
EXPOSE 3000

# 定义运行应用程序的命令
CMD ["npm", "start"]

2. 再写一个 docker-compose.build.yaml，定义构建和测试所需的服务。

   services:
     app:
       image: myprivaterepo.com/image:latest
       build: .
       volumes:
         - .:/app
       command: sh -c "npm install && npm test"

3. 先在本地跑一遍，这正是这套做法的意义所在：

   docker compose -f docker-compose.build.yaml build

4. 本地跑通之后，GitHub Actions 的工作流（换成别的 CI 平台也一样）就缩成了一个编排器：

   name: CI/CD Pipeline
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v1
         - name: Build and Test with Docker Compose
           run: docker compose -f docker-compose.build.yaml build
         - name: Push the image referenced in the docker compose file
           run: docker compose -f docker-compose.build.yaml push

现在 CI 工具只做两件事：构建和推送。所有值得看懂的东西都在几个文件里，任何平台、任何新同事都能直接运行。

推送镜像

#

Compose 文件还有个顺带的好处：推送镜像变得非常简单。Docker 根据镜像名判断推送目标，image: myprivaterepo.com/image:latest 就意味着推到 myprivaterepo.com。私有仓库需要访问令牌，这部分请查你所用仓库服务的说明。

如果你现在用 GitHub Actions 用得很顺，不必急着改。但哪天真要换供应商，迁移工作就从“移植三百行 YAML”变成“复制两条命令”。而在那天到来之前，你可以体面地在本地调试构建。