Supabase 自托管 Docker 完全指南：Compose 栈、run.sh 运维与升级流程

本文基于 Supabase 官方仓库的 docker 目录 及其配套脚本，讲解如何用官方 Docker Compose 配置在本地或自有基础设施上部署一套完整的自托管 Supabase：包括栈中各服务的职责与版本、setup.sh / run.sh 的完整操作方式、COMPOSE_FILE 覆盖文件机制，以及基于 .supabase-version 戳文件的升级与安全加固清单。读完本文，你可以独立完成部署、切换网关/代理、拉取新镜像并安全升级实例。

自托管栈包含哪些服务

docker/docker-compose.yml 定义了完整的服务拓扑，name: supabase 作为 Compose 项目名。README 中列出的 13 个组件与实际 compose 文件的对应关系如下（镜像版本以 docker-compose.yml 当前固定值为准）：

服务	镜像（compose 固定版本）	职责
studio	supabase/studio:2026.08.03-sha-022b374	管理自托管项目的 Web 仪表盘
api-gw	envoyproxy/envoy:v1.39.0	默认 API 网关（可切换为 Kong 覆盖文件）
auth	supabase/gotrue:v2.189.0	基于 JWT 的认证 API：注册、登录、会话管理
rest	postgrest/postgrest:v14.12	将 Postgres 直接暴露为 RESTful API
realtime	supabase/realtime:v2.102.3	监听 Postgres 变更并通过 WebSocket 广播
storage	supabase/storage-api:v1.60.4	文件管理 REST API，Postgres 负责权限
imgproxy	darthsim/imgproxy:v3.30.1	图像缩放/格式转换服务
meta	supabase/postgres-meta:v0.96.6	Postgres 管理 API（查表、建角色、跑 SQL）
functions	supabase/edge-runtime:v1.74.0	基于 Deno 的 Edge Functions 运行时
db	supabase/postgres:17.6.1.136	核心数据库（默认 PG 17）
supavisor	supabase/supavisor:2.9.5	连接池（Supabase 官方 pooler）
Logflare + Vector	见 docker-compose.logs.yml	日志管理与事件分析，属可选覆盖文件

几个从源码结构中可以确认的设计细节：

• 网关双别名：api-gw 服务在 Compose 网络中同时挂了 envoy 和 kong 两个网络别名，内部各服务统一通过 SUPABASE_URL: http://api-gw:8000 访问网关，因此无论实际激活 Envoy 还是 Kong，内部配置都无需改动。
• 健康检查驱动启动顺序：例如 auth、rest、storage、meta 都声明 depends_on: db: condition: service_healthy，db 的健康检查是 pg_isready -U postgres（间隔 5s、重试 10 次）；functions 则依赖 api-gw 健康。整套栈通过 docker compose up -d --wait 等待所有服务进入健康状态。
• 数据库初始化脚本：db 服务把 docker/volumes/db 下的 SQL 文件挂载为初始化脚本，包括 _supabase.sql（97 号，内部 schema）、pooler.sql、realtime.sql、webhooks.sql、roles.sql、jwt.sql 等；PGDATA 落在 ./volumes/db/data 持久化，pgsodium 解密密钥则存放在 db-config 命名卷中。
• 存储后端可切换：storage 默认 STORAGE_BACKEND: file，文件落在 ./volumes/storage；要启用 S3 后端，可叠加 docker-compose.s3.yml 或 docker-compose.rustfs.yml 覆盖文件。

快速开始：setup.sh 引导部署

docker/setup.sh 是一条命令的引导脚本，面向 Debian/Ubuntu 与 RHEL/CentOS/Fedora 系 Linux 发行版。它依次完成：

1. 安装前置依赖：git、openssl、jq、ca-certificates；
2. 若缺失则安装 Docker Engine 与 Compose 插件（含 Amazon Linux 的特殊处理）；
3. 以 sparse-checkout 方式只克隆仓库的 docker/ 目录，默认取最新的 self-hosted/v* 发布标签，找不到标签时回退到默认分支 HEAD；
4. 在当前目录创建项目目录（默认 supabase-project），把 docker/* 复制进去，并把 .env.example 复制为 .env；
5. 交互式询问 SUPABASE_PUBLIC_URL、API_EXTERNAL_URL、SITE_URL、PROXY_DOMAIN 并写回 .env，同时推导 CERTBOT_EMAIL；
6. 调用密钥生成脚本（见下文）；
7. 把部署所基于的 git ref 记录到 .supabase-version 戳文件，供后续 update.sh 做三方合并升级；
8. 执行 docker compose pull 拉取镜像。

常用参数（摘自脚本头部注释）：

sh setup.sh                            # 交互模式
sh setup.sh -y                         # 接受默认值，非交互
sh setup.sh --project-dir my-supabase  # 指定项目目录名
sh setup.sh --skip-deps                # 跳过系统包安装
sh setup.sh --with-aws                 # 顺带安装 AWS CLI v2
sh setup.sh --ref self-hosted/v0.7.0   # 从指定 git ref 提取 docker/
sh setup.sh --head                     # 从默认分支 HEAD 提取（跳过标签检测）

脚本具备幂等性：如果当前目录同时存在 .env、docker-compose.yml 和 utils/，会认为已是部署好的项目并直接跳过引导。

密钥生成与 .env 配置

setup.sh 在写完 URL 后会依次执行两个密钥脚本：

• docker/utils/generate-keys.sh：生成 JWT_SECRET 等对称密钥以及 ANON_KEY / SERVICE_ROLE_KEY 等传统 API Key；
• docker/utils/add-new-auth-keys.sh：生成 EC 非对称密钥对（写入 JWT_KEYS / JWT_JWKS）和不透明新式密钥 SUPABASE_PUBLISHABLE_KEY / SUPABASE_SECRET_KEY。

两者都带 --update-env 参数，直接把结果写入 .env。完整的变量清单与默认值可以在 docker/.env.example 中查看，而每个环境变量在各服务代码中的解析位置、类型、默认值，则汇总在体量更大的 docker/CONFIG.md 参考文档里（覆盖 Studio、Auth、PostgREST、Realtime、Storage、Edge Functions、Logflare、Postgres、Supavisor 九个服务）。部署完成后可以用 sh run.sh secrets 一次性打印 POSTGRES_PASSWORD、DASHBOARD_PASSWORD、新旧 API Key 等关键值。

run.sh：日常运维命令面

docker/run.sh 是对 docker compose 的封装，也是 README 中升级命令所依赖的入口。它的全部命令如下：

命令	实际行为
sh run.sh start	docker compose up -d --wait
sh run.sh stop	docker compose down
sh run.sh restart [service]	重启整个栈或指定服务
sh run.sh restart --except <svc>...	重启除指定服务外的所有服务
sh run.sh recreate [service]	无参数时 down + up；带参数时对指定服务 --force-recreate --no-deps
sh run.sh recreate --except <svc>...	强制重建除指定外的所有服务
sh run.sh status	docker compose ps
sh run.sh logs [service]	docker compose logs -f，可跟单一服务
sh run.sh inspect <service>	对容器执行 docker inspect
sh run.sh printenv <service>	逐行打印容器实际生效的环境变量
sh run.sh pull	docker compose pull
sh run.sh config	显示当前生效的 COMPOSE_FILE 列表
sh run.sh config add <name>	向 .env 的 COMPOSE_FILE 追加覆盖文件
sh run.sh config remove <name>	从 COMPOSE_FILE 中移除覆盖文件
sh run.sh compose-config	打印完全解析后的 compose 配置
sh run.sh secrets	打印 .env 中的关键密码与 API Key

--except 参数由脚本中的 services_except() 函数实现：它先取 docker compose config --services 的全量服务列表，再用 grep -vFx 剔除指定名称，对未知服务名会打印警告，剔除后若为空则报错退出——这意味着你可以做“滚动重启除数据库外所有服务”这类细粒度操作，而不用手写服务清单。

COMPOSE_FILE 覆盖文件机制

run.sh 通过读写 .env 中的 COMPOSE_FILE 变量来叠加覆盖配置，格式是冒号分隔的文件列表，且 docker-compose.yml 恒为第一个（基础文件，不允许通过 config add 加入）。config add 接受短名（如 pg17）或完整文件名（docker-compose.pg17.yml），脚本的 normalize_override() 会自动补全，并对“文件不存在”“基础文件”等情形给出明确错误。

仓库中当前可用的覆盖文件包括：

• docker-compose.envoy.yml / docker-compose.kong.yml：网关切换（README 指出 Envoy 是默认网关，Kong 通过 sh run.sh config add kong 启用）；
• docker-compose.nginx.yml / docker-compose.caddy.yml：在栈前加 HTTPS 反向代理；
• docker-compose.logs.yml：启用 Logflare + Vector 日志栈；
• docker-compose.s3.yml / docker-compose.rustfs.yml：把 Storage 后端切到 S3 协议端点 / RustFS；
• docker-compose.pg15.yml / docker-compose.pg17.yml：切换 Postgres 大版本；
• docker-compose.pgbouncer.yml：用 pgbouncer 替代/补充连接池。

修改 COMPOSE_FILE 后需要 sh run.sh recreate（或 start）让新拓扑生效；排查配置问题可用 sh run.sh compose-config 查看变量插值后的完整 YAML。注意 docker-compose.yml 头部注释提到，嵌套变量插值（${A:-${B}}）需要 podman-compose 1.6.0 及以上，若用 Podman 需注意版本。

暴露的端口与访问入口

从 compose 的端口映射看，自托管栈对外主要暴露三类端口：

• API 网关：${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000，即 http://<host>:8000 下聚合了 Studio、Auth、REST、Realtime、Storage、Functions 等路由；
• Postgres：supavisor 映射 ${POSTGRES_PORT}:5432（会话模式池）与 ${POOLER_PROXY_PORT_TRANSACTION}:6543（事务模式池），客户端连接时默认 POSTGRES_PORT=5432、事务池 6543；
• 覆盖文件追加：启用 nginx/caddy 后由代理接管 80/443。

各服务在 Compose 网络内部的监听端口从环境变量可读出：studio 3000、auth 9999、rest 3000（管理端口 3001）、realtime 4000、storage 5000、imgproxy 5001、meta 8080、functions 9000、supavisor 4000（API/健康检查）。这些内部端口一般不需要对外暴露，SUPABASE_PUBLIC_URL（如 http://localhost:8000）是最终面向客户端的地址。

升级实例：update.sh 流程

README 给出的标准升级流程是：

sh update.sh --dry-run   # 可选：预览变更
sh update.sh
sh run.sh pull && sh run.sh recreate

其背后的机制可以从脚本注释中看出：docker/setup.sh 在部署时写入 .supabase-version（内容只有一行 ref=<当时的 git ref>），而 docker/update.sh 升级时会拉取该 ref 处的文件快照作为三方合并的基线——即“你当初部署的版本 / 本地当前文件 / 新版文件”三方对比，从而保留你对 compose 文件的手工修改并提示冲突。仓库还附带 docker/upgrades.json 升级清单（由 docker/tests/test-upgrades-manifest.sh 校验），用于描述跨版本升级时的注意事项。docker/versions.md 则记录完整镜像版本历史，便于回滚到指定版本；日常版本演进见 docker/CHANGELOG.md。

对于 Postgres 大版本升级，docker/utils/upgrade-pg17.sh 提供了 PG15 数据目录就地升级到 PG17 的脚本（对应 docker-compose.pg15.yml / docker-compose.pg17.yml 的版本切换），仓库的 docker/tests/test-pg17-upgrade.sh 对该流程做了自动化验证。

重置与仓库自带的自动化测试

• docker/reset.sh：一键重置整个栈（compose 文件头部注释也标注了 Reset everything: sh reset.sh），会清掉卷与容器数据，操作前务必备份 volumes/db/data 等持久化目录。
• docker/tests/ 目录包含仓库 CI 使用的端到端脚本：test-self-hosted.sh（完整自托管流程）、test-s3.sh / test-s3-backend.sh / test-rustfs 相关 compose（验证 S3 存储后端）、test-update.sh（验证升级脚本）、test-container-logs.sh、test-auth-keys.sh 等。这些脚本展示了官方验证部署是否健康的方式，可作为你自查部署的参照。

生产环境安全清单

README 明确指出：默认配置不能直接用于生产。上线前至少完成以下事项（对应仓库中可落地的位置）：

1. 更换所有默认密码与密钥：.env 中的 POSTGRES_PASSWORD、DASHBOARD_USERNAME/DASHBOARD_PASSWORD、JWT_SECRET、SECRET_KEY_BASE、VAULT_ENC_KEY、PG_META_CRYPTO_KEY 等，建议重新运行 docker/utils/generate-keys.sh 与 docker/utils/add-new-auth-keys.sh 重新生成；
2. 审查 CORS 与网络暴露面：确认 SUPABASE_PUBLIC_URL、SITE_URL、API_EXTERNAL_URL 指向真实域名，只暴露必要的端口；
3. 部署安全反向代理：叠加 docker-compose.nginx.yml 或 docker-compose.caddy.yml 提供 TLS 终结（PROXY_DOMAIN / CERTBOT_EMAIL 已在 .env 中预留）；
4. 调整网络与安全策略：如 Postgres ACL、DASHBOARD 登录保护等；
5. 建立备份流程：volumes/db/data 是唯一的状态源，update.sh 之前和定期备份都应覆盖它，升级文档同样以“先备份数据库”作为第一步。

延伸阅读

• docker/docker-compose.yml：完整服务定义、健康检查与启动依赖；
• docker/CONFIG.md：按服务分组的环境变量参考（类型、默认值、读取位置）；
• docker/versions.md 与 docker/CHANGELOG.md：镜像版本历史与变更日志，用于回滚与升级决策；
• docker/dev/docker-compose.dev.yml：本地开发模式叠加配置；
• docker/volumes/functions 与 docker/volumes/snippets：Edge Functions 与 Studio 代码片段的持久化目录，分别挂载进 functions 与 studio 容器。

掌握以上内容后，你就可以在自有基础设施上完成从部署、日常运维到版本升级的完整闭环，并通过 run.sh 与覆盖文件机制按需求裁剪网关、代理、存储后端和数据库版本。