supabase/realtime Docker Image Overview

supabase/realtime

supabase

Supabase Realtime 是 Supabase 生态中的核心实时引擎 Docker 镜像，基于 WebSocket 协议提供高效的数据库变更同步服务，能够实时监听 PostgreSQL 数据库的 INSERT、UPDATE、DELETE 操作，并将数据变更即时推送到客户端，无需轮询请求。该镜像支持多客户端连接管理、消息广播与房间隔离机制，可轻松集成到各类 Web、移动应用中，为实时聊天、协作工具、动态仪表盘等场景提供低延迟数据同步能力，具备自动扩缩容、权限控制及断线重连特性，帮助开发者快速构建高可用的实时应用后端。

17 次收藏下载次数: 0状态：社区镜像维护者：supabase仓库类型：镜像

🚀 生产环境还在裸拉官方镜像？一次故障=一次通宵

中文简介版本下载

🚀 生产环境还在裸拉官方镜像？一次故障=一次通宵

Supabase Realtime

状态说明

功能	v1版	v2版	状态
Postgres 数据变更	✔	✔	正式可用
广播（Broadcast）		✔	测试版
在线状态（Presence）		✔	测试版

本仓库主要维护版本2，版本1的代码和Docker镜像仍可访问。最新Docker镜像可前往 [***] 获取。

代码库处于活跃开发阶段，文档持续更新。欢迎试用并通过创建issue反馈意见，关注发布记录获取更新通知，喜欢的话别忘了点星标！

概述

什么是Supabase Realtime？

这是一个基于Elixir和Phoenix Framework构建的服务器，支持以下功能：

广播（Broadcast）：低延迟地在客户端间发送临时消息
在线状态（Presence）：跟踪并同步客户端间的共享状态
Postgres 数据变更：通过WebSocket监听Postgres数据库的变更

详细介绍可查看Supabase Realtime指南。

消息传递保证

服务器不保证每条消息都能送达客户端，使用时请注意这一点。

快速开始

可查看多人协作演示，演示代码位于仓库的demo目录。

客户端库

JavaScript：@supabase/realtime-js
Dart：@supabase/realtime-dart

服务器设置

启动服务

通过docker-compose.yml启动Postgres数据库和Realtime服务器容器，示例命令：

bash
docker-compose -f docker-compose.yml up

注意
Supabase在生产环境中使用独立数据库管理租户，但本地开发时通过docker-compose.yml自动创建_realtime模式简化配置。

启动后会自动添加一个默认租户，可通过查询数据库的_realtime.tenants和_realtime.extensions表确认。

添加自定义租户

如需添加自己的租户，发送POST请求到服务器。需修改name和external_id，其他参数可按需调整：

bash
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIiLCJpYXQiOjE2NzEyMzc4NzMsImV4cCI6MTcwMjc3Mzk5MywiYXVkIjoiIiwic3ViIjoiIn0._ARixa2KFUVsKBf3UGR90qKLCpGjxhKcXY4akVbmeNQ' \
-d $'{
  "tenant" : {
    "name": "realtime-dev",
    "external_id": "realtime-dev",
    "jwt_secret": "a1d99c8b-91b6-47b2-8f3c-aa7d9a9ad20f",
    "extensions": [
      {
        "type": "postgres_cdc_rls",
        "settings": {
          "db_name": "postgres",
          "db_host": "host.docker.internal",
          "db_user": "postgres",
          "db_password": "postgres",
          "db_port": "5432",
          "region": "us-west-1",
          "poll_interval_ms": 100,
          "poll_max_record_bytes": ***,
          "ip_version": 4
        }
      ]
    }
  }
}' \
[***]> **注意**  
> 请求头中的`Authorization`令牌使用`docker-compose.yml`中`API_JWT_SECRET`配置的密钥签名。


### 监听Postgres变更

1. 创建测试表：  
```sql
create table test (
  id serial primary key
);

将表添加到supabase_realtime发布：

sql
alter publication supabase_realtime add table test;

测试功能

可通过以下方式测试广播、在线状态和Postgres变更功能：

使用客户端库（如@supabase/realtime-js）
访问本地Realtime Inspector：`[***]

WebSocket连接说明

WebSocket URL需包含租户的external_id（作为子域名），且令牌需使用租户的jwt_secret签名。

默认租户示例：

URL：ws://realtime-dev.localhost:4000/socket（端口需与开发环境一致）
令牌：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDMwMjgwODcsInJvbGUiOiJwb3N0Z3JlcyJ9.tz_XJ89gd6bN8MBpCl7afvPrZiBH6RB65iA1FadPT3Y（包含exp和role字段，role为数据库角色）

环境变量配置

Realtime服务器当前与Fly.io耦合紧密，以下是关键环境变量说明：

变量名	类型	说明
PORT	{数字}	客户端/监听器连接的端口
DB_HOST	{字符串}	数据库主机URL
DB_PORT	{数字}	数据库端口
DB_USER	{字符串}	数据库用户名
DB_PASSWORD	{字符串}	数据库密码
DB_NAME	{字符串}	Postgres数据库名
DB_ENC_KEY	{字符串}	加密`_realtime.tenants`和`_realtime.extensions`表敏感字段的密钥（推荐16字符）
API_JWT_SECRET	{字符串}	用于签名管理租户HTTP请求令牌的密钥
MAX_CONNECTIONS	{字符串}	WebSocket连接软上限（默认***）
NUM_ACCEPTORS	{字符串}	处理WebSocket连接请求的进程数（默认100）
DB_POOL_SIZE	{字符串}	数据库连接池大小（默认5）

WebSocket连接授权

WebSocket连接通过对称JWT验证授权，支持以下签名算法：HS256、HS384、HS512。

必要条件

令牌必须包含exp（过期时间）和role（数据库角色）字段，服务器会自动检查过期时间。
可通过JWT_CLAIM_VALIDATORS设置额外验证规则，例如：{'iss': 'Issuer', 'nbf': ***}，则JWT的iss需等于“Issuer”，nbf需等于***。

客户端授权方式

参考Realtime客户端库的使用说明，例如@supabase/realtime-js的Usage部分。

许可证

本仓库采用Apache 2.0许可证。

致谢

Phoenix：Realtime服务器基于Elixir的Phoenix框架构建。
Phoenix Channels JavaScript Client：@supabase/realtime-js客户端库大量参考了该库的实现。<|FCResponseEnd|># Supabase Realtime