> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/godot.md).

# Godot - 入门指南

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

## ✔️ 准备工作

在开始之前，请确保 [在 Edgegap 创建一个免费账户](https://app.edgegap.com/auth/register) （无需信用卡）。

**在你的开发机器上配置一些基本设置：**

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">安装 Docker Desktop（或 Docker CLI）</a></summary>

* [从官方来源安装 Docker Desktop](https://www.docker.com/products/docker-desktop/) （无需账户）。
* 完成安装后重启计算机。

</details>

<details>

<summary><a href="https://github.com/edgegap/edgegap-godot-plugin">安装 Edgegap 的 Godot 专用服务器快速入门插件</a></summary>

该插件已在 Godot 4.x.x 及更高版本上测试，并支持这些版本。

选项 1）从 ZIP 安装：

1. [下载最新的 ZIP 压缩包。](https://github.com/edgegap/edgegap-godot-plugin/archive/refs/heads/main.zip)
2. 将 ZIP 解压到你项目的 `addons` 文件夹中。

{% hint style="info" %}
要更新通过 ZIP 安装的插件，请删除旧插件并替换为新的 ZIP。
{% endhint %}

选项 2）从源代码安装：

1. [安装 git 客户端（例如 git-scm）](https://git-scm.com/).
2. 将我们的插件仓库克隆到你项目的 `addons` 文件夹中。

```
git clone git@github.com:edgegap/edgegap-godot-plugin.git
```

{% hint style="info" %}
要更新通过 git 安装的插件，请在插件文件夹中打开命令行并运行 `git pull`.
{% endhint %}

</details>

{% hint style="info" %}
**在 Project / Project Settings / Plugins 下启用你新的 Edgegap Servers Quickstart 插件。** 一个名为“Edgegap”的新标签页将出现在你右侧面板中，位于 Inspector 旁边。如果你之后关闭了该面板并需要重新打开，可在 Project / Tools / Edgegap 下找到该选项。
{% endhint %}

## ⚙️ 1. 连接账户

☑️ 登录并确认你的 Output 中没有与 Edgegap 插件相关的新错误。

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

## 🔧 2. 构建游戏服务器

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

☑️ **验证导出模板，以确保插件已正确设置你的 Linux 服务器模板。**

{% hint style="info" %}
**高级用户** - 可选地自定义 [导出模板](https://docs.godotengine.org/en/latest/tutorials/export/exporting_projects.html)。注意！这可能会破坏你的构建。
{% endhint %}

☑️ **向你的项目添加新的启动脚本，以便自动作为专用服务器启动。** 在你的主场景下创建一个新节点，并在 Inspector / Script / Load 下链接新脚本。

{% tabs %}
{% tab title="默认启动示例" %}
这是一个最小模板脚本，可扩展以满足你项目的需求。

{% file src="/files/abe1528c231c4d9203d1c17b03fe732a292b3920" %}
{% endtab %}

{% tab title="Netfox Forest Brawl 示例" %}
这是一个针对 [netfox forest brawl](#netfox-forest-brawl-example) 示例的启动脚本自定义版本。

{% file src="/files/0138b2c989d9651092c1a05d80a115b3554fc303" %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
服务器构建通常默认端口为 `7777`。如果你自定义了端口，请在你的~~e~~ 中指定相同的 [应用和版本](/zh/learn/bian-pai/application-and-versions.md#port-mapping) 一旦你 [#id-5.-upload-to-edgegap](#id-5.-upload-to-edgegap "mention").
{% endhint %}

☑️ 一旦你对配置满意，就点击 **构建服务器**，等待进程完成并确认你的 Output 中没有新的错误。完成这一步后，你的项目中将出现一个 **新的构建出现在你的项目中，位于文件夹** `build`**.**

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

## 🐋 3. 将服务器容器化

在一个开发者团队中工作意味着要共享代码。当出现问题时，您最不想听到的就是“在我的机器上可以运行”。游戏服务器必须能够在任何机器上可靠运行，因为成功的游戏服务器会在世界各地成千上万台服务器机器上运行。

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

{% hint style="info" %}
我们建议观看 [“永远不要本地安装”（视频）](https://www.youtube.com/watch?v=J0NuOlA2xDc\&ab_channel=Coderized). **使用 Docker 不需要使用 Dockerhub**。Docker ≠ Dockerhub。把 Docker 想象成一个编程引擎，把 Dockerhub 想成它的应用商店。
{% endhint %}

☑️ 首先点击 **验证 Docker** 按钮，以确保你已完成 [#preparation](#preparation "mention").

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">安装 Docker Desktop（或 Docker CLI）</a></summary>

* [从官方来源安装 Docker Desktop](https://www.docker.com/products/docker-desktop/) （无需账户）。
* 完成安装后重启计算机。

</details>

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

* **镜像名称** 是你自定义的唯一标识，用于在发布前标记你的服务器构建。
  * 通常，这会包含你游戏的名称——例如“my-game-server”。
* **镜像标签** 是指向你镜像特定版本的标识。
  * “构建产物”一词有时用于指代镜像的特定版本。
  * 时间戳是标记的绝佳选择，例如 `2026.07.30-16.25.00-UTC` .
* **Dockerfile 路径** 可用于自定义你镜像的构建配方。
  * 我们建议现在先保留默认设置，你可以稍后在以下部分了解更多： [#customize-image](#customize-image "mention").
* **可选的 docker 构建参数** 可用于进一步向 Docker 说明更细致的选项。
  * 我们建议现在先保留默认设置，你可以 [稍后在 Docker 文档中阅读更多](https://docs.docker.com/reference/cli/docker/image/build/#options).

{% hint style="info" %}
**从源代码重建** 将自动构建并容器化，以 **加快你下一次构建**.
{% endhint %}

☑️ 一旦你对配置满意，就点击 **使用 Docker 容器化**，等待进程完成并确认你的 Output 中没有新的错误。完成这一步后，你的项目中将出现一个 **新镜像出现在你的本地机器上**。你可以在 Docker Desktop 的 Local（默认）下的 Images 标签页中验证，或者在 docker CLI 中运行 `docker images` .

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

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

让我们先在本地（在你的机器上）尝试部署并连接游戏客户端，以确保服务器映像在我们上传和部署（可能需要一些时间）之前能正常工作。

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

* **服务器镜像标签** 来自上一步。
  * 默认使用你通过插件构建的最新标签。
  * :cloud: 出现在镜像名称前面表示该镜像已上传。
* **可选的 docker run 参数** 可用于暴露多个端口，或在 macOS 机器上运行你的镜像。
  * 如果需要，你可以为容器发布多个端口，只需添加参数 `-p {internal port}/{protocol}` ，每个端口都这样设置，例如 `-p 8080/tcp -p 7777/udp` 以发布并映射你的服务器端口 `8080` 到一个随机的外部端口，用于 TCP 连接，并且服务器端口 `7777` 同时到一个随机的外部端口，用于 UDP 连接。 **在你的启动脚本中查找服务器端口配置。**
  * 如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），你应该会在可选的 docker 构建参数中看到包含此可选参数： `--platform=linux/amd64` .

☑️ 一旦你对配置满意，就点击 **部署本地容器**，等待进程完成，并确认你的 Output 中没有新的错误。完成这一步后，你的项目中将启动一个 **新的容器正在启动** 在你的开发机器上。

{% hint style="info" %}
更多详情请参见 Docker Desktop / Containers，或 Docker CLI 命令 `docker ps` .
{% endhint %}

☑️ 现在是时候 **将你的 Godot 编辑器游戏客户端连接到本地 docker 容器** 以验证你的服务器镜像是否正常运行。找到你的客户端连接信息并输入：

* `localhost` 或 `0.0.0.0` （在大多数情况下等同）代替服务器 IP，
* Docker Desktop / Containers 中找到的随机外部端口值。

<figure><img src="/files/f867e9033203ef8e164ff7c8e1bbad3b59475759" alt=""><figcaption></figcaption></figure>

☑️ 一旦你确认可以连接到本地服务器容器并且能够正常游戏，就可以删除该容器 🗑️ 以释放机器上的资源供其他程序使用。

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

## ☁️ 5. 上传到 Edgegap

是时候将您的服务器上线了！既然您的镜像现在可以成功托管玩家，我们就可以将其上传到 Edgegap 并开始在世界任何地方运行。在本指南中，我们将使用 [**Edgegap 的容器注册表**](/zh/learn/advanced-features/edgegap-container-registry.md) （镜像的存储）。

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

* **应用名称** 在 Edgegap 上可以与镜像名称一致，也可以自定义。
  * 我们现在选择复制你的镜像名称。
* **应用版本** 在 Edgegap 上可以与标签一致，也可以自定义。
  * 时间戳是应用版本名称的绝佳选择，例如 `2024.01.30-16.50.20-UTC` .
  * 多个应用版本可以指向同一个镜像标签，例如 `v1.1.0` 和 `dev` .
  * 了解更多关于 [应用和版本](/zh/learn/bian-pai/application-and-versions.md) 稍后。
* **服务器镜像** 来自步骤 [#id-3.-containerize-server](#id-3.-containerize-server "mention").

{% hint style="success" %}
在你的机器中查找存储的任何镜像名称和标签 **Docker Desktop / 镜像**.
{% endhint %}

☑️ 一旦你对配置满意，就点击 **上传镜像并创建应用版本**，等待进程完成，并确认你的 Output 中没有新的错误。

☑️ 你将被带到我们的 [仪表板](https://app.edgegap.com/)，在那里你可以配置可选设置。完成这一步后将会 [创建一个新的应用版本](https://app.edgegap.com/application-management/applications/list)，并且你的 [构建产物将被打标签并上传到 Edgegap 的容器注册表](https://app.edgegap.com/registry-management/repositories/list).

* **应用版本** 在 Edgegap 上可以与标签一致，也可以自定义。
  * 时间戳是应用版本名称的绝佳选择，例如 `2024.01.30-16.50.20-UTC` .
  * 多个应用版本可以指向同一个镜像标签，例如 `v1.1.0` 和 `dev` .
  * 了解更多关于 [应用和版本](/zh/learn/bian-pai/application-and-versions.md) 稍后。

☑️ 现在系统会提示你为新的应用版本定义一个端口。请确保将服务器端口值设置为与步骤 [#id-4.-test-server-locally](#id-4.-test-server-locally "mention") 相同（默认为 7777）。

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

## 🚀 6. 部署到云端

这是本指南的最后一步，完成后您将在 Edgegap 云上部署一个服务器，来自世界任何地方的玩家都可以连接到该服务器。

☑️ **选择一个应用程序和版本** 从先前的步骤部署。

☑️ 一旦准备好，请点击 **部署到云端**，等待达到 [/pages/5e7e2169ca3822647d4607dfc1d3487ebcc0836c#id-3.-deployment-ready](https://docs.edgegap.com/zh/pages/5e7e2169ca3822647d4607dfc1d3487ebcc0836c#id-3.-deployment-ready "mention")。完成此步骤将导致 [一个新的部署被启动](https://app.edgegap.com/deployment-management/deployments/list) 在您的 Edgegap 帐户上。

☑️ 验证控制台输出中没有新的错误。同时确保您的 [部署](/zh/learn/bian-pai/deployments.md#container-logs) 没有显示任何错误，并且您的 [部署](/zh/learn/bian-pai/deployments.md#container-metrics) 未显示 100% 的资源利用率（vCPU 或内存），否则新的玩家连接可能会被拒绝，或您的服务器可能会陷入重启循环。请参阅下面的故障排除步骤以解决任何问题。

☑️ 现在我们将进行最后的测试，并 **将你的 Godot 编辑器游戏客户端连接到云端部署**。找到你的客户端连接信息并输入：

* **主机** **URL** 指向服务器的 IP，
* **外部端口** 映射到 [服务器的内部监听端口](/zh/learn/bian-pai/application-and-versions.md#port-mapping).

<figure><img src="/files/f1bd72895251e90b42ed7cafaf01a016ce4eaa2c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
您在 Edgegap 云上的部署的外部端口将随机选择，以便在潜在攻击者（黑客）造成损害之前减缓并检测到他们。
{% endhint %}

{% hint style="warning" %}
**测试时请禁用 VPN** 以获得更真实的条件并接收一个 [低延迟部署](/zh/learn/bian-pai/deployments.md#server-placement).
{% endhint %}

☑️ 一旦您确认可以无问题连接到您的部署并完成测试， **停止您的部署** 以释放您账户中的容量用于下一次构建。

* 如果您遇到问题， [检查您部署的仪表板日志](https://app.edgegap.com/deployment-management/deployments/list).
* 如果您无法找出问题，我们会在我们的频道等着您， [社区 Discord](https://discord.gg/NgCnkHbsGp) 遇到困难？我们在我们的

🙌 恭喜您在 Edgegap 上完成首次部署！如果您想了解更多，请继续阅读。

## 👉 后续步骤

一旦你有了可用的客户端/服务器设置，请确保 **保存你的项目副本** （使用诸如 git 之类的版本控制软件），以便在遇到问题时总能追溯你的步骤。

继续阅读以了解更多与服务器生命周期和可发现性相关的主题。

{% hint style="info" %}
如果你需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。关于实时游戏支持，请查看我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 停止部署

当比赛结束（或玩家离开）后，你可以停止部署以节省成本。 [空跑或只填充了一部分玩家会不必要地增加你的成本！](https://edgegap.com/blog/how-session-fill-rate-affects-your-multiplayer-hosting-costs)

{% hint style="success" %}
Godot 脚本示例即将推出！
{% endhint %}

{% hint style="warning" %}
连接你的 [Endpoint Storage](/zh/docs/endpoint-storage.md) 以保存部署日志，否则它们将被删除！
{% endhint %}

### 注入变量

通过访问注入的环境变量来读取有用信息，例如部署 ID、服务器 IP 地址、服务器位置等。每个部署都会自动包含：

* [部署变量](/zh/learn/bian-pai/deployments.md#injected-environment-variables) - 由 Edgegap 自动提供，
* [匹配变量](/zh/learn/pi-pei/matchmaker-in-depth.md#injected-environment-variables) - 在使用 [匹配](/zh/learn/pi-pei.md),
* [应用版本变量](/zh/learn/bian-pai/application-and-versions.md#injected-variables) - 由你配置的自定义键值对。

{% hint style="success" %}
Godot 脚本示例即将推出！
{% endhint %}

### 会话自动化

{% hint style="warning" %}
**手动启动你的部署，复制 URL 和端口在实时游戏中行不通。**
{% endhint %}

使用以下任一方式，自动化热门游戏流程，以管理会话并按需扩展：

{% columns %}
{% column width="33.33333333333333%" %}
[匹配](/zh/learn/pi-pei.md):

* 更短的回合
* 按需对局
* 技能评级和/或\
  自定义规则
  {% endcolumn %}

{% column width="33.33333333333333%" %}
[Server Browser](/zh/learn/server-browser.md):

* 持久模式或回合制
* 社交区域枢纽
* 自动分配和/或\
  自定义搜索
  {% endcolumn %}

{% column width="33.33333333333333%" %}
自定义后端：

* 迁移实时游戏
* [使用 v2 API 部署](/zh/docs/api/zhuan-yong-fu-wu-qi.md)
* [监控 Webhooks](/zh/learn/bian-pai/deployments.md#webhooks)
  {% endcolumn %}
  {% endcolumns %}

{% hint style="success" %}
Godot 脚本示例即将推出！
{% endhint %}

### 优化使用

以下是一些帮助你开始优化服务器使用的建议：

**更高的 tick 率意味着更多更新，需要更多 CPU 使用和数据外发。**

* Godot 默认每秒 60 tick，这对于快节奏射击游戏或高度依赖低延迟的游戏非常适合。其他类型的游戏可能只需要 30 Hz 甚至 15 Hz。
* 更高 tick 率的隐性成本是在每秒内进行更多 CPU 周期来对数据进行（解）包，以及重新计算服务器权威属性和流程。如果你的游戏每局有很多玩家（10+）、很多带碰撞体的节点、复杂的物理模拟，或大量机器人对手/队友，请谨慎处理。
* 在你的网络代码设置中用不同的 tick 率测试游戏响应速度。对于 ENET，请参见 Project Settings / Physics / Common / Physics Ticks Per Second。

**如何选择合适的网络协议？先让它可用，再让它更好。**

* Godot 内置的 ENET 和默认 UDP 协议是一个很好的默认选择，能够在最广泛的设备和使用场景中提供性能与兼容性。
* 某些游戏可能希望尝试 TCP、WS、WebRTC 或其他协议。这可能提高你在移动设备和主机上的连接可靠性，尤其是在公共网络上（蜂窝网络、公司网络、咖啡馆、酒店 Wi‑Fi 等），但这肯定需要额外的开发工作。问问自己这对你的目标受众是否至关重要。
* 并行使用多种协议，以确保重要更新优先传递，可能会改善某些类型游戏的玩家体验（例如 MMO），但这会带来大量额外开发工作，并可能为你的项目增加巨大的复杂性。
* 谨慎选择战场，游戏开发从不缺少挑战。

### 自定义镜像

我们还支持为需要更高镜像控制能力的用户添加自己的 Dockerfile，例如由于构建大小优化、额外依赖项，或需要更复杂的启动流程。你可以在步骤中可选地提供自定义 Dockerfile 的路径 [#id-3.-containerize-server](#id-3.-containerize-server "mention")。现在我们将分享一些“自己动手”的技巧和最佳实践。

**始终确保你使用的是一个可正常运行的服务器构建版本。**

* 在断定某个问题与自定义 Dockerfile 有关之前，请确保你的服务器构建能够启动，并且游戏引擎中的构建过程没有抛出任何异常或错误。

**上传前务必先在本地测试。**

* 在本地测试你的镜像可以为你节省大量等待上传完成的时间。而且它完全免费 ✨，因为不需要任何 Edgegap 资源。
* 在本地测试时，请务必正确设置内部端口：

  ```bash
  docker run \
    -p 7777/udp \
    -e ARBITRIUM_PORTS_MAPPING='{"ports":{"gameport":{"internal":7777}}}' \
    'registry.edgegap.com/<repository>:<tag>'
  ```

**确保你已经掌握了基础内容。每个 Dockerfile 都需要一些基本的必需命令：**

* `FROM {image}` 是你的基础镜像，我们通常使用长期支持的 Linux，但任何基于 Linux 的基础镜像都可以。这些通常是存储在 Docker Hub 上的公共镜像。Dockerfile 参考文档见此。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#from).
* `COPY {source} {destination}` 用于将你主机上的 Linux 服务器构建复制到镜像内部，以便之后可以启动它。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#copy).
* `USER {user}` 应该跟在一个 [useradd (ubuntu) 命令](https://manpages.ubuntu.com/manpages/bionic/man8/useradd.8.html) 之后，最好不要把所有东西都以 `root` 的身份运行，以便更安全。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#user).
* `CMD {command}` 将是最后一行，很可能会调用一个 `StartServer.sh` 或某种启动脚本，以确保在一切设置完成后你的服务器能够正确初始化。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#cmd).
* 不要使用 `VOLUME` - 你将无法通过这种方式在 Edgegap 上挂载任何本地存储，请考虑改用我们的 Endpoint Storage 功能并使用 S3 存储桶，参见 [Endpoint Storage](https://docs.edgegap.com/docs/deployment/endpoint-storage),
* `EXPOSE 7777/UDP`  不是必需的！这实际上不会让容器外部访问内部服务器端口，它只是给开发者的一个提示，而该端口需要
  * 在本地测试时通过以下方式发布： `docker run <image> -p 7777/udp` ,
  * 或映射到 [Edgegap Port Mapping](/zh/learn/bian-pai/application-and-versions.md#other-parameters-optional).

**尽可能将参数的声明延后到最后一刻。由于服务器构建时间较长，可配置性 > 可组合性。** [**将此方法应用到 Dockerfile 命令中，以更快地构建和上传。**](https://medium.com/@esotericmeans/optimizing-your-dockerfile-dc4b7b527756)

* 场景：你需要定义诸如部署阶段、版本、游戏模式、地图、每台服务器的玩家数量、备份频率或类似的参数。
* 糟糕的方案：为参数的每一种组合都创建一个单独的镜像。你会把所有时间都花在重新构建镜像上，而这种方法带来的好处却非常有限。
* 更好的方案——在需要时再替换配置参数：
  1. 部署参数——在部署前才提供——例如作为环境变量传递的匹配选择器，或者你的自定义会话管理系统在部署时传递环境变量，
  2. 版本参数——在同一应用版本的所有部署中共享——例如部署阶段、制品标签、第三方密钥和端点等；然后
  3. 一个单一镜像——在启动时包含并加载所有配置选项。

**不要在 Edgegap 部署中运行数据库。**

* Edgegap 部署并非为长时间运行的进程而设计，可能会在运行很久后未经事先通知而被终止。以这种方式运行的数据库（即使是分布式的）也可能被终止，并导致不可逆的数据丢失。如果你需要数据库，请考虑使用第三方 DBaaS。
* 考虑使用我们的 [托管集群](https://app.edgegap.com/cluster-management/clusters/list) 来托管数据库和长时间运行的服务。