Supabase 自托管 Docker 完全指南Compose 栈、run.sh 运维与升级流程【免费下载链接】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 目录 及其配套脚本讲解如何用官方 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 固定版本职责studiosupabase/studio:2026.08.03-sha-022b374管理自托管项目的 Web 仪表盘api-gwenvoyproxy/envoy:v1.39.0默认 API 网关可切换为 Kong 覆盖文件authsupabase/gotrue:v2.189.0基于 JWT 的认证 API注册、登录、会话管理restpostgrest/postgrest:v14.12将 Postgres 直接暴露为 RESTful APIrealtimesupabase/realtime:v2.102.3监听 Postgres 变更并通过 WebSocket 广播storagesupabase/storage-api:v1.60.4文件管理 REST APIPostgres 负责权限imgproxydarthsim/imgproxy:v3.30.1图像缩放/格式转换服务metasupabase/postgres-meta:v0.96.6Postgres 管理 API查表、建角色、跑 SQLfunctionssupabase/edge-runtime:v1.74.0基于 Deno 的 Edge Functions 运行时dbsupabase/postgres:17.6.1.136核心数据库默认 PG 17supavisorsupabase/supavisor:2.9.5连接池Supabase 官方 poolerLogflare 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_healthydb的健康检查是pg_isready -U postgres间隔 5s、重试 10 次functions则依赖api-gw健康。整套栈通过docker compose up -d --wait等待所有服务进入健康状态。数据库初始化脚本db服务把 docker/volumes/db 下的 SQL 文件挂载为初始化脚本包括_supabase.sql97 号内部 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 发行版。它依次完成安装前置依赖git、openssl、jq、ca-certificates若缺失则安装 Docker Engine 与 Compose 插件含 Amazon Linux 的特殊处理以 sparse-checkout 方式只克隆仓库的docker/目录默认取最新的self-hosted/v*发布标签找不到标签时回退到默认分支 HEAD在当前目录创建项目目录默认supabase-project把docker/*复制进去并把.env.example复制为.env交互式询问SUPABASE_PUBLIC_URL、API_EXTERNAL_URL、SITE_URL、PROXY_DOMAIN并写回.env同时推导CERTBOT_EMAIL调用密钥生成脚本见下文把部署所基于的 git ref 记录到.supabase-version戳文件供后续update.sh做三方合并升级执行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 Keydocker/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 startdocker compose up -d --waitsh run.sh stopdocker compose downsh run.sh restart [service]重启整个栈或指定服务sh run.sh restart --except svc...重启除指定服务外的所有服务sh run.sh recreate [service]无参数时 down up带参数时对指定服务--force-recreate --no-depssh run.sh recreate --except svc...强制重建除指定外的所有服务sh run.sh statusdocker compose pssh run.sh logs [service]docker compose logs -f可跟单一服务sh run.sh inspect service对容器执行docker inspectsh run.sh printenv service逐行打印容器实际生效的环境变量sh run.sh pulldocker compose pullsh 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 协议端点 / RustFSdocker-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 等路由Postgressupavisor映射${POSTGRES_PORT}:5432会话模式池与${POOLER_PROXY_PORT_TRANSACTION}:6543事务模式池客户端连接时默认POSTGRES_PORT5432、事务池6543覆盖文件追加启用 nginx/caddy 后由代理接管 80/443。各服务在 Compose 网络内部的监听端口从环境变量可读出studio3000、auth9999、rest3000管理端口 3001、realtime4000、storage5000、imgproxy5001、meta8080、functions9000、supavisor4000API/健康检查。这些内部端口一般不需要对外暴露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 明确指出默认配置不能直接用于生产。上线前至少完成以下事项对应仓库中可落地的位置更换所有默认密码与密钥.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 重新生成审查 CORS 与网络暴露面确认SUPABASE_PUBLIC_URL、SITE_URL、API_EXTERNAL_URL指向真实域名只暴露必要的端口部署安全反向代理叠加docker-compose.nginx.yml或docker-compose.caddy.yml提供 TLS 终结PROXY_DOMAIN/CERTBOT_EMAIL已在.env中预留调整网络与安全策略如 Postgres ACL、DASHBOARD登录保护等建立备份流程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/snippetsEdge Functions 与 Studio 代码片段的持久化目录分别挂载进functions与studio容器。掌握以上内容后你就可以在自有基础设施上完成从部署、日常运维到版本升级的完整闭环并通过run.sh与覆盖文件机制按需求裁剪网关、代理、存储后端和数据库版本。【免费下载链接】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），仅供参考