# 深入了解

深入了解 Edgegap 的无代码配对系统概念，并按你的需求进行自定义。

## ✔️ 介绍

**5 分钟内即可开始使用，并可免费测试全部功能，无需信用卡。**

当你准备好升级到更强大、私有（专属）的集群时即可升级。与 Edgegap 的原生集成 [deployments](https://docs.edgegap.com/zh/learn/bian-pai/deployments "mention") 无论你的玩家身在何处，都能提供一流的 ping。

{% hint style="info" %}
免费层在每次重启后可运行 3 小时。你的配对器将在资源受限的共享基础设施上运行，适合测试。 **在正式发布后，配对器需要 24/7 运行。**
{% endhint %}

每个配对器都有三个关键概念：

* [#hosting-cluster](#hosting-cluster "mention") - 底层服务器基础设施，由 Edgegap 全面托管和运营。
* [#configuration](#configuration "mention") - 定义配对器如何运行的一组规则和设置。
* 🌐 服务实例 **-** 在集群上 24/7 运行的实时匹配服务，使用配置将玩家匹配在一起并生成部署（服务器）分配。

{% hint style="success" %}
[频繁更新你的配对器版本](#changelog) 以 **利用新功能和错误修复。**
{% endhint %}

## ▶️ 开始匹配

了解匹配流程，以便自定义、排查故障并优化你的游戏集成。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fm4U4bgwucX6iGEieMISU%2Fimage.png?alt=media&#x26;token=39b97619-700b-4062-9dd9-73fa08fb96c2" alt=""><figcaption><p>匹配流程</p></figcaption></figure>

1. [验证玩家身份](#authenticate) - 防止盗版拷贝进行联机，
2. [创建大厅](#create-group) - 与好友组队并共享玩家/对局偏好，
3. [**组队**](#group-up) **- 将你的大厅注册为一个匹配组，**
4. [**寻找对局**](#find-match) **- 准备好并开始寻找对局（新的或已有的），**
   1. 分配服务器并注入票据 - 服务器会在几秒后自动分配，
5. [**连接并验证**](#connect-to-server) **- 尝试与游戏服务器建立安全连接，**
   1. 确认身份 - 服务器使用第三方令牌验证游戏客户端的身份，
   2. 接受玩家或踢出玩家 - 服务器决定是否允许玩家加入。

**快速开始 - 将我们的匹配入门示例添加到你的游戏中**:

### 验证

{% hint style="success" %}
**此令牌可以安全地包含在你的游戏客户端中，因为它不会授予对 Edgegap API 的访问权限。**
{% endhint %}

单个玩家可以通过其票据 ID 进行识别，该 ID 在客户端和服务器上都可用。可选地，你也可以使用自定义代理并通过 [#server-to-server-api](#server-to-server-api "mention") API 添加自定义身份验证或限制。

### 组队

创建组（party）可确保玩家与好友加入同一队伍和同一服务器。

{% hint style="success" %}
创建一个标记为准备就绪的组以 [#find-match](#find-match "mention") 快速地作为一个 **没有组成员的单人玩家**.
{% endhint %}

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FzPLV5ap16XQn0vYZsnQb%2FUntitled-2024-10-29-1018.png?alt=media&#x26;token=aa7165ab-abe1-4f7d-a84e-d2c4af8f36ad" alt=""><figcaption><p>组生命周期活动图</p></figcaption></figure>

#### 大厅和组

如果你的游戏设计需要设置由玩家控制的匹配偏好（例如角色选择、难度、地图等），请使用大厅服务。当玩家加入和离开大厅时，他们也会更新匹配组，以便稍后准备寻找对局。

{% hint style="success" %}
**没有时间使用大厅服务？** 引导玩家通过 Discord 或私信共享组 ID。
{% endhint %}

<table><thead><tr><th width="390">游戏设计 - 功能 / 需求</th><th>赛前大厅</th><th>匹配组</th></tr></thead><tbody><tr><td><a data-footnote-ref href="#user-content-fn-1">邀请好友和我一起玩</a></td><td>✅</td><td>✅</td></tr><tr><td>修改我的玩家/对局偏好</td><td>✅</td><td>❌</td></tr><tr><td>查看其他大厅成员偏好</td><td>✅</td><td>❌</td></tr><tr><td>存储和管理自定义键值数据</td><td>✅</td><td>❌</td></tr><tr><td>通知组成员我已准备好开始游戏</td><td>❌</td><td>✅</td></tr><tr><td>显示匹配进度并寻找对局</td><td>❌</td><td>✅</td></tr><tr><td>获取玩家/组的队伍分配</td><td>❌</td><td>✅</td></tr><tr><td>获取游戏服务器连接详情</td><td>❌</td><td>✅</td></tr></tbody></table>

我们的跨平台配对器支持所有商业和自定义大厅服务：

<table><thead><tr><th>大厅服务（第三方）</th><th width="120" data-type="checkbox">Unreal Engine</th><th width="75" data-type="checkbox">Unity</th><th width="50" data-type="checkbox">PC</th><th width="90" data-type="checkbox">主机</th><th width="65" data-type="checkbox">VR/XR</th><th width="100" data-type="checkbox">移动端</th></tr></thead><tbody><tr><td><a href="https://dev.epicgames.com/docs/game-services/lobbies-and-sessions/lobbies/lobbies-intro">Epic 在线服务大厅</a><br>（Epic Games）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="https://partner.steamgames.com/doc/features/multiplayer/matchmaking#friends">Steamworks 大厅</a><br>（Valve Corporation）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="https://heroiclabs.com/docs/nakama/concepts/groups/">Nakama 组</a><br>（Heroic Labs）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="https://learn.microsoft.com/en-us/gaming/playfab/community/associations/groups/quickstart">Playfab 大厅</a><br>（Microsoft）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="https://docs.braincloudservers.com/learn/key-concepts/multiplayer/lobbies/#lobby-experience">brainCloud 大厅</a><br>（bitHeads）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="https://developer.apple.com/documentation/gamekit/connecting-players-with-their-friends-in-your-game">Gamekit 好友</a><br>（Apple）</td><td>true</td><td>true</td><td>false</td><td>false</td><td>false</td><td>true</td></tr><tr><td>自定义大厅<br>（你的公司）</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td><td>true</td></tr></tbody></table>

大厅拥有者（发送邀请的玩家）也必须创建匹配组。

**将你组的 ID 存储在共享大厅数据中**，这样其他大厅成员就能轻松找到并加入与第三方大厅关联的匹配组。被邀请加入该组的玩家使用该组 ID 来 **创建他们的成员资格（加入）**，并 **安全地存储他们的** [**匹配属性**](#matchmaking-rules)**.**

{% hint style="warning" %}
**一旦一个组开始匹配，就不能再加入。** [#abandon-queue](#abandon-queue "mention") 并创建一个新的组。
{% endhint %}

#### Ping 优化

如果 [#configuration](#configuration "mention") 包含 [`延迟` 规则](#rule-example-elo_rating) 所有组成员都会发送他们的 [ping-beacons](https://docs.edgegap.com/zh/learn/bian-pai/ping-beacons "mention") 测量结果到 **防止将玩家匹配到遥远地区** 或 ping（延迟）高得多/低得多的区域。

{% code title="示例游戏客户端 ping 测量值（毫秒）" %}

```json
{
  "Chicago": 224.4,
  "Frankfurt": 23.2,
  "Tokyo": 167.4
}
```

{% endcode %}

#### **放弃队列**

组拥有者可以删除该组，这会自动删除所有组成员资格。匹配开始后删除该组会取消所有成员资格，并在稍后将其删除。

组成员（除拥有者外）可以在 [#find-match](#find-match "mention")之前的任何时间删除他们的成员资格（离开组）。之后删除成员资格将会取消整个组的匹配。

{% hint style="info" %}
一旦匹配被取消，成员会 [自动从匹配中移除](#matchmaking-profiles) 并通过成员资格 `status:CANCELLED`  状态在下一次状态轮询响应中收到通知。
{% endhint %}

一旦取消，如果组希望重新开始匹配，组拥有者必须重新创建该组，将新的组 ID 共享给成员，并让他们重新创建各自的成员资格。

**一旦找到对局，组就不能被删除** (`409 冲突`），并且会被 [自动移除](#connect-to-server)。你的服务器应当在判定玩家已离开之前，给玩家一些连接时间（例如 60 秒）。在这种情况下，你的服务器可以：

* 用 AI 角色替换离开的玩家，立即开始对局，
* 或者创建一个 [补位](#backfill-match) 来寻找新玩家替换离开的玩家，
* 或者如果你的游戏设计允许可变玩家数量，则在不替换离开的玩家的情况下继续。

### 寻找对局

要开始寻找对局，所有成员和拥有者都必须将自己标记为就绪。

{% hint style="success" %}
要让组拥有者 **立即开始匹配，在创建时将成员标记为就绪**。一旦拥有者将自己标记为就绪，匹配就会开始，因为每个人都已准备好。
{% endhint %}

{% hint style="info" %}
为了获得最佳体验， **请通过游戏内 UI 向玩家提供状态更新**.
{% endhint %}

**所有玩家必须定期轮询他们的成员资格** （建议 3-5 秒），以检测匹配何时开始，并通过游戏内 UI 传达匹配进度。

玩家应该 **持久化保存他们的成员资格和组 ID**，这样如果游戏客户端崩溃，他们可以重新启动游戏并继续，而不会丢失匹配进度。

一旦我们找到足够的玩家组成同一队伍并满足你的 [#matchmaking-rules](#matchmaking-rules "mention")，玩家将在其成员资格响应中收到 `status:TEAM_FOUND`.

在此阶段删除成员资格将导致所有组成员资格被取消，并且所有其他分配到同一队伍的组将返回到 `status:SEARCHING` .

队伍继续使用其各组之间重叠的值（如果是 `number_difference` 则取平均值）与其他队伍继续匹配，直到组队完成。成员资格会通过响应指示这一点  `status:MATCH_FOUND` ，这意味着你的 [部署正在启动](https://docs.edgegap.com/zh/bian-pai/deployments#id-1.-start-a-deployment).

**配对器旨在最大化对局填充率，并且不会继续到 `MATCH_FOUND` ，直到以下任一条件满足：**

1. 足够多的队伍与配置的最大队伍大小匹配，
2. 或者如果 [#rule-expansion](#rule-expansion "mention") 已定义且已达到扩展时间，并且足够多的队伍与配置的最小队伍大小匹配，
3. 或者配置的票据过期时间已到，并且足够多的队伍与配置的最小队伍大小匹配。

如果在配置的票据过期前这两种情况都未成功，组和票据将被取消。

{% hint style="info" %}
在测试期间，或与处于不太热门地区的玩家一起时，是否遇到较长的排队时间？请设置更短的票据过期时间（例如 30 秒），并在过期后在客户端重新创建组（或票据）。
{% endhint %}

当一个组（或玩家）被匹配到一个队伍时，票据过期会自动重置。

{% hint style="success" %}
存储 `team_id`  和 `match_id` 到你的游戏后端中，以在游戏内显示队伍成员信息。
{% endhint %}

{% hint style="info" %}
每位玩家都会收到一个 **唯一的票据 ID，可用于** [#authenticate](#authenticate "mention") **与游戏服务器连接。**
{% endhint %}

如果玩家已匹配并分配到游戏服务器，他们的票据会自动删除。那些在之后放弃队列的玩家 `status:HOST_ASSIGNED`  可以被替换为 [补位](#backfill-match).

一旦玩家收到 `status:HOST_ASSIGNED`  他们就会继续 [#connect-to-server](#connect-to-server "mention").

### 连接到服务器

### 补位对局

一旦游戏服务器初始化完成， **你的服务器应当**:

* **为每位新玩家启动离开计时器。** 我们建议使用加载场景/关卡向已连接玩家显示加载进度——可以是完整的 3D 场景、类似大厅的社交 UI，或者带进度条的加载界面。
* **持续跟踪新玩家连接或现有玩家随时间离开**:
  1. 新玩家必须向服务器声明票据 ID 以进行身份验证，并将其连接映射到配对器 [#injected-variables](#injected-variables "mention") 或 `assigned_ticket` （如果已补位）。
  2. 在服务器生命周期内为未使用的玩家容量（离开者）创建新的补位。
  3. 续订已过期的补位，这些补位会在以下时间后被删除 `ticket_expiration_period`.
* **清理（删除）任何剩余的补位** 一旦 [#id-5.-deployment-stopped](https://docs.edgegap.com/zh/bian-pai/deployments#id-5.-deployment-stopped "mention"):
  * Unity - [`OnApplicationQuit`](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/MonoBehaviour.OnApplicationQuit.html) 回调或自定义游戏结束回调，
  * Unreal Engine - [`OnWorldDestroyed`](https://forums.unrealengine.com/t/call-function-before-quit-game/344954/2) , [`PreExit`](https://forums.unrealengine.com/t/event-on-close/298087/2) ，或自定义游戏结束回调。

只要提供了有效的服务器分配和至少一个票据，任何配置文件都可用于补位。请参见 [#backfill-showcase](https://docs.edgegap.com/zh/learn/pi-pei/..#backfill-showcase "mention") 以获取一个最小示例。

## ⚙️ 配置

配对器 API 是从你创建新配对器（或快速重启配对器）时指定的 JSON 配置生成的。你可以指定任意数量、具有不同规则和扩展的配置文件：

{% hint style="success" %}
参见 [](https://docs.edgegap.com/zh/learn/pi-pei "mention") 以获取我们的 SDK 和详细示例场景。
{% endhint %}

{% hint style="warning" %}
编辑正在运行的配对器将 **触发快速重新加载**，删除所有票据并导致短暂停机。
{% endhint %}

### 配置文件（队列） <a href="#matchmaking-profiles" id="matchmaking-profiles"></a>

配置文件表示完全独立的匹配队列，共享相同的配对器版本。你可以 **为每个配对器配置任意数量的配置文件。** 将玩家基础拆分到多个配置文件中可能会导致玩家排队时间更长。

每个配对器配置文件使用一个 [应用版本](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions) 作为启动新部署（服务器）的模板。

{% hint style="success" %}
某些游戏模式可能需要更多 vCPU / RAM，尤其是在支持更多玩家数量时。每个 **配对器可以包含多个配置文件**，每个都链接到一个资源已调整的应用版本。
{% endhint %}

### 规则 <a href="#matchmaking-rules" id="matchmaking-rules"></a>

每位玩家和组一开始都通过  `初始` 规则进入匹配队列并寻找对局。

路径为 `.rules.initial` 的配置文件中的每个条目都表示一条规则，其中：

* **key** 是一个字符串值，用于按你喜欢的方式命名该规则；例如 `match_size` ，而
* **value** 是一个定义规则类型和属性的对象，遵循我们的标准规则集。

{% hint style="info" %}
所有规则必须同时满足，才能启动主机分配并开始或找到一个部署。
{% endhint %}

**运算符（规则类型）**

**`player_count`** 是一条特殊规则，用于定义启动分配需要匹配多少玩家。

{% hint style="warning" %}
规则 `player_count`  **是必需的，并且在你的初始配置规则中只能定义一次** 。
{% endhint %}

配对器始终努力最大化对局填充率，最高可达指定的 `max_team_size` :

1. 如果达到最大队伍大小，则会立即完成对局，
2. 否则，玩家会在队列中等待以填充对局，直到 [扩展](#rule-expansion) （或过期）即将到期，
3. 在 [扩展](#rule-expansion) （或过期）前不久，如果可以形成部分对局（≥ 最小值且 < 最大队伍大小），则将使用处于同一扩展阶段的所有玩家完成该对局（假设其他规则通过）。

{% hint style="success" %}
对于合作模式、自由混战或非对称队伍规模的游戏模式，请将你的 `"team_count": 1` .
{% endhint %}

队伍数量可配置为为竞技游戏组成多个平衡队伍：

* **组属性按平均值/重叠计算** ，基于组的 **玩家属性，**
* **队伍属性按平均值/重叠计算** ，基于队伍的 **组属性。**

假设固定队伍大小为 4 名玩家：

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FSFEzBayk3XNEUTIynjNd%2Fimage.png?alt=media&#x26;token=11a43fdf-3a99-4caa-8d2b-639e0f3cc06f" alt=""><figcaption><p>对局示例场景</p></figcaption></figure>

{% hint style="info" %}
**组在队伍中匹配时不会超员，** 仅当某个队伍有足够容量容纳整个组时才会匹配。
{% endhint %}

**`string_equality`** 匹配具有完全相同字符串值的玩家。

<details>

<summary>规则示例： <code>selected_game_mode</code></summary>

`selected_game_mode`  规则将以区分大小写的方式匹配玩家：

:white\_check\_mark: Alice + Bob + Dave 可能匹配，

:x: Alice + Erin，或 Charlie + Frank 永远不会匹配。

| "Free For All" | "Capture The Flag" | "capture the flag" |
| -------------- | ------------------ | ------------------ |
| Alice          | Erin               | Frank              |
| Bob            | Charlie            |                    |
| Dave           |                    |                    |

</details>

**`number_difference`** 匹配彼此数值绝对差在允许范围内的玩家。

<details>

<summary>规则示例： <code>elo_rating</code></summary>

`elo_rating`  上面的规则配合 `"max_difference": 50` 初始时：

:white\_check\_mark: Alice + Bob 可能匹配，或者 Bob + Charlie 可能匹配，

:x: Alice + Bob + Charlie 永远不会匹配。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FxtTxZ7TPSa8a8WtnGNAE%2Fimage.png?alt=media&#x26;token=c48b843b-c4e5-47bf-9154-07254a788067" alt=""><figcaption></figcaption></figure>

</details>

**`intersection`** 匹配拥有一个或多个重叠字符串值的玩家，且区分大小写。

<details>

<summary>规则示例： <code>selected_map</code></summary>

`selected_map` 上面的规则配合 `"overlap": 1`  将匹配：

:white\_check\_mark: Alice + Bob + Charlie 可能匹配，或者 Alice + Bob + Dave 可能匹配，

:x: Alice + Bob + Charlie + Dave 永远不会匹配。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FcQSUAnRkZKVyuGjFWSYL%2Fimage.png?alt=media&#x26;token=bf1a4e28-230a-4c9a-9ef6-a0dea4dbecdb" alt=""><figcaption></figcaption></figure>

</details>

#### 规则扩展

可选地， **`扩展`**  会在玩家在队列中等待一段时间后修改规则属性，以放宽限制并扩大可匹配的玩家池， **从而更快地完成匹配**.

<details>

<summary>示例场景：扩展</summary>

[最初，我们需要 1 个队伍，恰好由 4 名玩家组成（可以分成多个组）](https://docs.edgegap.com/zh/learn/pi-pei/..#advanced-example) 并满足：

* 对同一（任一）信标的最大延迟为 125 ms，
* 同一信标的最低/最高值之间延迟差不超过 125 ms，
* 最低和最高段位玩家之间的技能分差不超过 50 分，
* 完全相同（区分大小写）的所选游戏模式，
* 玩家之间至少有一个匹配的地图选择（区分大小写），
* 玩家之间至少有一个匹配的 [补位组大小](#backfill-match) 值。

在上面的示例中，我们 **通过修改属性来扩大搜索** 在以下时间后：

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>30 秒：</td><td><ul><li>4 名玩家</li><li><strong>150 技能分差范围</strong></li><li><strong>最大 250 ms 延迟</strong></li></ul></td></tr><tr><td>60 秒：</td><td><ul><li>4 名玩家</li><li><strong>200 技能分差范围</strong></li><li>最大 250ms 延迟</li></ul></td></tr><tr><td>3 分钟（180 秒）：</td><td><ul><li><strong>1-4 名玩家</strong></li><li>200 技能分差范围</li><li><strong>任意延迟</strong></li></ul></td></tr></tbody></table>

</details>

<details>

<summary>扩展微调</summary>

预测玩家偏好类似于射击一个移动目标。请在发布时使用较少限制的规则集开始，然后在之后通过迭代进行优化 [#analytics](#analytics "mention").

这些问题也许能帮助你梳理思路：

* 我的游戏时长是多久？
  * 5 分钟的游戏时长意味着每位玩家每 5 分钟都会重新加入队列，这会间接降低排队时间，因为任何给定时刻都有更多玩家在排队。
* 我的 [峰值 CCU](#user-content-fn-2)[^2] 以及我的 [低谷 CCU](#user-content-fn-3)[^3]?
  * 如果低谷/高峰之间差异很大（超过 60%），你可能需要为低谷单独设置一个配置文件，在每次扩展中等待更久，以积累更多玩家。
* 我的玩家地理分布如何？
  * 跨多个时区的均匀分布意味着高峰和低谷的差异较小，但不会提高匹配速度，因为如果你的 [#ping-optimization](#ping-optimization "mention") 配置正确，处于不同地区的玩家不应匹配（否则会导致高 ping）。
* 我的技能分布如何（按区域）？
  * 技能分布通常遵循 [钟形曲线](https://www.simplypsychology.org/normal-distribution.html) （自然分布），因此每偏离平均值一个标准差，离平均值越远的玩家就越少。平均值的玩家会在第一次扩展中更快匹配，但极端值会成为问题。
  * 我们建议每次扩展时增加扩大的差异值，例如 25 -> 50 -> 100，这样你可以考虑曲线两端的玩家较少。
  * 如果你有任何挑战者段位（职业玩家），我们建议使用带自定义技能设置的单独配置文件，因为样本更少，而且通常不符合整个玩家群体的整体趋势。（偏向极端、反向钟形曲线）
* 如何在玩家基数较小的情况下提升匹配速度和对局填充率？
  * 尽可能多地了解你的玩家及其偏好！
  * 考虑一开始移除一些规则或放宽限制。
  * 随着时间推移放宽队伍大小或队伍数量——部分匹配总比没有匹配好。
  * 延长扩展之间的持续时间，以积累更多玩家。
  * 如需更多技巧和诀窍，尤其是针对你的游戏设计，请联系我们。

</details>

{% hint style="info" %}
任何规则属性的扩展都会 **覆盖该属性之前的值** 。
{% endhint %}

## 📌 注入变量

你的服务器可能需要知道有关其玩家的详细信息。玩家属性、解析后的对局值以及其他值会与常规 [#injected-variables](https://docs.edgegap.com/zh/bian-pai/application-and-versions#injected-variables "mention").

预览未格式化 **🏁 高级示例变量：**

```
MM_MATCH_PROFILE=advanced-example
MM_EXPANSION=initial
MM_TICKET_IDS=["cusfn10msflc73beiik0","cusfn18msflc73beiil0"]
MM_TICKET_cusfn10msflc73beiik0={"id":"cusfn10msflc73beiik0","created_at":"2025-02-21T22:17:42.3886970Z","player_ip":"174.93.233.25","group_id":"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":12.3,"LosAngeles":145.6,"Tokyo":233.2},"elo_rating":1337,"selected_game_mode":"quickplay","selected_map":["DustII","Airport","BankVault"],"backfill_group_size":["new","1"]}}
MM_TICKET_cusfn18msflc73beiil0={"id":"cusfn18msflc73beiil0","created_at":"2025-02-21T22:17:42.2548390Z","player_ip":"174.93.233.23","group_id":"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":87.3,"LosAngeles":32.4,"Tokyo":253.2},"elo_rating":1339,"selected_game_mode":"quickplay","selected_map":["Island","Airport"],"backfill_group_size":["new","1"]}}
MM_GROUPS={"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1":["cusfn10msflc73beiik0"],"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f":["cusfn18msflc73beiil0"]}
MM_TEAMS={"cusfn1gmsflc73beiim0":["b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","015d4dc8-6c79-4b5c-bbc6-f309b9787c8f"]}
MM_MATCH_ID=advanced-example_initial-2025-02-21T22:17:43.3886970Z
MM_INTERSECTION={"selected_map":["Airport"],"backfill_group_size":["new","1"]}
MM_EQUALITY={"selected_game_mode":"quickplay"}
```

{% hint style="info" %}
环境变量被 **存储为字符串化的 JSON**，请使用我们的 SDK 或自定义方法进行解析。
{% endhint %}

{% hint style="success" %}
**服务器可以将玩家连接映射到组和属性** 在玩家向服务器发送其票据 ID 后。
{% endhint %}

## 🧵 玩家追踪

如果你的玩家遇到任何问题，将其路径追踪到服务器日志会很有帮助。每个配对器 **部署** **都会标记已分配的玩家票据 ID** 这样你就可以轻松 [#filter-deployments](https://docs.edgegap.com/zh/bian-pai/deployments#filter-deployments "mention") 并找到 [#container-logs](https://docs.edgegap.com/zh/bian-pai/deployments#container-logs "mention") 来帮助你排查问题。

{% hint style="success" %}
**在客户端对局历史 UI 中显示票据 ID 和部署 ID** 以便在排查问题时追踪玩家。
{% endhint %}

{% hint style="info" %}
参见 [#connection-quality](https://docs.edgegap.com/zh/bian-pai/deployments#connection-quality "mention") 以了解部署故障排查。
{% endhint %}

## 👀 分析

深入了解你的配对器负载和性能，无需任何代码或配置。

🌟 [**将配对器升级到企业层**](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) **以解锁匹配指标和洞察：**

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fhb8NmB4ELuG7ayGLTeHs%2Fimage.png?alt=media&#x26;token=e3e0371e-c33f-48c8-bd15-5c11448dc633" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fl0zTNccJASUTkJfTYxss%2Fimage.png?alt=media&#x26;token=0d061320-9524-4b12-83e6-ea9112ef1409" alt=""><figcaption></figcaption></figure>

## ☁️ 托管集群

Edgegap 提供全天候 24/7 便利托管和管理的配对器。

选择最适合你目标的托管方案：

#### 私有集群层级

只需点击一下即可升级到私有集群。发布后，在没有玩家停机时间的情况下更改私有集群层级也是可以的，使用 [#rolling-updates-and-ab-tests](#rolling-updates-and-ab-tests "mention")。受管集群为公开发布的游戏提供由 Edgegap 维护的高可用服务托管，并提供 24/7 实时支持。

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

* **玩家数量** - 玩家越多，票据和 API 请求越多，
* **每位玩家的请求数量** - 更快的重试会增加服务负载并消耗资源，
* **配置复杂度** - 重叠规则和扩展尤其耗费资源，
* **平均对局时长** - 更短的游戏时段会让玩家更频繁地重新加入匹配，
* **过期和移除周期** - 过期票据会随着时间堆积并消耗资源，
* **客户端重试回退逻辑** - 使用带抖动的退避重试有助于分散流量峰值。

{% hint style="warning" %}
**为成功做好准备，并在发布后进行优化，这样你就不会在上线当天阻塞玩家。** 使用 [#matchmaking-sdk](https://docs.edgegap.com/zh/unity/developer-tools#matchmaking-sdk "mention") 或 **实现指数抖动退避** 来应对高负载。
{% endhint %}

### 速率限制

为保护你的集群免于超过突发容量并崩溃，我们根据使用 [#advanced-example](https://docs.edgegap.com/zh/learn/pi-pei/..#advanced-example "mention") 配置进行的内部负载测试来限制每秒请求数。

<table><thead><tr><th>API 端点</th><th width="130">免费层</th><th width="130">业余爱好者层</th><th width="130">工作室层</th><th width="130">企业层</th></tr></thead><tbody><tr><td><strong>总限制</strong></td><td><strong>100</strong></td><td><strong>200</strong></td><td><strong>750</strong></td><td><strong>2,000</strong></td></tr><tr><td>创建部署</td><td>5</td><td>10</td><td>30</td><td>30</td></tr><tr><td>列出信标</td><td>10</td><td>20</td><td>75</td><td>200</td></tr><tr><td>创建组<br>+ 创建票据<br>+ 创建组票据</td><td>10</td><td>20</td><td>75</td><td>200</td></tr><tr><td>读取成员资格<br>+ 读取组<br>+ 读取票据</td><td>10</td><td>120</td><td>450</td><td>1,300</td></tr><tr><td>创建回填</td><td>5</td><td>10</td><td>37</td><td>100</td></tr></tbody></table>

速率限制以以下方式表示 **指定的一组 API 端点的每秒合并请求数**.

如果你的游戏客户端在收到响应后不重试请求 `429 请求过多`  **你的部署可能会缺少玩家** 这些玩家因负载过高而停止读取其分配信息。

#### 负载测试

匹配和分配需要 CPU 和内存使用，这会导致每个私有匹配器产生托管成本。有关每个层级相关的资源和价格，请参见 [我们的定价页面](https://edgegap.com/resources/pricing#matchmaker).

{% hint style="success" %}
**始终使用** [**私有集群**](#private-cluster-tiers) **进行压力测试。** 免费匹配器严格仅限于开发测试使用。
{% endhint %}

在设计负载测试时， **请考虑真实的玩家模式**:

| 真实场景                                    | 不真实的流量模式                       |
| --------------------------------------- | ------------------------------ |
| ✅ 玩家逐步加入匹配，数小时内 req/s 逐渐增加。             | ❌ 所有玩家协调一致，在完全相同的一秒内创建票据。      |
| ✅ 玩家在每次重试之间等待的时间逐渐增加（例如 1s-5s-10s-10s）。 | ❌ 所有玩家在收到 `429 请求过多`  响应后立即重试。 |
| ✅ 大多数玩家会在短时间内（10-60 秒）收到分配并停止轮询。        | ❌ 所有玩家在收到分配后仍继续轮询固定时长。         |
| ✅ 大多数玩家会先完成游戏（需要时间），然后再重新开始匹配。          | ❌ 所有玩家在收到分配后立即重新开始匹配。          |
| ✅ 高峰流量每天持续 6-8 小时，之后某些时区的流量会下降。         | ❌ 高峰流量每天持续 24 小时，所有玩家昼夜不停地游玩。  |

如果匹配器负载过高：

* 如果 CPU 被限流，匹配可能会变慢，
* 如果匹配器内存耗尽，它将重启而不会丢失票据数据，希望客户端实现指数退避，并将突发流量分散到更长时间内。

## ⏩ 滚动更新 <a href="#rolling-updates-and-ab-tests" id="rolling-updates-and-ab-tests"></a>

跟踪服务器和客户端版本之间的兼容性可能会变得复杂。请遵循我们的建议，以实现可靠的发布、更新，并避免停机或兼容性问题。

**重启后，你的匹配器 URL 和认证令牌将始终保持不变。**

{% hint style="danger" %}
**为开发和生产** 环境分别创建独立的匹配器，以便安全试验。
{% endhint %}

#### ⚠️ **上线前**

我们建议提前创建多个匹配器副本： `绿色`, `蓝色` 和 `橙色`。在发布更新时，你可以轮换使用哪个匹配器（[蓝绿策略](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment)).

**为每个实例选择不同的区域，以防止** 局部故障期间的停机。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Flzy4elHYDPBMpjSMG1HS%2Fimage.png?alt=media&#x26;token=7da795fc-ae6c-490f-b65c-5f8dda635503" alt=""><figcaption><p>蓝绿 DevOps 环境示例</p></figcaption></figure>

#### **🔃 客户端 + 服务器更新**

**前提条件：** 本节假设你已完成 [#before-going-live](#before-going-live "mention").

为了 **发布游戏客户端 + 服务器更新**，你可以：

1. 准备新的服务器应用版本 `v1.2.0-rc` 在 Edgegap 上：
   1. 向你的容器镜像仓库推送新的镜像标签 `t1.2.0`,
   2. 创建新的应用版本 `v1.2.0-rc`,
2. 通过以下方式执行任何开发测试： [部署你的新应用版本](https://app.edgegap.com/deployment-management/deployments/list) `v1.2.0-rc`:
   1. 将游戏引擎的编辑器连接到提供的 URL + 外部端口，
3. 更新未使用的匹配器 `蓝色` 以链接到你的新镜像标签 `t1.2.0`,
   1. 为新应用版本启用缓存 `v1.2.0-rc` ，为此版本启用缓存将确保镜像也会被缓存为版本 `v-blue`  ，因为它们引用的是同一个标签，
   2. 等待版本中的缓存指示器 `v1.2.0-rc`  达到 :green\_circle: 绿色，
4. 更新你的新游戏客户端 `c2` 以使用新版本 `v-blue` 在创建票据时：
   1. 在游戏客户端中更新你的基础 URL 和授权令牌，
5. 对你的新游戏客户端执行 QA 测试和最终验证 `c2`:
   1. 如果你发现并解决了任何问题，请从头重复该流程，
   2. 在匹配器停止后，等待 3-7 天让匹配器 DNS 变更传播到全球 ISP（快速重启不需要 DNS 更新或等待期），
6. 发布你的新游戏客户端更新 `c2` 到游戏分发平台，
7. 留出时间让新的游戏客户端 `c2` 分发到玩家设备（通常最长 3-7 天）：
   1. 监控过时的游戏客户端 `c1`  使用部署 [#analytics](https://docs.edgegap.com/zh/bian-pai/deployments#analytics "mention"),
8. 清理你 Edgegap 账户中未使用的资源：
   1. 删除镜像标签 `t1.0.0` 以释放容器镜像仓库容量，
   2. 删除镜像标签 `t1.1.0` 以释放容器镜像仓库容量，
   3. 关闭你的 `绿色`  匹配器，以暂停计费，直到下一次更新。

{% hint style="success" %}
**对于下一次更新**，增加版本号并交换 `绿色` 和 `蓝色` 指南中的关键字。
{% endhint %}

#### **⚡ 服务器热修复**

**前提条件：** 本节假设你已完成 [#before-going-live](#before-going-live "mention").

为了 **在不需要游戏客户端更新的情况下发布服务器补丁**，你可以：

1. 准备新的服务器应用版本 `v1.2.0-rc` 在 Edgegap 上：
   1. 向你的容器镜像仓库推送新的镜像标签 `t1.2.0`,
   2. 创建新的应用版本 `v1.2.0-rc`,
2. 通过以下方式执行测试和验证： [部署你的新应用版本](https://app.edgegap.com/deployment-management/deployments/list) `v1.2.0-rc`:
   1. 将游戏引擎的编辑器连接到提供的 URL + 外部端口，
   2. 如果你发现并解决了任何问题，请从头重复该流程，
   3. 为新应用版本启用缓存 `v1.2.0-rc` ，为此版本启用缓存将确保镜像也会被缓存为版本 `v-green`  稍后，因为它们将引用相同的标签，
   4. 等待版本中的缓存指示器 `v1.2.0-rc`  达到 :green\_circle: 绿色，
3. 更新版本 `v-green`  以链接到你的新镜像标签 `t1.2.0`,
   1. 新的匹配将自动使用更新后的标签开始分配 `t1.2.0`,
   2. 监控过时的游戏客户端 `c1`  使用部署 [#analytics](https://docs.edgegap.com/zh/bian-pai/deployments#analytics "mention"),
4. 清理你 Edgegap 账户中未使用的资源：
   1. 删除镜像标签 `t1.1.0` 以释放容器镜像仓库容量。

## 📗 API <a href="#matchmaking-api" id="matchmaking-api"></a>

客户端和服务器可以直接调用 API，或使用游戏引擎 SDK，另见 [](https://docs.edgegap.com/zh/learn/pi-pei "mention").

### 服务器到服务器 <a href="#server-to-server-api" id="server-to-server-api"></a>

为匹配流程添加增强或自定义控制 - 使用我们的 [managed-clusters](https://docs.edgegap.com/zh/learn/advanced-features/managed-clusters "mention") 或任何云 FaaS[^4] 计算平台，实现以下任一目标：

* 附加敏感玩家属性 - 例如作弊者标记、技能评级或类似信息，
* 在游戏内提供队伍和比赛上下文 - 在加载期间列出我的队友和对手，
* 限制特定边缘情况 - 例如一次只允许每个玩家加入 1 个组，
* 添加缓存或 API 速率限制 - 减少对匹配器的请求数量和负载，
* 自定义大厅-组集成 - 在匹配前创建非对称/基于角色的大堂。

{% hint style="success" %}
**包含参数 `player_ip`  以及成员的公网 IP 地址** 以确保尽可能低的玩家延迟并利用 [#id-1.-server-score-strategy-best-practice](https://docs.edgegap.com/zh/bian-pai/deployments#id-1.-server-score-strategy-best-practice "mention").
{% endhint %}

{% hint style="info" %}
游戏客户端可以使用 [ipify.org](http://ipify.org/) 的免费服务来查找其公网 IP。VPN 可能会隐藏公网 IP 地址。
{% endhint %}

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FzLfA3fEBgwaziGtp2yMO%2Fimage.png?alt=media&#x26;token=3d551e74-4a60-47a6-9d79-a506f961663d" alt=""><figcaption><p>服务器到服务器匹配活动图</p></figcaption></figure>

#### 跨源资源共享（CORS）

对于托管在第三方分发平台上的 WebGL 游戏（例如 [itch.io](http://itch.io/)），从游戏客户端向匹配器发送任何请求都可能导致 [跨源资源共享](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 策略违规。大多数现代网页浏览器会发送一个 [预检请求](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) 来验证后端服务（匹配器）是否理解并接受来自你的游戏客户端的通信。

预检检查失败（出于安全原因的默认设置）可能会导致 [若干可能的 CORS 相关错误之一](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin)，最常见的是 `缺少 CORS 头 'Access-Control-Allow-Origin'` .

要解决此错误，请将 **`allowed_cors_origin`** 参数添加到你的配置中，以便：

* 将你的确切客户端托管域名加入白名单：

<details>

<summary>🍀 简单示例（特定域名示例）</summary>

<pre class="language-json"><code class="lang-json">{
  "version": "3.2.0",
  "allowed_cors_origins": [
    "https://dev.my-game-server.com",
    "https://prod.my-game-server.com"
  ],
  "profiles": {
      <a data-footnote-ref href="#user-content-fn-5">...</a>
  }
}
</code></pre>

</details>

* 或将通配符域名加入白名单（包括所有子域名）：

<details>

<summary>🍀 简单示例（通配符域名示例）</summary>

<pre class="language-json"><code class="lang-json">{
  "version": "3.2.0",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
      <a data-footnote-ref href="#user-content-fn-5">...</a>
  }
}
</code></pre>

</details>

{% hint style="info" %}
**如果域名配置正确，则匹配器预检请求不需要任何凭据**。
{% endhint %}

## 🚨 故障排查

**你的成功是我们的首要任务。** 如果你想发送自定义请求、请求缺失的关键功能，或表达任何想法， [请在我们的社区 Discord 中联系我们](https://discord.gg/MmJf8fWjnt).

<details>

<summary>为什么我在尝试创建新的匹配器时会收到错误？</summary>

* 请阅读错误信息，可能是你拼错了标识符、规则或运算符。- 使用 [JSONLint](https://jsonlint.com/) 验证你的 JSON 格式，你可能遗漏了逗号或括号。- 通过 [我们的社区 Discord](https://discord.gg/MmJf8fWjnt) 寻求帮助，我们很乐意协助。🙏

</details>

<details>

<summary>为什么我的匹配器在 3 小时后自动关闭了？</summary>

* 免费层中的匹配器用于初始测试，并会在 3 小时后自动关闭。要继续测试，你可以 [重启你的匹配器](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list).
* 请考虑升级到付费层以获得无限运行时间。

</details>

<details>

<summary>为什么我无法在我的账户上启动第二个部署？</summary>

* 在免费层中，你一次只能运行 1 个并发部署。
* 请考虑升级到付费层以获得无限部署。

</details>

<details>

<summary>为什么我会在随机时间收到分配/部署，而忽略 <code>player_count</code>?</summary>

* 你或其他团队成员可能在之前未分配的测试会话中创建了票据。请 [重启你的匹配器](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list).

</details>

<details>

<summary>我的票据卡在 <code>SEARCHING</code> .</summary>

* 请确认你已根据你的配置创建了足够多的匹配票据。

</details>

<details>

<summary>我的票据反复卡在 <code>MATCH_FOUND</code> 和 <code>TEAM_FOUND</code> 之间切换。</summary>

* 免费层账户一次仅限 1 个部署。
* 请考虑升级，或停止当前部署以启动新的部署。

</details>

<details>

<summary>我的票据直接变为 <code>CANCELLED</code>.</summary>

* 你的票据已到期。请创建新票据，或在配置中增加到期时间以用于测试。

</details>

<details>

<summary>我在查看票据时收到 <code>HTTP 404 Not Found</code> 。</summary>

* 你的票据已被删除，原因可能是 DELETE 请求，或已达到其删除周期（在票据过期后开始，定义在你的配置中）。请重新创建新票据，或在配置中增加到期/删除周期以用于测试。

</details>

<details>

<summary>我的匹配器显示错误，我该怎么办？</summary>

* 如果这是一个开发或测试实例，请先尝试重启你的匹配器。- 请通过 [我们的社区 Discord](https://discord.gg/MmJf8fWjnt).
* 如果该问题影响到线上游戏，请创建一个 [紧急支持请求](https://edgegap.atlassian.net/servicedesk/customer/portal/3).

</details>

## 🔖 更新日志

你的配置文件将根据所使用的匹配器版本进行验证，请确保你的规则与该匹配器版本的能力相匹配。

{% hint style="info" %}
**最新版本的匹配器是 `3.2.2`**。本页上的所有示例均为最新。请留意你的匹配器版本的支持终止通知。另见 [#rolling-updates-and-ab-tests](#rolling-updates-and-ab-tests "mention").
{% endhint %}

#### 3.2.2（2025年3月18日）

🩹 **错误修复：**

* 一个小错误修复：如果已匹配的玩家在找到比赛前删除其票据，则解散队伍。

{% hint style="success" %}
**这是最新的匹配器服务版本，建议用于生产环境。**
{% endhint %}

{% hint style="warning" %}
**要升级你的匹配器版本 - 停止、编辑、重启。** 快速重启不会应用版本更改。
{% endhint %}

#### 3.2.1（2025年11月24日）

🩹 **错误修复：**

* 部署方面的轻微错误修复，解决了启动匹配器时的若干错误。

#### 3.2.0（2025年10月31日）

🩹 **错误修复：**

* 各种较小的规范修复和文档一致性更新。
* 跨匹配器基础设施的各种稳定性和自我修复修复。

**✨ 改进和新功能：**

* **引入** [#group-up](#group-up "mention") **功能** —— 管理组现在变得简单了，而且不需要第三方！
  * 不再需要在组成员之间共享复杂的票据属性，你只需要组 ID。
  * 当所有玩家都将自己标记为准备就绪后，开始作为组进行匹配。
  * 在加入时根据组长验证组成员属性，防止出现无法匹配的组（组内玩家的属性不符合配置文件规则）。
  * 验证组大小，并在达到最大队伍大小后拒绝新的成员加入。
  * 阅读我们更新后的文档，了解新的用户流程，SDK 更新即将推出！
* 票据（成员资格）现在包含你的比赛 ID - 跟踪玩家并添加 UI 元素，以共享你的队伍或对手队伍的昵称、技能评级或存储在第三方中的其他属性。
* 重大 [#rate-limits](#rate-limits "mention") 改造基于内部压力测试，对短时突发流量的处理更好。
* 通过将部分匹配大小延迟到扩展结束，提高了匹配填充率。
  * 如果达到最大队伍大小，立即匹配。
  * 否则在当前扩展结束时匹配，前提是已达到最小队伍大小。
* 为每个配置文件设置到期和删除周期，并针对最佳玩家体验进行优化。

{% hint style="warning" %}
要更新你的配置，请提高版本，并将到期和删除字段复制到每个配置文件。
{% endhint %}

#### 3.1.0（2025年6月10日）

🩹 **错误修复：**

* 匹配器现在可以正确验证包含不同规则的多个配置文件的票据。

**✨ 改进和新功能：**

* 更多优化以最大化匹配填充率，使用 [player\_count 规则](#matchmaking-rules)。如果只能形成部分匹配（>最小且 <最大队伍大小），票据现在将等待到扩展结束（或到期）。
  * 完整匹配（达到最大队伍大小）会立即进行（无变化）。
* 升级到企业版 [#hosting-cluster](#hosting-cluster "mention") 以解锁匹配 [#analytics](#analytics "mention")！无需代码或配置即可深入了解匹配器负载和性能。发布时的指标包括：
  * 在自定义时间段内创建的票据、回填、分配和部署总数，
  * 上述指标在自定义时间段内的每分钟速率，
  * 过期票据、扩展匹配、匹配填充率的总量和时间序列洞察，
  * API 使用指标等。
* 改进的 [#matchmaking-rules](#matchmaking-rules "mention") 文档，提供了更好的示例和可视化内容。

#### 3.0.0（2025年5月20日）

**⚠️ 重大变更：**

* 使用 [用于高效填充队伍的最小/最大队伍大小](#matchmaking-rules) （替代玩家数量扩展）：
  * 在你的配置中 `player_count` 规则，将 `team_size` 替换为 `min_team_size` 和 `max_team_size` 以实现“尽力而为”的匹配，尝试最大化匹配填充率，
  * 要要求每队特定数量的玩家，请将最小值和最大值设置为相同的值，
  * 回填绕过 `player_count` 规则，并始终与 1 个票据匹配（无变化）。
* 所有延迟都高于给定配置文件中最高 `max_latency` 的票据、组票据和回填将立即被拒绝，并返回 `400 错误请求` 响应给票据创建请求，而不是过期：
  * 仅在配置了 [延迟规则](#matchmaking-rules) 时适用，
  * 要绕过此行为，请创建一个扩展并设置 `max_latency: 99999` （任何高于你客户端延迟测量超时的值）。
* [注入的环境变量](#injected-environment-variables) 包含票据数据，现在包括字段 `id` （票据 ID），因此在创建 [#backfills](#backfills "mention").

🩹 **错误修复：**

* [#backfill](#backfill "mention") 时可以更容易复用，现在使用配置的删除和到期周期（类似于票据和组票据）。
* [#backfill](#backfill "mention") 现在可以正确使用配置的 [`intersection` 规则](#matchmaking-rules).
* 修复了 [openAPI 规范](#matchmaking-api) 针对 POST [#backfills](#backfills "mention") 请求（需要 `public_ip`）和 GET /tickets 响应（`team_id` 是可选的），并包含示例。

**✨ 改进和新功能：**

* 现在会考虑多达 3 倍更多的潜在匹配，从而生成更优的队伍并最大化匹配填充率。
* 由于并发优化，匹配速度最高提升 200%。
* 由于扩展算法优化，匹配填充率最高提升 40%。
* 提升了服务稳定性并加快了快速重启速度。

{% hint style="info" %}
基准测试使用混沌生成的数据制作，使用 [高级示例配置](#configuration).
{% endhint %}

<details>

<summary>更新日志归档（v2.1.0 及更早版本）</summary>

#### 2.1.0（2025年2月24日）

**⚠️ 重大变更：**

* 在 [#injected-environment-variables](#injected-environment-variables "mention"):
  * `MM_MATCH_PROFILE` 中分离了游戏配置文件和扩展阶段信息，现在只会包含配置中显示的配置文件名称。
  * 引入了 `MM_EXPANSION_STAGE` ，它将包含扩展阶段字符串（例如 “initial”、“15”、“30”）。
* 当 [#endpoint-tickets](#endpoint-tickets "mention")时，票据分配现在会包含组 ID。组 ID 也会作为 [#injected-environment-variables](#injected-environment-variables "mention")包含，即组 ID 到该组玩家 ID 列表的映射。
* 当 [#endpoint-tickets](#endpoint-tickets "mention")时，票据分配现在会包含队伍 ID。队伍 ID 也会包含在每个票据数据中 [#injected-environment-variables](#injected-environment-variables "mention").
* [#endpoint-tickets](#endpoint-tickets "mention") 现在返回 `409 冲突` HTTP 代码而不是 `204 无内容` 以表明由于部署正在启动，票据无法删除。要替换离开者，请使用 [#backfill](#backfill "mention") 由服务器在预先指定的超时后发出。
* [#endpoint-backfills](#endpoint-backfills "mention") 请求体参数 `attributes.deployment_request_id` 已移动到 `attributes.assignment.request_id`.
* [#endpoint-backfills](#endpoint-backfills "mention") 请求体现在要求将完整的分配详情作为 `attributes` 参数的一部分，此外还需要 `request_id`.

🩹 **错误修复：**

* 已解析的交集规则值现在位于 [#injected-environment-variables](#injected-environment-variables "mention") 中 `MM_INTERSECTION` 环境变量。
* 当配置更改时，快速重启功能现在可以可靠地重新生成 API 端点和 openAPI 规范。
* 修复了匹配器（重新）启动期间导致启动时间过长或匹配器卡住的若干错误。

**✨ 改进和新功能：**

* 提高了所有 API 端点的速率限制和可扩展性，覆盖所有匹配器层级。
* 当将玩家分配到 [#backfill](#backfill "mention")时，新增玩家的票据 ID 将作为标签添加到回填的 [deployments](https://docs.edgegap.com/zh/learn/bian-pai/deployments "mention").
* 添加了 swagger UI 认证功能，可直接在网页 UI 中测试 API，无需 postman。
* 改进了 openAPI 示例，使其更接近真实的请求和响应。
* 新增 [#inspect-api](#inspect-api "mention") 用于开发和调试目的。
  * 允许以分页列表形式列出所有当前玩家票据。
  * 允许以分页列表形式列出所有当前比赛。

#### 1.0.0（2024年12月9日）

* [#backfill](#backfill "mention")：根据（大量）请求，我们增加了带自动票据分配的回填，这使你在玩家离开会话时可以重复使用服务器座位。
  * 非常适合在比赛开始后填补空闲的玩家座位，或替换比赛中离开的玩家。
* [#join-as-group](#join-as-group "mention")：我们增加了以组加入的能力，作为已有的为多个队伍填充玩家的能力的补充。
  * 非常适合与一群朋友一起进入匹配队列，或来自共同大厅。
* [#matchmaking-sdk](https://docs.edgegap.com/zh/unity/developer-tools#matchmaking-sdk "mention") 和 [#edgegap-integration-kit-by-betide-studio](https://docs.edgegap.com/zh/xu-huan-yin-qing/developer-tools#edgegap-integration-kit-by-betide-studio "mention") 匹配 SDK：
  * 为了简化集成，我们现在为最流行的游戏引擎提供软件开发工具包。
* 修复了一个错误，其中 [#latencies-attributes](#latencies-attributes "mention") 没有被正确应用。
* 票据现在将在 [#matchmaking-process](#matchmaking-process "mention") 后自动取消，如果它们尚未被分配到部署。
* 你现在可以 [#endpoint-tickets](#endpoint-tickets "mention") 以增强匹配流程。
* 由匹配器创建的部署现在会使用票据 ID 进行标记。
* 你现在可以在匹配器运行时编辑配置。这会触发配置的快速重新加载，而无需对匹配器进行完整的开/关循环。注意：不建议在生产环境中使用此功能，因为它会删除所有当前票据并暂时使 API 无响应。
* 修复了 [#injected-environment-variables](#injected-environment-variables "mention") 以使用正确的原始类型而不是数组。
* 修复了 [#injected-environment-variables](#injected-environment-variables "mention") JSON 值，以前包含转义字符。

#### 0.2.3（2024年10月8日）

* 修复了一个错误：从 WebGL 应用发出请求时，某些头部不被匹配器接受（CORS 策略）。

#### 0.2.2（2024年10月3日）

* 修复了 TLS/SSL 证书验证问题，该问题阻止了匹配器启动。

#### 0.2.1（2024年9月30日）

* 修复了一个导致信标端点返回 500 错误的 bug。

#### 0.2.0（2024年9月25日）

* 所有端点现在都必须使用基本认证。
* 新增了在服务器分配失败时配置重试次数的能力。
* 基于队伍的匹配现在是所有匹配配置的默认设置。
* 所有配置文件现在都必须包含 application 和 version 两个必填字段。
* 引入了一个新的端点来监控匹配器状态。
* 更新了部署中 tickets 环境变量的格式。
* 新增了一个配置选项，允许主机与匹配器通信。
* 调试 API 现在仅在配置中显式启用时可用（当前为重新工作而禁用）。
* 该 `game_profile` 键在 GET 票据响应中已被替换为 `profile`.

</details>

[^1]: 游戏客户端加入大厅以获取匹配组 ID 并加入该组

[^2]: 某一天的最高同时在线用户数

[^3]: 非高峰时段的同时在线用户数

[^4]: [函数即服务](https://www.ibm.com/think/topics/faas)

[^5]: 查看其他示例