本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 教程：使用 Amazon GameLift Servers 封装器快速入门
教程：使用 Amazon GameLift Servers 封装器快速入门

欢迎使用 Amazon GameLift Servers 的入门教程。在本教程中，您将快速部署游戏服务器，使其托管于基于云的计算资源实例集上。通过本教程，您无需将 Amazon GameLift Servers 的服务器 SDK 集成到游戏代码中，而是直接部署具备基本功能的游戏，使其能够与 Amazon GameLift Servers 服务通信并运行游戏会话。您将搭建基础托管解决方案，并通过该解决方案体验自动扩展、对战系统等全套功能。此解决方案同样适用于托管游戏原型，可用于现场演示或测试场景。

这种入门方法的核心优势：
+ 快速部署游戏服务器，实现高效托管。
+ 无需更改游戏代码，零修改要求。
+ 适用于任何游戏可执行文件，不受游戏引擎限制。
+ 探索所有 Amazon GameLift Servers 管理工具，包括监控游戏会话活动和托管运行状况。

**注意**  
该封装器适用于评估场景及基础生产环境使用。详细玩家会话管理等高级功能需完整集成服务器 SDK 方可使用。

## 先决条件


在开始之前，请确保您满足以下条件：
+  Amazon Web Services 账户 具有适当权限的
+ Amazon CLI 已安装
+ Go 1.18 及以上版本
+ 多人游戏服务器可执行文件
+ Make 工具（Linux/Mac 系统）
+ 已安装 Git 且账户处于活跃状态

## 概述


本教程将引导您完成以下操作：

1. 获取并构建封装器

1. 准备游戏生成包

1. 配置封装器

1. 上传游戏服务器生成包

1. 创建托管 EC2 舰队

1. 创建游戏会话并连接

1. 监控和管理游戏服务器

1. 扩展游戏服务器

## 第 1 步：获取并构建游戏服务器封装器


使用以下命令获取游戏服务器封装器源代码并构建封装器。这些命令基于 SSH 执行，您也可直接访问 GitHub 存储库完成操作。

### Windows


```
> git clone git@github.com:amazon-gamelift/amazon-gamelift-servers-game-server-wrapper.git
> cd amazon-gamelift-servers-game-server-wrapper
> powershell -file .\build.ps1
```

### Mac 和 Linux


```
$ git clone git@github.com:amazon-gamelift/amazon-gamelift-servers-game-server-wrapper.git
$ cd amazon-gamelift-servers-game-server-wrapper
$ make
```

构建成功后，`amazon-gamelift-servers-game-server-wrapper` 目录下会新增一个“out”目录。该目录有三个文件夹，分别对应三种受支持的托管实例集选项，其中均包含一组构建构件。在本教程中，您将部署到托管 EC2 队列，因此您将使用该文件夹`gamelift-servers-managed-ec2`。

## 第 2 步：准备游戏服务器生成包


在此步骤中，您将准备要上传到 Amazon GameLift Servers 的游戏服务器生成包文件。

### 创建游戏目录


现在，在本地计算机上准备一个游戏目录。该目录需包含通过 Amazon GameLift Servers 运行游戏服务器所需的全部文件，包括游戏服务器封装器、游戏服务器生成包，以及使封装器与游戏服务器搭配运行的 config.yaml 配置文件。

使用以下步骤：

1. 托管 EC2 车队。在游戏服务器包装器输出文件夹中，找到用于部署到托管 EC2 队列的构建工件。该构建构件会写入如下指定的 out 目录：`out\linux\amd64\gamelift-servers-managed-ec2`。

1. 将游戏服务器可执行文件及其运行所需的全部关联文件复制至 `gamelift-servers-managed-ec2` 文件夹。您可根据需要创建嵌套目录。

示例目录结构如下所示：

```
gamelift-servers-managed-ec2
│-- config.yaml
│-- amazon-gamelift-servers-game-server-wrapper
│-- MyGame
│   │-- server-executable.exe
│   │-- my-game-settings
│   │ ......
```

## 第 3 步：为实例集配置封装器


Amazon GameLift Servers 会管理实例集的计算实例生命周期，启动已安装您的服务器生成包的新实例，并根据需要回收实例。该服务同时管理每个实例上运行的游戏服务器进程生命周期。托管 EC2 舰队可以在多个地点拥有实例，无论玩家身在何处，都能为他们提供支持。

编辑 config.yaml 文件以配置封装器的日志、端口设置及服务器初始化相关参数。

1. **配置日志设置**。游戏服务器封装器会为每个游戏服务器进程生成日志信息。默认日志级别为 debug，以输出最详尽的日志内容。该级别在部署配置和故障排除阶段非常实用，其日志消息详尽程度为最高级。可选日志级别包括 debug、info、warn 和 error（日志详尽程度最低）。

1. **指定游戏服务器日志目录的路径**。游戏服务器日志的默认路径是 `./game-server-logs`。该目录包含游戏服务器生成的所有日志，且每个实例均会生成独立日志文件。日志会自动上传至 Amazon GameLift Servers，您可在**事件**选项卡中查看。有关更多详细信息，请查看“故障排除”部分。

1. **定义网络端口配置**。游戏端口可按需自定义设置。本教程仅需指定一个端口，因为创建的实例集每个实例仅运行一个并发游戏服务器进程。若需同时运行多个进程，则需为每个并发进程配置足够的端口。配置文件中默认端口值为 37016，通用端口规则如下：对于使用 Linux 生成包的实例集，使用 22 端口及 1026-60000 端口段；对于使用 Windows 生成包的实例集，使用 1026-60000 端口段。

1. **设置游戏服务器可执行文件的路径**。对于 `./MyGame/my-server-executable.exe`，请根据实际游戏服务器可执行文件的名称和位置自定义其路径。该路径是启动游戏服务器的入口。

1. **配置游戏服务器参数**。至少需指定 -port 参数，并使用之前定义的游戏端口值。“pos”值设为 0，表示这是第一个参数。可按需添加其他参数，这些参数会在游戏服务器启动时传入，用于配置其运行时行为。

   1. 参数：`"--port"`

   1. 值：`"{{.port number here}}"`

   1. 位置：`0`（列表中的第一个参数）

示例配置：

```
log-config:
  wrapper-log-level: debug
game-server-logs-dir: ./game-server-logs
ports:
  gamePort: 37016
game-server-details:
  executable-file-path: ./MyGame/my-server-executable
game-server-args:
  - arg: "--port"
    val: "{{.gameport}}"
    pos: 0
```

## 第 4 步：上传游戏服务器生成包


您现已完成游戏服务器生成包的全部必要配置（含游戏服务器封装器、config.yaml 配置文件及游戏服务器文件），可将该游戏生成包上传至 Amazon GameLift Servers 进行托管。上传游戏版本的最快方法是使用 Amazon CLI 命令，`upload-build`如以下示例所示。

通过 Windows 上传游戏生成包：

```
aws gamelift upload-build \
    --name gamelift-test-2025-03-11-1 \
    --build-version gamelift-test-2025-03-11-1 \
    --build-root out/windows/amd64/gamelift-servers-managed-ec2 \
    --operating-system WINDOWS_2022 \
    --server-sdk-version 5.3.0 \
    --region us-west-2
```

**注意**  
对于 Mac 和 Linux 生成包，请使用 --operating-system AMAZON\$1LINUX\$12023

创建生成包时，请记录 API 响应中的生成包 ID 以将其用于实例集创建。

## 步骤 5：创建托管 EC2 舰队


以下步骤描述了最小化实例集配置流程，帮助您快速启动并运行实例集。

创建实例集：

1. 登录 Amazon Web Services 管理控制台 并导航至Amazon GameLift Servers。

1. 在控制台窗口顶部的菜单栏中，确认您的生成包所在的区域 并记录，因为您的实例集必须与生成包处于同一区域，否则将无法查找或选择该生成包。

1. 在导航窗格的 “**托管**” EC2 部分中，选择 “**生成**”。

1. 选择您之前上传的生成包，以显示**生成包详情信息**页面。

1. 在 “舰队” 部分中，选择 “**创建舰队**”，这将显示 “定义托管 EC2 舰队” 详细信息页面，您可以从中跟踪舰队的状态以及在 “事件” 选项卡上查看舰队创建**事件**。

1. 填写实例集名称和描述，然后选择**下一步**。

1. 在“定义实例详细信息”页面中，默认显示生成包所在的区域。如需添加任何其他区域，可自行选择。

1. 对于**实例集类型**，请选择**按需型**。

1. 在**实例类型**下选择 **c5.large**，然后选择**下一步**。

1. 在**运行时配置**下，由于您上传的游戏生成包已使用封装器，因此需指定封装器可执行文件路径而非游戏服务器本身。对于 Windows 游戏服务器，路径为 `C:\game\amazon-gamelift-servers-game-server-wrapper.exe`。对于 Linux 游戏服务器，路径为 `/local/game/amazon-gamelift-servers-game-server-wrapper`。

   例如：`LaunchPath": "/local/game/amazon-gamelift-servers-game-server-wrapper", "ConcurrentExecutions": 1, "Parameters": "—port 37016`

   此外，配置游戏端口范围值，该范围需包含您在 `config.yaml` 中设置的端口及运行时配置的启动参数端口。`config.yaml` 中的端口无需与实例集的运行时配置中指定的端口一致，但运行时若后者端口不同，该值将覆盖 `config.yaml` 中的配置。运行时配置中输入的启动参数同样会覆盖 `config.yaml` 中的相应设置。

1. 在**审核并创建**页面上，仔细核对所有配置，然后选择**提交**以创建您的实例集。实例集会启动容量以托管游戏服务器，状态将随之更新，很快显示为**活跃**。激活完成且实例集部署就绪后，服务会自动启动封装器，此时封装器已准备就绪，可接收游戏会话请求。

## 第 6 步：创建游戏会话并连接


当实例集状态显示为**活跃**时，表明游戏服务器已准备就绪，可等待托管游戏会话。要启动游戏会话，需向 Amazon GameLift Servers 服务发起游戏会话请求。在这里，您将使用 Amazon CLI 来提出此请求。

**注意**  
请记住，使用创建游戏会话对于测试和熟悉该过程非常有用。 Amazon CLI 在某个时候，你会将编程 Amazon SDK 调用添加到游戏后端服务中，作为游戏配对或游戏会话放置系统的一部分。

使用以下命令创建游戏会话：

```
aws gamelift create-game-session \
--fleet-id <FLEET_ID> \
--game-properties '[{"Key": "exampleProperty", "Value": "exampleValue"}]' \
--maximum-player-session-count 3 \
--region us-west-2
```

您也可向服务器可执行文件传递自定义游戏属性。有关详细信息，请参阅自述文件中的“游戏服务器参数”部分。当它接到 create-game-session呼叫时，会Amazon GameLift Servers通知包装器启动游戏服务器可执行文件并启动游戏会话。其中，`config.yaml` 中的配置影响游戏服务器的配置，而控制台中设置的启动参数则决定游戏会话本身的配置。

添加游戏属性的格式示例：

```
defaultArgs:
        - arg: "--port"
          val: "{{.GamePort}}"
          pos: 0
        - arg: "--ipAddress"
          val: "{{.IpAddress}}"
          pos: 1
        - arg: "--gameSessionId"
          val: "{{.GameSessionId}}"
          pos: 2
```

## 第 7 步：管理和监控实例集


您的游戏服务器实例集已配置完成且游戏会话已启动，您可通过 Amazon GameLift Servers 控制台对其进行管理和监控。最优操作方式是访问实例集详细信息页面，您可以在其中编辑实例集详细信息或在**扩展**选项卡上更改实例集扩展和容量。有关如何扩展游戏服务器，请参阅以下部分。

选择**指标**选项卡可查看描述监控活动指标和硬件指标的图表。有关指标图表的详细信息，请选择您的实例集 ID 旁边的**信息**链接。此外，虽然您可以通过 “**指标**” 选项卡密切监控游戏服务器，但也可以在 CloudWatch 控制面板中为这些指标添加警报。

要从控制台导航到 CloudWatch 仪表板，请执行以下操作：

1. 在搜索栏中键入 CloudWatch “”，然后从搜索结果列表中选择它以显示 CloudWatch 概览。

1. 向下滚动并选择 “**查看 GameLift 控制面板**”，查看基于舰队和游戏会话关键指标的图表。

## 第 8 步：扩展游戏服务器


下一步将设置自动扩缩。通过自动扩缩，实例集容量会根据游戏服务器的活动负载动态调整。当玩家加入并创建游戏会话时，自动扩缩会新增实例；当玩家需求减少时，自动扩缩会释放闲置实例。这是一种高效的优化方案，可在保障玩家流畅快速体验的前提下，最大程度地降低托管资源消耗和成本。

在游戏启动前，建议为实例集配置自动扩缩。自动扩缩是一种推荐的高效优化方案，可在保障玩家流畅快速体验的前提下，最大程度地降低托管资源消耗和成本。

### 手动设置实例集容量


手动设置实例集容量

1. 前往实例集详细信息页面中的**扩展**选项卡。

1. 选择一个位置并选择**编辑**。

1. 要突破当前配置值上限进行扩展，可更改**所需实例数**值，并调整**最小**和**最大**实例数设置，完成后选择**确认**。

**注意**  
最大实例数设置可作为临时管控措施，防止扩展过度导致资源浪费与成本超支。

### 使用基于目标的自动扩缩


使用基于目标的自动扩缩

基于目标的自动扩缩（目标跟踪模式）将实例集扩展与可用游戏会话百分比关联。当玩家流量激增导致可用游戏会话减少时，系统会自动为实例集新增实例以应对需求。

1. 在**基于目标的自动扩缩策略**下，选择**添加策略**，然后将实例集的容量设置为在达到您设置的可用游戏会话百分比的阈值时自动更改。设置更大的缓冲空间可更好地应对流量峰值，保障新玩家快速进入游戏，但可能会增加托管成本。

1. 选择**确认**以接受更改。

基于规则的自动扩缩提供更精细的控制能力，例如能够将扩展与其他实例集指标关联起来，并设置自定义阈值和扩展响应。它提供功能强大的选项，但需使用 CLI 配置且需经过充分测试，以验证自定义规则的实际运行效果。本教程重点介绍如何首先设置基于目标的策略。

## 常见问题故障排除


以下是游戏服务器及游戏会话部署运行过程中可能遇到的常见问题。如果服务器或游戏会话运行异常，第一步是检查日志，日志内容可能会揭示新部署项目或生产环境游戏中出现的以下问题之一。

日志中常见问题及排查方向如下：
+ 游戏服务器进程无法启动。这可能是封装器配置错误—请验证配置文件中的启动路径、启动参数及参数项是否正确。
+ 游戏服务器生成包无法运行。大概率是游戏代码存在错误。
+ 玩家无法连接到游戏会话。大概率是端口配置错误。
+ 连接延迟或缓慢。请查看扩展策略和阈值设置。
+ 完全无法建立连接。请验证实例集的端口规则和配置是否正确。

### 查看 Amazon GameLift Servers 实例集的事件日志


查看 Amazon GameLift Servers 实例集的事件日志

1. 打开 Amazon GameLift Servers 控制台。

1. 在实例集详细信息页面上，选择**事件**选项卡并下载日志。您还可以通过**指标**选项卡，实时监控游戏服务器运行状况、游戏会话激活情况等活动指标和硬件指标。

### 查看游戏会话日志


查看游戏会话日志

1. 通过控制台打开您的实例集并打开**游戏会话**选项卡。

1. 从列表中选择游戏会话 ID 即可显示其概述页面。

1. 选择**下载日志**，即可将日志文件下载至本地。

要通过 CLI 查看游戏会话日志，请使用 `GetGameSessionLogURL` API。Amazon GameLift Servers 会自动将日志存储 14 天。

您还可以为您的舰队配置 Amazon CloudWatch 日志。这提供了额外的日志记录功能以及与其他 Amazon 监控服务的集成。

通过 CloudWatch以下方式实时访问日志或延长保留期：

1. 在Amazon GameLift Servers控制台仪表板顶部的搜索栏中键入 CloudWatch “”，然后从结果下拉列表中进行选择。

1. 转到 CloudWatch 日志组并搜索特定会话。最简单的方法是单击 “**全部搜索**”，然后使用 gameSessionId 或 clientID 进行筛选。

## 后续步骤

+ [创建多位置实例集以在其他位置添加托管](gamelift-regions.md#gamelift-regions-hosting)
+ [添加游戏会话队列，为跨多个位置的游戏会话提供最优放置位置](queues-intro.md)
+ [通过为游戏创建 FlexMatch 匹配器和规则集来尝试配对](https://docs.amazonaws.cn/gameliftservers/latest/flexmatchguide/match-intro.html)
+ [开发游戏客户端和后端服务组件功能，支持玩家发起加入请求并直接连接到游戏会话](gamelift-sdk-client-api.md)
+ [准备就绪后，迁移至全集成式解决方案](gamelift-roadmap-managed.md)