> 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/ko/docs/sample-projects/web-games/supabase-sumo-push.md).

# Supabase 스모 푸시

Edgegap와 함께하는 Supabase 멀티플레이어 게임 백엔드: Supabase Edge Functions를 통해 로그인, 프로필, 리더보드 및 매치메이킹을 제공하며, 각 매치마다 Edgegap에서 권한을 가진 단일 Node.js 서버를 사용합니다.

Edgegap에서 호스팅되는 멀티플레이어 웹 게임의 백엔드로 Supabase를 사용하는 방법을 알아보세요.

![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/ko/docs/sample-projects/web-games/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 대시보드에서 **Authentication**을 열고, **Sign In / Providers**를 선택한 뒤, **Allow anonymous sign-ins**.

☑️ 복사 `client/config.js` 다음으로 `client/config.local.js` 를 활성화하고 다음 값을 입력하세요. **Project URL** 및 **Publishable key**를, **Project Settings**을 열고, **API Keys**.

{% hint style="success" %}
그 **Supabase 공개 키는 웹 페이지에 포함해도 안전합니다**: 행 수준 보안이 무엇을 읽고 변경할 수 있는지 결정합니다. 비밀 키나 서비스 역할 키를 페이지나 서버 이미지에 절대 넣지 마세요.
{% endhint %}

☑️ 새로고침 `http://localhost:8080`: 메뉴에 생성된 플레이어 이름, 기록, 그리고 순위표가 표시됩니다. 이름을 바꾸면 그 이름이 프로필에 저장됩니다.

✅ 이제 다음 단계로 진행할 수 있습니다.

## ⚡ 배포 및 연결

### 2. 서버 이미지 빌드하기

☑️ 시작하려면 다음이 필요합니다 [Edgegap에 무료 계정을 만드세요](https://app.edgegap.com/auth/register). 신용카드는 필요 없습니다.

☑️ 다음 항목을 찾습니다: [컨테이너 레지스트리](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md) 프로젝트 이름과 자격 증명.

☑️ Docker로 Edgegap의 Container Registry에 로그인하고, 레지스트리 프로젝트 이름, 사용자 이름 및 토큰을 사용하세요:

{% tabs %}
{% tab title="Bash (리눅스)" %}

```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 (윈도우)" %}

```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 및 512MB 메모리,
* **포트**: `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` 를 앱과 버전에.

☑️ 대시보드에서 [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 페이지를 열고, **생성**, 구성을 업로드한 뒤, **만들기 및 시작**.

그 `sumo` 프로필 매칭은 2\~8명의 플레이어를 지원합니다. 20초 후, 혼자 대기 중인 플레이어에게 서버가 할당되고 봇이 빈 자리를 채웁니다.

☑️ 매치메이커에 표시될 때 **온라인**, 해당 값을 복사하세요 **API URL** 및 **인증 토큰**.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 5. Edge Function 배포하기

☑️ 매치메이커 정보와 게임 서버 비밀을 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` 플레이어의 세션을 확인한 다음, 1인 그룹으로 매치메이커에 참여하고, 폴링한 뒤, 서버의 `wss://` 주소와 플레이어의 티켓 ID를 반환합니다. 그 `cancel` 동작은 플레이어의 그룹을 삭제해 대기열에서 나갑니다.
* `report-match` 는 게임 서버의 비밀을 확인한 다음, `record_match()`.

{% hint style="info" %}
**플레이어는 매치메이커에 직접 요청하지 않습니다.** Edge Function이 그 토큰을 보관하므로, 로그인한 플레이어만 대기열에 들어갈 수 있고 모든 티켓은 Supabase 사용자와 연결됩니다. 이는 또한 매치메이커의 `allowed_cors_origins` 는 페이지의 출처를 필요로 하지 않습니다.
{% endhint %}

✅ 이제 다음 단계로 진행할 수 있습니다.

### 6. 매치 찾기

☑️ 다음을 엽니다 `http://localhost:8080` 를 두 브라우저(또는 일반 창과 비공개 창에서, 하나의 브라우저 프로필이 하나의 Supabase 세션을 공유하므로)에서 실행하고, 클릭 **매치 찾기** 를 클릭하세요.

각 페이지는:

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 계정을 익명 사용자에 연결하여 플레이어가 기기 간에 계정을 유지할 수 있게 하세요.
* 로 설정 `inspect` 를 매치메이커 구성에서 끄세요.
* 낮추세요 `FIRST_JOIN_TIMEOUT_S` (예를 들어 `60`), 그래서 플레이어가 모두 합류하기 전에 떠난 서버가 더 빨리 종료됩니다.
* 오래된 행을 정리하세요 `tickets` 테이블에서, 예를 들어 매일 `pg_cron` 작업으로.
* 새 서버 빌드를 배포하려면 새 이미지 태그를 푸시하고 앱 버전을 그 태그로 가리키세요. 새 매치는 그 빌드를 사용하고, 실행 중인 매치는 이전 빌드를 유지합니다.

{% hint style="info" %}
코딩 에이전트를 사용 중이신가요? `edgegap-supabase` 스킬은 [Edgegap의 에이전트 스킬](https://github.com/edgegap/llm-agent-skills) 이 샘플의 스키마, Edge Function, 서버 및 클라이언트 변경 사항을 템플릿으로 제공하고, 에이전트가 자신의 게임에 대해 동일한 단계를 안내합니다.
{% endhint %}
