了解Edgegap的工作原理

對局配對

和

托管与编排

整合

PlayFab

部署至 Edgegap

已发布

2026/10/16

最近一次准确性审核

2026/10/28

PlayFab：如何通过 PlayFab 匹配启动 Edgegap 专用服务器

本指南向您展示如何继续使用 PlayFab 管理玩家账户和匹配队列，并为每场比赛启动 Edgegap 专用游戏服务器：当 PlayFab 找到匹配时，一个 Azure Function 会在玩家附近部署一台服务器，另一个 Azure Function 则将该服务器的地址分发给每位玩家。

一旦您的游戏服务器完成容器化，Edgegap 只需通过一个简单的 API 调用，即可在全球 615+ 个边缘云节点（按需）部署它，并完全按用量计费：无需在比赛间隙租用、配置或维持整台服务器运行。对于需要保留容量的持久服务器，Edgegap 提供了专用队列 (Private Fleets)。

PlayFab 负责玩家分组；Edgegap 负责承载比赛。这两个函数在您的 Azure 订阅中作为 PlayFab 的 CloudScript using Azure Functions 运行，因此您的 Edgegap API 令牌和 PlayFab 密钥均保留在那里：游戏客户端仅保存您的 Title ID，而游戏服务器则完全不保存任何密钥。

本指南涵盖：

准备可用的 Edgegap 应用版本、PlayFab Title 和 Azure 订阅
将您的代码辅助代理 (Coding Agent) 连接到 Edgegap（可选）
设置 PlayFab 匹配队列
添加用于部署服务器的 Azure Function
将服务器地址分发给玩家
从您的游戏客户端匹配玩家
使用两名玩家进行测试

您可以通过两种方式进行操作，也可以将它们结合使用：

使用代码辅助代理。 将 Claude Code、Cursor 或其他代理连接到 Edgegap MCP 服务器及其代理技能 (agent skills)。edgegap-playfab 技能附带了经过测试的 Azure Functions、设置脚本和一个 Unity 客户端，并且代理会检查您的应用版本和部署情况。您只需负责管理 PlayFab、Azure 和 Edgegap 仪表板、密钥以及进行游戏测试。
手动操作。 以下每个步骤在没有代理的情况下也完全适用。

想先看看它的实际效果？ SpaceEdge 示例在一个小巧的 Unity 太空射击游戏中运行了整套配置。

与工程师联系

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

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮件。测试无需信用卡。
游戏服务器的一个可用 Edgegap 应用版本：您已至少部署并加入过一次的服务器。PlayFab 会为每场比赛启动该版本，因此它需要一个功能完备的容器化游戏服务器来实现端到端运行。如果您目前还没有，请参考我们的指南：Unity Engine、Unreal Engine、Godot Engine 或 Custom Engine。将其游戏端口命名为 gameport，并记下应用程序名称和版本名称。该服务器不需要任何 PlayFab 设置或机密。
具备匹配功能的 PlayFab title，以及访问其 Game Manager 的权限：您需要其 Title ID 和一个密钥。
一个 Azure 订阅和 Azure CLI，用于两个 Azure Functions。测试适合使用弹性消耗（Flex Consumption）计划的每月免费额度。
一个 Edgegap API 令牌，可从仪表板 → 用户设置 → 令牌获取。它仅配置在您的 Function App 设置中。它适用于整个组织，因此切勿将其放入游戏客户端、游戏服务器、项目文件或聊天中。
可选：Edgegap 的 PlayFab 示例，这是一个 Unity 2021.3 项目，包含两个 Azure Functions 以及下面的客户端和服务器代码。

2. 将您的代码代理连接到 Edgegap

如果您全程手动操作，请跳过此步骤。

Edgegap MCP 服务器允许您的 Agent 检查应用程序及其版本、部署测试服务器，并读取您账户上的日志。edgegap-playfab Agent 技能为其提供了经过测试的 PlayFab 配置：两个 Azure Functions、用于部署它们并创建队列的脚本、一个 Unity 客户端，以及针对 PlayFab 已知问题的修复方案。

Claude Code：安装 Edgegap 插件。它会同时添加 MCP 服务器和技能，并在安装期间要求提供您的 API 令牌（存储在系统的凭据存储区中）：

/plugin marketplace add edgegap/llm-agent-skills，然后运行 /plugin install edgegap@edgegap。重启会话。

仅需要 MCP 服务器，不需要插件？请在您自己的终端中运行以下命令：claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user。请勿同时执行这两种操作，否则将存在两个 edgegap 服务器。

Cursor、VS Code 以及其他支持发送 Header 的客户端：添加 https://mcp.edgegap.dev/mcp 并附带 Header Authorization: token YOUR_EDGEGAP_API_TOKEN，然后使用 npx skills add edgegap/llm-agent-skills --skill "*" 安装技能。

Claude Desktop：自定义连接器无法发送 Header，因此请改用本地服务器（Node 18+）：{ "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }。首次使用时它会要求输入令牌。

检查是否正常运行：

“列出我的 Edgegap 应用程序及其版本，包括每个版本的端口。”

3. 设置 PlayFab 匹配队列

在 PlayFab 的 Game Manager 中，打开多人游戏 → 匹配并创建一个队列，或者复用现有队列。对于初次测试，无规则且匹配人数为 2 的队列会将任意两名玩家匹配在一起。
在队列上关闭启用服务器分配：PlayFab 仅负责组建比赛，而 Edgegap 负责托管服务器。
如果您的游戏使用 LoginWithCustomID 或设备 ID 登录玩家，请打开Title settings → API Features，并取消勾选 Disable player creation using Client/LoginWithCustomId。新标题默认会勾选该项，从而导致登录失败并显示 PlayerCreationDisabled。
在 Title settings → Secret Keys 中，为 Azure Functions 创建一个密钥。

您的比赛规则仍保留在 PlayFab 中。PlayFab 找到匹配项后，Edgegap 才会启动服务器。

是否要将现有队列从 PlayFab Multiplayer Servers 迁出？您已发布的客户端会从 GetMatch 读取服务器信息，一旦关闭分配，该接口将不再返回服务器信息。请在队列的副本上进行测试，并在切换之前发布新的客户端。

4. 添加用于部署服务器的 Azure Function

函数应用（Function App）。在美国西部（US West）区域（PlayFab 推荐）创建一个资源组、一个存储账户和一个基于 Node.js 22 的 Flex Consumption 函数应用。在其设置中，添加 PLAYFAB_TITLE_ID、PLAYFAB_SECRET_KEY、EDGEGAP_API_TOKEN（不带 token 前缀）、EDGEGAP_APP_NAME、EDGEGAP_APP_VERSION、EDGEGAP_PORT_NAME（可选，默认为 gameport）和 EDGEGAP_READY_WEBHOOK_URL（步骤 5）。可选：FALLBACK_LATITUDE / FALLBACK_LONGITUDE，在 PlayFab 无法定位任何玩家时使用。

函数。 StartEdgegapDeployment：

从找到匹配项（match-found）事件中读取 MatchId 和 QueueName。
获取匹配成员，并通过 Server/GetPlayerProfile 获取每位玩家的位置（PlayFab 会对其登录 IP 进行地理定位）。
调用 POST https://api.edgegap.com/v2/deployments，附带您的 application 和 version、作为 users 的玩家信息（"user_type": "geo_coordinates"）、带有匹配 ID（前 20 个字符）的标签、作为 environment_variables 的 PLAYFAB_MATCH_ID 和 PLAYFAB_QUEUE_NAME，以及指向第二个函数的 webhook_on_ready / webhook_on_error。
立即返回，大约需要一秒钟。它绝不等待服务器：PlayFab 的调用在 10 秒后超时，而服务器需要 5 到 30 秒才能就绪。

Edgegap 为整个组挑选最佳可用位置，并以 request_id 作为响应。将其与匹配 ID 一起记录在日志中。

match_found 会针对您游戏标题的每个队列触发。若要仅为部分队列提供 Edgegap 服务器，请在 EDGEGAP_QUEUES 中列出它们。

注册函数并添加规则。在 Automation → CloudScript → Functions 中，使用其 URL 和函数密钥注册 StartEdgegapDeployment。然后在 Automation → Rules 中添加一条规则：事件类型为 playfab.matchmaking.match_found，操作为 Execute Azure Function，函数为 StartEdgegapDeployment。

配合您的智能体（Agent）：

“加载 edgegap-playfab 技能。将其中的两个 Azure Functions 部署到美国西部新建的 Flex Consumption 函数应用中，从我的本地环境文件读取并配置应用程序设置而不打印它们，在我的 PlayFab 标题中注册 StartEdgegapDeployment，并在我添加规则之前运行链路测试。”

妥善保管机密信息：Edgegap 令牌和 PlayFab 密钥仅保存在函数应用的设置中。函数密钥也是机密信息：它们包含在 URL 中，因此切勿提交或共享这些 URL。

5. 将服务器地址提供给玩家

当服务器准备就绪时，Edgegap 会通过就绪 webhook 调用第二个函数 EdgegapDeploymentReady。是由 Edgegap 发起调用，而不是 PlayFab，因此请勿在 PlayFab 中注册它。

它不信任 webhook 正文：它会从 Edgegap API 读取部署信息，并检查该部署是否带有本次比赛的标签。
它会再次从 PlayFab 读取比赛成员信息。
它会将 {"matchId", "status", "host", "port"} 写入每位玩家的只读数据中，键名为 EdgegapServer。客户端可以读取但无法修改它。
如果服务器发生故障，它会写入 status: "error"，以便客户端停止等待。

游戏服务器只需监听其端口，并在比赛结束时自行停止：它会使用 ARBITRIUM_DELETE_TOKEN 调用 Edgegap 提供给每个部署的 ARBITRIUM_DELETE_URL。该示例在 120 秒内无人加入，或最后一名玩家离开 30 秒后停止。

在生产环境中，请将比赛的玩家 ID 传递给服务器（例如作为来自 StartEdgegapDeployment 的环境变量），并拒绝不在比赛中的玩家。

6. 从游戏客户端匹配玩家

客户端将玩家登录到 PlayFab（示例使用 LoginWithCustomID；请使用你游戏的登录方式）。它仅包含你的 Title ID。
它会在你的队列中创建一个匹配票证（CreateMatchmakingTicket），并每 6 秒使用 GetMatchmakingTicket 检查一次，直到状态变为 Matched。PlayFab 允许每个票证每分钟进行 10 次检查。
然后，它每 2 到 3 秒使用 GetUserReadOnlyData 读取一次 EdgegapServer，并忽略 matchId 不属于本次匹配的任何值。
它会连接到 host:port。如果出现 status: "error"，它会显示错误并允许玩家重新排队。

示例的 Unity 客户端仅使用 UnityWebRequest 和 JsonUtility 执行此操作，无需 PlayFab SDK。如果你游戏已在使用该 SDK，请通过该 SDK 进行相同的调用。

7. 双人测试

确保没有仍在运行的测试部署：免费层一次只能运行一个部署。
以两个不同的 PlayFab 玩家身份登录两个客户端，并在两端都开始对战匹配。在同一台机器上，为每个客户端分配其专属的玩家 ID：示例中使用 -playfabCustomId player-a 和 -playfabCustomId player-b。
当 PlayFab 完成匹配时，规则会运行 StartEdgegapDeployment。在 Edgegap 仪表板中，会显示一个带有匹配 ID 开头标签的部署，位置在距离您较近的地点。
两个客户端都会从其只读数据中读取地址，并连接到同一个服务器。
退出两个客户端：服务器会自动停止并从仪表板中消失。

匹配成功，但没有获取到地址？请检查 Function App 的日志（Application Insights，或每个函数的“监视”选项卡），并确认规则的事件类型严格为 playfab.matchmaking.match_found。Edgegap 返回 401 意味着令牌错误或仍然带有 token 前缀。部署已启动但无人连接？这是服务器的问题：请手动部署您的版本并直接加入。

后续步骤

准备上线？让您的智能体运行 edgegap-launch 技能清单：版本推出、重启策略、最长持续时间、成本控制。更倾向于无需脚本的托管撮合系统？查看 Edgegap 的撮合系统（matchmaker）。

遇到困难？让您的智能体加载 edgegap-troubleshoot，或在 Edgegap Discord 上向我们的团队和其他工作室咨询。

常见问题

关于在 Edgegap 专属服务器上托管 PlayFab 对局的常见问题。

我可以将 PlayFab 匹配与 Edgegap 服务器一起使用吗？

是的。保留您的 PlayFab 队列和规则，并关闭服务器分配。当 PlayFab 找到匹配项时，由匹配成功事件触发的 Azure Function 会在玩家附近部署一个 Edgegap 服务器，并且第二个函数会将其地址写入每个玩家的只读数据中。

我还需要 PlayFab Multiplayer Servers 吗？

不。Edgegap 托管专用服务器。PlayFab 保留您的账户、玩家数据和匹配，并且 Edgegap 仅在找到匹配时才启动服务器，在其运行期间按分钟计费。

Edgegap 是如何为 PlayFab 对局选择服务器位置的？

根据每位玩家的位置（Azure Function 从其 PlayFab 个人资料中读取该位置并作为坐标发送），Edgegap 会为整个群组挑选最佳的可用位置。

我的 Edgegap API 令牌应该放在 PlayFab 的哪里？

仅在您的 Azure Function App 设置中，配合您的 PlayFab 密钥。游戏客户端仅保留 Title ID，游戏服务器不保留任何密钥。

玩家如何从 PlayFab 获取服务器地址？

当服务器准备就绪后，Edgegap 会调用一个 Webhook 函数来检查部署情况，并将其主机和端口写入每个匹配玩家的只读数据中。然后，每个客户端读取该数据并进行连接。

我可以使用传统的旧版 CloudScript 来代替 Azure Functions 吗？

相同的规则和事件驱动两者，但 Microsoft 将 JavaScript CloudScript 标记为“旧版”，并将新工作指向使用 Azure Functions 的 CloudScript。Azure Functions 还可以让部署调用立即返回，并接收 Edgegap 的就绪 Webhook。