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

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

以上画面，来自 2025 年 7 月 14 日，某跨境电商大促前最后一次封板演练。主角就是本文的主角——Kong Gateway 3.8。

如果你正准备从 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 在 1.29 之后支持 --rbac-resources-only 和 --select-tag，我们把“蓝绿”玩出了花：

# 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

Redis 字段对齐：统一 redis.timeout 与 redis.connect_timeout，否则 3.8 启动即崩溃。
schema 兼容性：在 schema.lua 里加 legacy = true 标记，让 3.7 和 3.8 都能识别。
热升级测试：
- 用 Kong Pongo 起 3.7/3.8 容器双栈；
- 在 spec/03-plugins 写单元测试，断言插件重载后 worker 不崩溃。

4.2 蓝绿发布脚本模板

我们把当晚的脚本抽象成了 GitHub Actions workflow（已脱敏）：

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，直接切回蓝集群。

五、彩蛋：那些官方没写但你必须知道的细节

Wasm 插件缓存路径变动
3.8 在 /usr/local/kong/wasmtime-cache 新增文件锁，如果你用 tmpfs，记得加 size=1G,mode=1777，否则缓存写爆直接 500。
AI Gateway 计数器 License 陷阱
3.8 引入 /license/report 的新字段 ai_requests，每调一次 LLM 就写一次表；压测时把 PG 写满，IO util 飙 90%。解决：把 ai_requests_reporting = off 写进 kong.conf。
OpenSSL 3.2 Security Level 2
升级后所有 1024-bit RSA 证书直接拒绝握手，测试环境踩坑无数。提前用 openssl s_client -connect 扫一遍上游证书。

六、写在最后的 3 句忠告

不要迷信“滚动升级”，蓝绿才是网关升级的终极浪漫。
deck dump 不是备份，它是时光机——请每月跑一次 deck dump --all-workspaces 并加密存 S3。
Lua 插件是灵魂，也是炸弹——每次升级前，先把单元测试跑成烟花。

当你把以上三件事做成肌肉记忆，下一次“3.9 → 3.10”的凌晨，你就能在 Slack 里淡定地打出一句：

“流量已切绿，Prometheus 全绿，我去睡了，各位晚安。”