> 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/tools-and-integrations/playfab-bridge.md).

# 从 PlayFab 部署

保留 PlayFab Matchmaking，并通过两个 Azure Functions 为每场比赛在玩家附近启动一台 Edgegap 专用服务器。

使用 **PlayFab** 管理玩家帐户和匹配队列，并让每场比赛都在独立的 **Edgegap** 专用服务器上运行，该服务器部署在匹配到的玩家附近。两者通过 Azure Functions 连接：

* PlayFab 找到匹配对象后， `StartEdgegapDeployment` 会向 Edgegap 请求一台位于玩家附近的服务器，并立即返回。
* 服务器就绪后，Edgegap 会调用 `EdgegapDeploymentReady`，用于写入服务器地址和 **加入令牌** 到每位玩家的 **只读** PlayFab 数据。

Edgegap API 令牌和 PlayFab 标题机密密钥保存在 Function App 的设置中。游戏客户端仅持有标题 ID，游戏服务器则完全不持有任何机密信息。它只接纳由 PlayFab 匹配的玩家。

```
客户端 --LoginWithCustomID / CreateMatchmakingTicket--> PlayFab 队列（关闭服务器分配）
PlayFab --match_found 时触发的规则--> Azure Function StartEdgegapDeployment
             获取匹配结果和玩家位置 --POST /v2/deployments--> Edgegap
Edgegap --webhook_on_ready--> Azure Function EdgegapDeploymentReady
             读取部署信息 + 向每位玩家发送 --UpdateUserReadOnlyData "EdgegapServer"-->
                                              （主机、端口、加入令牌）
客户端轮询 GetUserReadOnlyData --> 连接到 host:port，并发送加入令牌 --> 服务器在没有玩家时自行停止
```

示例项目 **SpaceEdge**位于 [GitHub](https://github.com/edgegap/backend-game-sample-unity-playfab-matchmaker-fishnet-spaceedge)。该项目于 2026 年 10 月 21 日使用 Unity 2021.3.45f2、FishNet 3.11.14（Tugboat，UDP 7770）、Azure Functions（Flex Consumption）上的 Node.js 22，以及容量为 2 的 PlayFab 队列进行了端到端测试：PlayFab 为两个客户端完成匹配，函数调用后约 8 秒，服务器地址便传达给了双方。加入令牌和使用 Edgegap Unity 插件构建的版本是在该次测试之后加入的，并通过单元测试和本地服务器容器进行了测试。

{% hint style="info" %}
**正在使用编程代理吗？** 该 `edgegap-playfab` Edgegap MCP 服务器中的技能 [Edgegap MCP 服务器](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md) 包含相同的 Azure Functions、用于部署这些函数和创建队列的脚本、Unity 客户端和服务器代码，以及一项链路测试。请在添加规则前运行该测试。
{% endhint %}

## 🚀 入门

开始之前，你需要：

* 一个 **可正常运行的 Edgegap 应用版本** 用于你的游戏服务器：该服务器已部署，并且至少成功加入过一次。请参阅 [Unity](https://docs.edgegap.com/zh/unity.md), [Unreal Engine](https://docs.edgegap.com/zh/unreal-engine.md) 或 [Godot](https://docs.edgegap.com/zh/godot.md)。将其游戏端口命名为 `gameport`。服务器无需任何 PlayFab 设置或密钥。
* 一个 **PlayFab 标题** ，并启用 Matchmaking，提供其 Title ID 和密钥。
* 一个 **Azure 订阅** 和 [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)。测试使用 Flex Consumption 计划的每月免费额度即可满足。
* 一个 **Edgegap API 令牌**，获取方式： [Dashboard → User Settings → Tokens](https://app.edgegap.com/user-settings?tab=tokens)。它仅应放在 Function App 的设置中。

{% hint style="warning" %}
本指南的旧版本使用 JavaScript CloudScript，并将 PlayFab 标题密钥传递给游戏服务器。Microsoft 现在将 JavaScript CloudScript 称为“经典版”，并建议新项目使用 [使用 Azure Functions 的 CloudScript](https://learn.microsoft.com/en-us/gaming/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart)。请使用以下 Azure Functions，并从服务器中移除任何 PlayFab 密钥。
{% endhint %}

## 1. 游戏服务器

服务器必须监听其端口，只接纳匹配中的玩家，并在对局结束后自行停止。

* **监听固定端口**即应用版本中声明的 `gameport` 。示例使用 UDP 7770 端口进行监听。
* **停止自身部署** 如果没有玩家加入，或最后一名玩家离开，则向 `DELETE` 发送请求至 `ARBITRIUM_DELETE_URL` ，并附带请求头 `authorization: <ARBITRIUM_DELETE_TOKEN>`。这两个值都会 [注入每个部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#injected-environment-variables)。如果没有客户端连接，示例会在 120 秒后停止；如果最后一名玩家离开，则会在 30 秒后停止。
* **只接纳匹配中的玩家。** `StartEdgegapDeployment` 会通过隐藏变量传递该对局的加入令牌： `EDGEGAP_JOIN_TOKENS` （以逗号分隔），并为每个客户端连同地址一起提供独立令牌。要求每个客户端连接后立即发送令牌，并断开令牌不在列表中的客户端。已知令牌的新连接应替换旧连接，这样游戏崩溃的玩家就能在旧连接超时前重新加入。
* 移除所有 PlayFab GSDK 调用。此处不使用 PlayFab Multiplayer Servers。

`StartEdgegapDeployment` 还会传递 `PLAYFAB_MATCH_ID` 和 `PLAYFAB_QUEUE_NAME` 作为环境变量，供日志记录或游戏逻辑使用。

{% hint style="info" %}
在示例中， `EdgegapServer.cs` 会完成上述所有操作，并在服务器构建中于运行时将自身添加进来，无需设置场景。 `JoinTokenAuthenticator.cs` 使用 FishNet 验证器检查令牌；如果使用其他网络代码，则改用其连接审批或首条消息机制。如果使用 FishNet，请将 **Start On Headless** 在 `ServerManager`: `EdgegapServer.cs` 上的选项关闭，以便服务器在已知端口上启动。
{% endhint %}

照常构建、容器化并推送服务器，然后创建应用版本：一个名为 `gameport` （示例中为 UDP 7770）、0.5 个 vCPU 和 1 GB，最长运行时间为 60 分钟。此版本无需设置环境变量：函数会按场次传递这些变量。

{% hint style="warning" %}
Edgegap Unity 插件的默认 Dockerfile（最高至 3.2.1 版本）会在服务器启动前运行 `env` ，因此部署日志会列出其中的变量，包括加入令牌和自停止令牌。如果日志会被共享，请从 Dockerfile 的 `env;` CMD `中移除` 。
{% endhint %}

## 2. PlayFab 匹配队列

1. 在 Game Manager 中，打开 **多人游戏 → 匹配** 并创建一个队列（示例使用 `edgegap-fishnet`）。首次测试时，将比赛人数设为 2 且不添加规则，即可匹配任意两名玩家。
2. 关闭 **启用服务器分配** **开关**：PlayFab 只负责组建比赛，服务器由 Edgegap 托管。
3. 如果玩家使用 `LoginWithCustomID` 或设备 ID 登录，请打开 **标题设置 → API 功能** 并取消勾选 **禁止使用 Client/LoginWithCustomId 创建玩家**。新建标题默认会勾选此项，导致登录失败并返回 `PlayerCreationDisabled`.
4. 在 **标题设置 → 密钥**中，为 Azure Functions 创建一个密钥。

{% hint style="warning" %}
**要将正在运行的队列从 PlayFab Multiplayer Servers 迁出？** 已发布的客户端会通过 `GetMatch`读取服务器信息；停用分配后，该接口将不再返回服务器信息。请在队列副本上进行测试，并在切换前发布新版客户端。
{% endhint %}

## 3. Azure Functions

创建一个资源组、一个存储帐户，以及一个使用 Node.js 22 的 Flex Consumption Function App。PlayFab 推荐使用美国西部区域：

```bash
az group create -n rg-edgegap-playfab -l westus2
az storage account create -n <storageaccount> -g rg-edgegap-playfab -l westus2 --sku Standard_LRS
az functionapp create -g rg-edgegap-playfab -n <function-app> --storage-account <storageaccount> \
  --flexconsumption-location westus2 --runtime node --runtime-version 22
```

部署示例中的 `azure-functions` 文件夹（Node.js 22，不使用 PlayFab 或 Edgegap SDK）：

```bash
cd azure-functions
npm ci --omit=dev
# 将 host.json、package.json、src/ 和 node_modules/ 打包到 bridge.zip，然后：
az functionapp deployment source config-zip -g rg-edgegap-playfab -n <function-app> --src bridge.zip
```

添加应用设置（Function App → 设置 → 环境变量）：

| 设置项                                        | 值                                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `PLAYFAB_TITLE_ID`                         | 你的标题 ID。                                                                                  |
| `PLAYFAB_SECRET_KEY`                       | 标题密钥。                                                                                     |
| `EDGEGAP_API_TOKEN`                        | 你的 Edgegap API 令牌，不包含 `token` 前缀。                                                         |
| `EDGEGAP_APP_NAME` / `EDGEGAP_APP_VERSION` | 你的应用和版本名称。                                                                                |
| `EDGEGAP_READY_WEBHOOK_URL`                | `https://<function-app>.azurewebsites.net/api/EdgegapDeploymentReady?code=<function key>` |
| `EDGEGAP_PORT_NAME`                        | 可选，默认为 `gameport`.                                                                        |
| `EDGEGAP_QUEUES`                           | 可选，以逗号分隔。 `match_found` 会为标题的每个队列触发；只有这些队列会获得 Edgegap 服务器。                                |
| `FALLBACK_LATITUDE` / `FALLBACK_LONGITUDE` | 可选。当 PlayFab 没有任何玩家的位置信息时使用。                                                              |

使用以下命令获取每个函数的密钥： `az functionapp function keys list -g rg-edgegap-playfab -n <function-app> --function-name <name>`.

{% hint style="danger" %}
函数密钥属于机密信息：它们包含在函数 URL 中，因此不要提交或分享这些 URL。切勿将 Edgegap 令牌或 PlayFab 密钥放入游戏客户端、游戏服务器或代码仓库中。
{% endhint %}

### StartEdgegapDeployment

在 PlayFab 的 `match_found` 事件触发时运行：

1. 从事件中读取 `MatchId` 和 `QueueName` 。
2. 使用 `Match/GetMatch`获取比赛成员，并使用 `Server/GetPlayerProfile` 获取每位玩家的位置（PlayFab 会根据其登录 IP 进行地理定位）。
3. 为每位玩家计算一个加入令牌：以标题密钥为密钥，对比赛 ID 和玩家 PlayFab ID 进行 HMAC 运算，因此 `EdgegapDeploymentReady` 稍后无需存储这些令牌，也能计算出相同的令牌。
4. 调用 `POST https://api.edgegap.com/v2/deployments` 并传入玩家坐标、包含比赛 ID 前 20 个字符的标签、隐藏变量中的加入令牌 `EDGEGAP_JOIN_TOKENS`，以及就绪和错误 Webhook。
5. 大约一秒后返回。它不会等待服务器就绪：PlayFab 的调用会在 10 秒后超时，而服务器需要 5 到 30 秒才能就绪。

```javascript
// azure-functions/src/lib/edgegap.js
return call('POST', '/v2/deployments', {
  application: requireSetting('EDGEGAP_APP_NAME'),
  version: requireSetting('EDGEGAP_APP_VERSION'),
  users: locations.map((l) => ({ user_type: 'geo_coordinates', user_data: l })),
  tags: [matchTag(matchId), 'playfab'],
  environment_variables: [
    { key: 'PLAYFAB_MATCH_ID', value: matchId, is_hidden: false },
    { key: 'PLAYFAB_QUEUE_NAME', value: queueName, is_hidden: false },
    {
      key: join.ENV_KEY, // EDGEGAP_JOIN_TOKENS
      value: players.map((p) => join.joinToken(matchId, p.playFabId)).join(','),
      is_hidden: true,
    },
  ],
  webhook_on_ready: { url: webhook.toString() },
  webhook_on_error: { url: errorWebhook.toString() },
});
```

### EdgegapDeploymentReady

由 Edgegap 通过 ready webhook 调用，而不是由 PlayFab 调用，因此不要在 PlayFab 中注册它。

1. 它不信任 webhook 请求正文：它会从 Edgegap API 读取部署信息，并检查该部署是否带有此比赛的标签。
2. 它会再次从 PlayFab 读取比赛成员。
3. 它会将 `{"matchId", "status", "host", "port", "joinToken"}` 写入每位玩家的 **只读** 数据，键为 `EdgegapServer`，使用 `Server/UpdateUserReadOnlyData`。客户端可以读取，但不能修改。如果服务器启动失败，它会写入
4. 如果服务器启动失败，它会写入 `status: "error"`，这样客户端就会停止等待。

### 注册函数并添加规则

1. 在 **自动化 → CloudScript → 函数 → 注册函数**中，使用包含 `StartEdgegapDeployment` 的 URL 注册该函数，并包含 `?code=<function key>`.
2. 在 **自动化 → 规则 → 新建规则**中，将事件类型设为 `playfab.matchmaking.match_found` 并添加操作 **执行 Azure 函数 → StartEdgegapDeployment**.

{% hint style="info" %}
创建规则后，针对同一场比赛手动调用 `StartEdgegapDeployment` 会启动第二台服务器。请先手动测试这些函数，再添加规则。
{% endhint %}

## 4. 游戏客户端

1. 让玩家登录 PlayFab（示例使用 `LoginWithCustomID`；请使用你游戏中的登录方式）。客户端只持有你的标题 ID。
2. 在队列中创建匹配票据，使用 `Match/CreateMatchmakingTicket`，并使用 `Match/GetMatchmakingTicket` 每 6 秒检查一次，直到其状态变为 `Matched`。PlayFab 对每张票据每分钟允许检查 10 次。
3. 使用 `EdgegapServer` 调用 `Client/GetUserReadOnlyData` 每 2 到 3 秒读取一次。忽略 `matchId` 不是当前这场匹配的值：它是之前匹配留下的。
4. 连接到 `host:port`，并在连接建立后立即发送 `joinToken` 。如果收到 `status: "error"`，则显示错误并允许玩家重新排队。

示例中的 `PlayFabMatchmakingClient.cs` 仅使用 `UnityWebRequest` 和 `JsonUtility` 实现了上述功能，没有使用 PlayFab SDK。唯一与网络代码相关的部分是连接调用：

```csharp
// FishNet（Tugboat UDP）；JoinTokenAuthenticator 在连接后发送令牌
JoinTokenAuthenticator.Install(InstanceFinder.NetworkManager).Token = joinToken;
InstanceFinder.TransportManager.Transport.SetClientAddress(host);
InstanceFinder.TransportManager.Transport.SetPort(port);
InstanceFinder.ClientManager.StartConnection();
```

如果你的游戏已经使用 PlayFab SDK，请通过该 SDK 进行相同的调用。

## 5. 测试

1. 确保没有其他部署正在运行：免费套餐一次只能运行一个部署。
2. 以两个不同的 PlayFab 玩家身份启动两个客户端。在同一台机器上，它们会共用 PlayerPrefs，因此请为每个客户端指定不同的 ID：示例使用 `-playfabCustomId player-a` 和 `-playfabCustomId player-b`.
3. 在两个客户端上都启动匹配。PlayFab 为它们匹配成功后，Edgegap 仪表板中会出现一个部署，其标签以匹配 ID 的开头部分标记， [Edgegap 仪表板](https://app.edgegap.com/deployment-management/deployments/list)；几秒后，两个客户端都会连接到该部署。
4. 退出两个客户端：服务器会自行停止。

| 症状                                           | 解决方法                                                                                                         |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `登录时出现` PlayerCreationDisabled               | 取消勾选 **使用 Client/LoginWithCustomId 禁用玩家创建** （步骤 2）。                                                          |
| 已匹配，但没有服务器地址                                 | 检查 Function App 日志（Application Insights，或每个函数的 Monitor 选项卡），并确认规则的事件类型完全是 `playfab.matchmaking.match_found`. |
| `Edgegap POST /v2/deployments failed (401)`  | `EDGEGAP_API_TOKEN` 不正确，或者仍带有 `token` 前缀。                                                                    |
| Webhook 未写入任何内容                              | `EDGEGAP_READY_WEBHOOK_URL` 必须包含 `code=` 键值 `EdgegapDeploymentReady`.                                        |
| 两个客户端都以同一玩家身份登录                              | 使用不同的 `-playfabCustomId` 值运行它们。                                                                              |
| 部署已启动，但无人连接                                  | 问题出在服务器：手动部署你的版本并直接加入。                                                                                       |
| 服务器日志 `rejected: not a player of this match` | 客户端未发送令牌，或发送了来自其他比赛的令牌。请检查这两个函数是否运行相同的代码，并使用相同的 `PLAYFAB_SECRET_KEY`.                                        |

要从 PlayFab Multiplayer Servers 迁移？请参阅 [从 PlayFab 迁移](https://docs.edgegap.com/zh/docs/tuo-guan-qian-yi/switch-from-playfab.md) 了解需要进行哪些更改。

想使用无需运行函数的托管式匹配器？请参阅 [Edgegap 匹配服务](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md).
