> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 发布和回滚通用服务

> 选择直接发布或灰度发布通用服务，并根据验证结果完成全量发布、回滚或旧版本清理。

通用服务更新可以直接发布，也可以通过灰度发布先验证目标版本。灰度过程中，目标版本和旧版本并行运行，您可以逐步调整流量或副本，观察目标版本表现，再决定全量切换、回滚或清理旧版本。

## 选择发布方式

| 发布方式 | 适合场景 | 关注点 |
| - | - | - |
| 直接发布 | 测试环境，或影响可控的小改动。 | 目标版本就绪后承接全部流量，适合低风险变更。 |
| 灰度发布 | 镜像、资源配置、存储挂载、启动命令、环境变量或其他运行配置变更可能影响线上请求。 | 目标版本和旧版本并行运行，逐步放量；灰度未结束前会占用两侧资源。 |

同一个服务同时只能存在一个进行中的灰度流程。灰度全量切到目标版本后，仍需要清理旧版本才算结束；清理前可以回滚，清理后不再支持本轮灰度的快速回滚。

## 直接发布

测试环境或影响可控的已验证变更，可以在服务列表中单击 **更新 > 直接发布**。提交变更后，等待实例更新和就绪，再验证访问端点、最小请求和必要依赖。

直接发布会更新当前运行版本，不提供灰度期间目标版本与旧版本的并行验证。涉及镜像、资源配置、存储挂载、启动命令、环境变量或其他可能影响线上请求的变更时，优先使用灰度发布。

## 灰度发布

### 1. 进入灰度发布页面

在服务列表中单击 **更新 > 灰度发布**。页面的 **版本变更** 区域用于配置目标版本相关信息。

<Note>
  发起灰度前，建议记录当前镜像、版本、访问入口、目标副本和业务基线。服务需要处于 **运行中**，且没有进行中的灰度流程，具体以页面限制为准。
</Note>

### 2. 配置目标版本

| 配置区域 | 灰度发布中可处理的信息 |
| - | - |
| **资源信息** | 根据页面展示配置目标版本所需的资源类型、实例类型和资源优先级。资源总量需要同时满足目标版本与旧版本并行运行期间的需求。 |
| **环境信息** | 配置镜像、存储挂载、Pod 中挂载路径、启动命令和环境变量等目标版本运行信息。镜像、端口和命令应与实际应用一致。 |
| **增强功能** | 按页面支持的范围配置优雅退出延迟时间或健康检查等运行行为。 |

以下配置会在 **灰度发布不可修改** 区域展示：**网关配置**、**监控配置**、**指标配置**、**实例数** 和 **定时策略**。**实例数** 和 **定时策略** 标注为 **使用直接发布**；需要变更这些配置时，请使用服务页面提供的直接发布方式。

### 3. 选择灰度策略

| 模式 | 页面行为 | 使用建议 |
| - | - | - |
| **简单模式** | 填写 **初始灰度比例**。目标版本就绪后，页面会按该初始比例驱动流量和实例比例。 | 适合按初始比例开始验证的常规灰度场景。 |
| **自定义模式** | 分别设置旧版本和目标版本的目标实例数；提交后在灰度详情中继续推进调整。 | 适合需要独立控制两侧容量的场景。 |

两种模式都需要选择容量策略：

* **先启后停**：先启动目标版本实例，再缩减旧版本实例。可以避免过渡期容量下降，但需要额外资源。
* **先停后启**：先释放部分旧版本容量，再启动目标版本实例。适合资源紧张且可以接受过渡期容量下降的场景。

右侧 **灰度预览** 会显示旧版本和目标版本的流量比例、目标实例数、实例合计以及容量策略。提交前，确认预览中的总实例数和容量策略符合资源预算与业务承载要求。

### 4. 创建并启动灰度

单击 **创建并启动灰度**。提交后进入灰度详情，观察目标版本的目标副本、就绪副本、事件、日志、监控和本次变更差异。

## 观察和推进灰度

| 操作目标 | 适用阶段 | 预期结果 |
| - | - | - |
| 继续推进灰度 | 灰度进行中，需要继续调整流量或目标版本容量。 | 平台按调整后的目标逐步调整目标版本和旧版本的流量及副本。 |
| 全量切换到目标版本 | 目标版本已验证稳定，准备承接全部流量。 | 流量切到目标版本，旧版本保留用于观察期回退。 |
| 回滚当前灰度 | 目标版本异常、容量不足或业务指标不符合预期。 | 流量回到旧版本，目标版本资源按流程移除。 |
| 清理旧版本 | 全量切换后，目标版本稳定且不再需要快速回退。 | 删除旧版本资源，灰度流程结束。 |

每次调整目标后，等待实例就绪并观察错误率、延迟、业务结果和告警，再继续推进。小样本请求的实际比例可能与配置权重有偏差，应结合总体指标判断。

## 回滚当前灰度和清理旧版本

全量切到目标版本后，目标版本会按当前目标副本承接全部流量，旧版本通常仍会保留一段时间用于快速回滚。此时两侧仍可能占用资源。例如旧版本有 `3` 个副本、目标版本只有 `1` 个副本时，执行全量后会由 `1` 个目标版本副本承接全部流量，旧版本 `3` 个副本仍保留到清理旧版本为止。

* 目标版本异常时，确认旧版本容量可承接流量，再使用当前灰度流程提供的回滚操作。
* 目标版本稳定后，使用页面提供的旧版本清理操作释放旧版本资源。
* 清理旧版本后，本轮灰度结束，不能再通过当前灰度流程快速回滚。

## 回滚历史版本

历史版本回滚用于恢复曾经正式生效的服务配置，与撤回当前灰度不是同一操作。

1. 在服务的版本历史中选择曾经正式生效的版本，核对镜像、启动命令和依赖。
2. 确认当前没有进行中的灰度流程，并确认资源配额和存储权限仍能满足旧版本配置。
3. 按页面提示提交回滚，等待实例更新并就绪。
4. 重新验证访问入口、业务请求和外部依赖。

<Warning>
  历史版本回滚只恢复对应版本的服务配置，不恢复数据库或 Volume 中的数据。未正式生效的灰度候选不能作为历史版本回滚点。
</Warning>

## 常见问题

<AccordionGroup>
  <Accordion title="为什么灰度期间其他操作被禁用？">
    灰度流程正在管理目标版本和旧版本的流量与副本。为避免直接更新、扩缩容、上下线或入口变更覆盖灰度目标，部分操作会被禁用。需要恢复常规操作时，先完成清理旧版本或回滚结束灰度。
  </Accordion>

  <Accordion title="全量发布后为什么还占用旧版本资源？">
    全量发布只把流量切到目标版本，旧版本仍保留用于观察期回退。确认目标版本稳定后，使用页面提供的旧版本清理操作。
  </Accordion>

  <Accordion title="灰度推进失败应该先看什么？">
    先查看灰度详情的告警、目标副本和就绪副本，再查看目标版本事件和实例日志。资源不足时可降低目标版本目标、调整容量策略或回滚。
  </Accordion>
</AccordionGroup>

## 相关文档

* [管理通用服务](./manage-general-inference-services)