Supabase Self-Hosting with Docker 学习笔记

来源：https://supabase.com/docs/guides/self-hosting/docker

阅读时间：2026-04-10

目标：把 Supabase 官方 Docker 自托管文档整理成一份可直接执行的中文笔记。

1. 这篇文档讲了什么

Supabase 官方提供了一套基于 Docker Compose 的自托管方案，用来在自己的服务器或本地机器上部署一整套 Supabase 服务。它不是只启动一个 Postgres，而是把 Supabase 常见组件一起拉起来，包括：

• Studio：管理后台
• Kong：API Gateway
• Auth：认证服务
• PostgREST：REST API
• Realtime：实时订阅
• Storage：对象存储接口
• Edge Functions：函数运行时
• pg_meta / pg_graphql / Supavisor / Analytics 等配套服务

官方文档的核心思路是：

1. 从 supabase/supabase 仓库复制 docker/ 下的部署文件。
2. 基于 .env.example 生成自己的 .env。
3. 在第一次启动前，把默认密码和密钥全部改掉。
4. 用 docker compose up -d 启动整套服务。
5. 通过 :8000 访问 Studio 和各类 API。

2. 适用场景

这套方案适合：

• 本地开发环境
• 单机测试环境
• 小到中等规模的生产部署
• 希望掌控数据库、鉴权、存储和 API 的自建平台

官方给出的最低资源要求：

资源	最低	推荐
RAM	4 GB	8 GB+
CPU	2 cores	4 cores+
Disk	50 GB SSD	80 GB+ SSD

如果你不需要 Analytics、Realtime、Storage、imgproxy、Functions 等组件，可以精简 docker-compose.yml 来降低资源占用。

3. 标准安装流程

官方文档里的标准流程如下：

git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pull

然后再进入配置环节。

我的理解

• supabase/ 仓库只是模板来源。
• 真正运行的是你自己创建的 supabase-project/ 目录。
• 这样做的好处是你可以独立维护自己的 .env 和 docker-compose.yml。

4. 第一次启动前必须做的事

这是官方文档里最重要的一部分：不要直接使用 .env.example 里的默认值启动。

官方明确强调：

• 示例里的密码和密钥只是占位符
• 第一次启动前必须替换
• 生产环境更应该把这些密钥接入专门的 secrets manager

4.1 快速生成密钥

官方提供了一个实验性脚本：

sh ./utils/generate-keys.sh

这个脚本会尝试一次性生成并写入密钥，但官方也提醒你：

• 运行后仍然要人工复查输出
• 还要再次检查 .env

所以更稳妥的做法是：把它当作初稿生成器，而不是"运行完就安全了"。

4.2 数据库密码

第一次启动前要修改：

POSTGRES_PASSWORD=

这个密码用于：

• postgres
• supabase_admin

官方建议密码足够强，同时尽量使用字母和数字，减少 URL 编码带来的连接串问题。

4.3 API 密钥

官方要求在 .env 中配置以下关键项：

• JWT_SECRET
• ANON_KEY
• SERVICE_ROLE_KEY

含义可以理解为：

变量	用途	风险级别
JWT_SECRET	给 JWT 签名和验签	极高
ANON_KEY	前端公开使用的匿名访问 key	中
SERVICE_ROLE_KEY	服务端高权限 key	极高

其中：

• ANON_KEY 可以出现在前端
• SERVICE_ROLE_KEY 绝不能暴露到客户端

4.4 存储相关密钥

文档还要求配置与 Storage / MinIO / S3 协议相关的密钥，例如：

• SECRET_KEY_BASE
• VAULT_ENC_KEY
• MINIO_ROOT_PASSWORD
• S3_PROTOCOL_ACCESS_KEY_ID
• S3_PROTOCOL_ACCESS_KEY_SECRET

这些密钥不只是"可选增强"，而是整套服务安全性的底层组成部分。

4.5 外部访问 URL

以下几个 URL 变量必须根据实际部署地址修改：

SUPABASE_PUBLIC_URL=
API_EXTERNAL_URL=
SITE_URL=

可理解为：

• SUPABASE_PUBLIC_URL：整个 Supabase 对外访问入口
• API_EXTERNAL_URL：Auth 服务对外看到的地址
• SITE_URL：认证回调默认跳转地址

如果只是本地运行，可以先用 localhost。

4.6 Studio 账号密码

Studio 默认走 HTTP Basic Auth，所以至少要配置：

DASHBOARD_USERNAME=
DASHBOARD_PASSWORD=

官方特别指出：

• 默认密码必须在首次启动前修改
• 密码必须至少包含一个字母
• 不要只用纯数字
• 不要用特殊字符

这条看起来有点反直觉，但它来自官方当前这套 Compose 配置的限制，实操时应按文档要求来。

5. 启动与停止

启动：

docker compose up -d

查看状态：

docker compose ps

如果容器没有进入 Up ... (healthy)，官方建议查看日志，例如：

docker compose logs analytics

停止：

docker compose down

Rootless Docker 注意项

如果你使用 rootless Docker，需要在 .env 中修改：

DOCKER_SOCKET_LOCATION=

例如设置为：

DOCKER_SOCKET_LOCATION=/run/user/1000/docker.sock

否则可能出现 supabase-vector exited (0) 一类问题。

6. 启动后怎么访问

6.1 Studio

Studio 通过 8000 端口访问，例如：

• http://localhost:8000
• http://<your-ip>:8000
• http://example.com:8000

首次访问会要求输入前面配置的：

• DASHBOARD_USERNAME
• DASHBOARD_PASSWORD

6.2 各类 API

官方给出的统一入口如下：

• REST: http://<your-domain>:8000/rest/v1/
• Auth: http://<your-domain>:8000/auth/v1/
• Storage: http://<your-domain>:8000/storage/v1/
• Realtime: http://<your-domain>:8000/realtime/v1/

这意味着对外只有一个主要网关入口，背后由 Kong 分发到不同组件。

6.3 PostgreSQL / Supavisor

默认推荐通过 Supavisor 连接数据库。

会话型连接：

psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres'

事务池连接：

psql 'postgres://postgres.[POOLER_TENANT_ID]:[POSTGRES_PASSWORD]@[your-domain]:6543/postgres'

文档里还特别提醒：

• 如果你用命令行参数形式连接 Supavisor
• -U 不能只写 postgres
• 必须写成 postgres.[POOLER_TENANT_ID]

如果你不想经过 Supavisor，也可以直接暴露 Postgres 端口，但这通常意味着更高的运维和安全风险。

7. 生产环境必须补的配置

官方这篇文档不仅讲"怎么跑起来"，也明确指出要补齐下面几类生产项。

7.1 SMTP

如果你要启用注册、登录、找回密码、邮箱验证等能力，需要配置 SMTP：

SMTP_ADMIN_EMAIL=
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=
SMTP_SENDER_NAME=

官方推荐 AWS SES。

7.2 HTTPS

默认情况下是 HTTP。

如果是生产环境，尤其涉及 OAuth 登录，官方建议：

• 在 Kong 前面再加一个反向代理
• 用 Caddy 或 Nginx 之类组件终止 TLS
• 给外部入口配置有效证书

这件事不是优化项，而是正式上线前的必要动作。

7.3 S3 存储

默认存储后端是本地文件。

如果你希望：

• 把文件放到 AWS S3 / MinIO / Cloudflare R2
• 或者开放 S3 协议访问接口给 rclone 等工具

则需要继续参考官方的 S3 Storage 配置文档。官方也明确说明，这两个能力彼此独立。

7.4 OAuth / 社交登录

如果要接 GitHub、Google 等第三方登录，除了要配置 Supabase Auth 本身，还必须保证：

• 外部 URL 正确
• HTTPS 正确
• 回调地址与 SITE_URL 协调一致

8. 更新策略

官方说明 Docker Compose 自托管方案大约按月发布稳定更新。

更新原则：

1. 拉取最新的仓库配置变更
2. 查看 changelog
3. 更新 docker-compose.yml 中相关镜像 tag
4. 重新拉取镜像并重启服务

例如更新 Studio：

1. 去 Docker Hub 查看 supabase/studio
2. 找到目标 tag，例如 2025.11.26-sha-8f096b5
3. 修改 docker-compose.yml 中的镜像版本
4. 运行：

docker compose pull
docker compose down
docker compose up -d

注意：

• 官方明确说不同服务单独切换版本不保证兼容
• 重启服务会导致停机
• 所以上线环境应先在测试环境验证

9. 卸载与数据清理

停止并删除卷：

docker compose down -v

官方特别警告这会销毁数据，包括：

• 数据库数据
• 存储卷数据

如果你还执行：

rm -rf volumes/db/data
rm -rf volumes/storage

那就是彻底删除本地数据库与存储内容。

10. 我对这套方案的结论

优点

• 官方维护，路径正
• 一套 Compose 就能把主要服务拉起来
• 对本地开发、自建测试环境、轻量生产比较友好
• 组件边界清晰，后续拆分部署也有基础

风险点

• 默认示例配置绝不能直接上
• 生产环境一定要补 HTTPS、SMTP、Secrets 管理
• 升级时存在镜像兼容性与停机风险
• 直接暴露数据库、错误暴露 SERVICE_ROLE_KEY 都会带来严重安全问题

适合的落地方式

如果是个人项目或中小团队，我建议分三步：

1. 先用官方 Compose 在单机跑通
2. 再把 .env、反向代理、备份、监控补齐
3. 最后再考虑是否拆分数据库、存储、函数运行时等组件

11. 一个更实用的落地清单

如果你准备实际部署，可以按这个顺序执行：

1. 克隆 supabase/supabase
2. 拷贝 docker/ 到独立项目目录
3. 复制 .env.example 为 .env
4. 修改所有默认密码与密钥
5. 设置 SUPABASE_PUBLIC_URL / API_EXTERNAL_URL / SITE_URL
6. 设置 DASHBOARD_USERNAME / DASHBOARD_PASSWORD
7. 执行 docker compose pull
8. 执行 docker compose up -d
9. 用 docker compose ps 检查健康状态
10. 访问 http://<host>:8000
11. 补 SMTP、HTTPS、S3、OAuth 等生产配置
12. 建立备份、升级、回滚流程

12. 原始资料

• 官方文档：https://supabase.com/docs/guides/self-hosting/docker
• 文档中提到的镜像来源：https://hub.docker.com/u/supabase
• 自托管更新记录：https://github.com/supabase/supabase/blob/master/docker/README.md（文档中通过 changelog 链接指向相关更新信息）

13. 一句话总结

Supabase 的 Docker 自托管方案本质上是一套"官方打包好的单机平台栈"。它非常适合快速搭建完整后端平台，但前提是你必须在首次启动前认真处理密钥、密码、URL、HTTPS、SMTP 和升级策略，否则很容易把"能跑"误当成"可上线"。