> 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/learn/bian-pai/application-and-versions.md).

# 应用与版本

了解版本管理和应用——用于更深入理解的概念与最佳实践。

## 📦 应用

应用封装了服务器项目。这种上下文分离在以下情况下尤其有用：

* 同时开发多个游戏或非游戏项目（合并计费），
* 作为联合开发者参与外部项目（之后转移所有权），
* 依赖多个松耦合的服务器类型，且它们具有不同的扩展模式或需求。

你可以使用我们的插件在 Edgegap 上管理你的应用， [控制面板](https://app.edgegap.com/application-management/applications/list)，或使用我们的 API。

{% hint style="success" %}
查看我们的 [应用 API 参考](https://docs.edgegap.com/api/#tag/Applications)，或进一步阅读我们的 [管理 API](https://docs.edgegap.com/api/).
{% endhint %}

## 🏷️ 应用版本

随着你开发应用并持续产出新构建，你需要将每个构建作为单独的版本存储，以便：

* **保持兼容性** ，在客户端和服务器之间，
* 比较你的 **增量发布** 的各个方面（性能、用户反馈），
* 测试 **多个应用版本同时运行** （开发、质量保证、预发布、Beta）。

{% hint style="info" %}
每个应用版本都指向你选择的一个构建产物。多个版本可以指向同一个构建。
{% endhint %}

你可以使用我们的方式在 Edgegap 上管理你的应用版本 [控制面板](https://app.edgegap.com/application-management/applications/list)，或使用我们的 API。

{% hint style="success" %}
查看我们的 [应用版本 API 参考](https://docs.edgegap.com/api/#tag/Applications/operation/app-version-post)，或进一步阅读 [API](https://docs.edgegap.com/api/).
{% endhint %}

每个版本在其父应用中都通过以下方式唯一标识： **应用版本名称**。你可以自由决定自己的命名规范。以下是一些流行示例，供你参考：

* `2024.01.30-16.23.00-UTC` - 时间戳便于保留大量历史版本，
* `1.1.0` - [语义化版本](https://semver.org/) 是传达变更范围的绝佳选择，
* `开发` , `预发布`, `测试`, `生产` - 每个环境只保留最新版本会非常容易，
* `蓝色`, `绿色` - 版本可以作为别名，用于滚动更新发布策略。

{% hint style="success" %}
只要你保持客户端/服务器兼容性，就可以随时更改你的方法。
{% endhint %}

{% hint style="info" %}
你可以在我们的 [控制面板](https://app.edgegap.com/application-management/applications/list) 中 **禁用任何应用或版本，以**.
{% endhint %}

{% hint style="info" %}
免费层限制为 2 个应用、2 个版本以及 5 GB 的容器镜像仓库存储空间。
{% endhint %}

### 组合版本管理策略

通常，最佳方案是混合使用多种版本管理策略，例如：

* 对开发构建使用时间戳或语义化版本，以便更细粒度地跟踪；
* 保留 `预发布`, `测试` 和 `生产` 带有环境特定参数的版本；
* 交替使用 `蓝色` 和 `绿色` 版本作为 [零匹配停机更新](https://docs.edgegap.com/docs/gen2-matchmaker#rolling-updates-ab-tests).

## 🧱 必填参数

这些基础参数必须始终定义。

### 资源需求

除了 **版本名称**之外，创建新版本还需要以下几个参数：

* **vCPU** - 你的应用运行所需的虚拟 CPU 单元数（1024 单元 = 1 vCPU），
  * **最低允许的 vCPU 数量是 0.25 vCPU（256 单元），**

{% hint style="info" %}
每次部署需要少于 0.25 vCPU？ [联系我们，了解优化方案。](mailto:info@edgegap.com)
{% endhint %}

* **内存** - 你的应用运行所需的 RAM 兆字节数（1024MB = 1GB），
* **GPU** - 你的应用运行所需的图形处理单元数量，
  * 该功能尚未提供，如果你感兴趣，请联系我们。

{% hint style="success" %}
版本会自动按 2:1 的 RAM-vCPU 比例包含内存， **在 0.25 vCPU 下提供 512MB RAM**.
{% endhint %}

{% hint style="info" %}
我们的服务器机器使用 AMD/Intel CPU，时钟速度为 2.4 - 3.2 GHz，具体取决于位置。为确保你的服务器有足够的可用资源，请在以下渠道联系我们： [社区 Discord](https://discord.gg/MmJf8fWjnt).
{% endhint %}

### 镜像详情

这些参数将帮助我们的系统决定稍后应启动哪个服务器构建：

* **镜像仓库** - `registry.edgegap.com` 如果你使用我们的 [容器镜像仓库](https://docs.edgegap.com/docs/container/edgegap-container-registry),
  * ，若要使用第三方镜像仓库，请输入第三方镜像仓库的 Docker 凭证，
  * 该仓库作为你和其他用户仓库的共享存储服务。
* **镜像仓库** - 指你的应用专属仓库，
  * 你可以在我们的 [控制面板的容器镜像仓库页面中找到所有仓库](https://app.edgegap.com/registry-management/repositories/list),
  * 每个仓库可能包含你服务器镜像的多个标签。
* **标签** - 指你服务器镜像的某个特定构建产物（版本），
  * 默认情况下，我们的插件会将标签值从应用版本名称中复制过来，
  * 你可以在 Docker Desktop 的 Images 中或使用 docker CLI 查看本地存储的标签。

{% hint style="danger" %}
:x: **不要——覆盖现有标签或使用 `latest` 标签** ，以避免部署过时的构建。\
:white\_check\_mark: **要——始终递增你的版本标签** 并部署新构建，避免使用过期缓存。
{% endhint %}

* **私有镜像仓库** - 如果你的仓库访问受保护（私有仓库），我们还需要：
  * **用户名令牌** - 你的镜像仓库程序化访问用户名，
  * **密码令牌** - 你的镜像仓库程序化访问密码，
  * 用于 Edgegap [容器镜像仓库](https://docs.edgegap.com/docs/container/edgegap-container-registry)，你可以 [从我们的控制面板复制这些值](https://app.edgegap.com/registry-management/repositories/list),
  * 这些对于公共仓库不是必需的。

<details>

<summary>故障排查与常见问题</summary>

我收到了错误 `401 未授权` ，在推送服务器镜像时。

* 这表示你尚未登录到你的容器镜像仓库。有关说明，请参见容器镜像仓库： [Edgegap 容器镜像仓库说明](https://docs.edgegap.com/docs/container/edgegap-container-registry#getting-your-credentials)，或你的镜像仓库提供商的对应说明。重复上一次操作不会解决该错误。

***

我收到了错误 `403 禁止访问` ，在推送服务器镜像时。

* 这表示你当前登录的镜像仓库用户没有足够的权限（通常是推送新镜像的权限），或者你登录到了错误的镜像仓库提供商。请尝试退出登录，并使用具有足够权限的正确提供商和用户重新登录。重复上一次操作不会解决该错误。

***

镜像仓库、仓库和项目有什么区别？

* 可以把镜像仓库看作存储设施，把仓库看作储物单元，把项目看作储物单元编号。每个镜像仓库通常包含许多仓库，有些是公开的，有些则对组织和用户私有。
* 示例镜像仓库： `registry.edgegap.com` .
* 示例仓库： `registry.edgegap.com/my-edgegap-org/my-game-server`.
* 示例项目名称： `my-game-server` .

***

在推送新的镜像标签/构建时，我的更改没有正确重新加载。

* 请确保每次重新构建时，都使用新的镜像标签推送。Edgegap 的内部缓存系统使用标签名称，如果你覆盖某个标签值（例如 `latest`），它将不会识别新的构建。

***

我可以给同一个构建产物打上多个标签吗？

* 可以，你可以无障碍地为同一个构建产物打上多个标签，将其作为同一构建的多个别名。继续阅读，了解之后如何移除这些标签。

***

删除一个标签时会发生什么？为什么我不能使用哈希删除某个特定构建产物？

* 你必须删除与特定构建产物关联的所有标签，才能释放镜像仓库中的空间。
* 由于 Docker API 标准以及为了确保最佳用户体验，我们只提供删除标签的界面。有关删除构建产物，请参见上文。

</details>

## ⚙️ 可选参数

这些参数可以配置，用于进一步自定义你的部署。

### 注入变量

此版本的所有部署都会注入自定义环境变量：

* 常见示例包括：引擎参数、第三方密钥和端点，
* 参见 [部署](/zh/learn/bian-pai/deployments.md#injected-environment-variables) ，以了解根据部署上下文可注入环境变量的不同方式，除此之外还有应用版本变量，
* 每个环境变量最多可包含 4KB（千字节）的字符串数据。

{% hint style="warning" %}
请务必 **将你的敏感变量（密钥、令牌）设为隐藏** 以增强安全性！
{% endhint %}

### 主动缓存

:star2: [**升级到按需付费套餐**](https://app.edgegap.com/user-settings?tab=memberships) **即可解锁全球 0.5 秒部署时间！**

**加快部署速度，并在几秒内启动服务器，无需待机服务器。** 与此应用版本关联的服务器镜像将自动预加载到我们全球所有位置。

当你的应用版本缓存等级达到 🟢 良好 时，缓存才会完全生效。

{% hint style="success" %}
多个应用版本可以复用同一个镜像标签。 **为某个版本启用缓存后，自动为所有链接到同一镜像标签的版本启用缓存**，使参数化部署变得轻而易举。
{% endhint %}

{% hint style="info" %}
镜像还会在部署时被被动缓存，但仅缓存于部署所在的主机。
{% endhint %}

{% hint style="warning" %}
**如果镜像连续 72 小时未部署，它们将从缓存中移除。**
{% endhint %}

### 端口映射

每个服务器至少需要一个端口，以接受来自客户端的传入连接：

* **端口** 值指的是 **内部端口** 值，通常来自你的 netcode 集成，
* **协议** 将取决于你的 netcode 集成传输层，
* **名称** 是你自己需要的人类可读标识符，可以与端口相同，
* **验证** 可以启用，以确保容器在被标记为 READY 之前已初始化。

{% hint style="success" %}
大多数游戏只需要为端口添加一个 UDP 端口映射 `7777`.
{% endhint %}

尽管服务器进程的内部端口是在应用版本中定义的， **外部端口会在创建部署时随机分配**，从而使潜在的恶意方（黑客）在造成损害之前被拖慢并被检测到。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FXfDDoCk7J4O9qtkkjurh%2Fimage.png?alt=media&amp;token=a509cc92-a410-4658-9dcd-b032497debb5" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
如果你的服务器通过多个协议通信，请在端口映射中添加更多端口。
{% endhint %}

### 安全防护措施

这些参数有助于处理各种边缘情况和常见服务器故障排查：

* **时间限制** - 这些功能可以帮助你管理部署的资源生命周期：
  * **游戏最长时长** 可以设置为在给定时间后优雅关闭服务器，或者设置为 `-1`  配合 [应用版本 API 创建/编辑](/zh/docs/api/ban-ben-guan-li.md#post-v1-app-app_name-version) 用于 [持久化](/zh/learn/bian-pai/chi-jiu-hua.md) 配合 [私有舰队](/zh/learn/bian-pai/si-you-jian-dui.md).
  * **最大部署时间** 可以帮助你清理启动时间过长的部署。
* **进程重启策略** - 控制服务器进程停止时的部署行为。
  * 始终重启（默认）- 在成功退出代码（0）以及任何错误退出时都会重启。
  * 从不重启（推荐）- 成功和错误退出代码都会停止部署。
  * 崩溃时重启 - 仅在错误退出代码时重启，适用于持久化服务器。

{% hint style="info" %}
免费层限制为 2 个应用、2 个版本以及 5 GB 的容器镜像仓库存储空间。
{% endhint %}

### 日志存储

要在部署停止后导出服务器日志，请配置 [端点存储](/zh/docs/endpoint-storage.md) 使用 S3 存储桶。

{% hint style="warning" %}
未使用外部存储的版本日志会在部署终止时被删除。
{% endhint %}

## ⏩ 更新一致性

为了确保通过我们的 [控制面板](https://app.edgegap.com/application-management/applications/list)创建新的应用版本时不会更改任何参数，我们建议使用 **复制** 功能，位于你上一个应用版本控制面板页面的右上角。复制时，你可以在保存前编辑任何参数。

{% hint style="success" %}
**复制或编辑你的应用版本不需要重新构建服务器镜像。**
{% endhint %}

{% hint style="info" %}
参见 [匹配器滚动更新](https://docs.edgegap.com/docs/gen2-matchmaker#rolling-updates-ab-tests) 以进一步 **自动化发布**.
{% endhint %}