尧图网站建设 
Supabase 自托管 Docker 部署版本演进指南从 CHANGELOG 到安全升级的完整实践【免费下载链接】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/supabaseSupabase 官方自托管 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 gatewayAPI 网关、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.02026-08-11Envoy 取代 Kong 成为默认 API 网关这是当前最新的版本也是日志中明确标注「contains breaking changes」的一次发布。核心变化Envoy 成为默认 API 网关替代 Kong。原kong服务被重命名为api-gwKong 保留为可选覆盖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 toKONG_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、imagekong/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.12026-08update.sh 的自我修正与升级清单机制0.7.22026-08-04修复update.sh在更新过程中覆盖自身的缺陷新版本脚本现在暂存为update.sh.new供人工审阅而不是直接替换正在运行的脚本update.sh改为部分克隆partial clone只拉取docker/目录更新速度显著提升、流量更轻。0.7.12026-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-versionupdate.sh依赖它正式引入update.shutils/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.0nginx-certbot 升级至6.2.0-nginx1.31.3。Studio更新至2026.08.03-sha-022b374修复 Edge Functions URL 生成、Auth Users 中 Logs 页签可见性等问题。StorageRustFS 镜像临时改为1.0.0-beta.11涉及 docker-compose.rustfs.yml。Edge Runtime主 worker 的 JWKS 配置机制变更涉及docker-compose.yml与volumes/functions/main/index.ts。四、0.7.02026-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/v1PGRST_DB_SCHEMAS默认值改为public,graphql_public避免暴露受保护的storageschema。脚本setup.sh适配新API_EXTERNAL_URLutils/generate-keys.sh现在同时生成唯一的REALTIME_DB_ENC_KEYtests/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.02026-06-17Postgres 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/envoyKong 入口脚本改为使用/bin/sh。其他服务Studio 与 Postgres Meta 改用postgres连接 PostgresPostgRESTrest新增 healthcheckEdge Runtimefunctions新增 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.02026-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配置。各服务版本PostgRESTv14.12、Realtimev2.102.3、Storagev1.60.4、Postgres Metav0.96.6、Edge Runtimev1.74.0、Supavisor2.9.5新增POSTGRES_HOST涉及volumes/pooler/pooler.exs、Logflare1.43.1。这些镜像版本与 docker/versions.md 中 2026-06-03 条目完全对应每个都带prev版本便于回滚时精确回退。七、更早的重要发布节点速览2026-04-27Envoy 作为可选网关引入Podman 兼容性新增 docker-compose.envoy.yml 与volumes/api/envoy——Envoy 由此版本以可选身份登场后在 0.8.0 转正为默认Studio healthcheck 与部分配置调整以改善 Podman 兼容Studio 改为仅绑定所有 IPv4 接口新增 how-toStudio 从supabase_admin切换到postgres角色新增 utils/reassign-owner.sh 用于更新数据库对象属主utils/add-new-auth-keys.sh现在会同时更新docker-compose.ymlStudio 升级至2026.04.27-sha-5f60601Security Advisor 新增 4 条 lint 规则0026–0029。2026-04-08Postgres 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.ymlimgproxy 的IMGPROXY_ENABLE_WEBP_DETECTION环境变量更名为IMGPROXY_AUTO_WEBP需更新.env与docker-compose.yml镜像更新PostgRESTv14.8、Storagev1.48.26、Postgres Metav0.96.3、Logflare1.36.1。2026-03-16sb_新 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-5528817Integrations 增加 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_SECRETStorage 新增STORAGE_PUBLIC_URL以简化代理配置RustFS 作为可选 S3 后端引入S3 后端 compose 配置改用命名卷Edge Runtime 新增SUPABASE_PUBLISHABLE_KEYS、SUPABASE_SECRET_KEYS、SUPABASE_PUBLIC_URL新增「hybrid」JWT 校验选项与可选限流器Kong 升级至3.9.1PostgRESTv14.6。2026-02-18 / 2026-02-16Storage S3 栈与安全修复2026-02-18MinIO 镜像换用 Chainguard 发行版docker-compose.s3.yml中移除冗余的imgproxy服务并调整 storage 服务条目顺序。2026-02-16含多项破坏性变更Studio 增加 Edge Functions 管理 UIStorage 环境配置大改新增默认通过/storage/v1/s3端点访问桶的配置MinIO S3 后端配置重构Logflare 默认禁用0.0.0.0:4000暴露以防止/dashboard被访问Kong 路由默认不再包含/analytics/v1安全修复Vector 从0.28.1大版本跳升至0.53.0-alpinePostgres sink 改为绕过 Kong 直连所有 sink 重试超时上调。Edge Runtime 新增deno-cache命名卷避免重复下载依赖2026-02-18 条目。2026 年初及 2025 年2025-10 ~ 2026-012026-01-27Studio 增加 SQL snippetsAuth 修复安全问题Realtime healthcheck 日志默认关闭以降低日志量imgproxy 从v3.8.0升至v3.30.1Postgres 日志配置修复。2025-12-18新增utils/generate-keys.sh密钥生成与utils/db-passwd.shreset.sh改为 POSIX 并增加检查Studio 修复 React2Shell 相关安全问题。2025-12-10PostgREST 从 v13.x 主版本升级至 v14.x日志提示如遇异常行为请反馈MCP 工具get_anon_key更名为get_publishable_keys。2025-12-08Realtime 的 compose 布尔值改为字符串、healthcheck 调整均为 Podman 兼容性。2025-11 系列Storage 修复大于 6MB 文件的 resumable uploadRealtime 修复 Studio 中日志不显示Studio 修复非默认 Postgres 配置下连接失败、log drains 显示付费选项等问题。2025-10 系列MCP server 路由进入 Kong 配置并新增文档页Studio 连接方式改为经postgres-meta影响非标准数据库端口配置Studio 增加 local remote MCP server。2025-10-08Postgres 镜像更新至15.8.1.085Supavisor 升至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 basetarget 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追加缺失键」不做三方合并用户路径的识别依赖目标快照中的.gitignoregit 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 recreaterun.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.shPG17 迁移含 pg_cron 测试、test-s3.sh/test-s3-backend.shS3 后端、test-update.sh更新流程本身、test-upgrades-manifest.shupgrades.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、--fromdocker/setup.sh / docker/run.sh初始化写.supabase-version与日常 compose 管理docker/CONFIG.md全部环境变量配置项参考docker/docker-compose.yml默认全栈Studio、api-gwEnvoy、Auth、PostgREST、Realtime、Storage、postgres-meta、Postgres、Edge Runtime、Supavisor 等docker/docker-compose.envoy.yml / docker/docker-compose.kong.ymlEnvoy 空操作垫片 / 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.shPG17 迁移、密钥生成/轮换/属主变更、密码重置docker/tests/自托管栈的 100 自动化测试用例docker/reset.sh重置整个栈POSIX 兼容适用前提与限制本文描述的行为以当前仓库快照0.8.02026-08-11 之后的 master 状态为准CHANGELOG 中标注「requires [...] update」的条目含义是「该变更已包含在仓库最新文件中」而非需要手工改配置0.5.0 之前的版本在 CHANGELOG 中以日期为标题0.7.1 起才采用语义化版本标签体系历史版本对照时请以 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Supabase 自托管 Docker 部署版本演进指南：从 CHANGELOG 到安全升级的完整实践
Supabase 自托管 Docker 部署版本演进指南从 CHANGELOG 到安全升级的完整实践【免费下载链接】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/supabaseSupabase 官方自托管 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 gatewayAPI 网关、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.02026-08-11Envoy 取代 Kong 成为默认 API 网关这是当前最新的版本也是日志中明确标注「contains breaking changes」的一次发布。核心变化Envoy 成为默认 API 网关替代 Kong。原kong服务被重命名为api-gwKong 保留为可选覆盖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 toKONG_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、imagekong/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.12026-08update.sh 的自我修正与升级清单机制0.7.22026-08-04修复update.sh在更新过程中覆盖自身的缺陷新版本脚本现在暂存为update.sh.new供人工审阅而不是直接替换正在运行的脚本update.sh改为部分克隆partial clone只拉取docker/目录更新速度显著提升、流量更轻。0.7.12026-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-versionupdate.sh依赖它正式引入update.shutils/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.0nginx-certbot 升级至6.2.0-nginx1.31.3。Studio更新至2026.08.03-sha-022b374修复 Edge Functions URL 生成、Auth Users 中 Logs 页签可见性等问题。StorageRustFS 镜像临时改为1.0.0-beta.11涉及 docker-compose.rustfs.yml。Edge Runtime主 worker 的 JWKS 配置机制变更涉及docker-compose.yml与volumes/functions/main/index.ts。四、0.7.02026-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/v1PGRST_DB_SCHEMAS默认值改为public,graphql_public避免暴露受保护的storageschema。脚本setup.sh适配新API_EXTERNAL_URLutils/generate-keys.sh现在同时生成唯一的REALTIME_DB_ENC_KEYtests/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.02026-06-17Postgres 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/envoyKong 入口脚本改为使用/bin/sh。其他服务Studio 与 Postgres Meta 改用postgres连接 PostgresPostgRESTrest新增 healthcheckEdge Runtimefunctions新增 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.02026-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配置。各服务版本PostgRESTv14.12、Realtimev2.102.3、Storagev1.60.4、Postgres Metav0.96.6、Edge Runtimev1.74.0、Supavisor2.9.5新增POSTGRES_HOST涉及volumes/pooler/pooler.exs、Logflare1.43.1。这些镜像版本与 docker/versions.md 中 2026-06-03 条目完全对应每个都带prev版本便于回滚时精确回退。七、更早的重要发布节点速览2026-04-27Envoy 作为可选网关引入Podman 兼容性新增 docker-compose.envoy.yml 与volumes/api/envoy——Envoy 由此版本以可选身份登场后在 0.8.0 转正为默认Studio healthcheck 与部分配置调整以改善 Podman 兼容Studio 改为仅绑定所有 IPv4 接口新增 how-toStudio 从supabase_admin切换到postgres角色新增 utils/reassign-owner.sh 用于更新数据库对象属主utils/add-new-auth-keys.sh现在会同时更新docker-compose.ymlStudio 升级至2026.04.27-sha-5f60601Security Advisor 新增 4 条 lint 规则0026–0029。2026-04-08Postgres 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.ymlimgproxy 的IMGPROXY_ENABLE_WEBP_DETECTION环境变量更名为IMGPROXY_AUTO_WEBP需更新.env与docker-compose.yml镜像更新PostgRESTv14.8、Storagev1.48.26、Postgres Metav0.96.3、Logflare1.36.1。2026-03-16sb_新 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-5528817Integrations 增加 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_SECRETStorage 新增STORAGE_PUBLIC_URL以简化代理配置RustFS 作为可选 S3 后端引入S3 后端 compose 配置改用命名卷Edge Runtime 新增SUPABASE_PUBLISHABLE_KEYS、SUPABASE_SECRET_KEYS、SUPABASE_PUBLIC_URL新增「hybrid」JWT 校验选项与可选限流器Kong 升级至3.9.1PostgRESTv14.6。2026-02-18 / 2026-02-16Storage S3 栈与安全修复2026-02-18MinIO 镜像换用 Chainguard 发行版docker-compose.s3.yml中移除冗余的imgproxy服务并调整 storage 服务条目顺序。2026-02-16含多项破坏性变更Studio 增加 Edge Functions 管理 UIStorage 环境配置大改新增默认通过/storage/v1/s3端点访问桶的配置MinIO S3 后端配置重构Logflare 默认禁用0.0.0.0:4000暴露以防止/dashboard被访问Kong 路由默认不再包含/analytics/v1安全修复Vector 从0.28.1大版本跳升至0.53.0-alpinePostgres sink 改为绕过 Kong 直连所有 sink 重试超时上调。Edge Runtime 新增deno-cache命名卷避免重复下载依赖2026-02-18 条目。2026 年初及 2025 年2025-10 ~ 2026-012026-01-27Studio 增加 SQL snippetsAuth 修复安全问题Realtime healthcheck 日志默认关闭以降低日志量imgproxy 从v3.8.0升至v3.30.1Postgres 日志配置修复。2025-12-18新增utils/generate-keys.sh密钥生成与utils/db-passwd.shreset.sh改为 POSIX 并增加检查Studio 修复 React2Shell 相关安全问题。2025-12-10PostgREST 从 v13.x 主版本升级至 v14.x日志提示如遇异常行为请反馈MCP 工具get_anon_key更名为get_publishable_keys。2025-12-08Realtime 的 compose 布尔值改为字符串、healthcheck 调整均为 Podman 兼容性。2025-11 系列Storage 修复大于 6MB 文件的 resumable uploadRealtime 修复 Studio 中日志不显示Studio 修复非默认 Postgres 配置下连接失败、log drains 显示付费选项等问题。2025-10 系列MCP server 路由进入 Kong 配置并新增文档页Studio 连接方式改为经postgres-meta影响非标准数据库端口配置Studio 增加 local remote MCP server。2025-10-08Postgres 镜像更新至15.8.1.085Supavisor 升至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 basetarget 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追加缺失键」不做三方合并用户路径的识别依赖目标快照中的.gitignoregit 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 recreaterun.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.shPG17 迁移含 pg_cron 测试、test-s3.sh/test-s3-backend.shS3 后端、test-update.sh更新流程本身、test-upgrades-manifest.shupgrades.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、--fromdocker/setup.sh / docker/run.sh初始化写.supabase-version与日常 compose 管理docker/CONFIG.md全部环境变量配置项参考docker/docker-compose.yml默认全栈Studio、api-gwEnvoy、Auth、PostgREST、Realtime、Storage、postgres-meta、Postgres、Edge Runtime、Supavisor 等docker/docker-compose.envoy.yml / docker/docker-compose.kong.ymlEnvoy 空操作垫片 / 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.shPG17 迁移、密钥生成/轮换/属主变更、密码重置docker/tests/自托管栈的 100 自动化测试用例docker/reset.sh重置整个栈POSIX 兼容适用前提与限制本文描述的行为以当前仓库快照0.8.02026-08-11 之后的 master 状态为准CHANGELOG 中标注「requires [...] update」的条目含义是「该变更已包含在仓库最新文件中」而非需要手工改配置0.5.0 之前的版本在 CHANGELOG 中以日期为标题0.7.1 起才采用语义化版本标签体系历史版本对照时请以 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考