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

本指南向您展示如何在 Edgegap 的专用游戏服务器上托管任何 Colyseus 多人游戏,然后添加撮合匹配功能,以便玩家能够自动分组并连接到距离他们较近的服务器。
一旦您的游戏服务器容器化,Edgegap 只需一个简单的 API 调用即可将其(按需)部署到全球 615 多个边缘云节点,并完全按使用量计费:无需租用整台服务器、预置或在对局之间保持运行。对于预留容量的持久化服务器,Edgegap 提供了 Private Fleets。Edgegap 的匹配基于此构建,并且是可选的。
您的房间(rooms)、架构(schemas)和客户端 SDK 均保持不变。最简单的配置(也是本指南测试的配置)是为每场对局提供其独立的 Colyseus 服务器:Edgegap 会在对局玩家附近启动它,并在比赛结束时自动停止,因此您不需要 PM2、Redis presence 或房间数量容量规划。一台服务器也可以托管多个房间,例如一个大厅及其各场比赛:此时它会在最后一名玩家离开 30 秒后停止,即使房间仍然保持开放。对于常开服务器,请使用 Private Fleets。
本指南涵盖:
准备您的 Colyseus 项目、Edgegap 账户和容器化工具
将您的编程智能体连接到 Edgegap(可选)
让您的 Colyseus 服务器为 Edgegap 做好准备
容器化服务器并创建应用版本
部署测试服务器并连接客户端
添加撮合匹配(可选)
将您的其他客户端指向 Edgegap
使用两名玩家测试完整闭环
您可以通过两种方式进行操作,也可以将它们结合使用:
使用编程智能体。 将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器 及其 智能体技能。
edgegap-colyseus技能可以完成服务器修改、编写 Dockerfile、部署测试服务器并将撮合器接入您的客户端。您只需负责 Edgegap 控制面板、密钥配置和实际试玩测试。手动操作。 下面的每个步骤也可以在不使用智能体的情况下进行。
本指南使用的是 Edgegap 分叉(fork)自官方的 Colyseus Realtime Tanks 演示 demo:包含一个 Colyseus 0.17 服务器和九个客户端(从 Three.js 到 Unity 和 Godot)。Edgegap 托管已经内置在该分叉版本中,因此您可以直接原样运行它,也可以将其作为您自己游戏的参考。

在 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 服务器允许您的智能体在您的账户上创建应用和版本、部署服务器、读取日志并生成撮合系统配置。edgegap-colyseus 技能为其提供了通过 Realtime Tanks 测试的文件:生命周期模块、Dockerfile、部署脚本、撮合系统配置以及适用于浏览器、Unity 和 Godot 的撮合客户端。上线后,MCP 服务器还可以检查实例集健康状况、跨部署搜索日志并在回滚前比较两个版本。
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 "*" 安装技能。对于监控智能体,还需添加请求头 X-Edgegap-Read-Only: 1:这样它可以读取数据但无法进行任何更改。
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。
在控制面板中创建应用程序和版本:
您的镜像和标签,以及 registry 登录凭据(Registry Profile,或 Container Registry 页面中的用户名和令牌)。
开始时配置 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 导出版本。
从该分支的
matchmaker-config.json开始。它的casual配置文件可匹配 2 到 8 名玩家。其最小值 (2) 低于最大值 (8),因此匹配器还会与当前等待的任何玩家进行部分匹配,无需扩展阶段,且票据在 30 秒后过期。在其中设置您的应用程序名称和版本。浏览器构建版本:在
allowed_cors_origins中列出提供您游戏服务的所有网址,否则浏览器会阻止匹配器的回复。该文件仅允许本地开发服务器。省略针对浏览器玩家的任何延迟规则:浏览器无法发送桌面游戏所使用的延迟 ping。在控制面板中,打开 Matchmaker,选择创建匹配器 (Create Matchmaker),上传该文件并选择创建并启动 (Create and Start)。
当显示为在线 (Online) 时,复制其 API URL 和 Auth Token。Auth Token 旨在随游戏一起发布:它只能创建和读取撮合票据。它并不是您的 Edgegap API 令牌。
将它们提供给客户端: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 中配置我的 Web 源,以及在分配服务器后重试加入。”
手动操作:请参阅匹配文档。
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. 由两名玩家测试完整循环
请确保没有正在运行的测试部署。在免费层级上,遗留的部署会阻止匹配系统的部署。
使用匹配系统设置打开两个客户端。它们可以使用不同的引擎,例如浏览器中的 Three.js 客户端和 Godot 桌面端版本。
在两端均选择开始游戏:进行搜索,然后双方进入同一个竞技场。服务器日志会显示两个票证 ID。
退出两端。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 的工作室案例研究。

《以太之战 2》完美的全球发布
Aether Studios
了解Aether Studios是如何快速添加Edgegap并向他们的社区交付完美的启动和后启动服务的。
案例研究

克服因虚拟现实在竞技Multiplay中使用WiFi而引入的延迟
Halfbrick Studios
Discover how Halfbrick successfully launched & maintains a multiplayer-focused Early Access on META Quest's VR platform.
案例研究

MENA的社交应用添加了在线游戏
WOLF
了解这款在中东和北非地区广受欢迎的社交应用如何轻松地将 matchmaking 和多人游戏编排添加到 WOLF Qanawat。
案例研究

混合编排让开球策略随时应对任何流量做好准备
Birch Games
混合编排如何帮助 Birch Games 应对流量——将免流出费用的 Fleets 与无区域限制云相结合。
案例研究

真实的在线战争需要终极的协调
Highwire Games
了解Highwire对性能的需求如何需要只有Edgegap才能提供的编排。
案例研究

22,000 条评价、4.8 颗星以及自动扩展的基础架构
Sinn Studios
一个由 Slack 提供支持的简单集成,如何让 Sinn Studio 的热门 VR 游戏快速上线并保持稳定运行。
案例研究

动态服务器编排
Under NDA - AAA Studio
了解世界上最大的AAA工作室之一如何通过边缘计算改善其对等多人游戏体验。
案例研究

对于 AAA 格斗游戏的近零延迟
AAA Studio - Under NDA
一个未宣布的项目如何实现了最低延迟,并改善了其1v1游戏中的公平性。
案例研究

Play Gods with Multiplayer Physics
Squido Studio
Learn how Squido uses Edgegap's highligh optimized game servers to deliver mind-bending & chaotic VR gameplay.
案例研究

全面托管的解决方案为独立游戏节省时间 多人VR恐怖游戏
Dirty Pearl Studios
了解Dirty Pearl Studios如何通过Edgegap的轻松集成和自动编排,以及其Nakama集成,节省了开发时间。
案例研究

7天血月
The Fun Pimps & iLLOGIKA
了解 Illogika 如何大幅降低服务器成本,并确保提供《七日杀 (7 Days to Die)》玩家所期望的在线体验。
案例研究

即时全球服务器部署以促进协作式XR医学教育
AlensiaXR
AlensiaXR如何利用Edgegap为全球医学生提供低延迟、始终可用的共享解剖课程。
案例研究

趣加
FunPlus
案例研究

守光人:具有专用服务器的 VR 社交合作游戏
Spectral Games
Spectral Games 如何在无需任何服务器经验的情况下,利用 Edgegap Matchmaking 和 Server Browser 为其 VR 社交大厅启动专用服务器。
案例研究

全球范围内快速可靠的部署,适用于PvPvE挑战者Gravebound
Crater Studios
Edgegap 的调度和配对如何帮助 Crater Studios 使他们能够将重心从基础设施转移到游戏玩法上。
案例研究

快速扩展网络元宇宙
Hiber
了解Hiber如何通过Edgegap消除服务器容量规划中的猜测。
案例研究

高硬件要求和自定义游戏服务器池
Alderon Games
了解Alderon Games如何瞬间利用全球多个供应商的自定义游戏服务器池来支持其热门MMO。
案例研究

独立开发者的简单集成
WhaleFood Games
阅读关于WhaleFood Games如何使用Edgegap解决其网络代码问题的文章。
案例研究

推动东南亚首款电子竞技游戏的尖端技术。
Anantarupa Studios
了解Edgegap如何通过一个无缝解决方案简化复杂基础设施和尖端技术,从而改变东南亚的游戏格局。
案例研究

一次打击。全球抵达。
Triple Hill Interactive
Triple Hill Interactive如何利用Edgegap的编排来提供低延迟,并提高在每毫秒都至关重要的游戏类型中的公平性。
案例研究

快节奏团队大逃杀...带着枪的动物毛绒玩具!
SANDYFLOOR
了解一家韩国独立工作室是如何将其多人游戏发布到全球的。
案例研究

移动端赛马游戏凭借即时、高效能的服务器走向全球
Mirai Labs
看 Mirai Labs 如何通过即时服务器部署和细分 vCPU 来运行 Pegaxy Blaze 的全球多人竞速游戏,从而将单个玩家的成本保持在极低水平。
案例研究

服务器管理与分发
Matrioshka Games
阅读关于Matrioshka Games如何在资源有限的情况下发布早期访问的战斗 Royale。
案例研究

听我的信号,释放地狱!
TyGames
探索独立工作室TyGames如何让玩家沉浸在第三人称角斗士战斗的多人游戏中。
案例研究

瞬时全球编排
Soliton Interactive
探索Soliton Interactive如何做到了不可能……首次推出可多人玩的版本!
案例研究

竞技游戏具有服务器端物理引擎,确保理想的低于50毫秒的延迟
NS7
了解为什么仅有Edgegap能够使独立工作室通过服务器端物理和权限实现其AAA质量的免费游戏体育玩法愿景。
案例研究

iGaming的区域部署
X1 Contra 1
X1 Contra 1 通过经济高效的托管和区域部署,为其巴西玩家提供实时 PvP 休闲游戏,确保数据和法律合规。
案例研究

仅在玩家游玩时付费:经济实惠的多人游戏基础设施
Meltdown Interactive
Edgegap 如何帮助独立开发商 Meltdown Interactive Media 在无需复杂方案的情况下,以高性价比解决扩缩容和匹配问题,从而让他们能够专注于游戏开发。
案例研究

同一个 Edgegap 平台,三种截然不同的网络配置
Warped Games
了解 Warped Games 如何在同一个 Edgegap 部署 API 和同一个容器管线上运行社交中心、实时合作以及回合制合作。
案例研究

台球大师巡回赛Max
RETA Games
案例研究

韩国的Web3 POP提取射击游戏走向全球,即刻启程
NDUS Entertainment
XOCIETY 如何轻松地添加 Edgegap 编排并集成自定义 matchmaking,与 Edgegap Ping Beacons 一起优化延迟。
案例研究

Multiplayer in Every Dimension
Arcadia.tv
Discover how Arcadia.tv uses Edgegap's edge network to deliver an innovative, team and location-based athletic VR sport.
案例研究

F2P 移动格斗游戏利用即时(Just-In-Time)服务器降低基础设施成本
Game Changers Worldwide
Game Changer Worldwide 如何在全球移动端托管 Rumble Rush 的实时 3v3 PvP 游戏。
案例研究
他们选择 Edgegap 的关键原因
了解 Edgegap 自动化游戏服务器编排如何带来无缝的多人游戏体验。









