Files

90 lines
4.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
id: devops.k8s.scenario.agent-rollout
title: AI Agent 服务上 K8s:发布时流式回答不中断、慢启动、密钥管理和按负载扩容
type: scenario
domain: devops
stack: [k8s, docker, nginx, cicd]
tags: [滚动更新, 优雅退出, SSE, 探针, HPA, Secret, 回滚]
level: intermediate
prerequisites: [devops.k8s.core-objects, devops.docker.image-dockerfile]
est_hours: 2.5
related: [devops.k8s.interview, devops.cicd.release-rollback]
week: [14]
---
# AI Agent 服务上 K8s:发布时流式回答不中断、慢启动、密钥管理和按负载扩容
## 业务背景与问题
Agent API 从虚拟机迁移到公司的 K8s 集群后:
1. 每次发布,正在进行中的流式回答被切断,用户看到“网络错误”;
2. 新版本启动需要预热(加载提示词模板、建立连接池),偶尔被重启循环;
3. 有人把模型 API Key 直接写在 Deployment 的环境变量里提交到了仓库;
4. 高峰期响应变慢,但 CPU 使用率并不高,HPA 没有扩容。
## 约束
- 集群由平台团队维护,应用团队只能修改自己的清单。
- 回答可能持续 60 秒以上。
## 方案设计
1. **优雅退出**:
- 应用收到 SIGTERM 后:就绪检查立即返回失败、不再接受新请求、等待进行中的流结束(最长 80 秒)后退出;
- `preStop` 短暂等待,给 Ingress / Service 摘除端点的时间;
- `terminationGracePeriodSeconds: 90` 大于最长回答时间;
- 滚动更新 `maxUnavailable: 0`。
2. **慢启动**:startupProbe 给足启动时间;就绪探针在预热完成后才返回成功。
3. **密钥**:轮换已泄露的 Key;清单中只引用 Secret;Secret 由密钥管理系统同步(或平台提供的方案);CI 中加密钥扫描。
4. **扩容指标**:AI 服务主要在等待模型返回,CPU 低但并发连接数高。改用“每个 Pod 的进行中请求数”作为自定义指标(需要平台支持指标适配器),或者先按经验提高副本下限。
5. **发布与回滚**:镜像固定版本;CI 中先 `kubeconform` + 规范测试;发布后观察错误率和首 token 延迟,异常时 `kubectl rollout undo`。
## 关键代码
FastAPI 应用的优雅退出(示意):
```python
import asyncio, signal
active_streams = 0
shutting_down = False
@app.get("/readyz")
async def readyz():
if shutting_down:
raise HTTPException(503) # 让 K8s 尽快摘除这个 Pod
return {"ok": True}
async def drain(timeout: float = 80):
global shutting_down
shutting_down = True
loop = asyncio.get_running_loop()
deadline = loop.time() + timeout
while active_streams > 0 and loop.time() < deadline:
await asyncio.sleep(0.5) # 等待进行中的流式回答结束
```
(Uvicorn 自身也会在收到 SIGTERM 后停止接收新连接并等待请求完成,具体参数如 `--timeout-graceful-shutdown` 以官方文档为准。)
完整清单:[examples/agent-api](../examples/agent-api/)。SSE 在 Nginx 层的配置见 [AI 网关场景](../../nginx/scenarios/ai-gateway-sse-canary.md)。
## 取舍
| 选择 | 优点 | 缺点 |
| --- | --- | --- |
| **优雅退出 + 长宽限期(本方案)** | 用户无感知 | 发布时间变长 |
| 前端断线自动续传(从断点继续) | 对任何中断都有效 | 后端要保存生成进度,复杂 |
| 发布时间放在低峰期 | 简单 | 治标不治本 |
## 易错点
- 宽限期比最长回答时间短,SIGKILL 依然切断。
- 应用作为 shell 脚本的子进程启动,收不到 SIGTERM(使用 exec 形式的启动命令)。
- 就绪探针在退出阶段仍然返回成功,新请求继续进来。
- 以为 Secret 是加密的。
## 面试怎么讲
> “迁移到 K8s 后发布会切断流式回答。我做了优雅退出:收到 SIGTERM 后就绪探针立即失败,停止接新请求,等进行中的流结束;preStop 留出摘除端点的时间,宽限期设为 90 秒,大于最长回答;滚动更新不减少可用副本。慢启动用 startupProbe。泄露的 Key 立即轮换,清单只引用 Secret,CI 加密钥扫描。扩容方面,AI 服务 CPU 不高但并发高,改用进行中请求数作为指标。”