> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/sample-projects/wang-ye-you-xi/supabase-sumo-push.md).

# Supabase Sumo Push

结合 Edgegap 的 Supabase 多人游戏后端：通过 Supabase Edge Functions 实现登录、个人资料、排行榜和匹配，每场比赛在 Edgegap 上运行一个权威的 Node.js 服务器。

了解如何将 Supabase 用作托管在 Edgegap 上的多人网页游戏后端。

![Edgegap 服务器上的一场对局](https://raw.githubusercontent.com/edgegap/netcode-sample-threejs-supabase/main/docs/images/match.jpg)

这个示例以 Sumo Push 为基础， [three.js](https://threejs.org/) 一款来自 [Three.js Minigames](https://docs.edgegap.com/zh/docs/sample-projects/wang-ye-you-xi/threejs-minigames.md) 示例的派对游戏，并添加 [Supabase](https://supabase.com/) 作为其后端。玩家登录、保留个人资料、攀升实时排行榜，并点击 **查找匹配**。Edgegap 的匹配器会在他们附近启动一个权威的 node.js 服务器，记录结果到 Supabase，并在对局结束时自行停止。

* **Supabase**：登录、个人资料、胜场、对局历史、排行榜更新，以及通往匹配器的入口。
* **Edgegap**：匹配，以及每场对局一个专用服务器，位于玩家附近。

此示例展示：

* **匿名登录**：每位玩家都会获得一个真正的 Supabase 用户，无需电子邮件或密码，并会在下次访问时保留。之后可以绑定电子邮件或 OAuth 身份，以便在不同设备间保留进度。
* **通过 Supabase Edge Function 寻找对局**：页面从不持有匹配器令牌。该函数会检查玩家会话、加入匹配器，并记住哪个票证属于哪个玩家。
* **由游戏服务器验证的玩家**：每位玩家在连接时都会发送其 Supabase 访问令牌。服务器会用项目的公钥验证其签名，因此无需持有任何 Supabase 密钥也能知道是谁在玩。
* **服务器上报的结果**：当对局结束时，服务器会将分数发送到第二个 Edge Function。Postgres 只接受那些带着自己在该对局中未使用过票证的玩家，因此结果无法伪造或重复计分。
* **行级安全**：玩家可以读取个人资料和对局，并修改自己的名字，但不能更改自己的胜场。
* **实时排行榜** 配合 Supabase Realtime：任意地点的对局结束都会更新每个已打开的页面。

{% hint style="info" %}
查看 [示例仓库](https://github.com/edgegap/netcode-sample-threejs-supabase) 用于数据库架构、两个 Edge Function、游戏服务器，以及整条流程的端到端测试。
{% endhint %}

## ✔️ 准备工作

开始之前，你需要：

* [Supabase Sumo Push 示例](https://github.com/edgegap/netcode-sample-threejs-supabase).
* [Node.js](https://nodejs.org/) 22 或更新版本，用于在本地运行服务器和页面，以及 [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) 通过 `npx`.
* [Docker](https://docs.docker.com/get-started/get-docker/)，用于构建服务器镜像。
* 一个 [Supabase 账户](https://supabase.com/dashboard)。免费套餐就足够了。

☑️ 先在本地试试游戏：

{% code collapsedlinecount="10" %}

```bash
npm install
npm run dev
npm run web
```

{% endcode %}

打开 `http://localhost:8080`，点击 **本地服务器**，再打开第二个标签页和自己对战。如果没有配置 Supabase，服务器会允许任何人进入且不记录任何内容。 `npm test` 进行一场包含两个无头玩家的完整对局。

## 🗄️ Supabase 后端

### 1. 创建项目

☑️ 创建一个 Supabase 项目并应用示例的架构：

{% code collapsedlinecount="10" %}

```bash
npx supabase login
npx supabase projects create edgegap-sumo --org-id <org-id> --region us-east-1
npx supabase link --project-ref <project-ref>
npx supabase db push --remote
```

{% endcode %}

`npx supabase orgs list` 会显示你的组织 ID。 `db push` 会创建 `profiles`, `tickets`, `matches` 以及 `match_players` 这些表、它们的行级安全策略、一个为每个新用户提供个人资料的触发器，以及 `record_match()` 函数。

☑️ 在 Supabase 控制台中，打开 **身份验证**，然后打开 **登录 / 提供商**，并启用 **允许匿名登录**.

☑️ 复制 `client/config.js` 变为 `client/config.local.js` ，并填写你的 **项目 URL** 以及 **可发布密钥**，来自 **项目设置**，然后打开 **API 密钥**.

{% hint style="success" %}
该 **Supabase 可发布密钥可以安全地放在网页中发布**：行级安全决定它可以读取和更改什么。切勿将密钥或 service role 密钥放在页面或服务器镜像中。
{% endhint %}

☑️ 重新加载 `http://localhost:8080`：菜单会显示你生成的玩家名称、战绩和排行榜。重命名自己后，该名称会保存到你的个人资料中。

✅ 现在你可以继续下一步。

## ⚡ 部署并连接

### 2. 构建服务器镜像

☑️ 开始前，你需要 [在 Edgegap 创建一个免费账户](https://app.edgegap.com/auth/register)。无需信用卡。

☑️ 找到你的 [容器仓库](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md) 项目名称和凭据。

☑️ 使用你的注册表项目名称、用户名和令牌，通过 Docker 登录 Edgegap 的容器注册表：

{% tabs %}
{% tab title="Bash（Linux）" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell（Windows）" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

☑️ 构建并推送包含游戏服务器的镜像，并使用构建时间作为标签：

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/sumo-supabase:<tag> .
docker push registry.edgegap.com/<project>/sumo-supabase:<tag>
```

{% endcode %}

✅ 现在你可以继续下一步。

### 3. 创建应用版本

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list) 名称为 `sumo-supabase`，创建一个以你的标签命名的版本：

* **镜像**: `registry.edgegap.com/<project>/sumo-supabase`，标签 `<tag>`,
* **镜像仓库凭据**：你的容器镜像仓库用户名和令牌，以便 Edgegap 拉取镜像，
* **资源**：0.25 vCPU 和 512 MB 内存，
* **端口**: `7777`，名称 `gameport`，协议 **WS**，并启用 **TLS 升级** 启用，
* **环境变量**:
  * `SUPABASE_URL` - 你的项目 URL， `https://<project-ref>.supabase.co`,
  * `GAME_SERVER_SECRET` - 一串很长的随机字符串，标记为 **隐藏**，在第 5 步与 Supabase 共享，
  * `REQUIRE_TICKET` - `1`，用于拒绝那些匹配器没有发送到这场对局的玩家，
* **最大时长**：30 分钟，作为安全保障：服务器会自行停止。

{% hint style="warning" %}
**TLS 升级** 允许位于 `https` 的页面连接到 `wss://<id>.pr.edgegap.net:<port>`。Edgegap 终止 TLS，并将普通 WebSocket 流量转发到端口 `7777`.
{% endhint %}

✅ 现在你可以继续下一步。

### 4. 创建匹配器

☑️ 将 `application.name` 以及 `application.version` 在示例的 `edgegap/matchmaker-config.json` 到你的应用和版本。

☑️ 打开 [匹配器](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 仪表板中的页面，点击 **创建**，上传配置，然后点击 **创建并启动**.

该 `sumo` 该配置的对局支持 2 到 8 名玩家。20 秒后，独自等待的玩家会获得一个服务器，机器人会填补空座位。

☑️ 当匹配器显示 **在线**时，复制其 **API URL** 以及 **认证令牌**.

✅ 现在你可以继续下一步。

### 5. 部署 Edge Functions

☑️ 将匹配器详情和游戏服务器密钥存入 Supabase，然后部署这两个函数：

{% code collapsedlinecount="10" %}

```bash
npx supabase secrets set EDGEGAP_MM_URL=<API URL> EDGEGAP_MM_TOKEN=<Auth Token> GAME_SERVER_SECRET=<same secret as step 3>
npx supabase functions deploy matchmaking
npx supabase functions deploy report-match
```

{% endcode %}

* `matchmaking` 会检查玩家会话，然后以单人组的形式加入匹配器，轮询它，并返回服务器的 `wss://` 地址和玩家的票证 ID。它的 `cancel` 操作通过删除玩家组来离开队列。
* `report-match` 会检查游戏服务器的密钥，然后调用 `record_match()`.

{% hint style="info" %}
**玩家永远不会直接调用匹配器。** Edge Function 持有其令牌，因此只有已登录的玩家才能排队，而且每张票证都绑定到一个 Supabase 用户。这也意味着匹配器的 `allowed_cors_origins` 不需要你页面的来源。
{% endhint %}

✅ 现在你可以继续下一步。

### 6. 寻找对局

☑️ 打开 `http://localhost:8080` 在两个浏览器中（或一个普通窗口和一个隐私窗口，因为一个浏览器配置共享一个 Supabase 会话）。点击 **查找匹配** ，并在 20 秒内在两个标签页中都点击。

每个页面：

1. 调用 `matchmaking` Edge Function，每 1.5 秒一次，直到匹配器返回 `HOST_ASSIGNED`,
2. 连接到 `wss://<fqdn>:<port>` 并发送其票证 ID 和 Supabase 访问令牌，
3. 进行游戏：它发送输入并绘制服务器返回的状态。

游戏服务器：

1. 将每位玩家的访问令牌与 `https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json`进行验证，并将其票证与该对局的 `MM_TICKET_IDS`,
2. 运行对局，
3. 将每位玩家的票证、用户 ID、分数和名次发送到 `report-match`,
4. 在结果屏幕后停止其自身部署。

{% hint style="warning" %}
**取消搜索是玩家放弃的**，否则匹配器仍可能把他们匹配起来并启动一个无人加入的服务器。示例会在 **取消** 按钮上、在新的 **查找匹配**时，以及页面在搜索中途关闭时取消，使用一个 `keepalive` 请求，浏览器会在页面消失后完成该请求。离开时若对局已经形成，玩家仍会获得一个服务器：如果没人加入，它会在 `FIRST_JOIN_TIMEOUT_S` （120 秒）后自行停止。
{% endhint %}

🙌 现在两位玩家已进入同一场对局，在离他们附近的服务器上进行，并且对局结束时两个页面上的排行榜都会更新。

☑️ 要在不使用浏览器的情况下测试整条路径，请运行端到端测试。它会登录无头玩家、通过 Edge Function 为他们寻找对局、进行游戏、从 Supabase 读取结果，并等待部署自行停止：

{% code collapsedlinecount="10" %}

```bash
SUPABASE_URL=https://<project-ref>.supabase.co SUPABASE_PUBLISHABLE_KEY=<publishable key> npm run e2e
```

{% endcode %}

## 📦 发布你的游戏

* 可在任何地方托管页面：它是静态文件，没有构建步骤（`index.html`, `client/`, `game/`).
* 通过将电子邮件或 OAuth 身份与匿名用户关联，让玩家可以在不同设备间保留他们的账号。
* 将 `检查` 在发布前在匹配器配置中关闭。
* 降低 `FIRST_JOIN_TIMEOUT_S` （例如降到 `60`），这样那些所有玩家在加入前就已离开的服务器会更快停止。
* 清理 `tickets` 表中的旧行，例如通过一个每日的 `pg_cron` 任务。
* 要发布新的服务器构建，请推送一个新的镜像标签并将应用版本指向它。新的对局会使用它，进行中的对局会继续使用旧构建。

{% hint style="info" %}
在使用编码代理吗？ `edgegap-supabase` Edgegap 的代理技能中的 [Edgegap 的代理技能](https://github.com/edgegap/llm-agent-skills) 将此示例的架构、Edge Function、服务器和客户端更改作为模板提供，并引导你的代理为你自己的游戏完成同样的步骤。
{% endhint %}
