Supabase Realtime

通过WebSocket发送临时消息、追踪和同步共享状态，以及监听Postgres变更。
多人演示 · 请求新功能 · 报告错误

状态

本仓库主要关注第2版，但你仍可以访问之前版本的代码和Docker镜像。最新的Docker镜像请访问https://hub.docker.com/r/supabase/realtime。

代码库正在快速开发中，文档也在不断完善。欢迎试用并通过创建issue告诉我们你的想法。关注本仓库的releases以获取更新通知。如果你喜欢这个项目，请给我们一个星标！

概述

这是什么？

这是一个使用Phoenix框架构建的Elixir服务器，提供以下功能：

• 广播：以低延迟从客户端向客户端发送临时消息。
• 在线状态：追踪和同步客户端之间的共享状态。
• Postgres变更：监听Postgres数据库变更并将其发送给授权的客户端。

更详细的概述请查看Realtime指南。

这个服务器能保证消息送达吗？

服务器不保证每条消息都会被送达到你的客户端，使用Realtime时请记住这一点。

快速开始

你可以查看多人演示，它展示了广播、在线状态和Postgres变更功能。演示代码位于：https://github.com/supabase/realtime/tree/main/demo。

客户端库

• JavaScript: @supabase/realtime-js
• Dart: @supabase/realtime-dart

服务器设置

首先，启动docker-compose.yml中定义的Postgres数据库和Realtime服务器容器。例如，你可以运行docker-compose -f docker-compose.yml up。

注意 Supabase在生产环境中使用单独的数据库来跟踪所有租户。但是，为了简化本地开发，当通过docker-compose.yml启动容器时，会创建一个_realtime模式。

系统已为你添加了一个租户。你可以通过检查数据库中的_realtime.tenants和_realtime.extensions表来确认这一点。

你可以通过向服务器发送POST请求来添加自己的租户。你必须更改name和external_id，其他值可以根据需要更新：

  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": 1048576
          }
        }
      ]
    }
  }' \
  http://localhost:4000/api/tenants

注意 Authorization令牌使用docker-compose.yml中API_JWT_SECRET设置的密钥签名。

如果你想监听Postgres变更，可以创建一个表，然后将该表添加到supabase_realtime发布中：

create table test (
  id serial primary key
);

alter publication supabase_realtime add table test;

你可以使用客户端库（如@supabase/realtime-js）或使用本地主机上的内置Realtime检查器http://localhost:4000/inspector/new（确保端口与你的开发环境一致）开始使用广播、在线状态和Postgres变更功能。

WebSocket URL必须包含子域名（_realtime.tenants表中租户的external_id），令牌必须使用与租户一起插入的jwt_secret签名。

如果你使用默认租户，URL为ws://realtime-dev.localhost:4000/socket（确保端口与你的开发环境一致），你可以使用eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDMwMjgwODcsInJvbGUiOiJwb3N0Z3JlcyJ9.tz_XJ89gd6bN8MBpCl7afvPrZiBH6RB65iA1FadPT3Y作为令牌。令牌必须包含exp和role（数据库角色）键。

环境变量

WebSocket URL

本地开发时，WebSocket URL的格式如下：ws://[external_id].localhost:4000/socket/websocket

如果你在生产环境中使用Supabase托管的Realtime，URL为wss://[project-ref].supabase.co/realtime/v1/websocket?apikey=[anon-token]&log_level=info&vsn=1.0.0"

WebSocket连接授权

WebSocket连接通过对称JWT验证进行授权。仅支持使用以下算法签名的JWT：

• HS256
• HS384
• HS512

通过设置JWT_CLAIM_VALIDATORS来验证JWT声明：

例如 {'iss': 'Issuer', 'nbf': 1610078130}

然后JWT的"iss"值必须等于"Issuer"，"nbf"值必须等于1610078130。

注意：

JWT过期会自动检查。exp和role（数据库角色）键是必需的。

授权客户端连接：您可以按照实时客户端库中的说明传递JWT。例如，请参阅@supabase/realtime-js客户端库的使用部分。

错误操作代码

这是可以帮助您理解部署和使用情况的操作代码列表。

许可证

此仓库采用Apache 2.0许可。

致谢

• Phoenix - Realtime服务器是使用这个出色的Elixir框架构建的。
• Phoenix Channels JavaScript Client - @supabase/realtime-js客户端库很大程度上借鉴了Phoenix Channels客户端库。