自定义引擎：如何在专用服务器上托管您自己的游戏服务器，并添加對局配對

本指南向您展示如何在 Edgegap 的专用游戏服务器上托管基于您自研引擎构建的多人游戏，或使用任意语言（C++、C#、Go、Rust、Java 等）编写的游戏服务器，随后添加匹配功能，以便玩家能够自动分组并连接到离他们最近的服务器。

一旦您的游戏服务器完成容器化，Edgegap 只需通过一个简单的 API 调用即可将其（按需）部署到全球 615+ 个边缘云节点，并完全按用量计费：无需租用整台服务器、预配置或在比赛间隙保持其运行。对于需要预留容量的持久化服务器，Edgegap 提供了 Private Fleets。Edgegap 的匹配服务构建于此基础之上，并且是可选的。

Edgegap 不需要 SDK，也不需要引擎插件。只要您的服务器可以在 Linux 容器中以无头（headless）模式运行，它就能在 Edgegap 上运行：您推送一个镜像，Edgegap 会为每场比赛启动该镜像的一个副本，并将地址提供给玩家。本页面介绍了您的服务器为了契合该模式需要遵循的几项规则。

本指南涵盖：

准备您的服务器、Edgegap 账户和容器化工具
将您的编码智能体连接到 Edgegap（可选）
让您的服务器契合 Edgegap 的生命周期
将其容器化并创建应用版本
在本地进行测试，然后部署测试服务器
添加匹配功能（可选）
使用两名玩家测试完整闭环

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

使用编码智能体。将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器及其智能体技能。智能体会适配您的服务器、编写 Dockerfile、测试容器、进行部署并生成匹配器配置。您只需负责 Edgegap 控制面板、机密信息配置和游戏试玩测试。
手动操作。以下所有步骤均可在不使用智能体的情况下完成。

正在使用 Unity、Unreal Engine 或 Godot 构建游戏？请改为从 Unity 引擎、Unreal Engine 或 Godot 引擎开始。

与工程师联系

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

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮箱。测试无需信用卡。
一个可在 Linux x86-64 上以无头模式运行的游戏服务器：无窗口、无 GPU、无输入提示，通过命令行标志或环境变量进行配置。两名玩家应能够在 localhost 上加入该服务器。
一个主导游戏逻辑的权威服务器。客户端发送输入；服务器决定位置、击中情况和得分。仅转发客户端声明内容的服务器只是一种昂贵的中继，并且很容易被作弊。
一个处于运行状态的容器化工具。我们推荐使用 Docker Desktop。
对于 Agent 路径：一个 Edgegap API 令牌，获取自控制面板 → 用户设置 → 令牌。它是组织级别的，因此请像对待密码一样对待它：切勿将其放入您的服务器、游戏客户端、项目文件或聊天工具中。

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

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

Edgegap MCP 服务器允许您的智能体在您的账户上创建应用和版本、部署服务器、读取日志并生成撮合系统配置。智能体技能为其提供了与引擎无关的规则：用于生命周期的 edgegap-server-design、用于镜像的 edgegap-containerize，以及在您花钱之前的 edgegap-local-testing。

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 和其他发送请求头的客户端：添加 https://mcp.edgegap.dev/mcp 并带上请求头 Authorization: token YOUR_EDGEGAP_API_TOKEN，然后使用 npx skills add edgegap/llm-agent-skills --skill "*" 安装技能。

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

检查其是否正常工作：

“列出我的 Edgegap 应用。”

返回空列表是正常的。关于令牌的错误通常意味着请求头被写成了 token token ...。

3. 让您的服务器适配 Edgegap 的生命周期

在 Edgegap 上，一次部署通常对应一场对局：它为一组玩家启动，并在他们的对局结束时停止。您的服务器需要遵循以下六条规则：

绑定在 0.0.0.0 上的固定端口，例如 7777/UDP。Edgegap 会在每次部署时为玩家分配一个随机的外部端口，并将其映射到您的端口。绑定 127.0.0.1 或随机端口可以在您的本地机器上运行，但在 Edgegap 上将无法访问。
从环境变量中读取配置。Edgegap 会将它们注入到每次部署中：ARBITRIUM_REQUEST_ID（部署 ID；建议记录日志）、ARBITRIUM_PORT_GAMEPORT_INTERNAL 和 _EXTERNAL、ARBITRIUM_PUBLIC_IP，以及在匹配系统部署中的 MM_MATCH_ID 和 MM_TICKET_IDS（匹配成功的对象）。您自己的设置则配置在应用版本或部署上。
一旦开始接受玩家，向 stdout 记录一行清晰的日志，例如 READY port=7777。日志应输出至 stdout 和 stderr，绝不能仅写入文件。
在对局结束时自动停止服务器，或者在无玩家连接约 30 秒后停止：使用请求头 Authorization: <ARBITRIUM_DELETE_TOKEN> 向 ARBITRIUM_DELETE_URL 发送 DELETE 请求。处于空闲状态的服务器会持续计费，直至达到其最长运行时长。
处理 SIGTERM 信号：将结果保存至后端，通知玩家，并在几秒钟内退出。
限制您的 tick 率或帧率。无上限运行的无头（headless）循环会耗尽整个 CPU 核心。20 到 30 Hz 适用于大多数动作游戏，60 Hz 适用于快节奏射击游戏。

您的服务器绝不会持有 Edgegap API 令牌：自动停止功能拥有自己独立的、按每次部署生成的令牌。

配合您的智能体使用：

“加载 edgegap-server-design 技能并让我的游戏服务器适配 Edgegap：在固定端口上绑定 0.0.0.0，读取 ARBITRIUM_ 和 MM_ 环境变量，在开始接受玩家时记录 READY 日志，在对局结束或无玩家连接 30 秒后通过 ARBITRIUM_DELETE_URL 自动停止，在收到 SIGTERM 时安全退出，并限制 tick 率。然后检查它是否仍可在两个本地客户端下正常运行。”

4. 将您的服务器容器化并创建应用版本

Edgegap 运行 linux/amd64 容器。请在 Docker 外部构建服务器，或者针对编译型语言在构建阶段进行构建，然后仅将服务器复制到精简镜像中：

将其作为容器的主进程启动，采用 exec 格式：ENTRYPOINT ["./my-server"]。置于其前面的 Shell 脚本会吞掉 SIGTERM 信号；如果您需要使用 Shell 脚本，请以 exec ./my-server "$@" 结尾。
针对 Edgegap 平台进行构建，即使在 Apple Silicon 上也是如此：docker build --platform linux/amd64 -t registry.edgegap.com/<project>/<image>:<tag> .
镜像中不得包含敏感信息，且绝不要在启动时打印环境变量：这会导致自停止令牌暴露在日志中。
推送到 Edgegap 容器镜像仓库：使用来自容器镜像仓库页面的用户名和令牌自行运行 docker login registry.edgegap.com，然后执行 docker push。每次构建都请使用新标签，切勿使用 latest。Docker Hub、GHCR、ECR、GCP 和 GitLab 镜像仓库也同样支持。

然后在控制面板中创建应用程序及其版本：设置您的镜像和标签、镜像仓库凭据（若缺少凭据，部署将失败并提示“Unable to pull image from registry”）、初始配置 1 vCPU 和 2 GB、端口及其协议命名为 gameport，重启策略设为从不 (Never)。

配合您的智能体使用：

“加载 edgegap-containerize 技能。为我的 linux/amd64 服务器编写一个多阶段构建 Dockerfile，使用新标签构建并推送它，然后创建 Edgegap 应用及应用版本，配置我的端口和协议，命名为 gameport，重启策略设为 never。”

5. 本地测试，然后部署到测试服务器

首先在本地进行，使用 Edgegap 会设置的环境变量：docker run --rm -p 7777:7777/udp -e ARBITRIUM_PORT_GAMEPORT_INTERNAL=7777 <image>:<tag>。将客户端连接到 127.0.0.1:7777，然后使用 docker stop 停止容器，并检查您的服务器是否正常退出。

然后在 Edgegap 上进行。从控制面板部署您的版本（点击 Deploy，选择一个离您较近的位置），或者让您的智能助手执行：“在离我较近的位置部署我最新的 Edgegap 版本，等待就绪，显示日志，并向我提供地址和外部端口。”

当部署状态为 Ready 时，将客户端连接到其主机 URL（或 IP）和外部端口。每次部署时外部端口都会发生变化。Ready 意味着容器已启动；您的服务器可能还需要几秒钟来加载，因此请让客户端重试最多一分钟。

完成后停止部署。免费层一次只能运行一个部署。

6. 添加匹配功能

Edgegap 的匹配器是一项托管服务：您的客户端发送票证（ticket），匹配器根据您的规则（比赛规模、队伍、延迟、技术水平、模式）将玩家分组，在他们附近部署您的服务器，并将服务器地址返回给每个客户端。无需链接任何库：它是一个 HTTP API。

编写配置：您的应用程序及版本、每场比赛的玩家人数，以及一条让单人玩家在测试时等待 20 秒后即可获得服务器的规则。您的智能体（Agent）可以生成该配置：“为我的应用版本生成 Edgegap 匹配器配置：一支 2 到 4 名玩家的队伍，单人玩家在 20 秒后获得服务器。”
在控制面板中，打开 Matchmaker，选择 Create Matchmaker，上传文件并选择 Create and Start。复制 API URL 和 Auth Token。Auth Token 可以安全地随游戏客户端一同发布。
在您的客户端中，使用 API URL 和 Auth Token 创建票证，然后检查其状态，直至状态从 SEARCHING 变为 MATCH_FOUND，再变为 HOST_ASSIGNED，并获取服务器的地址和端口。进行连接。