> 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 %}

## 🏷️ 应用版本

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

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

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

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

{% hint style="success" %}
探索我们的 [应用版本 API 参考](https://docs.edgegap.com/api/#tag/Applications/operation/app-version-post)在 Edgegap 上管理你的应用版本，或进一步了解 [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 比例包含 RAM， **每 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`）它将不会识别新的构建。

***

我可以给同一个构建制品添加多个标签吗？

* 可以，你可以多次为同一个制品添加标签而不会有问题，这相当于为同一个构建提供多个别名。继续阅读以了解之后如何移除这些标签。

***

当我删除一个标签时会发生什么？为什么我不能使用哈希删除某个特定制品？

* 如果在 [API 请求](https://docs.edgegap.com/api/#tag/Container-Registry/operation/image-tag-delete).
* 时该制品没有其他关联标签，删除标签也会导致相关构建制品被删除。由于 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="/files/a9beeb419bfb59f63e55b32a7622aff167022fcb" 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 %}

### 日志存储

要在部署停止后导出服务器日志，请配置 [Endpoint Storage](/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 %}