Supabase 自托管 Docker 镜像版本管理：读懂 docker/versions.md 并完成镜像回滚

本文以 Supabase 仓库中 docker/versions.md 为主体，讲清这份“Docker 镜像版本历史”文件的格式约定、当前各服务镜像标签的快照状态，以及它如何与 docker-compose.yml、update.sh 三向合并机制和 upgrades.json 破坏性变更门禁协同工作。读完后你可以：为生产环境核对并固定（pin）各组件镜像版本、按日期条目快速定位某次升级的旧版本完成回滚、并在执行自托管升级时正确预判哪些镜像变更属于常规合并、哪些需要人工干预。

一、versions.md 是什么：一份按日期倒序的镜像标签变更台账

versions.md 的文件标题即说明了它的定位：

Docker image version updates in docker-compose.yml

它不是一份安装文档，而是一份按日期倒序排列的镜像标签变更台账，记录每一次对自托管 docker/ 目录中 Compose 文件镜像标签的更新。它的格式约定非常固定：

• 每个二级标题（H2）是一个变更日期（如 ## 2026-08-03）；
• 日期下的每条列表项格式为：镜像:新标签 (prev 镜像:旧标签)，prev 即升级前正在使用的标签；
• 一次发布可能同时更新多个镜像，因此同一天会出现多条记录（如 2026-06-03 一次性更新了 9 个镜像）。

docker/README.md 对它的定位是 “Complete history of Docker image versions for rollback reference”（完整镜像版本历史，用于回滚参考），docker/CHANGELOG.md 则注明镜像层面的完整历史“refer to versions.md”，自身只按服务分组记录配置层面的重要变更。换句话说：CHANGELOG 回答“改了什么配置”，versions.md 回答“每个镜像具体从哪个标签升到哪个标签”。

二、当前各镜像标签快照（截至 2026-08-03 条目）

versions.md 最新条目（2026-08-03）显示：

• supabase/studio:2026.08.03-sha-022b374（前版 supabase/studio:2026.07.07-sha-a6a04f2）
• kong/kong:3.9.3（前版 kong/kong:3.9.1）

将该条目与 docker-compose.yml 中当前实际声明的 image: 标签逐一对账，主 Compose 文件中的镜像标签如下（均已在源码中核实）：

服务（container_name）	当前镜像标签	文件行号
supabase-studio	supabase/studio:2026.08.03-sha-022b374	docker-compose.yml#L17
supabase-envoy（默认 API 网关）	envoyproxy/envoy:v1.39.0	docker-compose.yml#L72
supabase-auth（GoTrue）	supabase/gotrue:v2.189.0	docker-compose.yml#L111
supabase-rest（PostgREST）	postgrest/postgrest:v14.12	docker-compose.yml#L251
supabase-realtime	supabase/realtime:v2.102.3	docker-compose.yml#L288
supabase-storage	supabase/storage-api:v1.60.4	docker-compose.yml#L334
supabase-imgproxy	darthsim/imgproxy:v3.30.1	docker-compose.yml#L397
supabase-meta（postgres-meta）	supabase/postgres-meta:v0.96.6	docker-compose.yml#L420
supabase-edge-functions	supabase/edge-runtime:v1.74.0	docker-compose.yml#L437
supabase-db	supabase/postgres:17.6.1.136	docker-compose.yml#L479
supabase-supavisor（连接池）	supabase/supavisor:2.9.5	docker-compose.yml#L534

需要注意的几点事实（均可在仓库中核实）：

1. API 网关已从 Kong 切换为 Envoy。自 0.8.0 版本起，默认网关是 docker-compose.yml 中的 envoyproxy/envoy:v1.39.0（container_name 为 supabase-envoy）；Kong 保留为可选 override，其标签为 docker-compose.kong.yml 中的 kong/kong:3.9.3，通过 sh run.sh config add kong 启用。versions.md 中 2026-08-03 条目里的 kong/kong:3.9.3 即对应此 override 文件。
2. 日志栈独立于主 Compose。supabase/logflare:1.43.1 与 timberio/vector:0.53.0-alpine 位于 docker-compose.logs.yml，versions.md 中对 logflare、vector 的记录对应的是这份 override 文件而非主文件。
3. Postgres 大版本可用 override 固定。versions.md 2026-06-17 条目记录了 supabase/postgres:17.6.1.136（前版 15.8.1.085），而 docker-compose.pg15.yml 中仍保留 supabase/postgres:15.8.1.085，docker-compose.pg17.yml 为 supabase/postgres:17.6.1.136，与台账完全一致。

三、如何阅读版本历史：从台账中还原一次升级

以 2026 年上半年几次典型条目为例，展示如何从 versions.md 中提取信息：

2026-06-17：Postgres 15 → 17 的默认镜像切换

• supabase/postgres:17.6.1.136 (prev supabase/postgres:15.8.1.085)

这是主 Compose 文件中数据库镜像的跨大版本变更。配合 upgrades.json 中 0.6.0 条目可知，该升级被标记为 breaking: true 并带门禁脚本 utils/upgrade-pg17.sh，且明确要求“Postgres 17 不能直接启动在 Postgres 15 的旧数据目录上，需先备份数据库”。台账条目本身不携带这些语义，这正是它必须与 upgrades.json 和 CHANGELOG 配套使用的原因。

2026-06-03：一次典型的“批量小版本升级”

同一天 9 个镜像一起更新：studio 2026.06.03、gotrue v2.189.0、postgrest v14.12、realtime v2.102.3、storage-api v1.60.4、postgres-meta v0.96.6、edge-runtime v1.74.0、supavisor 2.9.5、logflare 1.43.1。这类条目没有破坏性语义，update.sh 的三向合并会自动处理对应 compose 文件变更。

2026-03-16：网关镜像的命名空间变更

• kong/kong:3.9.1 (prev kong:2.8.1)

注意“prev”里的镜像名是 kong:2.8.1——上游镜像仓库命名从 kong 变为 kong/kong。回滚时要连镜像名一起还原，不能只改标签。

四、回滚实操：以 versions.md 为锚点固定旧镜像

versions.md 的核心用途是回滚参考。回滚一个镜像标签的操作路径是：

1. 在 versions.md 中按日期找到目标版本，取该条目中该镜像的“新标签”（即你想回到的版本）；
2. 修改对应 compose 文件（docker-compose.yml 或相应 override）中的 image: 标签；
3. 拉取并重建容器。仓库的 run.sh 提供了封装命令：sh run.sh pull（对应 docker compose pull）和 sh run.sh recreate [service]（对应 docker compose up -d --wait --force-recreate --no-deps，可只重建单个服务）；
4. 只回滚个别服务时，优先用 sh run.sh recreate <service> 精确重建，避免全栈重启。

回滚时还需注意边界：

• 镜像标签回滚不等于数据回滚。镜像只决定运行时行为，Postgres 数据目录（volumes/db/data）的版本状态独立存在；跨大版本回滚（如 Postgres 17 回到 15）涉及数据目录兼容问题，upgrades.json 的 0.6.0 条目明确建议先备份、必要时用 docker-compose.pg15.yml override 延迟升级。
• 跨网关时代的回滚要注意服务名。0.8.0 起 kong 服务已更名为 api-gw，kong 网络别名仍保留解析；若你要回滚到 Envoy 之前的版本，需同时还原 compose 文件结构，而不是只改一个标签。

五、versions.md 在更新流水线中的位置

从 update.sh 的源码结构看，versions.md 处于自托管更新链路的“查询层”，而真正的更新由脚本完成：

• 基线版本定位：当部署目录缺少 .supabase-version 戳文件时，update.sh 会提示用户“对照 versions.md 中 docker-compose.yml / .env 里的镜像标签，或回忆最后一次拉取时的 CHANGELOG.md 章节”来确定基线版本（见 update.sh#L266-L267）。也就是说，versions.md 是把“我部署目录里的镜像标签”映射回“上游某个 release ref”的人工索引。
• 三向合并只改 compose 与配置，不改数据：update.sh 对每个 vendor 文件做 base/target/user 三向 git merge-file 合并，.env 只做缺失键的追加（update.sh#L406-L537）。镜像标签的常规变更就是走这条合并路径落入你的 docker-compose.yml。
• 破坏性门禁独立于台账：升级窗口内若命中 upgrades.json 中 breaking: true 或带 gate 脚本的条目，update.sh 会在任何写盘之前交互式确认（confirm_gate），中止则部署原样保留。测试用例 tests/test-upgrades-manifest.sh 专门校验该清单的 JSON 合法性、键格式与字段拼写——注释指出拼错字段名（如 breakng）会让门禁“静默失效”，因此被拒绝。
• 脚本自身版本戳：干净完成后 update.sh 会把目标 ref 写入 .supabase-version；出现冲突时戳文件不前进，提示下次干净运行时再更新。

一条完整的升级链路因此是：sh update.sh --dry-run 预演 → 结合 upgrades.json 门禁与 versions.md 确认镜像变更范围 → sh update.sh 应用合并 → sh run.sh pull 拉取新镜像 → sh run.sh recreate 重建容器 → 按 CHANGELOG 验证行为。

六、维护视角：新增一条 versions.md 记录的约定

从现有 40+ 个日期条目的写法可以归纳出本文件的维护规范：

• 标题固定为 # Docker image version updates in docker-compose.yml，条目按日期倒序追加在最上方；
• 每条必须包含 prev 旧标签，保证任意相邻两个日期之间都能无歧义地还原升级前状态；
• 记录粒度是“镜像:标签”，镜像名变更（如 kong:2.8.1 → kong/kong:3.9.1）也要完整写出两侧全名；
• 纯配置变更（不涉及镜像标签）不进本文件，而进 CHANGELOG.md；需要人工干预的版本进 upgrades.json。

七、小结

versions.md 是 Supabase 自托管体系中镜像层的唯一权威台账：它用最简洁的“新标签 (prev 旧标签)”格式，把 studio、gotrue、postgrest、realtime、storage-api、postgres-meta、edge-runtime、supavisor、logflare、imgproxy、vector、Postgres、Kong/Envoy 网关等全部镜像的版本轨迹按日期留痕。对运维者而言，它是回滚时的标签字典；对升级流程而言，它是 update.sh 在缺少版本戳时定位基线的对照索引；对仓库维护者而言，它是与 CHANGELOG.md、upgrades.json 分工明确的三层变更记录体系中的镜像层。掌握这份文件，就掌握了自托管 Supabase 镜像版本管理的全部入口。