了解Edgegap的工作原理

對局配對

和

托管与编排

整合

PlayFab

SpaceEdge

PlayFab

SpaceEdge

部署至 Edgegap

已发布

2026/10/28

最近一次准确性审核

2026/10/29

SpaceEdge：在 Unity 中于 Edgegap 专用服务器上运行 PlayFab 匹配示例

SpaceEdge 是一款小型 Unity 太空射击游戏，端到端展示了 PlayFab 匹配与 Edgegap 的协同工作：PlayFab 负责玩家登录和匹配，每场对局都会获得其专用的 Edgegap 专属游戏服务器。

PlayFab 继续发挥其原有作用：账户、登录和匹配队列。当找到对局时，Azure Function 会在匹配玩家附近启动 Edgegap 服务器，随后第二个 Function 会告知每位玩家应连接到何处。

游戏中不包含机密信息：客户端仅持有您的 PlayFab title ID，游戏服务器不持有任何 PlayFab 或 Edgegap 凭据，且仅允许匹配成功的玩家加入。玩家离开后，服务器会自动停止运行。

Edgegap 的网络覆盖 615+ 个边缘云节点（了解更多）。每台服务器都会部署到最适合其玩家的可用位置，并且仅在对局进行期间计费。

克隆示例：GitHub 上的 SpaceEdge PlayFab 示例
完整指南：参考 PlayFab 集成指南将 Edgegap 添加到您自己的 PlayFab 游戏中

支持平台：Windows 桌面客户端（已测试）。使用 Edgegap Unity 插件构建的 Linux 专用服务器。客户端代码可以在 WebGL 中运行，但尚未对 WebGL 进行测试。

工作原理

玩家登录 PlayFab 并点击开始游戏 (Start Game)：客户端在 PlayFab 队列中创建匹配票证。
PlayFab 匹配两名玩家并触发 playfab.matchmaking.match_found 事件。该事件上的规则会运行 Azure Function StartEdgegapDeployment。
该函数查找每位玩家的位置，并请求 Edgegap 在他们附近进行部署，并使用比赛 ID 开头进行标记。返回大约需要一秒钟。
当服务器启动后，Edgegap 会调用第二个函数 EdgegapDeploymentReady。它通过 Edgegap API 检查部署情况，然后将服务器的主机、端口以及加入令牌写入每位玩家的只读 PlayFab 数据中。
两端客户端读取该地址，使用其加入令牌通过 UDP 连接并开始游戏。服务器会拒绝其他任何人。当他们离开后，服务器会自行停止部署。

代码库包含内容：

路径	功能描述
`azure-functions/`	两个 Azure Functions（Node.js 22，无需 PlayFab 或 Edgegap SDK）。
`.../PlayfabTest/PlayFabMatchmakingClient.cs`	客户端：登录、票证、等待匹配、等待服务器、连接。仅使用 `UnityWebRequest` 和 `JsonUtility`，无 PlayFab SDK。
`.../Edgegap/EdgegapServer.cs`	服务端：在服务器构建版本中启动游戏服务器，并在比赛结束时停止 Edgegap 部署。运行时自行添加，无需场景配置。
`.../Editor/EdgegapPluginBuild.cs`	命令行构建：Edgegap 插件的服务器构建版本和 Windows 测试客户端。
`.../Edgegap/JoinTokenAuthenticator.cs`	仅允许匹配成功的玩家加入：检查每个客户端发送的加入令牌。

与工程师联系

无需信用卡。免费版包含部署真实游戏服务器所需的资源。

分步指南

运行示例

1. 开始之前

一个免费的 Edgegap 账户以及从仪表板 → 用户设置 → 令牌获取的 API 令牌。它适用于整个组织，因此只需配置到 Function App 的设置中，绝不可放入游戏中。
Unity 2021.3 LTS（已在 2021.3.45f2 上测试），需包含 Linux Build Support 和 Linux Dedicated Server Build Support。
Docker Desktop，用于 Edgegap Unity 插件构建镜像。
一个 PlayFab Title。
一个 Azure 订阅和 Azure CLI。
克隆示例。

2. 将游戏服务器部署在 Edgegap 上

在 Unity 中打开 SpaceEdge_project，然后依次点击 Tools → Edgegap Server Hosting，并使用 Edgegap 登录。

点击 Build server，然后点击 Containerize with Docker：镜像名称为 playfab-fishnet，镜像标签留空（插件将使用当前 UTC 时间）。

点击 Upload to Edgegap：应用程序为 playfab-fishnet，然后点击 Upload image and Create app version。插件将推送镜像并打开版本表单：

若不使用编辑器，相同的服务器构建也可以从命令行运行：

"<Unity>" -batchmode -projectPath SpaceEdge_project -executeMethod EdgegapPluginBuild.BuildServer -logFile build-server.log

对于后续的构建，Rebuild from Source 可以一键完成构建、容器化和推送。

在版本表单中：

保留插件建议的镜像和版本名称（即镜像标签）。Azure Functions 需要该名称。如果表单要求提供注册表凭据，请使用容器注册表页面中的用户名和令牌。
一个端口：名称为 gameport，端口号 7770，UDP。函数将按该名称查找端口。
0.5 vCPU 和 1 GB。
最长持续时间为 60 分钟。服务器也会自行停止。

该版本不需要环境变量和机密信息：函数会将比赛详情和加入令牌传递给每个部署。

3. 设置您的 PlayFab Title

匹配队列 (Multiplayer → 匹配 → New queue)：名称为 edgegap-fishnet，匹配大小 2-2，Enable server allocation 关闭，因为服务器由 Edgegap 托管。匹配任意两名玩家无需规则。
Let clients create players（齿轮图标 → Title settings → API Features）：取消勾选 Disable player creation using Client/LoginWithCustomId。新 Title 默认已勾选此项，登录将失败并提示 PlayerCreationDisabled。
记下您的 Title ID，并为 Azure Functions 创建一个 Secret Key（Title settings → Secret Keys）。

4. 部署 Azure Functions

在 Node.js 22 上创建一个资源组、一个存储帐户和一个弹性消耗型（Flex Consumption）函数应用。PlayFab 建议选择美国西部区域：

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 目录下运行 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

添加应用设置（函数应用 → 设置 → 环境变量）：

PLAYFAB_TITLE_ID 和 PLAYFAB_SECRET_KEY：来自步骤 3。
EDGEGAP_API_TOKEN：您的 Edgegap 令牌，不包含 token 前缀。
EDGEGAP_APP_NAME / EDGEGAP_APP_VERSION：playfab-fishnet / 步骤 2 中的版本名称。EDGEGAP_PORT_NAME 为可选项，默认值为 gameport。
EDGEGAP_READY_WEBHOOK_URL：https://<function-app>.azurewebsites.net/api/EdgegapDeploymentReady?code=<function key>。
可选：EDGEGAP_QUEUES 用于仅向某些队列提供 Edgegap 服务器，以及针对 PlayFab 无法定位的玩家配置 FALLBACK_LATITUDE / FALLBACK_LONGITUDE。

使用 az functionapp function keys list -g rg-edgegap-playfab -n <function-app> --function-name <name> 获取每个函数的密钥。函数密钥属于敏感机密信息：请勿提交或分享包含这些密钥的 URL。

然后，在 PlayFab 中：

Automation → CloudScript → Functions → Register Function：命名为 StartEdgegapDeployment，并填入其 URL 和函数密钥。
Automation → Rules → New Rule：事件类型为 playfab.matchmaking.match_found，操作选择 Execute Azure Function → StartEdgegapDeployment。

不要注册 EdgegapDeploymentReady：该函数由 Edgegap 调用，而非 PlayFab。

5. 进行一场比赛

打开 SpaceEdge_project 以及场景 Assets/SpaceEdge/Scenes/MainMenu。
在 PlayfabRestApiService 对象（组件 PlayFabMatchmakingClient）上，设置 Title Id。Queue Name 已设置为 edgegap-fishnet。
确保没有其他部署正在运行：免费层一次只能运行一个。

您需要两名玩家。构建一个 Windows 客户端（Mono，因此不需要 Windows IL2CPP 模块）并运行两次，每次使用各自的 PlayFab 玩家：

"<Unity>" -batchmode -projectPath SpaceEdge_project -executeMethod EdgegapPluginBuild.BuildClient -logFile build-client.log

SpaceEdge_project/Builds/Client/win64/Game.exe -playfabCustomId player-a

SpaceEdge_project/Builds/Client/win64/Game.exe -playfabCustomId player-b

在两个客户端中均点击 Start Game。一旦 PlayFab 将它们匹配成功，标记有比赛 ID 开头的部署就会出现在 Edgegap 控制面板中，几秒钟后两个客户端都会连接到该部署。退出两个客户端：服务器将在几分钟内自动停止。

其他选项：-playfabTitleId <id>、-playfabQueue <name>，以及用于在登录后立即排队的 -autoMatch。对于无头测试客户端，请添加 -batchmode -nographics -client。

6. 将 PlayFab 匹配添加到你自己的游戏中

该示例是一个可用的参考：您的代码编写代理可以直接复制其经过测试的文件，而无需从头编写。通过四项更改，即可让游戏在 Edgegap 上配合 PlayFab 匹配运行：

PlayFab 仅负责匹配。在您的队列中关闭服务器分配，以便 PlayFab 组建比赛而由 Edgegap 进行托管。无需 GSDK，也无需 PlayFab 构建版本。
两个 Azure Functions 将它们连接起来。一个在 match_found 时在玩家附近部署服务器；另一个接收 Edgegap 的就绪 Webhook，并将地址和加入令牌写入每位玩家的只读数据中（azure-functions/，可直接用于任何引擎）。
服务器以无头模式运行并自行停止。它监听固定端口，不保存任何机密，仅允许匹配的玩家进入，并在无人加入或所有人离开时停止部署（EdgegapServer.cs）。该示例的网络代码是 FishNet；对于其他网络代码，请替换启动服务器和统计玩家人数的部分。
客户端等待其服务器。在 Matched 之后，它从其只读数据中读取 EdgegapServer，并使用其加入令牌连接到 host:port（PlayFabMatchmakingClient.cs，包含一个特定于网络代码的连接调用）。

配合您的代理使用：

“加载 edgegap 技能，然后加载 edgegap-playfab 以及适用于我的网络代码的技能。以 github.com/edgegap/backend-game-sample-unity-playfab-matchmaker-fishnet-spaceedge 为参考，为我的游戏添加一个可自行停止的无头服务器模式，将这两个 Azure Functions 部署到我的订阅中，并连接我的客户端以便在 PlayFab 中排队并连接到其只读数据中的地址。”

有关手动完成每个步骤的详细信息，请参阅 PlayFab 集成指南。

已知限制

每场比赛 2 名玩家。队列为 2-2，且仅对 2 人的队列进行了测试。对于规模更大的比赛，请增加队列的比赛规模并重新测试。
仅限 Windows 客户端。未测试 macOS 和 Linux 客户端版本。
未测试 WebGL。客户端代码避免了使用线程和 PlayFab SDK，因此它可以在浏览器中运行，但 Web 版本还需要一个带有 TLS Upgrade 的 WebSocket 端口。

测试了什么

于 2026 年 10 月 21 日在 Edgegap 上进行了端到端测试，使用 Unity 2021.3.45f2、Azure Functions（弹性消耗计划）上的 Node.js 22 以及大小为 2 的 PlayFab 队列：

两名客户端登录并通过 PlayFab 进行了匹配。
规则运行了 StartEdgegapDeployment，一台服务器在他们附近启动，函数调用后约 8 秒地址便发送给了两名玩家。
两人均连接到同一台服务器并进行了游戏。
服务器在玩家退出后自行停止，并在无人加入的情况下于启动 2 分钟后自行停止。

加入令牌（Join tokens）以及带有 Edgegap Unity 插件的构建版本是在此运行之后推出的。它们于 2026 年 10 月 29 日通过单元测试和本地服务器容器进行了测试：匹配成功的玩家顺利进入，其他任何人均被拒绝，且崩溃退出的玩家可以重新加入。未测试项目：WebGL 客户端、大于 2 的队列、基于延迟的队列规则。