自托管 Supabase 0.6.0 → 0.8.0：Envoy 顶掉 Kong，以及同一季度的三个破坏性变更

七周里的三个破坏性变更

如果跟的是 master，下面这些都不是可选项：

0.8.0（2026-08-11）：Envoy 成为默认网关，Kong 转为 opt-in

2026 年 8 月 9 日那一周，自托管 Supabase 的默认 API 网关由 Kong 换成 Envoy。Envoy 在此之前已经作为可选覆盖 docker-compose.envoy.yml 存在若干版本，现在进入默认 docker-compose.yml，Kong 变成可选覆盖。

• docker-compose.yml 里的网关服务改名为 api-gw，容器名 supabase-envoy；为兼容保留 kong 网络别名。
• Kong 改为 opt-in：新增 docker-compose.kong.yml，启用命令：

sh run.sh config add kong

• 网关 HTTP 端口改用 API_GW_HTTP_PORT（回退到已有的 KONG_HTTP_PORT，再回退 8000），老 .env 仍可用。
• 默认网关只监听明文 HTTP（8000）；Kong 的 8443 内置 HTTPS 监听不在 Envoy 默认里。TLS 用随附的 docker-compose.caddy.yml 或 docker-compose.nginx.yml 覆盖文件终止，或者退回 Kong。
• docker-compose.envoy.yml 在一个发布周期内变成 no-op 空操作垫片，之后移除。
• OSS Kong 已停止前进：OSS 版本只有安全/nginx 回移，3.10 起移除免费（未授权）功能；建议只当过渡用。
• Caddy/nginx 反代配置同步更新为转发到 api-gw，涉及 docker-compose.caddy.yml、docker-compose.nginx.yml、volumes/proxy/caddy/Caddyfile、volumes/proxy/nginx/supabase-nginx.conf.tpl；tests 也做了适配。

.env 里可以这样写：

API_GW_HTTP_PORT=8000

谁受影响

同时满足「从 ./docker 目录跑自托管」「从 master 拉更新」，并且符合以下任一条：

• 依赖 Kong 内置 :8443 HTTPS 监听（前面没有反向代理）。Envoy 默认不暴露 8443，需要前置 Caddy/Nginx 或退回 Kong。
• 维护自定义 kong.yml（自定义路由、插件、ACL）。这些不会迁移到 Envoy，会静默失效。要保留就退回 Kong，或把定制移植到 volumes/api/envoy/ 下的 Envoy 配置。
• 脚本/工具按服务名/容器名引用网关（kong / supabase-kong），例如 docker compose logs kong、run.sh restart kong。服务现在叫 api-gw，容器叫 supabase-envoy；kong 主机名仍可解析（网络别名）。
• 正在用 Envoy 覆盖（COMPOSE_FILE 里有 docker-compose.envoy.yml）。行为不变，但拉更新后应从 COMPOSE_FILE 里移除该条目：

sh run.sh config remove envoy

• 若同时更新 docker-compose.yml 与 .env.example 且没有网关定制，无需操作，只是请求现在走 Envoy。

排查动作

# 找出所有 logs.all 调用者
grep -rn "logs\.all" .

# 找出 compose 文件与内部服务配置里的 kong / kong.yml / 8443
grep -rnE "kong|kong\.yml|8443" docker-compose*.yml volumes/ run.sh

# 确认实际跑的 supabase/postgres 镜像，而不是以为跑的那个
docker compose ps

网关想在 staging 先试 Envoy 覆盖的话，跑一遍 200/401 检查，再走一次路由表：catch-all 之前的自定义路由、TLS 在 Caddy/Nginx 终止、X-Forwarded-Prefix 到达 Storage、MCP 除非故意放行否则仍被拒。

迁移建议：自定义过 kong.yml → 退回 Kong（config add kong）或移植到 Envoy 配置；已在用 Envoy 覆盖 → 从 COMPOSE_FILE 移除 envoy；想缓一缓 → 固定 checkout 或加 Kong 覆盖，行为不变。这是默认变更，不是移除，但建议迁到 Envoy（OSS Kong 不再活跃维护）。

0.7.1（2026-08-03）与 0.7.2（2026-08-04）

• 为 Edge Functions 新增 SUPABASE_JWKS 配置；
• 新增 upgrades.json（版本键控、用于门控破坏性变更，update.sh 需要）；
• Kong 升到 3.9.3；新增 KONG_DNS_VALID_TTL；
• Envoy 升到 1.39.0；
• nginx-certbot 升到 6.2.0-nginx1.31.3。

0.7.0（2026-07-07，含破坏性变更）

• API_EXTERNAL_URL 默认加上 /auth/v1 前缀（如 http://localhost:8000/auth/v1），让自定义 OAuth provider 开箱可用，SAML 端点移到 /auth/v1/sso/saml/*。
• KONG_ROUTER_FLAVOR 加入 compose。
• .env.example 默认 API_EXTERNAL_URL 含 /auth/v1。
• PGRST_DB_SCHEMAS 默认改为 public,graphql_public，去掉 storage，避免该 schema 被暴露。
• Kong/Envoy 配置限制对 PostgREST /rest/v1/ 的访问、匹配新的 SAML SSO 路由。

API_EXTERNAL_URL=http://localhost:8000/auth/v1
PGRST_DB_SCHEMAS=public,graphql_public

0.6.0（2026-06-17）：Postgres 17 成为默认

• 不要在已有 Postgres 15 数据目录上启动 Postgres 17。
• API 网关配置含 Realtime 路由安全修复（阻止 /api/tenants、/api/openapi），强烈建议所有跑 Realtime 的自托管实例应用。
• 默认 Postgres 镜像改为 supabase/postgres:17.6.1.136。
• 新增 docker-compose.pg15.yml（未升级部署的保留项，也是 utils/upgrade-pg17.sh 的回滚目标）。
• Studio 与 postgres-meta 改用 postgres 角色（而非 supabase_admin）连 Postgres。
• 新建 PG17 实例 pg_graphql 默认关闭，需在 Studio 或 create extension pg_graphql; 启用；已有 GraphQL 的库升级后保留。

create extension pg_graphql;

2026-06-01：analytics 与 vector 移出默认 compose

analytics（Logflare）与 vector 从默认 docker-compose.yml 移除，迁到可选 overlay docker-compose.logs.yml（PR #45327）。默认 docker compose up -d 启动更精简的栈。

要用 Studio 的 Logs Explorer，需要带上 overlay：

docker compose -f docker-compose.yml -f docker-compose.logs.yml up -d

基础 compose 默认给 Studio 设 ENABLED_FEATURES_LOGS_ALL: false，不启 overlay 就不显示 Logs 菜单。也可以让 -f 隐式生效：

COMPOSE_FILE=docker-compose.yml:docker-compose.logs.yml

不用 Logs Explorer 就无动作；确认健康后可移除旧容器：

docker compose rm -f -s -v analytics vector

2026-09-23：logs.all 端点移除

logs.all Management API 端点移除，日志查询迁到 ClickHouse 后端的新 logs 端点，只接受 ClickHouse SQL。脚本、集成、看板里调用 analytics/endpoints/logs.all 的地方都要迁移。做法是把每个 logs.all 调用者迁到 ClickHouse 方言，新旧查询并行跑到 9-23。

升级：update.sh 与三方合并

拉最新镜像并重建：

docker compose pull && docker compose down && docker compose up -d

update.sh 在现有部署上做三方合并：base 是你当前版本，记录在 .supabase-version；new 是要升到的版本，默认最新 self-hosted/v* tag；yours 是你部署目录里的文件。它保留 secrets、覆盖文件与本地改动，冲突显式暴露。每次增量、有门控：保留 .env 和数据，备份配置，应用前停下提示破坏性变更。新装会自动记录版本。

• 有些发布需要手动前置步骤（例如 Postgres 大版本升级）。update.sh 从 release manifest（upgrades.json）读取，在任何文件改动前打印所需步骤并要求确认；没准备好就拒绝提示，此时什么都没改。
• 冲突未解决前不会推进 .supabase-version，只在干净运行时记录新版本；解决冲突标记后重跑 sh update.sh 完成版本戳。
• 没有 .supabase-version 时无法安全合并，只能有限报告模式（只列全新文件与全新 .env key），无法检测哪些已有文件会变或冲突。需要先补记版本再重跑。
• 长期部署常由多个上游时间点拼成，三方合并假设单一共同祖先，冲突数量大致与部署年龄成正比；首次追赶是一次的成本，成功后版本被记录，后续都是干净的、有门控的合并。
• 大部分冲突在「vendor 文件」（run.sh、setup.sh、tests/*、覆盖模板），直接取新版本即可；需要手工编辑的通常是你故意改过的 compose 配置。.env 永不冲突，update.sh 会追加新 key 供你单独审阅。
• 可以先预演：

sh update.sh --dry-run

单服务回滚示例：改 docker-compose.yml 里 Studio 的 image tag，然后：

sh run.sh pull && sh run.sh recreate studio

不动整个栈。

自托管常见的几个坑

JWT_SECRET 与 key 不匹配

网关每次请求校验签名，JWT_SECRET 与 ANON_KEY/SERVICE_ROLE_KEY 不匹配就返回：

{"message":"Invalid authentication credentials"}

最常见的是改了 JWT_SECRET 却留着示例 key。重新一起生成：

sh utils/generate-keys.sh --update-env

然后让服务读新值：

sh run.sh recreate

RLS

新表默认不开 RLS，拿到 anon key 就能整表读写；public schema 里未开 RLS 的表完全敞开。service_role key 绕过 RLS，只能放服务端，绝不能进浏览器包。Storage 桶有自己基于 storage.objects 的策略，公开桶无策略与表未开 RLS 一样暴露。审计：

SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname='public';

端口

默认 compose 绑定 0.0.0.0，Postgres/PostgREST/Kong 对全网可达。应改成 127.0.0.1:PORT:PORT，前面加 Nginx/Caddy 做 TLS，只暴露 80/443。

资源

整栈空闲约 2.5–3GB 常驻（约 14 个容器），2GB 机器会被 OOM 杀掉容器，症状是 exit code 137 反复重启。建议生产 8GB/4vCPU，单机开发 4GB 起步，磁盘 40GB 起。

环境变量不重读

docker compose restart 不重读 .env，改环境变量要：

docker compose up -d --force-recreate

Realtime 收不到变更

连接正常但收不到变更，需要 wal_level=logical 且 publication 覆盖该表：

select * from pg_publication_tables;
alter publication supabase_realtime add table your_table;

执行后重连。

备份

Postgres 数据在 ./volumes/db/data 绑定挂载，容器运行时直接拷目录是撕裂副本（只在 checkpoint 一致），恢复可能丢最后事务；用 pg_dump。

schema 暴露

PostgREST 默认只暴露 public schema，其他 schema 的表不会自动出现；开了 RLS 但没有任何 policy，anon/authenticated 查询返回空。

项目与文档地址

• Supabase 仓库：https://github.com/supabase/supabase
• 自托管 Docker 文档：https://supabase.com/docs/guides/self-hosting/docker
• 自托管更新文档：https://supabase.com/docs/guides/self-hosting/updating
• 自托管 changelog（Envoy 成为默认网关）：https://supabase.com/changelog/48048-self-hosted-supabase-envoy-becomes-the-default-api-gateway-breaking-change