了解Edgegap的工作原理

了解Edgegap的工作原理

對局配對

對局配對

和

和

托管与编排

托管与编排

整合

/

Colyseus

/

Colyseus

部署至 Edgegap

已发布

已发布

已发布

Colyseus：如何集成和托管专用服务器，并为您的多人游戏添加對局配對

Colyseus：如何集成和托管专用服务器，并为您的多人游戏添加對局配對

本指南将向您展示如何在 Edgegap 的专用游戏服务器上托管任意 Colyseus 多人游戏，然后添加对局配对功能，以便玩家能够自动分组并连接到距离他们最近的服务器。

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

您的房间、架构和客户端 SDK 保持不变。最简单的配置（也是本指南测试的配置）是为每场比赛分配其独立的 Colyseus 服务器：Edgegap 会在比赛玩家附近启动它，并在比赛结束时自动停止，因此您不需要 PM2、Redis 在线状态管理或房间数量的容量规划。一台服务器也可以托管多个房间，例如一个大厅及其比赛：即使某个房间仍处于开启状态，它也会在最后一名玩家离开 30 秒后停止。对于常开服务器，请使用 Private Fleets。

本指南涵盖：

  1. 准备您的 Colyseus 项目、Edgegap 账户和容器化工具

  2. 将您的编程智能体连接到 Edgegap（可选）

  3. 让您的 Colyseus 服务器为 Edgegap 做好准备

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

  5. 部署测试服务器并连接客户端

  6. 添加对局配对（可选）

  7. 将您的其他客户端指向 Edgegap

  8. 使用两名玩家测试完整闭环

您可以通过两种方式进行，也可以混合使用它们：

  • 使用编程智能体。 将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器 及其 智能体技能。edgegap-colyseus 技能会完成服务器更改、编写 Dockerfile、部署测试服务器并将配对器接入您的客户端。您只需负责 Edgegap 控制台、密钥配置和试玩测试。

  • 手动操作。 以下每个步骤在没有智能体的情况下也完全可行。

本指南使用的是 Edgegap 基于官方 Colyseus Realtime Tanks 示例 的分支版本：包含一个 Colyseus 0.17 服务器和九个客户端（涵盖从 Three.js 到 Unity 和 Godot）。Edgegap 托管功能已内置于该分支中，因此您可以直接运行它，或将其作为您自己游戏的参考。

与工程师联系

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

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

Colyseus's Realtime Tanks demo, a multiplayer tank battle running on Edgegap dedicated game servers.

在 Edgegap 上运行的 Colyseus 实时坦克演示

分步指南

详细集成步骤

1. 开始之前

  • 一个免费的 Edgegap 账户。请验证您的电子邮箱。测试无需信用卡。

  • 一个 Colyseus 服务器。本指南使用 Colyseus 0.17（defineServer / defineRoom）。Colyseus 0.15 和 0.16 应该以相同方式工作（入口点不同），但尚未经过测试。

  • Node.js（推荐版本 22）和一个正在运行的容器化工具。我们推荐 Docker Desktop。

  • Unity 客户端：该分支的 Unity 匹配客户端需要 Unity 2023.1 或 Unity 6（使用了 Awaitable）。

  • 对于代理路径：需要一个 Edgegap API 令牌，可从 Dashboard → User Settings → Tokens 获取。该令牌适用于整个组织，因此请像对待密码一样妥善保管：切勿将其放入客户端、服务器镜像或聊天中。

快捷方式：先运行示例。克隆 Realtime Tanks 分支，然后对其 server/ 文件夹执行步骤 4 到 8。步骤 3 中的所有更改都已包含在其中。在 Windows 上，克隆前请运行 git config --global core.longpaths true：某些客户端文件路径超出了 Windows 的默认长度限制。

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

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

Edgegap MCP 服务器允许您的智能体（agent）在您的账户上创建应用和版本、部署服务器、读取日志并生成匹配器（matchmaker）配置。edgegap-colyseus 技能为其提供了经过 Realtime Tanks 测试的文件：生命周期模块、Dockerfile、部署脚本、匹配器配置，以及适用于浏览器、Unity 和 Godot 的匹配器客户端。

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

/plugin marketplace add edgegap/edgegap-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/edgegap-agent-skills --skill "*" 安装技能。

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

检查是否生效：

“列出我的 Edgegap 应用。”

3. 让您的 Colyseus 服务器准备好接入 Edgegap

当对局需要时，Edgegap 会启动一台服务器。只有你的游戏才知道对局何时结束，因此需要由服务器自行停止其部署。否则，空闲的服务器将持续运行并计费，直至达到其最长运行时长。

该分支中的三处更改，位于 server/src/edgegap.ts 及其 BattleRoom.ts 中：

  • 生命周期模块，仅在 Edgegap 上运行（当设置了 ARBITRIUM_REQUEST_ID 时，Edgegap 会在每次部署时设置该变量）。如果在 120 秒内无人加入、所有人离开且在 30 秒内无人返回，或对局结束时，它会停止部署。

  • 统计房间中的玩家数量：在 onJoin 中调用 playerJoined()，并在席位真正空出时调用 playerLeft()。在使用 allowReconnection 的情况下，是指在重连窗口期超时之后，而不是刚掉线时。重连机制未在 Edgegap 上进行测试；在每场对局对应一台服务器的情况下，重连的客户端必须连同重连令牌一起保存服务器地址。

  • 如果你的游戏有结束对局的逻辑：锁定房间，展示几秒钟结果，执行 disconnect()，然后停止。Realtime Tanks 会在赢得 MATCH_ROUNDS 轮后执行此操作（默认值为 0，即无尽竞技场）。

此外，在 Edgegap 上关闭 playground 和 monitor：任何拥有服务器地址的人都可以打开它们。该分支仅在非 Edgegap 环境下挂载它们，因此 npm run dev 的运行方式与之前完全一致。

使用你的 Agent：

“加载 edgegap skill，然后加载 edgegap-colyseus。将生命周期模块添加到我的 Colyseus 服务器，统计每个房间的玩家人数，在对局结束时停止服务器，并在 Edgegap 上保持关闭 playground 和 monitor。然后使用 Docker 在本地进行测试。”

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

Edgegap 运行 linux/amd64 容器。该分支的 server/Dockerfile 基于 node:22-slim，并将 Node 作为主进程运行，因此您的服务器可以接收到 Edgegap 的停止信号，且 Colyseus 能够正常关闭其房间。

为 Edgegap 平台进行构建（即使在 Apple Silicon 上），并为每次构建使用新的标签：

cd server

docker build --platform linux/amd64 -t registry.edgegap.com/<project>/realtime-tanks:v1 .

在推送镜像之前先在本地进行测试。ARBITRIUM_REQUEST_ID 使其表现得如同在 Edgegap 上一样：docker run --rm -p 2567:2567 -e ARBITRIUM_REQUEST_ID=local -e EMPTY_TIMEOUT_S=10 registry.edgegap.com/<project>/realtime-tanks:v1。位于 ws://localhost:2567 的客户端加入，并在其离开 10 秒后，容器退出。

然后使用来自 Container Registry 页面的凭据执行 docker login registry.edgegap.com，并执行 docker push registry.edgegap.com/<project>/realtime-tanks:v1。

在控制面板中创建应用程序和版本：

  • 您的镜像和标签，以及注册表凭据。

  • 初始配置 0.25 vCPU 和 512 MB。

  • 端口 2567，协议 WS，名称 gameport，并开启 TLS Upgrade。

  • 测试时的最长持续时间为 60 分钟。

TLS Upgrade 允许所有客户端（包括浏览器版本）使用 wss:// 进行连接。Edgegap 会处理证书，并将明文 HTTP 和 WebSocket 流量转发到端口 2567。Colyseus 的 matchmake 请求和房间连接都使用这同一个端口。

使用您的智能体：

“为 linux/amd64 构建我的 Colyseus 服务器，使用新标签推送它，并创建 Edgegap 应用程序和版本：端口 2567，协议 WS，开启 TLS Upgrade，命名为 gameport，0.25 vCPU 和 512 MB，最长 60 分钟。”

5. 部署测试服务器并连接客户端

通过复刻分支（fork）的部署脚本在靠近您的位置启动服务器。您的 API 令牌将保留在您的本地机器上：

macOS 和 Linux：EDGEGAP_API_TOKEN=<token> npm run edgegap:deploy -- realtime-tanks v1

Windows (PowerShell)：$env:EDGEGAP_API_TOKEN="<token>"; npm run edgegap:deploy -- realtime-tanks v1

它会输出 wss://<request_id>.pr.edgegap.net:<port>。您也可以从控制面板部署（Deploy，选择靠近您的位置），或者询问您的智能体：“在靠近我的位置部署我最新的 Edgegap 版本，等待其就绪，并将 wss:// 地址发送给我。”

将该地址传递给客户端。在 Three.js 客户端中，在页面地址后添加 ?server=wss://...；在 Godot 或 Unity 桌面构建版本中，使用 --server=wss://... 启动。务必使用主机名，而不是 IP 地址，否则证书检查将失败。

如果首次加入时返回 502，请重试：刚启动的服务器在最初几秒内可能会响应 502。复刻版本的客户端重试时间最长为 20 秒。

当客户端离开时，服务器日志会显示 self-stop: empty for 30s，并且该部署将从控制面板中消失。免费层每次仅可运行一个部署。

在不使用 Edgegap 匹配系统的真实游戏中，当队伍准备就绪时，您的后端或大厅会调用相同的 Deploy API（POST /v2/deployments），并将地址发送给玩家。接下来，让匹配系统为您完成此操作。

6. 添加匹配功能

Edgegap 的匹配器可将玩家分组，在他们附近部署您的服务器，并将服务器地址发送给每个客户端。该分支的 Three.js、Unity 和 Godot 客户端会发送票证，显示“正在寻找玩家...”，并在分配服务器后立即连接。已在 Edgegap 上测试：浏览器中的 Three.js、Godot 桌面版和 Unity Windows 构建版本。未运行 Unity WebGL 和 Godot Web 导出版本。

  1. 从该分支的 matchmaker-config.json 开始。其 casual 配置文件可匹配 2 到 8 名玩家，并在 15 秒后与当前等待的任何玩家（至少 2 人）开始一场比赛。在其中设置您的应用程序名称和版本。

  2. 浏览器构建版本：在 allowed_cors_origins 中列出提供您游戏服务的所有网址，否则浏览器会阻止匹配器的回复。该文件仅允许本地开发服务器。省略针对浏览器玩家的任何延迟规则：浏览器无法发送桌面游戏所使用的延迟 Ping。

  3. 在控制面板中，打开 Matchmaker，选择 Create Matchmaker，上传该文件并选择 Create and Start。

  4. 当显示为 Online 时，复制其 API URL 和 Auth Token。Auth Token 旨在随您的游戏一同发布：它只能创建和读取撮合票证。它不是您的 Edgegap API 令牌。

  5. 将它们提供给客户端：Three.js ?mm=<API URL>&mmToken=<Auth Token>（或 VITE_MM_URL / VITE_MM_TOKEN），Unity --mm=<API URL> --mm-token=<Auth Token> 或 GameManager 上的字段，Godot -- --mm=<API URL> --mm-token=<Auth Token>。server 设置始终优先于匹配器。

使用您的智能体：

“使用 edgegap-colyseus 技能，为我的客户端添加 Edgegap 撮合功能：包含 2 到 8 名玩家的休闲配置文件、allowed_cors_origins 中的我的网络源，以及在分配服务器后重试的加入逻辑。”

手动操作：请参阅 對局配對文档。

7. 将您的其他客户端指向 Edgegap

每个 Colyseus 客户端 SDK 都连接到相同的 wss:// 地址。该分支将直接模式接入其全部九个客户端中。仅 Three.js、Godot 桌面端和 Unity Windows 客户端在 Edgegap 上运行过；下面针对其他客户端的设置已编写但未经过测试：

  • Three.js、PlayCanvas、Construct 3：页面地址中的 ?server=wss://...。

  • Godot：--server=wss://...；Web 导出：?server=wss://...。

  • Unity：--server=wss://...、serverUrl 字段，或 WebGL 中的 ?server=wss://...。

  • Defold：HTML5 ?server=wss://...；原生 --config=tanks.server_url=wss://...。

  • GameMaker、Haxe、MonoGame：--server=wss://...（HTML5 和 JS 构建：?server=wss://...；MonoGame 还会读取 TANKS_SERVER_URL）。

匹配器客户端体积小且无依赖项，因此很容易移植到其他引擎。请从 Matchmaker.ts、EdgegapMatchmaker.cs 或 edgegap_matchmaker.gd 开始。

8. 由两名玩家测试完整循环

  1. 请确保没有正在运行的测试部署。在免费层级上，遗留的部署会阻止匹配系统的部署。

  2. 使用匹配系统设置打开两个客户端。它们可以使用不同的引擎，例如浏览器中的 Three.js 客户端和 Godot 桌面端版本。

  3. 在两端均选择开始游戏：进行搜索，然后双方进入同一个竞技场。服务器日志会显示两个票证 ID。

  4. 退出两端。30 秒后，服务器将停止自身的部署，并且该部署会从控制台中消失。

在发布之前：在匹配系统配置中将 inspect 设置为 false，列出真实的 Web 源地址，提高最大持续时间以适应您的比赛，并且仅允许匹配的玩家进入（每个匹配成功的部署都会在 MM_TICKET_IDS 中接收到对应的票证 ID；请在 onAuth 中对它们进行验证）。

在免费层级中，匹配系统每次启动 3 小时后会停止（可从控制台重新启动），部署在 60 分钟后停止，并且一次只允许运行一个部署。

后续步骤

后续步骤

准备上线？让您的智能体运行 edgegap-launch 技能的检查清单。

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

常见问题

关于在 Edgegap 专属服务器上托管 Colyseus 游戏的常见问题。

如何托管 Colyseus 服务器？

将您的 Colyseus 服务器打包为暴露端口 2567 的容器，然后将其在主机上运行。在 Edgegap 上，每场比赛都会在玩家附近分配专属服务器，通过带有 TLS Upgrade 的 wss:// 进行访问，且服务器会在比赛结束时自行停止。

一个 Colyseus 服务器可以在 Edgegap 上运行多个房间吗？

是的。一个部署会运行一个 Colyseus 进程，该进程可以托管任意数量的房间；它会在最后一名玩家离开 30 秒后自行停止。大多数游戏会采用每个部署一场比赛的方式，这样就无需使用 PM2、Redis 状态监控或负载均衡器。

Colyseus 是否可以在 Edgegap 上与 Unity 和 Godot 一起使用？

是的。Colyseus 的 Unity 和 Godot SDK 会像任何其他客户端一样连接到服务器的 wss:// 地址。Realtime Tanks 示例为其 Three.js、Unity 和 Godot 客户端包含了 Edgegap 匹配功能，并在 Edgegap 上通过 Three.js、Godot 桌面版和 Unity Windows 构建进行了端到端测试。

浏览器客户端如何安全地连接到 Colyseus 服务器？

通过 https:// 提供的页面只能打开安全的 WebSocket (wss://)。请在服务器的 WS 端口上开启 TLS Upgrade：Edgegap 会处理证书并将明文流量转发给 Colyseus，因此服务器无需证书。

在使用 Edgegap 时，我还需要 Colyseus 的匹配器（matchmaker）吗？

Colyseus 仍在其服务器上处理加入房间的逻辑。Edgegap 的匹配器负责决定哪些玩家一起玩，并启动他们的服务器。您也可以跳过此步骤，直接让后端通过 Edgegap 的 Deploy API 启动服务器。

客户

了解更多已接入 Edgegap 的客户案例

提供 31 个从其他平台迁移至 Edgegap 的工作室案例研究。

他们选择 Edgegap 的关键原因

了解 Edgegap 自动化游戏服务器编排如何带来无缝的多人游戏体验。

+平均延迟减少 58

+平均延迟减少 58

14M CCU 快速缩放

14M CCU 快速缩放

+615多全球位置

+615多全球位置

~2 秒。游戏服务器平均启动时间

~2 秒。游戏服务器平均启动时间

多版本支持和滚动更新

多版本支持和滚动更新

91% 填充率對局配對

91% 填充率對局配對

跨平台兼容

跨平台兼容

即时 DDoS 保护

即时 DDoS 保护

跨 17+ 家提供商的多云架构，提供 99.99% 可用性

跨 17+ 家提供商的多云架构，提供 99.99% 可用性

费用

定价

定价

通过混合编排优化成本与性能

通过混合编排优化成本与性能

通过混合编排优化成本与性能

边缘云

按需

$0.00115

/ vCPU

/ 分钟

按分钟计费，仅按实际使用量收费

只有在玩家在线玩游戏时才需付费。0 个活动服务器 = $0

在全球 615 多个边缘云节点中按实例部署游戏服务器。零承诺。

只需添加信用卡。

全球 615+ 家分店

每月流出流量 $0.10/GB

0.25 到 4 个 vCPU 的部署

比较功能与价格

边缘云

按需

$0.00115

/ vCPU

/ 分钟

按分钟计费，仅按实际使用量收费

只有在玩家在线玩游戏时才需付费。0 个活动服务器 = $0

在全球 615 多个边缘云节点中按实例部署游戏服务器。零承诺。

只需添加信用卡。

全球 615+ 家分店

每月流出流量 $0.10/GB

0.25 到 4 个 vCPU 的部署

比较功能与价格

专属物理机集群 (裸金属)

预留容量

$0.0261

/ vCPU

/ 小时

按月计费，始终开启

每个主机每月 $280（12个月标准价），或按月支付每月 $350

通过无出站流量费用的专用机队托管，优化您游戏服务器的成本效益。

持久在线，24/7全天候可用，您的工作室专属。

全球 58 个分支机构

包含出站流量

每台主机总计 16 个 vCPU（14.7 个可用）

比较功能与价格

专属物理机集群 (裸金属)

预留容量

$0.0261

/ vCPU

/ 小时

按月计费，始终开启

每个主机每月 $280（12个月标准价），或按月支付每月 $350

通过无出站流量费用的专用机队托管，优化您游戏服务器的成本效益。

持久在线，24/7全天候可用，您的工作室专属。

全球 58 个分支机构

包含出站流量

每台主机总计 16 个 vCPU（14.7 个可用）

比较功能与价格

您的账单因费率和使用量而异；这可能会根据游戏类型、玩家人数等因素而有所不同。

您的账单因费率和使用量而异；这可能会根据游戏类型、玩家人数等因素而有所不同。

使用我们的预估计算器模拟您的用量 ->

使用我们的预估计算器模拟您的用量 ->

Edgegap 的功能与价格：边缘云与私有集群（Private Fleets）详细对比

Edgegap 的功能与价格：边缘云与私有集群（Private Fleets）详细对比

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

0.00115 美元/vCPU/分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

$0.00115 / vCPU / 分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

0.00115 美元/vCPU/分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署