> 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/) 非常适合传达变更范围，
* `dev` , `staging`, `qa`, `prod` ——每个环境只保留最新版本非常容易，
* `blue`, `green` ——版本可以作为滚动更新发布策略的别名。

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

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

{% hint style="info" %}
免费套餐限制为 2 个应用程序、2 个版本以及 5 GB 的容器注册表存储空间。
{% endhint %}

### 组合版本管理策略

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

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

## 🧱 必需参数

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

### 资源要求

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

* **vCPU** - 你的应用运行需要多少虚拟 CPU 单元（1024 单元 = 1 vCPU），
  * **允许的最小 vCPU 数量为 0.25 vCPU（256 单元），**
  * 此设置不能在现有应用版本上编辑，你必须创建一个新版本。
* **内存** - 你的应用运行需要多少兆字节的 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 %}

### 端口映射

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

* **端口** 值指的是 **内部端口** 值，通常来自你的网络代码集成，
* **协议** 将取决于你的网络代码集成传输方式，
* **名称** 是一个便于人工阅读的标识符，供你自己使用，可以与端口相同，
* **校验** 可以启用，以确保容器在被标记为 READY 之前已完成初始化。

{% hint style="success" %}
大多数游戏只需要为端口 `7777`.
{% endhint %}

添加一个 UDP 端口映射即可，而服务器进程的内部端口是作为应用版本的一部分定义的， **外部端口会在部署创建后随机分配**，从而减缓潜在恶意方（黑客）的行动，并在其造成损害前被检测到。

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

### 日志存储

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