使用 Docker 自托管

学习如何通过 Docker 配置和部署 Supabase。

Docker 是开始自托管 Supabase 最简单的方式，只需几分钟即可完成部署并运行。本指南假设您将在目标主机上直接执行这些命令。

准备工作

您的系统需要预先安装以下工具：Git 和 Docker（Windows、macOS 或 Linux）。

安装并运行 Supabase

按照以下步骤在您的机器上启动 Supabase：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 获取代码库git clone --depth 1 https://github.com/supabase/supabase# 创建新的supabase项目目录mkdir supabase-project# 目录结构应如下所示# .# ├── supabase# └── supabase-project# 将compose文件复制到项目目录cp -rf supabase/docker/* supabase-project# 复制示例环境变量文件cp supabase/docker/.env.example supabase-project/.env# 切换到项目目录cd supabase-project# 拉取最新镜像docker compose pull# 启动服务（后台模式）docker compose up -d

如果使用 rootless docker，请编辑 .env 文件并将 DOCKER_SOCKET_LOCATION 设置为您的 docker socket 路径。例如：/run/user/1000/docker.sock。否则可能会出现类似 container supabase-vector exited (0) 的错误。

所有服务启动后，您可以通过以下命令查看运行状态：

1
docker compose ps

所有服务状态应显示为 running (healthy)。如果看到 created 但未显示 running，可以尝试手动启动该服务：docker compose start <服务名称>。

您的应用现在使用默认凭证运行。请立即按照以下说明保护您的服务。

访问 Supabase Studio

您可以通过端口 8000 的 API 网关访问 Supabase Studio。例如：http://<您的IP>:8000，如果您在本地运行 Docker 则为 localhost:8000。

系统会提示输入用户名和密码。默认凭证为：

用户名：supabase
密码：this_password_is_insecure_and_should_be_updated

请尽快按照以下说明修改这些凭证。

访问 API

所有 API 都通过同一个 API 网关提供：

REST: http://<您的IP>:8000/rest/v1/
认证: http://<您的域名>:8000/auth/v1/
存储: http://<您的域名>:8000/storage/v1/
实时: http://<您的域名>:8000/realtime/v1/

访问您的边缘函数

边缘函数存储在 volumes/functions 目录中。默认配置包含一个名为 hello 的函数，您可以通过 http://<your-domain>:8000/functions/v1/hello 调用它。

您可以通过在 volumes/functions/<FUNCTION_NAME>/index.ts 路径下添加新文件来创建新函数。修改后需要重启 functions 服务以使更改生效：docker compose restart functions --no-deps

访问 Postgres 数据库

默认情况下，Supabase 堆栈运行 Supavisor 连接池。Supavisor 提供了高效的数据库连接管理。

您可以通过以下方式连接到 Postgres 数据库：

基于会话的连接（等同于直接 Postgres 连接）：

1
psql 'postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@localhost:5432/postgres'

事务型连接池连接：

1
psql 'postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@localhost:6543/postgres'

默认租户 ID 为 your-tenant-id，默认密码为 your-super-secret-and-long-postgres-password。您应该尽快按照下方说明修改这些凭证。

默认情况下，数据库只能从本地机器访问，但连接池对外开放。您可以通过修改 docker-compose.yml 文件来更改此设置。

您可能还希望通过 ORM 或其他直接方式（而非 psql）连接到 Postgres 数据库。

此时可以使用标准的 Postgres 连接字符串。您可以在下一节将介绍的 .env 文件中找到以下环境变量值：

1
postgres://postgres:[POSTGRES_PASSWORD]@[your-server-ip]:5432/[POSTGRES_DB]

更新服务

出于安全考虑，我们在 docker-compose 文件中"固定"了每个服务的版本（这些版本大约每月更新一次）。如果您想立即更新任何服务，可以通过修改 docker compose 文件中的版本号，然后运行 docker compose pull 来实现。您可以在 Supabase Docker Hub 找到所有最新的 docker 镜像。

您应该经常更新服务以获取最新功能、错误修复和安全补丁。请注意，您需要重启服务才能使更改生效，这会导致您的服务出现短暂停机。

示例您会希望经常更新 Studio（仪表盘）以获取最新功能和错误修复。更新仪表盘的步骤如下：

访问 Supabase Docker Hub 中的 supabase/studio 镜像
查找最新版本（标签）号，格式类似于 20241029-46e1e40
在 docker-compose.yml 文件中更新 image 字段为新版本，格式应为：image: supabase/studio:20241028-a265374
运行 docker compose pull 然后执行 docker compose up -d 以使用新版本重启服务

保护服务安全

虽然我们提供了一些示例密钥帮助您快速开始，但您绝对不应该使用我们提供的默认配置部署 Supabase 设置。请遵循本节所有步骤确保您的设置安全，然后重启所有服务使更改生效。

生成API密钥

我们需要为访问您的服务生成安全密钥。我们将使用下方的表单，通过JWT密钥来生成anon和service两种API密钥。

获取密钥：使用提供的40字符密钥，或创建您自己的密钥。如自行创建，请确保是一个40字符的强随机字符串。
安全存储：将密钥保存在本地机器的安全位置。不要公开分享或提交到版本控制系统。
生成JWT：使用下方表单，通过您的密钥生成新的JWT。

更新API密钥

请运行此表单两次，分别生成新的anon和service API密钥。然后替换./docker/.env文件中的对应值：

ANON_KEY - 替换为anon密钥
SERVICE_ROLE_KEY - 替换为service密钥

您需要重启所有服务才能使更改生效。

更新密钥配置

使用您自己的密钥更新./docker/.env文件。以下配置项尤为重要：

POSTGRES_PASSWORD：postgres角色的密码
JWT_SECRET：被PostgREST和GoTrue等服务使用
SITE_URL：您站点的基准URL
SMTP_*：邮件服务器凭证，可使用任意SMTP服务器
POOLER_TENANT_ID：Supavisor连接池将用于连接字符串的租户ID

您需要重启所有服务才能使更改生效。

控制面板认证

控制面板受基础认证保护。在生产环境中使用 Supabase 前，必须修改默认的用户名和密码。请更新 ./docker/.env 文件中的以下值：

DASHBOARD_USERNAME: 控制面板的默认用户名
DASHBOARD_PASSWORD: 控制面板的默认密码

您还可以在 ./docker/volumes/api/kong.yml 中添加更多凭证以支持多用户登录。例如：

1
2
3
4
5
6
7
basicauth_credentials:  - consumer: DASHBOARD    username: user_one    password: password_one  - consumer: DASHBOARD    username: user_two    password: password_two

若要在 localhost 之外启用所有控制面板功能，请更新 ./docker/.env 文件中的以下值：

SUPABASE_PUBLIC_URL: 用于访问控制面板的 URL 或 IP

您需要重启所有服务才能使更改生效。

重启所有服务

您可以通过以下命令重启服务以应用配置变更：

1
2
3
4
5
# 停止并移除容器docker compose down# 重新创建并启动容器docker compose up -d

请注意这将导致服务中断。仅重启服务不会应用配置变更。

停止所有服务

在 docker-compose.yml 文件所在目录运行 docker compose stop 即可停止 Supabase 服务。

卸载

在 docker-compose.yml 文件所在目录运行以下命令可卸载 Supabase：

1
2
3
4
5
# 停止 Docker 并移除卷：docker compose down -v# 删除 Postgres 数据：rm -rf volumes/db/data/

这将销毁数据库和存储卷中的所有数据，请谨慎操作！

管理您的密钥

Supabase 内部的许多组件都使用安全密钥和密码。这些密钥列在自托管环境的 env 文件中，但我们强烈建议在生产环境部署时使用密钥管理系统。像 dotenv 这样的纯文本文件容易导致意外泄露，造成重大损失。

推荐使用的密钥管理系统包括：

Doppler
Infisical
Azure (Microsoft) 的 Key Vault
AWS 的 Secrets Manager
GCP 的 Secrets Manager
HashiCorp 的 Vault

高级配置

本指南后续内容将帮助您理解系统工作原理，以及如何根据需求进行定制化修改。

架构设计

Supabase 是由多个开源工具组合而成，每个工具都经过精心挑选以满足企业级需求。

如果工具和社区已经存在，并且采用 MIT、Apache 2 或等效的开源许可，我们将使用并支持该工具。如果工具不存在，我们会自行构建并开源。

Kong 是一个云原生API网关
GoTrue 是基于JWT的用户管理API，用于签发JWT令牌
PostgREST 是一个将Postgres数据库直接转换为RESTful API的Web服务器
Realtime 是一个Elixir服务器，允许通过WebSocket监听Postgres的插入、更新和删除操作。Realtime轮询Postgres内置的复制功能获取数据库变更，将变更转换为JSON格式，然后通过WebSocket广播给授权客户端
Storage 提供RESTful接口管理存储在S3中的文件，使用Postgres进行权限管理
postgres-meta 是用于管理Postgres的RESTful API，可以获取表信息、添加角色和执行查询等
Postgres 是一个对象关系型数据库系统，拥有30多年的持续开发历史，以可靠性、功能完备性和性能著称
Supavisor 是Postgres的可扩展连接池管理器，用于高效管理数据库连接

为了使系统协同工作，某些服务需要在Postgres数据库中进行额外配置。例如，API和认证系统需要几个默认角色以及pgjwt Postgres扩展。

您可以在模式迁移脚本仓库中找到所有默认扩展。这些脚本被挂载在/docker-entrypoint-initdb.d目录下，在启动数据库容器时会自动运行。

服务配置

每个系统都有若干配置选项，可在相关产品文档中找到：

这些配置项通常添加到 docker-compose.yml 文件中每个服务的 env 部分。若配置项包含敏感信息，应存储在密钥管理器中，或使用 .env 文件并通过 ${} 语法引用。

1
2
3
4
5
services:  rest:    image: postgrest/postgrest    environment:      PGRST_JWT_SECRET: ${JWT_SECRET}

通用配置

每个系统都可以独立配置。以下列出了一些最常用的配置选项。

配置邮件服务器

您需要使用生产级SMTP服务器发送邮件。通过更新以下环境变量来配置SMTP服务器：

1
2
3
4
5
6
SMTP_ADMIN_EMAIL=SMTP_HOST=SMTP_PORT=SMTP_USER=SMTP_PASS=SMTP_SENDER_NAME=

我们推荐使用AWS SES，它价格低廉且稳定可靠。修改配置后需重启所有服务使配置生效。

配置 S3 存储

默认情况下，所有文件都存储在服务器本地。您可以通过更新以下环境变量来配置存储服务使用 S3：

1
2
3
4
storage:  environment: STORAGE_BACKEND=s3    GLOBAL_S3_BUCKET=您的S3存储桶名称    REGION=您的S3存储桶区域

您可以在存储库中找到所有可用选项。重启 storage 服务以使更改生效：docker compose restart storage --no-deps

配置 Supabase AI 助手

配置 Supabase AI 助手是可选的。通过添加您自己的 OPENAI_API_KEY，您可以启用 AI 服务，该服务可帮助编写 SQL 查询、语句和策略。

1
2
3
4
5
services:  studio:    image: supabase/studio    environment:      OPENAI_API_KEY: ${OPENAI_API_KEY:-}

设置数据库的 `log_min_messages`

默认情况下，docker compose 将数据库的 log_min_messages 配置设置为 fatal，以防止 Realtime 生成冗余日志。您可以使用 Postgres 的严重级别中的任意级别来配置 log_min_messages。

通过 Supavisor 访问 Postgres

默认情况下，Postgres 数据库可通过 Supavisor 连接池访问。这样可以更高效地管理数据库连接。您可以使用 POOLER_PROXY_PORT_TRANSACTION 端口连接池化数据库，使用 POSTGRES_PORT 进行基于会话的连接。

有关配置和使用 Supavisor 的更多信息，请参阅 Supavisor 文档。

直接暴露您的Postgres数据库

如果您需要绕过Supavisor直接访问Postgres数据库，可以通过更新docker-compose.yml文件来实现：

1
2
3
4
5
6
7
8
9
10
# 注释或删除docker-compose文件中的supavisor部分#  supavisor:#    ports:# ...db:  ports:    - ${POSTGRES_PORT}:${POSTGRES_PORT}

这种方式安全性较低，请确保在服务器前运行防火墙。

macOS上的文件存储后端

默认情况下，存储后端设置为file，即使用本地文件作为存储后端。为了兼容macOS，您需要选择VirtioFS作为Docker容器文件共享实现（在Docker Desktop -> 偏好设置 -> 常规中设置）。

配置Analytics服务器的日志记录

自托管Analytics服务器需要额外配置。完整设置说明请参阅自托管Analytics。

升级Analytics

由于Analytics服务器的变更，您需要运行以下命令来升级Analytics服务器：

运行以下命令时，analytics中的所有数据都将被删除。

1
2
3
4
5
6
7
8
9
10
11
### 销毁analytics以过渡到postgres自托管解决方案，同时避免其他数据丢失# 进入容器并使用.env中的POSTGRES_PASSWORD值登录docker exec -it $(docker ps | grep supabase-db | awk '{print $1}') psql -U supabase_admin --password# 删除_analytics模式中的所有数据DROP PUBLICATION logflare_pub; DROP SCHEMA _analytics CASCADE; CREATE SCHEMA _analytics;\q# 删除analytics容器docker rm supabase-analytics

演示

这是一个在DigitalOcean上托管的Ubuntu最小化配置示例。

DigitalOcean使用演示

初始阶段使用1GB内存和25GB固态硬盘(SSD)的DigitalOcean Droplet即可满足需求
要访问Dashboard，请使用您的Droplet的ipv4 IP地址
如果无法访问Dashboard，请运行docker compose ps命令检查Studio服务是否正常运行

使用 Docker 自托管

学习如何通过 Docker 配置和部署 Supabase。

目录

准备工作

安装并运行 Supabase#

访问 Supabase Studio#

访问 API#

访问您的边缘函数

访问 Postgres 数据库#

更新服务

保护服务安全

生成API密钥#

更新API密钥#

更新密钥配置

控制面板认证

重启所有服务

停止所有服务

卸载

管理您的密钥

高级配置

架构设计

服务配置

通用配置

配置邮件服务器

配置 S3 存储#

配置 Supabase AI 助手#

设置数据库的 log_min_messages#

通过 Supavisor 访问 Postgres#

直接暴露您的Postgres数据库#

macOS上的文件存储后端#

配置Analytics服务器的日志记录#

升级Analytics#

演示

DigitalOcean使用演示#

安装并运行 Supabase

访问 Supabase Studio

访问 API

访问 Postgres 数据库

生成API密钥

更新API密钥

配置 S3 存储

配置 Supabase AI 助手

设置数据库的 `log_min_messages`

通过 Supavisor 访问 Postgres

直接暴露您的Postgres数据库

macOS上的文件存储后端

配置Analytics服务器的日志记录

升级Analytics

DigitalOcean使用演示