了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Nakama

部署至 Edgegap

已发布

2026/10/16

最近一次准确性审核

2026/10/16

Nakama：如何通过 Nakama 匹配系统启动 Edgegap 专用服务器

本指南向您展示如何保留 Heroic Labs 的 Nakama 用于您的账户、社交功能和匹配系统，并为每场比赛启动一个 Edgegap 专属游戏服务器：当 Nakama 的匹配系统将玩家分组时，Nakama 会在他们附近部署一个服务器，并将服务器地址发送给每个玩家。

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

Nakama 和 Edgegap 通过 Edgegap 的 Nakama Fleet Manager 插件进行连接，这是与 Heroic Labs 共同维护的经过验证的集成方案。它在您的 Nakama 服务器内部运行，因此您的 Edgegap API 令牌始终保留在后端，绝不会发送给游戏客户端。

本指南涵盖：

准备可用的 Edgegap 应用版本和 Nakama 服务器
将您的代码助手 (Coding Agent) 连接到 Edgegap（可选）
将 Edgegap Fleet Manager 添加到 Nakama
对其进行配置
向 Nakama 上报游戏服务器的状态
在 Nakama 的匹配系统找到比赛时启动服务器
使用两名玩家进行测试

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

使用代码助手。将 Claude Code、Cursor 或其他 Agent 连接到 Edgegap MCP 服务器及其 Agent 技能。Agent 会编写 Nakama 模块和游戏服务器调用，并检查您的应用版本和部署情况。您只需负责 Nakama 和 Edgegap 的控制面板、机密信息以及游玩测试。
手动操作。以下每个步骤也可以在没有 Agent 的情况下完成。

Nakama

Edgegap

得到 Mirror Networking 创建者的完全认可

英雄实验室

“借助 Edgegap，Nakama 开发者能够更智能地进行扩展，获得实时编排能力、真正的超低延迟以及前所未有的成本效益”

在我们的博客上阅读更多内容

Mo Firouz

Heroic Labs 首席运营官兼联合创始人

@mofirouz

与工程师联系

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

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮箱。测试无需信用卡。
一个可正常运行的 Edgegap 应用版本的游戏服务器：即您已成功部署并至少加入过一次的服务器。Nakama 会为每场比赛部署该版本，因此它需要一个功能完备的容器化游戏服务器来实现端到端运行。如果您目前还没有，请参考我们的指南：Unity Engine、Unreal Engine、Godot Engine 或 Custom Engine。请记下其应用名称、版本名称和端口名称（通常为 gameport）。
一个 Nakama 服务器，您可以向其添加 Go 运行时模块：可通过 Docker 自托管，或在 Heroic Cloud 上托管。
一个 Edgegap API 令牌，可从控制面板 → 用户设置 → 令牌获取。它仅用于您的 Nakama 服务器配置。该令牌适用于整个组织，因此切勿将其放入您的游戏客户端、游戏服务器、项目文件或聊天中。

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

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

Edgegap MCP 服务器允许您的智能体在您的账户上查看应用程序和版本、部署测试服务器并读取其日志。edgegap-nakama 智能体技能为其提供了用于启动 Edgegap 服务器（包括 Nakama）的经测试后端的规则。

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 以及其他发送标头的客户端：添加包含标头 Authorization: token YOUR_EDGEGAP_API_TOKEN 的 https://mcp.edgegap.dev/mcp，并使用 npx skills add edgegap/llm-agent-skills --skill "*" 安装技能。

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

检查是否正常运行：

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

3. 将 Edgegap Fleet Manager 添加到 Nakama

该插件实现了 Nakama 的 Fleet Manager（队列管理器）：Nakama 向其请求服务器，它会在 Edgegap 上部署一个服务器并在 Nakama 的存储中进行跟踪。

自托管 Nakama：使用 go get github.com/edgegap/nakama-edgegap 将 Go 软件包添加到您的运行时模块中，然后在模块的 InitModule 中注册它：

fleetmanager.NewEdgegapFleetManager(ctx, logger, db, nk, initializer)，然后调用 initializer.RegisterFleetManager(efm)。
initializer.RegisterAfterAuthenticateCustom(fleetmanager.OnAuthenticateUpdateCustom)：在每位玩家登录时存储其公网 IP，以便 Edgegap 能够将服务器部署在离整组玩家较近的位置。
initializer.RegisterMatchmakerMatched(...)：用于步骤 6 的回调。

对于本地测试，该仓库包含一个 docker-compose.yml 和 Dockerfile：docker compose up --build -d。

Heroic Cloud：从 nakama-edgegap 仓库（或包含您自己模块代码的复刻仓库）创建一个 Builder。

配合您的智能体（Agent）：

“加载 edgegap-nakama skill。将 github.com/edgegap/nakama-edgegap 添加到我的 Nakama Go 模块中：注册 Edgegap Fleet Manager、用于存储玩家 IP 的认证后钩子，以及一个撮合成功（matchmaker-matched）回调，该回调可为匹配的用户创建 Edgegap 实例并通知他们。从环境变量中读取所有设置。”

4. 配置车队管理器

在您的 Nakama 服务器上设置这些环境变量（在 Heroic Cloud 上，位于您的实例配置中）：

EDGEGAP_API_URL：https://api.edgegap.com
EDGEGAP_API_TOKEN：您的 API 令牌，包含其 token 前缀。请将其保存在您的机密存储中。
EDGEGAP_APPLICATION：您的 Edgegap 应用程序名称。
INITIAL_EDGEGAP_VERSION：要部署的应用版本，在您设置另一个版本之前一直使用。
EDGEGAP_PORT_NAME：玩家连接的端口，通常为 gameport。
NAKAMA_ACCESS_URL：Nakama 服务器的公开 https:// 地址，游戏服务器会对其进行回调。

可选配置：EDGEGAP_POLLING_INTERVAL（默认 15 分钟）、NAKAMA_CLEANUP_INTERVAL（1 分钟）和 NAKAMA_RESERVATION_MAX_DURATION（30 秒）。在生产环境中保持这两个后台工作进程处于开启状态。

发布新的服务器版本而无需重启 Nakama：使用您的 Nakama HTTP 密钥调用服务器对服务器 RPC update_edgegap_version，附带 {"version": "..."}。它会先检查 Edgegap 上是否存在该版本。游戏客户端无法调用它。

5. 向 Nakama 上报游戏服务器状态

Nakama 会跟踪其启动的每个服务器：它是否已就绪、谁已连接以及剩余多少空位。您的游戏服务器会通过插件注入到每个部署中的三个环境变量来向其汇报：

NAKAMA_INSTANCE_EVENT_URL：一旦服务器开始接受玩家，发送 READY；如果无法开始比赛，发送 ERROR；当比赛结束时，发送 STOP。收到 STOP 后，Nakama 会停止 Edgegap 部署。
NAKAMA_CONNECTION_EVENT_URL：发送已连接用户 ID 的完整列表，大约每 5 秒批量发送一次。
NAKAMA_INSTANCE_METADATA：Nakama 创建服务器时所使用的比赛详细信息，格式为 JSON。

Unity：Edgegap Server Nakama Plugin for Unity 会为您进行这些调用。其他引擎：通过您的服务器代码发起三次简短的 HTTP 调用。

使用您的智能体：

“在我的游戏服务器中，读取 NAKAMA_INSTANCE_EVENT_URL、NAKAMA_CONNECTION_EVENT_URL 和 NAKAMA_INSTANCE_METADATA。服务器开始监听后立即随实例 ID 发送 READY，每 5 秒发送一次已连接的用户 ID，并在比赛结束时发送 STOP。”

6. 当 Nakama 找到匹配时启动服务器

玩家像往常一样从您的游戏客户端加入 Nakama 的匹配系统（使用 Nakama 客户端 SDK 中的 AddMatchmaker）。
当 Nakama 将他们分组时，您的匹配成功回调会收集匹配的用户 ID，并带上匹配规模和这些用户调用 Fleet Manager 的 Create。
Fleet Manager 会在玩家附近部署您的应用版本，并等待服务器返回 READY。
每位玩家都会收到一条主题为 connection-info 的 Nakama 通知，其中包含：IpAddress、DnsName、Port 和 InstanceId。客户端将连接到该地址和端口。如果服务器无法启动，玩家则会收到 create-timeout 或 create-failed：此时将他们重新放回队列中。