# 配置上游慢启动

新的应用实例在承接正常流量份额前，可能需要一定时间预热缓存或初始化连接。上游慢启动会逐步增加新节点的有效负载均衡权重，同时由现有节点继续处理请求。

慢启动改变的是流量分配，而不是请求总速率。仅含一个节点的上游仍会接收全部请求。如果所有可用节点都是新节点，这些节点仍会共同处理全部流量。

## 前置要求[​](#前置要求 "前置要求的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker)。
* 安装 [cURL](https://curl.se/)，用于向服务发送请求以进行验证。
* 按照[快速入门教程](https://docs.apiseven.com/apisix/getting-started.md)在 Docker 中启动 APISIX 实例。

## 启动示例上游服务[​](#启动示例上游服务 "启动示例上游服务的直接链接")

将 `GATEWAY_CONTAINER` 设置为正在运行的 APISIX 容器。将该容器和两个 echo 服务器连接到专用网络：

```
export GATEWAY_CONTAINER=replace-with-apisix-container-name

docker network create apisix-slow-start-net

docker network connect apisix-slow-start-net "$GATEWAY_CONTAINER"

docker run -d --name slow-start-existing --hostname existing \

  --network apisix-slow-start-net jmalloc/echo-server:v0.3.7

docker run -d --name slow-start-new --hostname new \

  --network apisix-slow-start-net jmalloc/echo-server:v0.3.7
```

服务器会在响应中标识自身。两个服务器均已运行，但最初只有现有服务器属于该上游。

## 创建上游和路由[​](#创建上游和路由 "创建上游和路由的直接链接")

创建包含一个节点、预热窗口为 60 秒的上游：

```
curl "http://127.0.0.1:9180/apisix/admin/upstreams/slow-start" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "type": "roundrobin",

    "nodes": {

      "slow-start-existing:8080": 100

    },

    "warm_up_conf": {

      "slow_start_time_seconds": 60,

      "min_weight_percent": 10

    }

  }'
```

创建引用该上游的路由：

```
curl "http://127.0.0.1:9180/apisix/admin/routes/slow-start" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "uri": "/slow-start",

    "upstream_id": "slow-start"

  }'
```

添加第二个节点前发送请求，并确认响应标识为 `existing`：

```
curl "http://127.0.0.1:9080/slow-start"
```

请在添加第二个节点前发送此请求，使 APISIX 将现有节点记录为已完成预热。如果在首次请求前就配置两个节点，APISIX 会将二者都视为初始成员，不会让其中一个节点相对另一个逐步提升权重。

APISIX 会在 `upstream-slow-start` 共享内存字典中保存慢启动生命周期状态，并在优雅重载后继续保留。要重复本演练并观察新的权重提升过程，请使用新 ID 和新请求路径创建新的上游和路由。也可以完全重启 APISIX 容器，再重新创建资源。立即重新应用相同 ID 可能会复用之前的节点状态。

## 添加节点并观察慢启动[​](#添加节点并观察慢启动 "添加节点并观察慢启动的直接链接")

添加配置权重相同的第二个节点。PATCH 会将该节点合并到现有节点映射中：

```
curl "http://127.0.0.1:9180/apisix/admin/upstreams/slow-start" -X PATCH \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "nodes": {

      "slow-start-new:8080": 100

    }

  }'
```

在接下来一分钟内分批发送请求，并统计各服务器的响应数。每批请求提供足够的样本，便于观察流量份额的变化：

```
for elapsed in $(seq 0 10 60); do

  echo "After ${elapsed} seconds:"

  seq 1 100 | xargs -P 20 -I {} \

    curl -sS "http://127.0.0.1:9080/slow-start" | \

    grep -o 'Request served by [^[:space:]]*' | sort | uniq -c

  [ "$elapsed" -lt 60 ] && sleep 10

done
```

新节点的初始有效权重为 10，现有节点的权重为 100。随着新节点的权重逐步达到 100，它所处理的请求比例会接近一半。由于配置更新和请求会分布到不同的网关工作进程，实际计数会有所波动。最小百分比是相对于该节点配置权重的百分比，而不是相对于全部流量的百分比。

## 调整慢启动[​](#调整慢启动 "调整慢启动的直接链接")

在上游的 `warm_up_conf` 对象中配置以下字段：

| 字段                           | 必填 | 默认值 | 有效值                                      | 说明                                                                           |
| ------------------------------ | ---- | ------ | ------------------------------------------- | ------------------------------------------------------------------------------ |
| `slow_start_time_seconds`      | 是   | 不适用 | 大于或等于 `1` 的整数                       | 新节点达到配置权重所需的秒数。                                                 |
| `min_weight_percent`           | 是   | 不适用 | `1` 到 `100` 之间的整数                     | 节点配置权重的最小百分比。                                                     |
| `interval`                     | 否   | `1`    | `1` 到 `slow_start_time_seconds` 之间的整数 | 刷新有效权重的时间间隔，单位为秒。                                             |
| `aggression`                   | 否   | `1`    | 大于或等于 `0.01` 的数值                    | 权重提升曲线。`1` 表示线性提升；大于 `1` 时初始提升更快；小于 `1` 时提升更慢。 |
| `startup_grace_period_seconds` | 否   | `0`    | 大于或等于 `0` 的整数                       | 网关启动后，将新发现节点视为已完成预热的时间，单位为秒。                       |

权重为整数，正数节点权重不会低于 1。如果需要逐步提升权重，请配置足够大的初始权重：权重为 1 的节点无法再降低权重。

慢启动适用于使用加权轮询且节点优先级单一的 HTTP 上游。其他负载均衡算法、流路由和混合节点优先级不支持慢启动。`traffic-split` 插件中的内联上游会拒绝慢启动配置。

每个 APISIX 实例都会独立跟踪新节点。首次启用慢启动时，现有节点会被视为已完成预热；新节点首次具备接收流量的条件时开始提升权重。节点在一个提升周期内重新出现时会继续原来的提升过程；离线时间超过一个提升周期后重新出现，则会开始新的提升过程。慢启动不能替代就绪检查。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

将慢启动与[上游健康检查](https://docs.apiseven.com/apisix/how-to-guide/traffic-management/health-check.md)结合使用，确保新部署的节点仅在能够正常提供服务时才接收流量。有关完整配置 Schema，请参阅[上游 Admin API 参考](https://docs.apiseven.com/apisix/reference/admin-api.md#tag/Upstreams)。
