supabase/realtime

Supabase Realtime

状态说明

本仓库主要维护版本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 sql
create table test (
  id serial primary key
);

2. 将表添加到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耦合紧密，以下是关键环境变量说明：

WebSocket连接授权

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

必要条件

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

客户端授权方式

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

许可证

本仓库采用Apache 2.0许可证。

致谢

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

状态说明

本仓库主要维护版本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
);

2. 将表添加到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耦合紧密，以下是关键环境变量说明：

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客户端库大量参考了该库的实现。{ "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": 1048576, "ip_version": 4 } ] } } }'
  []> 注意

请求头中的Authorization令牌使用docker-compose.yml中API_JWT_SECRET配置的密钥签名。

监听Postgres变更

1. 创建测试表：

sql
create table test (
  id serial primary key
);
__CODE_TOKEN_2__sql
alter publication supabase_realtime add table test;
__CODE_TOKEN_3__bash
docker-compose -f docker-compose.yml up
__CODE_TOKEN_4__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
        }
      ]
    }
  }
}' \
[]> **注意**  
> 请求头中的__CODE_TOKEN_14__令牌使用__CODE_TOKEN_15__中__CODE_TOKEN_16__配置的密钥签名。


### 监听Postgres变更

1. 创建测试表：  
__CODE_TOKEN_5__

2. 将表添加到__CODE_TOKEN_17__发布：  
__CODE_TOKEN_6__


### 测试功能

可通过以下方式测试广播、在线状态和Postgres变更功能：  
- 使用客户端库（如__CODE_TOKEN_18__）  
- 访问本地Realtime Inspector：__CODE_TOKEN_19__external_id__CODE_TOKEN_20__jwt_secret__CODE_TOKEN_21__ws://realtime-dev.localhost:4000/socket__CODE_TOKEN_22__eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDMwMjgwODcsInJvbGUiOiJwb3N0Z3JlcyJ9.tz_XJ89gd6bN8MBpCl7afvPrZiBH6RB65iA1FadPT3Y__CODE_TOKEN_23__exp__CODE_TOKEN_24__role__CODE_TOKEN_25__role__CODE_TOKEN_26___realtime.tenants__CODE_TOKEN_27___realtime.extensions__CODE_TOKEN_28__exp__CODE_TOKEN_29__role__CODE_TOKEN_30__JWT_CLAIM_VALIDATORS__CODE_TOKEN_31__{'iss': 'Issuer', 'nbf': ***}__CODE_TOKEN_32__iss__CODE_TOKEN_33__nbf`需等于***。  


### 客户端授权方式

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


## 许可证

本仓库采用Apache 2.0许可证。


## 致谢

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