Supabase 自托管 Docker 镜像版本管理读懂 docker/versions.md 并完成镜像回滚【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase本文以 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-a6a04f2kong/kong:3.9.3前版 kong/kong:3.9.1将该条目与 docker-compose.yml 中当前实际声明的image:标签逐一对账主 Compose 文件中的镜像标签如下均已在源码中核实服务container_name当前镜像标签文件行号supabase-studiosupabase/studio:2026.08.03-sha-022b374docker-compose.yml#L17supabase-envoy默认 API 网关envoyproxy/envoy:v1.39.0docker-compose.yml#L72supabase-authGoTruesupabase/gotrue:v2.189.0docker-compose.yml#L111supabase-restPostgRESTpostgrest/postgrest:v14.12docker-compose.yml#L251supabase-realtimesupabase/realtime:v2.102.3docker-compose.yml#L288supabase-storagesupabase/storage-api:v1.60.4docker-compose.yml#L334supabase-imgproxydarthsim/imgproxy:v3.30.1docker-compose.yml#L397supabase-metapostgres-metasupabase/postgres-meta:v0.96.6docker-compose.yml#L420supabase-edge-functionssupabase/edge-runtime:v1.74.0docker-compose.yml#L437supabase-dbsupabase/postgres:17.6.1.136docker-compose.yml#L479supabase-supavisor连接池supabase/supavisor:2.9.5docker-compose.yml#L534需要注意的几点事实均可在仓库中核实API 网关已从 Kong 切换为 Envoy。自 0.8.0 版本起默认网关是 docker-compose.yml 中的envoyproxy/envoy:v1.39.0container_name 为supabase-envoyKong 保留为可选 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 文件。日志栈独立于主 Compose。supabase/logflare:1.43.1与timberio/vector:0.53.0-alpine位于 docker-compose.logs.ymlversions.md 中对 logflare、vector 的记录对应的是这份 override 文件而非主文件。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.085docker-compose.pg17.yml 为supabase/postgres:17.6.1.136与台账完全一致。三、如何阅读版本历史从台账中还原一次升级以 2026 年上半年几次典型条目为例展示如何从 versions.md 中提取信息2026-06-17Postgres 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 的核心用途是回滚参考。回滚一个镜像标签的操作路径是在 versions.md 中按日期找到目标版本取该条目中该镜像的“新标签”即你想回到的版本修改对应 compose 文件docker-compose.yml 或相应 override中的image:标签拉取并重建容器。仓库的 run.sh 提供了封装命令sh run.sh pull对应docker compose pull和sh run.sh recreate [service]对应docker compose up -d --wait --force-recreate --no-deps可只重建单个服务只回滚个别服务时优先用sh run.sh recreate service精确重建避免全栈重启。回滚时还需注意边界镜像标签回滚不等于数据回滚。镜像只决定运行时行为Postgres 数据目录volumes/db/data的版本状态独立存在跨大版本回滚如 Postgres 17 回到 15涉及数据目录兼容问题upgrades.json 的0.6.0条目明确建议先备份、必要时用docker-compose.pg15.ymloverride 延迟升级。跨网关时代的回滚要注意服务名。0.8.0 起kong服务已更名为api-gwkong网络别名仍保留解析若你要回滚到 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 镜像版本管理的全部入口。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考