Supabase 自托管 Docker 部署版本演进指南：从 CHANGELOG 到安全升级的完整实践

2026-09-06 16:56:34作者：范靓好Udolf

Supabase 官方自托管 Docker 配置维护着一份按服务分组、以发布版本为单元的变更日志 docker/CHANGELOG.md，它记录了每一次镜像升级、配置变更与破坏性更新（breaking change）的细节。读完本文，你将掌握：如何正确解读这份日志中「requires [...] update」「⚠️」等标记的准确含义；0.5.0 至 0.8.0 每个版本的关键变更（API 网关从 Kong 切换到 Envoy、Postgres 17 成为默认、sb_ 新 API 密钥格式等）；以及如何结合 upgrades.json 破坏性变更门控与 update.sh 三方合并机制，安全地把现有自托管实例更新到最新版本。

一、这份 Changelog 的阅读规则：按服务分组，而非按变更类型

docker/CHANGELOG.md 的开篇定义了两个核心约定，直接决定了你升级前该看什么：

按服务（service）分组，而非按变更类型分组。 每个版本内部划分为 Configuration（配置）、Documentation（文档）、Utils and tests（脚本与测试）、API gateway（API 网关）、Studio、Auth、Realtime、Storage、PostgREST、Postgres Meta、Edge Runtime、Supavisor、Analytics (Logflare)、Vector、imgproxy 等小节。这与 docker/docker-compose.yml 中的服务划分一一对应，方便你只关注自己实际启用的服务。
只收录对自托管最重要的变更。 日志明确声明「仅收录与自托管 Supabase 最相关的变更」，完整变更需参照各服务自身的 release notes 与 changelog。

日志中还有一条贯穿全篇的操作语义，务必理解：

标记为 "requires [...] update" 的配置更新，已包含在仓库最新版本中。拉取最新代码后，执行 docker compose pull && docker compose down && docker compose up -d 即可让变更生效。

这句话的含义是：绝大多数「requires docker-compose.yml update」类变更，本质上是仓库内文件的变更（compose 文件、volumes/ 下的配置文件），你无需手写配置，只需同步仓库文件并重建容器。只有少数变更需要你主动执行脚本或手工决策（如 Postgres 15 到 17 的数据目录迁移），这类变更会以更醒目的 ⚠️ 提示并给出具体指引。

配套的两个文件构成完整的版本追踪体系：

docker/versions.md：记录 docker-compose.yml 中每个 Docker 镜像标签的完整版本历史（含 prev 上一版本），用于回滚参考。例如 2026-08-03 条目为 supabase/studio:2026.08.03-sha-022b374 (prev supabase/studio:2026.07.07-sha-a6a04f2)、kong/kong:3.9.3 (prev kong/kong:3.9.1)；
docker/CONFIG.md：所有环境变量配置项的完整参考清单（0.5.0 版本引入），日志中「Added a new reference list of all configuration environment variables」即指它。

二、0.8.0（2026-08-11）：Envoy 取代 Kong 成为默认 API 网关

这是当前最新的版本，也是日志中明确标注「contains breaking changes」的一次发布。核心变化：

Envoy 成为默认 API 网关，替代 Kong。 原 kong 服务被重命名为 api-gw；Kong 保留为可选覆盖（opt-in override），启用方式为 sh run.sh config add kong。
新增 API_GW_HTTP_PORT 配置变量，向后兼容回退到 KONG_HTTP_PORT，需要更新 .env 与 docker-compose.yml。
更新了多个自托管 how-to 指南，并更新了自托管架构图。
tests/ 目录下的测试用例同步适配了 Envoy 切换。
docker-compose.envoy.yml 从「启用 Envoy 的覆盖文件」变为空操作垫片（no-op shim）；新增可选的 docker-compose.kong.yml。
Caddy 与 nginx 反向代理配置更新为转发到 api-gw（涉及 docker-compose.caddy.yml、docker-compose.nginx.yml、volumes/proxy/caddy/Caddyfile、volumes/proxy/nginx/supabase-nginx.conf.tpl）。

从源码验证：切换是如何落地的

查看当前仓库的 docker/docker-compose.yml 可以印证日志描述。默认网关服务如下（约 L68-L96）：

  # Envoy is the default API gateway
  api-gw:
    container_name: supabase-envoy
    image: envoyproxy/envoy:v1.39.0
    restart: unless-stopped
    networks:
      default:
        # Expose `envoy` and `kong` as network aliases, so internal configs
        # that reference either hostname resolve to whichever gateway is active.
        aliases:
          - envoy
          - kong
    ...
    ports:
      - ${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp

两个设计细节值得注意：

网络别名双注册。 api-gw 容器同时注册了 envoy 和 kong 两个网络别名，内部服务引用哪个主机名都能解析到当前生效的网关——这是降低切换破坏性的关键手段。
嵌套变量回退。 ${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}} 实现了日志中「falls back to KONG_HTTP_PORT」的承诺：未设置新变量时自动沿用旧变量，最终兜底为 8000 端口。注意 docker-compose.yml 文件头部注释说明：这种嵌套变量插值要求 podman-compose >= 1.6.0。

docker/docker-compose.envoy.yml 现在只剩一个空声明，其文件头注释说明了处置方式：

# DEPRECATED: Envoy is now the default API gateway defined directly in
# docker-compose.yml, so this override is no longer needed and does nothing.
#
# This no-op shim is kept for one release cycle so existing COMPOSE_FILE
# entries referencing it do not break. Remove it from your configuration:
#
#   sh run.sh config remove envoy
#
# To run Kong instead of Envoy, use the Kong override:
#
#   sh run.sh config add kong
#
# This file will be removed in a future release.

services: {}

保留一个发布周期的空垫片，是为了让 .env 中已有 COMPOSE_FILE=...:docker-compose.envoy.yml 条目的用户不会直接报错——这是「破坏性变更也留迁移窗口」的典型做法。

而 docker/docker-compose.kong.yml 则展示了 Kong 覆盖的完整形态：它原地覆盖 api-gw 服务的 container_name、image（kong/kong:3.9.3）、healthcheck、端口（额外恢复 8443 HTTPS 监听）、volumes 与环境变量，并使用 compose 的 !override 标签替换而非合并对应字段：

services:
  api-gw:
    container_name: supabase-kong
    image: kong/kong:3.9.3
    ports: !override
      - ${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp
      - ${KONG_HTTPS_PORT:-8443}:8443/tcp
    environment: !override
      KONG_DATABASE: "off"
      KONG_ROUTER_FLAVOR: expressions
      KONG_DNS_VALID_TTL: 5
      ...

run.sh 提供 config add|remove <name> 子命令来管理 .env 中的 COMPOSE_FILE 列表（冒号分隔，基础文件 docker-compose.yml 永远隐式在首位），例如 sh run.sh config add kong 接受短名或完整文件名，脚本内部会自动归一化为 docker-compose.kong.yml。

三、0.7.2 与 0.7.1（2026-08）：update.sh 的自我修正与升级清单机制

0.7.2（2026-08-04）

修复 update.sh 在更新过程中覆盖自身的缺陷：新版本脚本现在暂存为 update.sh.new 供人工审阅，而不是直接替换正在运行的脚本；
update.sh 改为部分克隆（partial clone）只拉取 docker/ 目录，更新速度显著提升、流量更轻。

0.7.1（2026-08-03）

配置：docker-compose.yml 为 Edge Functions 新增 SUPABASE_JWKS 配置；新增 upgrades.json——一个以版本为键的清单文件，用于门控破坏性变更（update.sh 依赖它）；更新 .gitignore。
文档：新增「Custom Postgres Extensions」与「Update Your Self-Hosted Deployment」两份 how-to。
脚本与测试：setup.sh 增加基础版本戳（写入 .supabase-version，update.sh 依赖它）；正式引入 update.sh；utils/add-new-auth-keys.sh 增加 SUPABASE_JWKS；更新 tests/test-s3.sh 与 test-s3-backend.sh。
API 网关：Kong 升级至 3.9.3；新增 KONG_DNS_VALID_TTL 环境变量；Envoy 升级至 1.39.0；nginx-certbot 升级至 6.2.0-nginx1.31.3。
Studio：更新至 2026.08.03-sha-022b374，修复 Edge Functions URL 生成、Auth > Users 中 Logs 页签可见性等问题。
Storage：RustFS 镜像临时改为 1.0.0-beta.11（涉及 docker-compose.rustfs.yml）。
Edge Runtime：主 worker 的 JWKS 配置机制变更（涉及 docker-compose.yml 与 volumes/functions/main/index.ts）。

四、0.7.0（2026-07-07）：外部 URL 前缀与路由的两处破坏性变更

日志明确列出两个 ⚠️ 破坏性变更：

匿名（publishable）密钥无法再访问 /rest/v1/ 的 OpenAPI 规范。 使用 service role 或新 secret 密钥的请求不受影响，通过 /rest/v1/your_table 或任意客户端库的数据访问完全不受影响。
API_EXTERNAL_URL 默认值加入 /auth/v1 路径前缀（例如 http://localhost:8000/auth/v1），使自托管与平台、CLI 对齐，自定义 OAuth 提供方开箱即用，SAML SSO 端点随之迁移到 /auth/v1/sso/saml/*。

其余要点：

配置：为 Kong 新增 KONG_ROUTER_FLAVOR；.env.example 中 API_EXTERNAL_URL 默认值改为含 /auth/v1；PGRST_DB_SCHEMAS 默认值改为 public,graphql_public，避免暴露受保护的 storage schema。
脚本：setup.sh 适配新 API_EXTERNAL_URL；utils/generate-keys.sh 现在同时生成唯一的 REALTIME_DB_ENC_KEY；tests/test-self-hosted.sh、tests/test-auth-keys.sh 同步更新。
API 网关：Kong 与 Envoy 配置收紧对 PostgREST /rest/v1/ 的访问控制（涉及 docker-compose.yml、volumes/api/kong.yml、volumes/api/envoy）；两者同步适配 /auth/v1/sso 的 SAML 新路由。
Studio：更新至 2026.07.07-sha-a6a04f2；修复 SQL Editor 本地 Snippets 不显示、Data API 设置页暴露 schema 的 UI 反映错误、Data API 文档页类型生成器行为等问题。
Auth：配置占位符与 GOTRUE_JWT_ISSUER 均改为匹配新的 API_EXTERNAL_URL（需更新 docker-compose.yml）。
Realtime：新增 REALTIME_DB_ENC_KEY 配置变量，带回退默认值（需更新 docker-compose.yml）。

五、0.6.0（2026-06-17）：Postgres 17 成为默认 + Realtime 安全修复

日志标注本版本含破坏性变更，三条要点必须逐条阅读：

Postgres 17 成为默认。 严禁在已有 Postgres 15 的数据目录上直接启动 Postgres 17，需先备份数据库并走官方升级流程；
API 网关配置包含 Realtime 路由的安全修复，对任何运行 Realtime 的自托管实例强烈建议应用该更新；
Studio 与 Postgres Meta 改用 postgres 角色（而非 supabase_admin）连接 Postgres。

配置层面：默认 Postgres 镜像改为 supabase/postgres:17.6.1.136；新增 docker-compose.pg15.yml 作为尚未升级部署的保留选项，同时充当 utils/upgrade-pg17.sh 的回滚目标；docker-compose.pg17.yml 同步更新。

脚本与测试：utils/upgrade-pg17.sh 升级了 Postgres 镜像并追加迁移步骤，tests/test-pg17-upgrade.sh 增加 pg_cron 测试；tests/test-self-hosted.sh 增加 resumable upload 测试并调整 Realtime、GraphQL 测试；tests/test-auth-keys.sh 调整 Realtime 用例。

API 网关：阻塞 Realtime 的 /api/tenants 与 /api/openapi 端点——这是一个安全修复（涉及 volumes/api/kong.yml 与 volumes/api/envoy）；Kong 入口脚本改为使用 /bin/sh。

其他服务：Studio 与 Postgres Meta 改用 postgres 连接 Postgres；PostgREST（rest）新增 healthcheck；Edge Runtime（functions）新增 healthcheck；新装实例上 pg_graphql 默认禁用（已有数据库升级后保留）。

这一版本在 upgrades.json 中对应最完整的门控条目：

"0.6.0": {
  "breaking": true,
  "gate": "utils/upgrade-pg17.sh",
  "migration_guide_url": "https://supabase.com/docs/guides/self-hosting/postgres-upgrade-17",
  "requires": [
    "Postgres 17 is now the default. Do NOT start Postgres 17 against an existing Postgres 15 data directory - back up your database first.",
    "Run 'sudo bash utils/upgrade-pg17.sh' (needs bash + root) to migrate Postgres 15 -> 17, then recreate containers. To defer, pin Postgres 15 with the docker-compose.pg15.yml override.",
    "Includes a security fix for the API gateway (Realtime /api/tenants and /api/openapi routes) - strongly recommended for any instance running Realtime."
  ]
}

gate 字段指向的 utils/upgrade-pg17.sh 会由 update.sh 在跨越该版本时先于任何写入操作执行确认；如果不想立刻升级，可以用 docker-compose.pg15.yml 覆盖把 Postgres 钉在 15。

六、0.5.0（2026-06-03）：日志与分析变为可选，run.sh/setup.sh 登场

本版本引入两项「important changes」：

日志与分析（Logflare + Vector）从默认 docker-compose.yml 中移除，变为可选，由新的 docker-compose.logs.yml 覆盖文件提供；
.env.example 新增 COMPOSE_FILE 变量用于配置 compose 覆盖文件（run.sh 也使用它）。

其他要点：

脚本：新增 setup.sh 与 run.sh（快速启动 + compose 配置管理）；utils/add-new-auth-keys.sh 与 utils/rotate-new-api-keys.sh 移除对 OpenSSL 和 Node.js 的依赖；tests/test-container-logs.sh 在 kong/analytics/vector 未运行时跳过对应检查。
API 网关：Envoy 升级至 1.38.0，并修复 API key 校验的一处不一致。
Studio：更新至 2026.06.03-sha-0bca601；新增 ENABLED_FEATURES_LOGS_ALL、SUPABASE_PUBLISHABLE_KEY、SUPABASE_SECRET_KEY 配置项；healthcheck 增加 start_period 以改善慢主机冷启动可靠性；修复自托管环境下 connect 页连接串错误；新增最小项目设置实现。
Auth：升级至 v2.189.0，新增 GOTRUE_JWT_ISSUER 配置。
各服务版本：PostgREST v14.12、Realtime v2.102.3、Storage v1.60.4、Postgres Meta v0.96.6、Edge Runtime v1.74.0、Supavisor 2.9.5（新增 POSTGRES_HOST，涉及 volumes/pooler/pooler.exs）、Logflare 1.43.1。

这些镜像版本与 docker/versions.md 中 2026-06-03 条目完全对应（每个都带 prev 版本，便于回滚时精确回退）。

七、更早的重要发布节点速览

2026-04-27：Envoy 作为可选网关引入，Podman 兼容性

新增 docker-compose.envoy.yml 与 volumes/api/envoy——Envoy 由此版本以可选身份登场（后在 0.8.0 转正为默认）；
Studio healthcheck 与部分配置调整以改善 Podman 兼容；Studio 改为仅绑定所有 IPv4 接口；
新增 how-to：Studio 从 supabase_admin 切换到 postgres 角色；
新增 utils/reassign-owner.sh 用于更新数据库对象属主；utils/add-new-auth-keys.sh 现在会同时更新 docker-compose.yml；
Studio 升级至 2026.04.27-sha-5f60601，Security Advisor 新增 4 条 lint 规则（0026–0029）。

2026-04-08：Postgres 17 覆盖与升级脚本首次落地

新增自定义邮件模板、SAML SSO、Postgres 17 三份 how-to；
新增 utils/upgrade-pg17.sh 与 docker-compose.pg17.yml 覆盖；
Kong 配置新增 SAML SSO 路由（需更新 .env、docker-compose.yml、volumes/api/kong.yml）；
imgproxy 的 IMGPROXY_ENABLE_WEBP_DETECTION 环境变量更名为 IMGPROXY_AUTO_WEBP（需更新 .env 与 docker-compose.yml）；
镜像更新：PostgREST v14.8、Storage v1.48.26、Postgres Meta v0.96.3、Logflare 1.36.1。

2026-03-16：`sb_` 新 API 密钥格式与非对称认证

日志明确列出本版本涉及的文件：utils/add-new-auth-keys.sh、utils/rotate-new-api-keys.sh、docker-compose.yml、.env.example、docker-compose.s3.yml、docker-compose.rustfs.yml、volumes/api/kong.yml、volumes/api/kong-entrypoint.sh、docker-compose.caddy.yml、docker-compose.nginx.yml、volumes/functions/main/index.ts、volumes/proxy。

新增脚本与模板支持 sb_ API 密钥与新的非对称认证（ES256）；可选的 Caddy/nginx 反向代理配置（HTTPS）同批引入；
tests/ 目录首次落地，包含 100+ 测试用例——今天 docker/tests/ 下 test-self-hosted.sh、test-pg17-upgrade.sh 等测试脚本的历史起点；
Studio 升级至 2026.03.16-sha-5528817，Integrations 增加 Data API 页链接，Studio 配置新增 PGRST_DB_SCHEMAS、PGRST_DB_EXTRA_SEARCH_PATH、PGRST_DB_MAX_ROWS（这三项在当前 docker-compose.yml 的 studio 服务中可以看到，如 PGRST_DB_MAX_ROWS: ${PGRST_DB_MAX_ROWS:-1000}）；
Realtime 新增强制必填的 METRICS_JWT_SECRET；
Storage 新增 STORAGE_PUBLIC_URL 以简化代理配置；RustFS 作为可选 S3 后端引入；S3 后端 compose 配置改用命名卷；
Edge Runtime 新增 SUPABASE_PUBLISHABLE_KEYS、SUPABASE_SECRET_KEYS、SUPABASE_PUBLIC_URL，新增「hybrid」JWT 校验选项与可选限流器；Kong 升级至 3.9.1；PostgREST v14.6。

2026-02-18 / 2026-02-16：Storage S3 栈与安全修复

2026-02-18：MinIO 镜像换用 Chainguard 发行版；docker-compose.s3.yml 中移除冗余的 imgproxy 服务并调整 storage 服务条目顺序。
2026-02-16（含多项破坏性变更）：Studio 增加 Edge Functions 管理 UI；Storage 环境配置大改，新增默认通过 /storage/v1/s3 端点访问桶的配置，MinIO S3 后端配置重构；Logflare 默认禁用 0.0.0.0:4000 暴露以防止 /dashboard 被访问，Kong 路由默认不再包含 /analytics/v1（安全修复）；Vector 从 0.28.1 大版本跳升至 0.53.0-alpine，Postgres sink 改为绕过 Kong 直连，所有 sink 重试超时上调。
Edge Runtime 新增 deno-cache 命名卷避免重复下载依赖（2026-02-18 条目）。

2026 年初及 2025 年（2025-10 ~ 2026-01）

2026-01-27：Studio 增加 SQL snippets；Auth 修复安全问题；Realtime healthcheck 日志默认关闭以降低日志量；imgproxy 从 v3.8.0 升至 v3.30.1；Postgres 日志配置修复。
2025-12-18：新增 utils/generate-keys.sh（密钥生成）与 utils/db-passwd.sh；reset.sh 改为 POSIX 并增加检查；Studio 修复 React2Shell 相关安全问题。
2025-12-10：PostgREST 从 v13.x 主版本升级至 v14.x（日志提示如遇异常行为请反馈）；MCP 工具 get_anon_key 更名为 get_publishable_keys。
2025-12-08：Realtime 的 compose 布尔值改为字符串、healthcheck 调整，均为 Podman 兼容性。
2025-11 系列：Storage 修复大于 6MB 文件的 resumable upload；Realtime 修复 Studio 中日志不显示；Studio 修复非默认 Postgres 配置下连接失败、log drains 显示付费选项等问题。
2025-10 系列：MCP server 路由进入 Kong 配置并新增文档页；Studio 连接方式改为经 postgres-meta（影响非标准数据库端口配置）；Studio 增加 "local" remote MCP server。
2025-10-08：Postgres 镜像更新至 15.8.1.085，Supavisor 升至 2.7.0。

八、源码纵深：upgrades.json 与 update.sh 如何把日志变成可执行的升级流程

CHANGELOG 告诉人「发生了什么」，而 docker/upgrades.json + docker/update.sh 告诉机器「升级时必须做什么」。upgrades.json 文件内的 _schema 自描述说明了它的定位：

以自托管发布版本（如 "0.7.0"，对应 self-hosted/vX.Y.Z 标签与 CHANGELOG 的 ## [0.7.0] 标题）为键，手工维护、无生成步骤；
只为文件 diff 无法表达的变更建条目：数据迁移、须先运行的脚本、破坏性默认值。常规配置变更由 update.sh 的三方合并自动应用，不应列入；
字段含义：breaking（需用户显式确认）、gate（升级越过该版本前须先运行的脚本，如 utils/upgrade-pg17.sh）、migration_guide_url、requires（展示给用户的自由文本手工步骤）；
update.sh 按 sort -V 排序，只对落在 (你的版本, 目标版本] 区间内的条目生效。

从 update.sh 的头部注释可以看到完整流水线与关键设计决策：

#   resolve refs -> fetch base+target snapshots -> [report-only exit]
#   -> build manifest gate -> confirm_gate (before any writes)
#   -> backup → merge vendor files + .env keys -> summary → stamp

三方合并：部署目录中混有供应商文件（docker-compose.yml、覆盖文件、volumes/*、脚本、.env.example）与用户状态（.env、docker-compose.override.yml、volumes/db/data、volumes/storage 等）。脚本拉取新版本的供应商文件，相对起始版本做三方合并，本地修改得以保留，真正冲突会被显式暴露而非静默覆盖；
版本基线来自 .supabase-version（由 setup.sh 写入）；缺失时可用 --from <ref> 指定；
绝不触碰：你设置的 .env 值、docker-compose.override.yml、数据目录。.env 只做「从 .env.example 追加缺失键」，不做三方合并；
用户路径的识别依赖目标快照中的 .gitignore（git check-ignore --no-index 会应用否定规则，例如 volumes/functions/** 被忽略但 volumes/functions/main/index.ts 保留合并）；
CHANGELOG.md 本身从不被解析——update.sh 只把它作为给人看的指引。

对应命令（见 docker/README.md 的 Updates 一节）：

sh update.sh --dry-run   # 可选的预演，不写任何文件
sh update.sh
sh run.sh pull && sh run.sh recreate

run.sh 本身则是日常运维入口：start/stop/restart [service]（支持 --except）/recreate/status/logs [service]/inspect <service>/printenv <service>/pull/config/config add|remove <name>/compose-config/secrets。所有子命令都是对 docker compose 的薄封装，并共享 .env 中的 COMPOSE_FILE 覆盖层机制。

九、结合日志的自托管升级操作清单

把 CHANGELOG 的规则落到操作层面，一次完整的版本跟踪流程如下（以当前仓库状态为准）：

先读目标版本的 CHANGELOG 小节。 重点扫 ⚠️ 条目与版本级 Note。例如升到 0.8.0 前必须确认：你是否自定义过 volumes/api/kong.yml 或网关服务（若是，需 sh run.sh config add kong 保留 Kong，否则合并后切到 Envoy）；升到 0.7.0 前必须更新自定义 OAuth 回调 URL 与 SAML 配置（SAML 端点已迁至 /auth/v1/sso/saml/*），且确认没有依赖 anon key 访问 /rest/v1/ OpenAPI 的流程；升到 0.6.0 前必须先备份数据库，并准备好运行 sudo bash utils/upgrade-pg17.sh（或用 docker-compose.pg15.yml 暂缓）。
查 versions.md 确认镜像版本变化，需要回滚时按 prev 标签精确回退 compose 中的 image: 行。
执行 sh update.sh --dry-run 预演，再用 sh update.sh 正式应用（跨越 0.6.0 时会触发 upgrades.json 中 breaking: true 的确认与 gate 脚本）；完成后 sh run.sh pull && sh run.sh recreate。
验证。 docker/tests/ 提供现成用例：test-self-hosted.sh（含 resumable upload、Realtime、GraphQL 用例）、test-auth-keys.sh、test-pg17-upgrade.sh（PG17 迁移含 pg_cron 测试）、test-s3.sh / test-s3-backend.sh（S3 后端）、test-update.sh（更新流程本身）、test-upgrades-manifest.sh（upgrades.json 门控逻辑）、test-container-logs.sh。测试脚本的维护历史在 CHANGELOG 的「Utils and tests」小节中均有对应 PR 记录。

十、值得收藏的相关文件

文件	作用
docker/CHANGELOG.md	本文章节的主体：按服务分组、按版本组织的变更日志
docker/versions.md	全部 Docker 镜像标签的历史与 `prev` 版本，用于回滚
docker/upgrades.json	破坏性变更门控清单，`update.sh` 的机器可读依据
docker/update.sh	三方合并式原地更新脚本（partial clone、`--dry-run`、`--to`、`--from`）
docker/setup.sh / docker/run.sh	初始化（写 `.supabase-version`）与日常 compose 管理
docker/CONFIG.md	全部环境变量配置项参考
docker/docker-compose.yml	默认全栈：Studio、`api-gw`（Envoy）、Auth、PostgREST、Realtime、Storage、postgres-meta、Postgres、Edge Runtime、Supavisor 等
docker/docker-compose.envoy.yml / docker/docker-compose.kong.yml	Envoy 空操作垫片 / Kong 回退覆盖
docker/docker-compose.pg15.yml / docker/docker-compose.pg17.yml / docker/docker-compose.logs.yml / docker/docker-compose.s3.yml / docker/docker-compose.rustfs.yml / docker/docker-compose.pgbouncer.yml / docker/docker-compose.caddy.yml / docker/docker-compose.nginx.yml	各场景覆盖文件，经 `sh run.sh config add <name>` 叠加
docker/utils/upgrade-pg17.sh / docker/utils/generate-keys.sh / docker/utils/add-new-auth-keys.sh / docker/utils/rotate-new-api-keys.sh / docker/utils/reassign-owner.sh / docker/utils/db-passwd.sh	PG17 迁移、密钥生成/轮换/属主变更、密码重置
docker/tests/	自托管栈的 100+ 自动化测试用例
docker/reset.sh	重置整个栈（POSIX 兼容）

适用前提与限制：本文描述的行为以当前仓库快照（0.8.0，2026-08-11 之后的 master 状态）为准；CHANGELOG 中标注「requires [...] update」的条目含义是「该变更已包含在仓库最新文件中」，而非需要手工改配置；0.5.0 之前的版本在 CHANGELOG 中以日期为标题，0.7.1 起才采用语义化版本标签体系，历史版本对照时请以 versions.md 的日期条目为准。

supabase

The 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

登录后查看全文