> 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/ru/docs/sample-projects/veb-igry/supabase-sumo-push.md).

# Supabase Sumo Push

бэкенд многопользовательской игры на supabase с edgegap: вход в систему, профили, таблица лидеров и подбор соперников через edge-функции supabase, по одному авторитетному серверу node.js на каждый матч на edgegap.

Узнайте, как использовать 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/ru/docs/sample-projects/veb-igry/threejs-minigames.md) примерa, и добавляет [Supabase](https://supabase.com/) в качестве бэкенда. Игроки входят в систему, сохраняют профиль, поднимаются в живом рейтинге и нажимают **Найти матч**. Матчмейкер Edgegap запускает авторитетный сервер node.js рядом с ними, который записывает результат в Supabase и останавливает себя, когда матч заканчивается.

* **Supabase**: вход в систему, профили, победы, история матчей, обновления таблицы лидеров и шлюз к матчмейкеру.
* **Edgegap**: подбор игроков и по одному выделенному серверу на матч рядом с его игроками.

В этом примере показано:

* **Анонимный вход**: каждый игрок получает настоящего пользователя Supabase без адреса электронной почты или пароля и сохраняет его при следующем визите. Позже можно привязать email или OAuth-идентификатор, чтобы сохранять прогресс на разных устройствах.
* **Поиск матча через Edge Function Supabase**: страница никогда не хранит токен матчмейкера. Функция проверяет сессию игрока, подключается к матчмейкеру и запоминает, какой билет принадлежит какому игроку.
* **Игроки, проверяемые игровым сервером**: каждый игрок отправляет свой токен доступа Supabase при подключении. Сервер проверяет его подпись по публичным ключам проекта, поэтому знает, кто играет, не храня ни одного ключа Supabase.
* **Результаты, которые сообщает сервер**: когда матч заканчивается, сервер отправляет результаты во вторую Edge Function. Postgres принимает только игроков, которые пришли со своим, ещё не использованным билетом для этого матча, поэтому результаты нельзя подделать или засчитать дважды.
* **Безопасность на уровне строк**: игроки могут читать профили и матчи, а также менять своё имя, но не могут изменять свои победы.
* **Живая таблица лидеров** с Supabase Realtime: завершение матча в любом месте обновляет каждую открытую страницу.

{% hint style="info" %}
См. [репозиторий с примером](https://github.com/edgegap/netcode-sample-threejs-supabase) для схемы базы данных, обеих Edge Functions, игрового сервера и end-to-end теста всего потока.
{% 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` играет полный матч с двумя headless-игроками.

## 🗄️ Бэкенд 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 Keys**.

{% hint style="success" %}
Правило **Публичный ключ Supabase безопасно встраивать в веб-страницы**: безопасность на уровне строк определяет, что он может читать и менять. Никогда не помещайте секретный ключ или ключ service role в страницу или в образ сервера.
{% endhint %}

☑️ Перезагрузите `http://localhost:8080`: в меню отображаются сгенерированное имя игрока, ваш рекорд и таблица лидеров. Измените имя, и оно сохранится в вашем профиле.

✅ Теперь можете перейти к следующему шагу.

## ⚡ Развертывание и подключение

### 2. Соберите образ сервера

☑️ Для начала вам нужно будет [создать бесплатную учетную запись в Edgegap](https://app.edgegap.com/auth/register). Кредитная карта не требуется.

☑️ Найдите свой [Container Registry](https://docs.edgegap.com/ru/learn/advanced-features/edgegap-container-registry.md) имя проекта и учётные данные.

☑️ Войдите в Container Registry Edgegap с помощью Docker, используя имя проекта реестра, имя пользователя и токен:

{% 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>`,
* **Учётные данные реестра**: имя пользователя и токен вашего Container Registry, чтобы Edgegap мог загрузить образ,
* **Ресурсы**: 0,25 vCPU и 512 МБ памяти,
* **Порт**: `7777`, имя `gameport`, протокол **WS**, с **включённым TLS Upgrade** включено,
* **Переменные окружения**:
  * `SUPABASE_URL` - URL вашего проекта, `https://<project-ref>.supabase.co`,
  * `GAME_SERVER_SECRET` - длинная случайная строка, помеченная **скрытая**, переданная Supabase на шаге 5,
  * `REQUIRE_TICKET` - `1`, чтобы отклонять игроков, которых матчмейкер не отправлял в этот матч,
* **Максимальная длительность**: 30 минут, как страховка: сервер сам останавливается.

{% hint style="warning" %}
**включённым TLS Upgrade** позволяет браузерам на `https` страницах подключаться к `wss://<id>.pr.edgegap.net:<port>`. Edgegap завершает TLS и пересылает обычный WebSocket-трафик на порт `7777`.
{% endhint %}

✅ Теперь можете перейти к следующему шагу.

### 4. Создайте матчмейкер

☑️ Установите `application.name` и `application.version` в примере `edgegap/matchmaker-config.json` к вашему приложению и версии.

☑️ Откройте [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) страницу в панели управления, нажмите **Создать**, загрузите конфигурацию и нажмите **Создать и запустить**.

Правило `sumo` профиль рассчитан на 2–8 игроков. Через 20 секунд игрок, ожидающий в одиночку, получает сервер, а боты заполняют пустые места.

☑️ Когда матчмейкер показывает **Онлайн**, скопируйте его **API URL** и **Auth Token**.

✅ Теперь можете перейти к следующему шагу.

### 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 билета игрока. Его `отмена` действие покидает очередь, удаляя группу игрока.
* `report-match` проверяет секрет игрового сервера, затем вызывает `record_match()`.

{% hint style="info" %}
**Игроки никогда не вызывают матчмейкер напрямую.** Edge Function хранит его токен, поэтому в очередь могут становиться только вошедшие игроки, и каждый билет привязан к пользователю Supabase. Это также означает, что у матчмейкера `allowed_cors_origins` не нужен origin вашей страницы.
{% 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 %}

🙌 Теперь оба игрока в одном матче, на сервере, размещённом рядом с ними, и таблица лидеров обновляется на обеих страницах, когда он заканчивается.

☑️ Чтобы проверить весь путь без браузера, запустите end-to-end тест. Он выполняет вход для headless-игроков, находит им матч через 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/`).
* Позвольте игрокам сохранять свой аккаунт на разных устройствах, привязав email или OAuth-идентификатор к их анонимному пользователю.
* Выключите `inspect` в конфигурации матчмейкера перед запуском.
* Уменьшите `FIRST_JOIN_TIMEOUT_S` (например, до `60`), чтобы серверы, у которых все игроки ушли до присоединения, останавливались раньше.
* Очищайте старые строки в `tickets` таблице, например с помощью ежедневной `pg_cron` задачи.
* Чтобы выпустить новую сборку сервера, отправьте новый тег образа и укажите на него версию приложения. Новые матчи будут использовать её, а уже идущие сохранят старую сборку.

{% hint style="info" %}
Используете кодирующего агента? `edgegap-supabase` навык в [навыках агента Edgegap](https://github.com/edgegap/llm-agent-skills) поставляет схему этого примера, Edge Functions, изменения сервера и клиента как шаблоны и проводит вашего агента через те же шаги для вашей собственной игры.
{% endhint %}
