服务器浏览器

欢迎使用 Edgegap 服务器浏览器 公开测试版。 我们希望您喜欢预览我们新服务的机会，并通过 Discord 的圆桌讨论帮助塑造其未来。

服务器浏览器是一个托管服务，适用于 部署 和 持久的 服务器：

• 帮助玩家列出并加入合适的服务器 基于容量、延迟或游戏参数；

• 预热新服务器 以大规模满足全球需求并防止令人沮丧的排队；

• 📢 简化服务器运营 包括更新、重启、持久化、网格化等。

带有 📢 图标的项目是计划在初始发布及以后推出的功能（尚不可用）。

希望根据严格规则匹配玩家且不允许选择服务器？请考虑 匹配.

✔️ 准备工作

网络流

服务器浏览器 - 网络流

使用服务器浏览器时有四（4）种重要的数据流：

1. 部署 API 用于部署、扩展和管理您的专用服务器。

   1. 使用 v2/deploy API 用于 与匹配绑定的会话 持续少于 24 小时。

   2. 使用 私有机群部署 API 以启动 待命服务器 具有 持久化.

   3. 📢 使用热待命以支持基于规则的自动扩缩和网格化。

2. 服务器 API 由专用服务器用于宣布可用性并管理容量。

3. 席位预留 API 由游戏客户端用于发现并连接到专用服务器。

4. Netcode 传输用于在游戏客户端与专用服务器之间通信。

发布后， 您的服务器浏览器需要全天候 24/7 运行 以确保世界各地的玩家可以加入服务器。

▶️ 开始浏览

了解服务器/玩家生命周期及其责任，以确保服务器的高效使用。

认证

服务器浏览器会自动生成两种类型的令牌：

• 服务器令牌 - 用于所需的 服务器 API 方法，可以被 注入为应用版本变量.

  • 授予对所有 API 方法的访问权限，适合测试、运维或自定义编排器使用。

• 客户端令牌 - 用于所需的 监控和席位预留 API 由游戏客户端使用的方法。

  • 我们建议将此令牌存储在第三方密钥库中，以便更容易进行令牌轮换。

发现实例

部署 API 用于部署、扩展和管理您的专用服务器。

• 使用 v2/deploy API 用于 与匹配绑定的会话 持续少于 24 小时。

• 使用 私有机群部署 API 以启动 待命服务器 具有 持久化.

• 📢 使用热待命以支持基于规则的自动扩缩和网格化。

当您启动新的 部署, 时，通知服务器浏览器有关新实例的信息并设置任意数量的可选元数据参数， 这些参数有助于玩家过滤、排序和浏览：

• 插槽信息 - 队伍容量和队伍特定的元数据（例如队伍名称），

  • 每个实例至少需要一个插槽以管理玩家容量；

• 名称和标签 - 可自定义、唯一、易读且可搜索的标签；

• 连接详情 - URL、IP、外部端口或其他参数；

• 兼容性数据 - 服务器版本或支持的客户端版本；

• 延迟限定符 - 城市和区域标识符，以及分配的 Ping 信标 详情；

• 游戏参数 - 关卡/场景/地图、游戏模式、难度、使用的模组；

• 任何其他自定义参数以帮助玩家筛选并找到合适的服务器。

以上元数据参数仅为示例，您可以定义任何参数包括上述内容。所有元数据参数均为可选，有些实例可能不需要定义所有参数。

元数据支持字符串键和值，值可以是字符串、数字、布尔值或字符串数组。

要序列化嵌套对象，尝试在键中对其访问路径进行编码，如 "object.child.property".

服务器可以 随时更新实例或插槽元数据 以修改其可发现性标准。

服务器实例必须定期发送存活心跳 以验证其持续可用性并防止玩家尝试加入已崩溃或离线的服务器。缺少心跳达 30 秒将自动移除该实例及任何未决的席位预留。

📢 服务器可以在缩减（停止）之前将其实例更新为“休眠模式”，以在不发送更多心跳请求的情况下保持可发现性。当玩家请求 服务器浏览器 休眠实例时，服务器浏览器将自动重新部署您的服务器。

参见 持久化 以管理持久世界状态以及 应用与版本 以实现更快速的部署。

搜索与浏览

玩家可以列出服务器实例并 分页浏览结果， 以查找他们想要加入的服务器。要显示 Ping（延迟）数据，请读取每个实例的 Ping 信标 详情并 测量延迟.

实例和插槽可以按可加入的席位或 已索引的元数据参数进行过滤.

参数	运算符	示例过滤器（基于简单示例）
"joinable_seats"	eq 或 ne 或 lt 或 le 或 gt 或 ge	?filter=joinable_seats gt 0 &orderby=joinable_seats desc
"string" （元数据）	eq 或 ne 或 lt 或 le 或 gt 或 ge 或 包含	?filter=metadata.custom_name contains 'my game' 并且 metadata.server_version le '1.1.0' 并且 metadata.server_version ge '1.0.0' &orderby=metadata.custom_name asc
"int" , 或 "float" （元数据）	eq 或 ne 或 lt 或 le 或 gt 或 ge	?filter=metadata.xp_multiplier gt 1.0 &orderby=metadata.xp_multiplier desc
"bool" （元数据）	eq 或 ne	?filter=metadata.allows_new_connections eq true

按区域和/或城市过滤，以在测量到服务器的延迟之前缩小选择范围。

了解基于游标的 服务器浏览器 以让用户获取更多结果。

预留席位

在加入服务器之前，需要进行席位预留以确保实例提供足够的可用容量。预留可以包括一组玩家或单个玩家。

超过插槽可加入席位容量的预留将被自动拒绝， (409 冲突）。可加入的席位是指尚未被其他玩家预留的任何可用席位。

联合身份：玩家必须在其预留中提供唯一的第三方玩家 ID。一旦他们发送相同的 ID， 服务器浏览器 将允许服务器验证其身份。

一旦预留成功（200 OK），玩家应立即尝试连接。未确认的 预留将在 30 秒后过期，除非由您的服务器 确认。

服务器可以强制更改任何插槽的容量，添加、删除或更新任何插槽。 如果任何未决预留超过新的可用插槽容量，则该插槽的所有预留将被移除。

连接到服务器

一旦玩家找到合适的实例，他们可以 从元数据中检索所需的连接详情 （URL、IP、 外部端口）。一旦席位预留完成， 玩家即可继续连接到您部署的游戏服务器并传递其玩家 ID.

虚幻引擎

要在 连接来自 PIE（编辑器） 在开发和测试期间，按下波浪号键 ~ 并输入 open {URL}:{port} 并等待您的编辑器加载地图。

如果连接失败或出现黑屏，请参考我们的 故障排除指南.

Unity

要验证新连接， 您的服务器必须发送包含所有新玩家 ID 的批量预留确认 请求，并在确认响应中接收信息：

• 将被接受的玩家预留分配到其首选插槽，

• 将已过期的玩家预留分配到其首选插槽，

• 未知玩家 ID 列表。

您的 服务器可以决定如何处理每组玩家 以及是否允许或踢出/封禁已过期或被拒绝的用户。每个 实例的插槽必须立即使用新的可用席位计数进行更新， 以确保新的预留不会超过容量。

放弃服务器

当玩家离开时，服务器必须更新其分配的插槽以反映新的可用席位容量。

如果您的游戏设计允许重连期，服务器可以在释放席位前等待一段时间。

我们建议停止没有玩家的服务器以优化托管成本。在此之前等待几分钟可以减少短时间空闲期间的重启次数。

阅读有关 持久化 以防止令人沮丧的持久服务器回滚。

⚙️ 配置

服务器浏览器 API 是根据您创建新的（或快速重启）服务器浏览器时指定的 JSON 配置生成的。您可以指定服务器和插槽的过期时间以及自定义元数据：

🍀 简单示例

{
  "version": "0.0.5",
  "server_instances": {
      "expiration_period": "30s",
      "indices": {
        "custom_id": "string",
        "custom_name": "string",
        "server_version": "string",
        "allows_new_connections": "bool",
        "xp_multiplier": "float",
        "beacon_ip": "string",
        "beacon_port_udp": "int",
        "beacon_port_tcp": "int"
      }
  },
  "server_instance_slots": {
    "indices": {
      "custom_team_name": "string",
      "average_team_skill_rating": "float"
    }
  },
  "seat_reservations": {
    "expiration_period": "30s"
  }
}

为获得最佳性能，避免为不用于过滤或排序的元数据指定索引。非索引参数仍然可以通过服务器实例或插槽详情 API 方法设置和读取，请参见 📗 API.

☁️ 托管集群

服务器浏览器由 Edgegap 便捷地托管和管理，全天候 24/7 运行。

选择最适合您目标的托管选项：

私有集群层级

一键升级到私有集群，可享受由 Edgegap 团队维护的高可用托管服务，并为已公开发布的游戏提供 24/7 现场支持。

实例的资源需求将取决于以下因素：

• 玩家数量 - 更多玩家会导致更多的 API 请求，

• 每位玩家的请求次数 - 更快的重试会增加服务负载并消耗资源，

• 服务器数量 - 更多服务器会导致更多的数据存储和更多的 API 请求，

• 客户端重试回退逻辑 - 带抖动的退避重试有助于分散流量高峰，

• 平均对局时长 - 较短的会话需要更频繁地与服务器浏览器交互。

📗 API

游戏客户端和专用服务器在其整个生命周期中向服务器浏览器发送 API 请求。

57KB

sb-openapi-open-beta.json

打开

将 API 规范导入到 Scalar API Web 客户端 或 Swagger 编辑器 以检查详细信息。

分页

服务器浏览器提供基于游标的分页，以按特定顺序增量获取过滤后的数据。 这种方法在获取更多结果时需要发送游标（起始点）和页面大小（响应项数量），与传统的 limit-offset 分页不同。

结合我们为游戏服务器元数据开发的专有数据库索引系统，基于游标的分页为过滤高度动态的数据提供快速、一致且灵活的用户体验。

我们的目标是让用户在第一页就能找到合适的服务器。为获得最佳体验，我们建议显示之前页面的缓存结果，并仅在用户点击搜索时刷新结果。

🔖 更新日志

服务器浏览器的最新版本是 0.0.4 。请关注更新和公告。

0.0.4（2026 年 1 月 05 日）

• 进入公开测试版，推出了 服务器实例和插槽的过滤与排序功能!

0.0.3（2025 年 11 月 28 日）

• 服务器浏览器服务的初始版本以封闭测试形式上线。

• 列出服务器、管理容量并获取连接详情。

• 支持使用云部署的匹配会话以及使用私有机群的始终在线模式。