Unity

通过实践学习并在 Edgegap 部署你的第一个专用服务器。本指南结束时，你将免费使用 Edgegap 部署一个专用服务器。

✔️ 准备工作

对你的服务器构建有信心吗？ 跳到 Unity 或高级功能以了解更多。

⚙️ 1. 连接账户

☑️ 登录并确认 Unity 控制台中没有与 Edgegap 插件相关的新错误。

✅ 你现在可以继续下一步。

故障排除和常见问题

!Success: 400 BAD REQUEST - POST | https://api.edgegap.com/v1/wizard/init-quick-start - {"message": "浏览器（或代理）发送了服务器无法理解的请求。"}

如果你是通过复制 ZIP 文件安装或使用包含以这种方式安装的插件副本的示例项目，你需要手动安装包依赖项，包括 Newtonsoft JSON 库，参见官方插件仓库.
如有需要请通过以下方式联系我们：社区 Discord 若情况并非如此，请在此处寻求帮助。

🔧 2. 构建游戏服务器

无论你使用的是 Windows、Mac 还是 Linux 机器， 都需要将你的服务器构建为 Linux 运行时，因为如今大多数云提供商（包括 Edgegap）都运行在 Linux 上。别担心，使用我们的插件完成此操作不需要 Linux 知识。

☑️ 验证你已安装所需的 Unity Linux 构建工具。

☑️ 编辑构建设置以 确保包含你所有需要的游戏场景.

高级 Unity 用户 - 可选地更改 Unity 构建设置。注意！这可能会破坏你的构建。

☑️ 可选：从 Edgegap Server Hosting 菜单（在层次视图中右键 / ➕ ）将与网络代码相关的端口验证和环境引导脚本添加到你的初始服务器场景。

完成第 Unity步后，如果你的网络代码地址或端口与 Edgegap 的应用版本端口映射配置不匹配，端口验证脚本将记录一个警告。

服务器构建应在你的网络代码传输中使用地址 0.0.0.0 和端口 7777 。如果你自定义端口，请在你的应用与版本中指定相同的端口，一旦你 Unity.

☑️ 一旦你对配置满意，点击 构建服务器，等待进程完成并验证 Unity 控制台中没有新错误。完成此步骤将导致 项目根目录下出现一个新文件夹 - Builds/EdgegapServer/ServerBuild .

✅ 你现在可以继续下一步。

故障排除和常见问题

Unity：唯一受支持的独立目标是 Windows x64 和带 OpenXR 的 OSX。

在构建服务器之前，打开你的包并禁用 OpenXR。
OpenXR 插件仅对客户端需要，与 Linux 服务器构建不兼容。将其从服务器构建中排除并不会丢失任何功能。

🐋 3. 将服务器容器化

在开发团队中工作意味着要共享代码。当出现问题时，你最不想听到的是“在我机器上可以运行”。游戏服务器必须能在任何机器上可靠运行，因为成功的游戏服务器将在全球数千台服务器上运行。

为了帮助使你的服务器可靠，我们使用 Docker —— 一种虚拟化软件，确保从操作系统层面起你所有服务器代码的依赖项始终完全相同，无论服务器如何或在何处启动。

☑️ 现在，先点击验证按钮以确保你已完成开发者工具.

☑️ 你可以配置以下选项（或保持默认）：

构建路径 是指向你的服务器构建产物的相对路径，暂时保持默认即可。

Docker 仅接受相对于项目根文件夹的构建路径， 请将构建保留在项目文件夹内.

镜像名称 是你选择的唯一标识符，用于在发布前标记你的服务器构建。
- 通常，这将包含你的游戏名称——例如 “my-game-server”。
镜像标签 是指向镜像特定版本的标识符。
- 术语“构建产物”有时用于指代镜像的特定版本。
- 时间戳是标记的一个好选项，例如 2024.01.30-16.23.00-UTC .
Dockerfile 路径 可用于自定义镜像的配方。
- 我们建议暂时保持默认设置，你可以稍后在第 Unity.
节中阅读更多， 可选的 docker 构建参数
- 可用于进一步指示 Docker 处理更细微的差异。我们建议暂时保持默认设置，你可以在 Docker 文档中.

☑️ 一旦你对配置满意，点击 阅读更多，等待进程完成并验证 Unity 控制台中没有新错误。完成此步骤将导致 用 Docker 容器化后，你的本地机器上将出现一个新镜像。你可以在 Docker Desktop 的 Images 下的 Local（默认）选项卡中验证，或在 docker CLI 中运行 docker images .

✅ 你现在可以继续下一步。

故障排除和常见问题

/bin/bash: docker: command not found ，或 找不到 Packages\com.edgegap.unity-servers-plugin\Editor

首先，确保你已完成开发者工具.
确认你已验证 Edgegap 帐户，你应该已经通过电子邮件收到了一条验证链接。
在更新 Docker Desktop 后某些设置可能已重置。尝试导航到 Docker Desktop 的设置 / 高级，并在“Choose how to configure the installation of Docker’s CLI tools:” 选择“System (requires password)”。

docker build 需要且仅需要 1 个参数

请验证你的镜像标签中不包含任何空白字符（空格、制表符）。重新输入镜像标签值以确保你没有意外复制到此类字符。

(HTTP code 400) unexpected - invalid tag format

这是一个已知的 macOS Docker 4.33 版本问题，请考虑回退到 4.32 或升级到 4.35。

ERROR: failed to solve: ubuntu:22.04: failed to resolve source metadata for http://docker.io/library/ubuntu:22.04: failed to authorize: failed to fetch oauth token

你位于中国境内吗？你的连接可能受防火长城影响被中断。尝试运行 docker pull ubuntu:22.04 在命令行中手动执行（打开命令行可按 Win+R，然后输入 cmd 并回车）。

System.IndexOutOfRangeException: 索引超出数组界限。

如果你是通过下载 ZIP 安装我们的 Unity 快速入门插件，你的 Unity 编辑器缓存可能已损坏。尝试删除插件副本并使用 git URL 或从 Unity 资源商店安装。你应该不再需要 Newtonsoft.JSON 包，因为它已随其他来源自动包含。

我的 docker 镜像体积非常大（超过 1GB）/ 非常小（低于 100MB），这正常吗？

在某些情况下这可能没问题，只要你能运行服务器并成功连接（参见 Unity）。如果不是这种情况，请考虑检查你的构建选项，将其重置为默认，并逐步添加选项以查看它们如何影响构建大小。另请参见 Unity.

我遇到了文档中未提及的其他问题。

首先，请尝试更新你的 Edgegap 插件因为我们可能已经发布了修复。如果这无济于事，请通过我们的社区 Discord 与我们联系，我们会尽快与你一起调查。

🧪 4. 在本地测试服务器

☑️ 你可以配置以下选项（或保持默认）：

服务器镜像标签 来自上一步。
- 默认使用你通过插件构建的最后一个标签。
可选的 docker 运行参数 可用于公开多个端口，或在 macOS 机器上运行你的镜像。
- 如果需要，你可以为容器发布多个端口，只需为每个端口添加参数 -p {内部端口}/{协议} ，例如 -p 8080/tcp -p 7770/udp 以将你的服务器端口 8080 发布并映射到随机的外部端口用于 TCP 连接，且同时将服务器端口 7777 映射到随机的外部端口用于 UDP 连接。
- 在你的传输或网络代码特定设置中查找服务器端口配置。
- 如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），你应该在可选的 docker 构建参数中包含该可选参数： --platform=linux/amd64 .

☑️ 一旦你对配置满意，点击 部署本地容器，等待进程完成，并确认 Unity 控制台中没有新错误。完成此步骤将会 在你的开发机器上启动一个新容器。 有关更多详细信息，请参见 Docker Desktop / Containers，或 Docker CLI 命令

docker ps ☑️ 现在是时候 .

将你的 Unity 编辑器游戏客户端连接到本地 docker 容器 以验证你的服务器镜像是否正常工作。找到你的网络代码客户端设置并输入： localhost

（在大多数情况下等效）替代服务器 IP， 或 127.0.0.1 使用在 Docker Desktop / Containers / edgegap-server-test 中找到的随机化外部端口值。
我无法使用 Unity 编辑器游戏客户端连接到本地 docker 容器。

✅ 你现在可以继续下一步。

故障排除和常见问题

首先，确保容器状态为 Up 且不是 Restarting 或 Exited，这些状态表明运行时异常。如果容器未运行，请通过 Docker Desktop 的 Containers 选项卡（点击你的容器）或使用

docker logs {container_id} --timestamps 在 docker CLI 中检查其日志。 接下来，请验证你服务器构建中的网络管理器端口设置是否与
中发布的端口匹配。如果不匹配，尝试重置或手动更改此输入字段的值以匹配 可选的 docker 运行参数{container} 端口与你的网络管理器设置。请在你的网络代码设置中查找你的协议。 最后，确认你的 Unity 编辑器游戏客户端网络代码设置正在使用在
中发布的端口（参见上方截图）。 可选的 docker 运行参数 (Segmentation fault) - core dumped

。如果不是，请尝试重置此输入字段的值。

如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），你应该在可选的 docker 构建参数中包含该可选参数： --platform=linux/amd64 SceneId of 9120233082191360994 not found in SceneObjects.

这可能意味着你尝试加载的场景未正确包含在构建中，这是旧插件版本中的已知问题。为了解决此问题，请尝试更新你的网络代码集成版本或

http2: server: error reading preface from client //./pipe/docker_engine: file has already been closed 更新你的 Edgegap 插件.

Windows 旧版本 Docker Desktop 的已知问题。

这是一个请更新你的 Docker Desktop 应用并重试容器化。Curl error 35: 证书握手失败。致命错误。UnityTls 错误代码：7

此错误表示根 SSL 证书验证问题，是旧插件版本中的已知问题。为了解决此问题，请尝试

☁️ 5. 上传到 Edgegap 更新你的 Edgegap 插件.

应用名称

☑️ 你可以配置以下选项（或保持默认）：

在 Edgegap 上可以与镜像名称相同或自定义。 我们目前选择复制你的镜像名称。
- 应用版本
在 Edgegap 上可以与标签相同或自定义。 时间戳是应用版本名称的一个好选项，例如，
- 2024.01.30-16.50.20-UTC 多个应用版本可以指向相同的镜像标签，例如 .
- v1.1.0 和 dev 稍后了解更多关于 .
- 的信息。应用与版本服务器镜像名称
来自第 步 Unity.
服务器镜像标签 步 Unity.

在 Docker Desktop / Images.

☑️ 一旦你对配置满意，点击 中查找存储在你机器上的任何镜像名称和标签。上传镜像并创建应用版本

，等待进程完成，并验证 Unity 控制台中没有新错误。 ☑️ 你将被带到我们的仪表板，在此你可以配置可选设置。完成此步骤将导致创建一个新的应用版本，并将你的.

构建产物标记并上传到 Edgegap 的容器注册表。 Unity ☑️ 现在系统会提示你为新的应用版本定义端口。确保设置与第

✅ 你现在可以继续下一步。

步中你的传输或网络代码特定设置相同的服务器端口值。

🚀 6. 部署到云端 ☑️ 现在我们将执行最终测试并将你的 Unity 编辑器游戏客户端连接到云端部署

。从部署的以下项中填写游戏客户端连接详情： 主机 URL 指向服务器 IP，通常在 NetworkManager
组件中。 外部端口映射到服务器的内部监听端口

故障排除和常见问题

，通常在 Transport 组件中。 无法将客户端连接到服务器 - , 请求超时。 , 请求超时 ，或 连接失败

端口验证失败 ☑️ 你将被带到我们的.
首先，确保部署处于 Ready 状态，并且部署日志中没有运行时异常或错误。如果你的部署停止，请在我们的中检查日志。如果你使用 Mirror 网络代码，你需要在你的 指向服务器 IP，通常在 中勾选
“自动启动服务器（Auto Start Server）” ，重新构建、推送并重新部署你的服务器。如果你使用 FishNet 网络代码，你需要在你的 ServerManager中勾选
中启用 “Headless 启动（Start on Headless）” 如果你使用 Photon Fusion 2 网络代码，请确保服务器正在传递部署的公共 IP、外部端口以及服务器上的 roomCode ，并且客户端在 “NetworkRunner.StartGame”参数 StartGameArgs中使用相同的房间代码。部署 ID（例如 b63e6003b19f dev 深入解析.
）是一个很好的选择，因为它在全局范围内唯一并且客户端可以通过 Matchmaker轻松获取。 Matchmaker 接下来，请验证服务器构建的网络代码设置中的端口设置是否与你在
应用版本 中的内部端口匹配。你可以通过编辑 来更改端口映射，无需重建。在你的网络代码集成中查找你的协议。
请确保你的游戏客户端正在连接到部署详情页上显示的 Matchmaker 外部端口，出于安全原因该值将始终是随机化的。
如果你在网络代码集成中使用安全 Websocket（WSS）协议，请确保为 WSS 端口的端口配置启用了 TLS 升级。你是否位于中国并使用智能舰队（Smart Fleets）

？你的连接可能被防火长城阻止。考虑向你的舰队添加位于中国的服务器，或使用 VPN 进行连接。

我的部署停止/重启且我无法再访问其日志。如果服务器进程由于异常崩溃，我们的系统会尝试自动重启服务器。考虑在本地测试你的服务器
以找出根本原因。我们只在部署运行期间保留日志，如果你希望在部署停止后检查日志，请.
集成第三方日志存储。部署参见

以了解导致部署停止的所有原因。

我的部署在 X 分钟后自动停止。
免费层部署有 60 分钟限制，请考虑升级你的账户。私有舰队根据我们的服务器清理策略，出于基础设施维护并为防止在部署未正确关闭时产生意外费用，所有部署将在运行 24 小时后终止。对于长期运行的服务器，请考虑使用持久化.
集成第三方日志存储。部署参见

与

我的部署已经就绪，但我在随后几分钟内无法连接。
一旦部署处于 Ready，游戏引擎初始化就开始。此过程可能需要几秒到几分钟不等，在此期间服务器不会接受玩家连接。
考虑优化服务器初始化以缩短此时间。
游戏客户端应以 1 秒间隔重试连接，持续有限的时间（取决于你的初始化时长），之后应返回匹配流程。

考虑添加一个加载场景，以便服务器可以在客户端同时执行初始化（以及在 Unreal Engine 中的 travel），同时同步双方状态。 我的 Meta Quest 设备抛出错误 .

HTTP 0：无法解析目标主机
在为 Android 目标构建 Unity 应用时，你的 Internet Access 权限可能会被自动从输出的 APK 客户端构建产物中移除。
- 重新在以下位置添加权限（需要随后重建客户端）： ⚙️ 项目设置 / OpenXR /
- Meta Quest 支持 / 强制移除 Internet 权限（取消勾选）。

播放器设置 / Internet Access（设置为 require）。

如果玩家离开我的部署，会发生什么？
默认情况下，服务器不会拒绝玩家连接。玩家认证由你的开发者决定，因为可以使用许多不同的方法和玩家认证提供商。
游戏客户端可以在本地存储连接信息，以便在客户端意外崩溃时尝试重新连接。深入解析或为允许玩家加入正在进行的游戏，考虑使用.

会话（Sessions）

我的服务器在就绪后显示 100% CPU 使用率。
这可能不是问题，因为游戏引擎在服务器初始化期间往往会执行 CPU 密集型操作。如果从部署开始 2-3 分钟后 CPU 使用率仍未下降，你可能需要优化服务器或增加应用版本资源。
首先，确保部署处于 Ready 状态，并且部署日志中没有运行时异常或错误。如果你的部署停止，请在我们的中检查日志。如果你使用 Mirror 网络代码，你需要在你的 指向服务器 IP，通常在 中勾选
“自动启动服务器（Auto Start Server）” ，重新构建、推送并重新部署你的服务器。如果你使用 FishNet 网络代码，你需要在你的 ServerManager中勾选
降低 tick 频率可以影响 CPU 使用，因为服务器执行更少的消息操作。
免费层限制为 1.5 vCPU 和 3GB 内存（RAM）。

创建新应用版本时你可以增加分配的资源。你可以在我们的仪表板中复制你的应用版本并根据需要调整这些值，无需重新构建服务器或镜像。 我的部署反复重启并显示错误

OOM kill
这是由于超出分配的内存量导致的。考虑通过对象池、压缩或从场景中移除不需要的对象来优化内存使用。 指向服务器 IP，通常在 确保你的项目正在加载包含你的
降低 tick 频率可以影响 CPU 使用，因为服务器执行更少的消息操作。
免费层限制为 1.5 vCPU 和 3GB 内存（RAM）。

的默认场景，并且该场景已包含在 Unity 的构建设置中。

有时我的服务器内存（RAM）使用会飙高，这是问题吗？
只要你保持在分配的应用版本内存量范围内，这不是问题。 我的部署反复重启并显示错误 超出分配的应用版本内存量将导致

（见上文）。

同一台机器上运行的其他服务器会影响我的服务器性能吗？

不会，我们的平台确保分配的资源不会被其他工作室或共享基础设施上的其他服务器使用。在 Edgegap 上，没有噪声邻居问题。

👉 下一步

停止部署了解各种方法以停止部署

在比赛结束且玩家离开后。

对于优雅的关停，我们强烈建议在你的游戏中实现自我停止 API：

Unity C# 自我停止 API 代码示例
using System;
using System.Collections;
using UnityEngine;

using UnityEngine.Networking;
{
    public class EdgegapSelfStop : MonoBehaviour
    private const int MaxRetries = 2;
    private const int TimeoutSeconds = 30;
    private string url = Environment.GetEnvironmentVariable("ARBITRIUM_DELETE_URL");

    private string token = Environment.GetEnvironmentVariable("ARBITRIUM_DELETE_TOKEN");
    {
        public void Run()
    }

    StartCoroutine(SendDeleteWithRetry());
    {
        private IEnumerator SendDeleteWithRetry()
        {
            if (string.IsNullOrEmpty(url))
            Debug.LogError("Edgegap | ARBITRIUM_DELETE_URL 未设置。");
        }

        yield break;
        {
            if (string.IsNullOrEmpty(token))
            Debug.LogError("Edgegap | ARBITRIUM_DELETE_URL 未设置。");
        }

        Debug.LogError("Edgegap | ARBITRIUM_DELETE_TOKEN 未设置。");

        int attempt = 0;
        {
            while (attempt <= MaxRetries)

            attempt++;
            {
                using (UnityWebRequest request = UnityWebRequest.Delete(url))
                request.timeout = TimeoutSeconds;

                request.SetRequestHeader("Authorization", token);

                yield return request.SendWebRequest();
                {
                    if (request.result == UnityWebRequest.Result.Success)
                    Debug.LogError("Edgegap | ARBITRIUM_DELETE_URL 未设置。");
                }

                Debug.Log("Edgegap | DELETE 请求成功。");
                    Debug.LogWarning(
                    $"Edgegap | DELETE 尝试 {attempt} 失败。\n" +
                );

                $"结果: {request.result}, 错误: {request.error}"
                {
                    if (attempt == MaxRetries)
                    Debug.LogError("Edgegap | ARBITRIUM_DELETE_URL 未设置。");
                }
            }
        }
    }
}

Debug.LogError("Edgegap | DELETE 请求在所有重试后失败。");

如果发生崩溃或内存不足，你的 Unity 服务器将会自动重启。

注入变量

通过访问注入的环境变量读取部署 ID、服务器 IP 地址、服务器位置等有用信息。每次部署会自动包含：部署变量
- 由 Edgegap 自动提供，匹配变量 b63e6003b19f,
- 在使用时由 Edgegap 自动提供，应用版本变量

- 由你可配置的自定义键值对。 通过检查 Edgegap 变量是否设置来验证当前实例是游戏客户端还是服务器：

if (
  string.IsNullOrEmpty(Environment.GetEnvironmentVariable("ARBITRIUM_REQUEST_ID"))
)
{
  // 客户端代码
} else {
  // 服务器代码
}

匹配服务（Matchmaking）

手动启动部署并粘贴 URL 和端口并不能满足线上游戏的需求。

阅读有关匹配服务的更多内容 以便自动按需部署，正好在玩家上线时启动。优化服务器构建

仅重建自上次构建以来已更改的资源。

考虑使用

Unity 的增量构建（Incremental Builds）以加快构建时间。仅包含服务器运行所绝对需要的内容。

Unity 的增量构建（Incremental Builds）以加快构建时间。仅包含服务器运行所绝对需要的内容。

在镜像中复制未使用的文件会导致镜像膨胀、更长的上传时间、更慢的缓存速度以及更慢的整体服务器启动。

查看 Docker 镜像优化建议禁用网格的静态合批以减少镜像大小。.

禁用静态合批以加快构建、上传和部署。

压缩网格以减少镜像大小。

将网格压缩设置为高以加快构建、上传和部署。

顶点压缩并不影响镜像大小。
实现资源的条件懒加载。

通过将纹理和网格设置为禁用 CPU 读/写，排除仅客户端资源，

用于你的客户端构建以通过 Unity Addressables.
Unity 的增量构建（Incremental Builds）按需加载资产来加速构建和部署，或者在服务器构建中通过检查来跳过加载某些资源，多阶段 Docker 构建（链接）。将玩家重新匹配到新的部署.

Unity 的增量构建（Incremental Builds） 将大型服务器依赖项分离到单独的镜像，以在多阶段构建中重用。Docker 会缓存每一层并简单地重用先前版本，除非特别指示，否则跳过上传这部分，这样可以节省带宽和等待上传完成的时间。.

如果你不确定为何某个 Dockerfile 命令会抛出错误，尝试在本地调试。在问题发生之前创建一个新阶段（添加第二个
FROM 命令），使用 --target 指示构建进程在有问题的阶段停止，然后使用 docker exec -it {container} /bin/bash 进入容器内的交互终端。之后，你可以在基础镜像中使用 shell 命令进一步调查（例如在 ubuntu 上使用 top ）。 自定义服务器镜像

我们还支持为需要对镜像有更多控制的用户添加自定义 Dockerfile，以便进行构建大小优化、移除多余依赖或需要更复杂的启动流程。你可以在第

步中可选地提供自定义 Dockerfile 的路径。我们现在将分享一些“自己动手”的提示和最佳实践。 Unity使用 Websockets 或 HTTPS 请求时遇到问题？

如果你收到

，别惊慌，这是旧基镜像（ 此错误表示根 SSL 证书验证问题，是旧插件版本中的已知问题。为了解决此问题，请尝试 ）的已知问题，其中包含已过期的根证书。你可以通过更新到较新的基镜像版本（例如命令），使用ubuntu:22.04 ）并运行update-ca-certificates 来修复， 在你的 Dockerfile 中添加：
```
FROM ubuntu:22.04

RUN apt-get install -y ca-certificates && \
    apt-get clean && \
    来修复，
```

遇到难题？我们在我们的社区 Discord 中可以为你提供帮助，很乐意协助你。

最后更新于14天前

这有帮助吗？

hashtag✔️ 准备工作

hashtag⚙️ 1. 连接账户

hashtag🔧 2. 构建游戏服务器

hashtag🐋 3. 将服务器容器化

hashtag🧪 4. 在本地测试服务器

hashtag应用名称

hashtag步中你的传输或网络代码特定设置相同的服务器端口值。

hashtag不会，我们的平台确保分配的资源不会被其他工作室或共享基础设施上的其他服务器使用。在 Edgegap 上，没有噪声邻居问题。

hashtag👉 下一步

hashtag如果发生崩溃或内存不足，你的 Unity 服务器将会自动重启。

hashtag匹配服务（Matchmaking）

hashtag仅重建自上次构建以来已更改的资源。

hashtag我们还支持为需要对镜像有更多控制的用户添加自定义 Dockerfile，以便进行构建大小优化、移除多余依赖或需要更复杂的启动流程。你可以在第

✔️ 准备工作

⚙️ 1. 连接账户

🔧 2. 构建游戏服务器

🐋 3. 将服务器容器化

🧪 4. 在本地测试服务器

应用名称

步中你的传输或网络代码特定设置相同的服务器端口值。

不会，我们的平台确保分配的资源不会被其他工作室或共享基础设施上的其他服务器使用。在 Edgegap 上，没有噪声邻居问题。

👉 下一步

如果发生崩溃或内存不足，你的 Unity 服务器将会自动重启。

匹配服务（Matchmaking）

仅重建自上次构建以来已更改的资源。

我们还支持为需要对镜像有更多控制的用户添加自定义 Dockerfile，以便进行构建大小优化、移除多余依赖或需要更复杂的启动流程。你可以在第