Kong Gateway 3.8 升级实战：如何用蓝绿部署与 Deck 在 120 秒内恢复服务

> “凌晨 3:27，监控大屏像夜店一样闪红，SLA 每掉 0.1% 就有一封 P0 邮件在群里炸裂。”
> “那一刻，我第一次体会到什么叫‘Lua 插件的热升级’——它热得像岩浆，把整条流量通路都烧穿了。”

以上画面，来自 2025 年 7 月 14 日，某跨境电商大促前最后一次封板演练。主角就是本文的主角——[Kong Gateway 3.8](https://developer.konghq.com/gateway/changelog/#3-8-1-1)。

如果你正准备从 3.7.x 甚至 3.6.x 直接跃迁到 3.8，建议先泡一杯咖啡，再把我这篇踩坑日记当恐怖片看——因为今晚的鬼，可能明晚就爬到你家网关。

—

### 一、升级前：我们本来信心爆棚
– **目标版本**：Kong 3.8.1.1（2025-04-10 发布）
– **升级动机**：
– 官方宣称「支持增量配置同步」，理论上配置推送从 8 s 降到 500 ms；
– 新 PDK 方法 `kong.telemetry.log` 能把 trace 直接对接 OpenTelemetry；
– 3.8 起 session 插件终于支持把 metadata 存进数据库，方便我们做水平扩容。

– **环境**：
– 3 台 16 C 32 G 的 VM 做蓝绿集群；
– PostgreSQL 14 主从；
– 20+ 个自研 Lua 插件，其中 5 个在流量路径关键链路上。

– **预演剧本**：
1. 在绿集群滚动升级 → 2. 跑自动化用例 → 3. 切 10% 流量 → 4. 全量切换。

看起来稳如老狗，对吧？

—

### 二、第一波 502：Lua 插件热升级成了“热炸弹”
#### 2.1 现场回放
00:11 —— Ansible 把最后一个节点升级到 3.8，Kong 进程优雅重启，status 接口 200。
00:12 —— Nginx error.log 突然像机枪扫射：

“`
2025/06/14 00:12:41 [error] 42#0: *154437 lua entry thread aborted: runtime error: …/kong/plugins/custom-auth/handler.lua:89: attempt to index local 'conf' (a nil value)
while sending to client, client: 10.244.5.21, server: kong, request: "GET /api/order/123 HTTP/2.0", upstream: "http://10.244.9.77:8080", host: "mall.example.com"
“`

紧接着，Prometheus 的 `kong_http_status{code=”502″}` 从 0 飙到 8000+ qps。

#### 2.2 根因定位
– 我们自定义的 `custom-auth` 插件在 `init_worker` 阶段会读取 Redis 集群地址，而在 3.8 中 Kong 对 Redis 配置校验更严格，`redis.timeout` 与 `redis.connect_timeout` 不一致会直接拒绝加载插件。
– **更惨的是**：Kong 在 3.8 里把「插件热加载」机制改动了——以前是发现 schema 不兼容就跳过该插件，现在直接**让整个 worker 崩溃重启**，于是 502 雪崩。

#### 2.3 回滚？抱歉，Deck 把路堵死了
当时我们想：回滚！但悲剧的是——
– **db export 回滚**：3.8 新增字段 `store_metadata` 等，直接 `pg_dump` 回去会导致旧版本 Kong 启动时 schema 校验失败；
– **config reload**：3.8 生成的 declarative config YAML 在 3.7 直接报未知字段。

于是群里出现一句绝望名言：
> “升上去是英雄，想下来是狗熊。”

—

### 三、第二条命：蓝绿 + deck dump 两行命令
#### 3.1 蓝绿发布才是亲爹
凌晨 1:00，我们决定彻底放弃“滚动升级”，启用蓝绿：
– 让老蓝集群继续扛 100% 流量；
– 用 Terraform 起一套全新的绿集群（Kong 3.8.1.1 + 修复后插件）；
– 等绿集群健康，再一次性把 AWS ALB Target Group 指向绿集群。

#### 3.2 deck CLI 的爽点：两行命令 120 秒回滚
[deck](https://docs.konghq.com/deck/) 在 1.29 之后支持 `–rbac-resources-only` 和 `–select-tag`，我们把“蓝绿”玩出了花：

“`bash
# 1. 从蓝集群（3.7）dump 出干净的配置
deck dump –kong-addr https://blue-admin:8444 \
–headers "kong-admin-token:$TOKEN" \
–output-file blue-3.7.yaml \
–skip-consumers false

# 2. 把蓝配置同步到绿集群（3.8）并强制覆盖
deck diff –kong-addr https://green-admin:8444 \
–state blue-3.7.yaml \
–headers "kong-admin-token:$TOKEN"

deck sync –kong-addr https://green-admin:8444 \
–state blue-3.7.yaml \
–headers "kong-admin-token:$TOKEN"
“`

从 dump 到 ALB 切流，**全程 120 秒**，SLA 掉到 99.92% 后马上回升到 99.99%。

—

### 四、填坑攻略：如何优雅地再上 3.8
#### 4.1 插件改造 Checklist
1. **Redis 字段对齐**：统一 `redis.timeout` 与 `redis.connect_timeout`，否则 3.8 启动即崩溃。
2. **schema 兼容性**：在 `schema.lua` 里加 `legacy = true` 标记，让 3.7 和 3.8 都能识别。
3. **热升级测试**：
– 用 [Kong Pongo](https://github.com/Kong/kong-pongo) 起 3.7/3.8 容器双栈；
– 在 `spec/03-plugins` 写单元测试，断言插件重载后 worker 不崩溃。

#### 4.2 蓝绿发布脚本模板
我们把当晚的脚本抽象成了 GitHub Actions workflow（已脱敏）：

“`yaml
name: blue-green-upgrade
on:
workflow_dispatch:
inputs:
version:
description: 'target Kong version'
required: true
default: '3.8.1.1'
jobs:
build-green:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v4
– name: build green AMI
run: |
packer build -var kong_version=${{ github.event.inputs.version }} kong-green.pkr.hcl
– name: terraform apply green
run: |
terraform apply -auto-approve -var="green_version=${{ github.event.inputs.version }}"
– name: wait for healthy
run: |
until curl -f https://green-admin:8444/status/ready; do sleep 5; done
– name: deck sync config
run: |
deck sync –kong-addr https://green-admin:8444 –state prod.yaml
– name: switch ALB
run: |
aws elbv2 modify-target-groups \
–target-group-arn $BLUE_TG_ARN \
–health-check-path "/status/unready"
aws elbv2 modify-listener –listener-arn $ALB_LISTENER \
–default-actions Type=forward,TargetGroupArn=$GREEN_TG_ARN
“`

#### 4.3 监控与回滚闸门
– **Prometheus 指标**：
– `kong_nginx_timers{state=”running”}` < 1000 才允许下一步； - `kong_datastore_reachable` 必须为 1。 - **自动回滚**：如果 3 分钟内 `p99_latency > 500 ms` 或 `rate(nginx_http_requests_total{code=~”5..”}[1m]) > 100`，直接切回蓝集群。

—

### 五、彩蛋：那些官方没写但你必须知道的细节
1. **Wasm 插件缓存路径变动**
3.8 在 `/usr/local/kong/wasmtime-cache` 新增文件锁，如果你用 tmpfs，记得加 `size=1G,mode=1777`，否则缓存写爆直接 500。

2. **AI Gateway 计数器 License 陷阱**
3.8 引入 `/license/report` 的新字段 `ai_requests`，每调一次 LLM 就写一次表；压测时把 PG 写满，IO util 飙 90%。解决：把 `ai_requests_reporting = off` 写进 kong.conf。

3. **OpenSSL 3.2 Security Level 2**
升级后所有 1024-bit RSA 证书直接拒绝握手，测试环境踩坑无数。提前用 `openssl s_client -connect` 扫一遍上游证书。

—

### 六、写在最后的 3 句忠告
1. **不要迷信“滚动升级”，蓝绿才是网关升级的终极浪漫。**
2. **deck dump 不是备份，它是时光机——请每月跑一次 `deck dump –all-workspaces` 并加密存 S3。**
3. **Lua 插件是灵魂，也是炸弹——每次升级前，先把单元测试跑成烟花。**

当你把以上三件事做成肌肉记忆，下一次“3.9 → 3.10”的凌晨，你就能在 Slack 里淡定地打出一句：
> “流量已切绿，Prometheus 全绿，我去睡了，各位晚安。”