服务器浏览器

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

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

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

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

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

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

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

✔️ 准备工作

网络流（Networking Flows）

服务器浏览器架构

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

1. ——你的后端使用 用于部署、扩展和管理您的专用服务器（Dedicated Servers）。

   1. fqdn v2/deploy API 用于 基于匹配的会话 持续少于 24 小时。

   2. fqdn 私有集群部署 API 以启动 待命服务器 所有部署在运行 24 小时后将根据我们的服务器清理策略被终止，以进行基础设施维护，并防止在部署未正确关闭时产生意外费用。对于长期运行的服务器，请考虑使用 持久化.

   3. 📢 使用热待命（Hot Standby）以获得基于规则的自动扩展和网格化支持。

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

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

4. 网络传输（Netcode Transports）用于在游戏客户端和专用服务器之间通信。

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

▶️ 开始浏览

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

身份验证

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

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

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

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

  • 我们建议将此令牌存储在第三方机密存储中以便于令牌轮换。

发现实例

——你的后端使用 用于部署、扩展和管理您的专用服务器（Dedicated Servers）。

• fqdn v2/deploy API 用于 基于匹配的会话 持续少于 24 小时。

• fqdn 私有集群部署 API 以启动 待命服务器 所有部署在运行 24 小时后将根据我们的服务器清理策略被终止，以进行基础设施维护，并防止在部署未正确关闭时产生意外费用。对于长期运行的服务器，请考虑使用 持久化.

• 📢 使用热待命（Hot Standby）以获得基于规则的自动扩展和网格化支持。

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

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

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

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

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

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

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

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

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

上述元数据参数仅为示例，您可以定义包括上述在内的任意参数。所有元数据参数均为可选，有些实例可能无需定义所有参数。

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

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

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

服务器实例必须定期发送保活心跳（keep-alive heartbeat） 以验证其持续可用性并防止玩家尝试加入已崩溃或离线的服务器。缺少 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） 或 包含（contains）	?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 冲突（Conflict））。可加入座位是指尚未被其他玩家预留的任何可用座位。

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

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

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

连接到服务器

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

虚幻引擎（Unreal Engine）

要 从 PIE（编辑器）连接 在开发和测试期间，按下波浪号键（tilde） ~ 并输入 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 日）

• 进入公开测试（OPEN BETA），引入了 对服务器实例和插槽的过滤与排序!

0.0.3（2025 年 11 月 28 日）

• 服务器浏览器服务的首次发布以封闭测试（CLOSED BETA）形式上线。

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

• 支持与云部署的匹配会话以及通过私有集群实现始终在线。