大模型应用开发 / 系统课时
封装镜像并部署无状态服务
封装镜像并部署无状态服务
本篇把一个最小客服 API 封装成容器,并将会话、缓存、向量索引和运行配置外置到独立服务。最终得到可健康检查、可滚动发布、可多副本运行,并能通过 HPA 扩容的部署基线。
学习目标
- 将 API 进程改造成不依赖本机状态的无状态服务
- 构建容器镜像并用健康检查验证启动结果
- 配置 Kubernetes 多副本、滚动发布和弹性扩容
先划清无状态边界
无状态不是“系统里没有状态”,而是任意一个 API 副本被删除后都不丢业务状态。请求可以落到任意 Pod,会话上下文和缓存放入 Redis,知识索引放入独立向量库,密钥与环境配置由 ConfigMap、Secret 或配置中心注入。
本地内存只适合保存可随时重建的短期对象,例如连接池和模型客户端;不要把用户会话、任务进度或唯一一份索引写到容器文件系统。这样滚动升级、Pod 漂移和自动扩容才不会改变业务语义。

准备可容器化的最小 API
下面的服务只保存进程级客户端配置,不保存用户会话。/livez 只判断进程是否存活,/readyz 判断依赖地址是否已通过环境变量注入。
import os
from fastapi import FastAPI
from fastapi.responses import JSONResponse
app = FastAPI()
redis_url = os.getenv("REDIS_URL")
vector_url = os.getenv("VECTOR_URL")
@app.get("/livez")
def livez():
return {"status": "ok"}
@app.get("/readyz")
def readyz():
if not redis_url or not vector_url:
return JSONResponse(
status_code=503,
content={"status": "not_ready"}
)
return {"status": "ready"}
@app.get("/answer")
def answer(q: str):
# 真实项目在这里通过外部 Redis、向量库和模型服务完成请求。
return {"question": q, "status": "accepted"}预期结果
GET /livez -> HTTP 200 {"status":"ok"}
GET /readyz -> HTTP 200 {"status":"ready"}
缺少 REDIS_URL 或 VECTOR_URL 时 /readyz -> HTTP 503 {"status":"not_ready"}实际业务应继续把会话与检索状态写入外部服务,而不是模块级字典或本地文件。
依赖文件可保持最小:
fastapi>=0.110,<1
uvicorn[standard]>=0.27,<1Dockerfile 使用非 root 用户运行服务,并把监听地址固定为容器内的 8080:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
RUN useradd --create-home appuser
USER appuser
EXPOSE 8080
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]镜像构建、启动和健康检查可以一次完成:
docker build -q -t kb-cs:1.0 .
docker run -d --name kb-cs -p 8080:8080 -e REDIS_URL=redis://<HOST>:6379/0 -e VECTOR_URL=http://<HOST>:6333 kb-cs:1.0
curl -s http://localhost:8080/readyz预期输出
<ID>
<ID>
{"status":"ready"}前两行分别是镜像 ID 与容器 ID,实际值不同;<HOST> 也应替换成容器可访问的真实依赖地址。
部署多副本并滚动发布
下面的清单把运行参数放到 ConfigMap,把模型密钥放到 Secret,再用 3 个副本承载流量。maxUnavailable: 0 保证滚动升级时不主动减少可用副本,maxSurge: 1 允许临时多起一个新 Pod。
apiVersion: v1
kind: List
items:
- apiVersion: v1
kind: ConfigMap
metadata:
name: kb-cs-config
data:
REDIS_URL: redis://redis.default.svc:6379/0
VECTOR_URL: http://vector-db.default.svc:6333
- apiVersion: v1
kind: Secret
metadata:
name: kb-cs-secret
type: Opaque
stringData:
LLM_API_KEY: "<API_KEY>"
- apiVersion: apps/v1
kind: Deployment
metadata:
name: kb-customer-service
spec:
replicas: 3
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
selector:
matchLabels:
app: kb-customer-service
template:
metadata:
labels:
app: kb-customer-service
spec:
containers:
- name: api
image: kb-cs:1.0
ports:
- containerPort: 8080
envFrom:
- configMapRef:
name: kb-cs-config
- secretRef:
name: kb-cs-secret
readinessProbe:
httpGet:
path: /readyz
port: 8080
initialDelaySeconds: 3
periodSeconds: 5
livenessProbe:
httpGet:
path: /livez
port: 8080
initialDelaySeconds: 10
periodSeconds: 10
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "1"
memory: "1Gi"
- apiVersion: v1
kind: Service
metadata:
name: kb-customer-service
spec:
selector:
app: kb-customer-service
ports:
- port: 80
targetPort: 8080
- apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: kb-customer-service
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: kb-customer-service
minReplicas: 3
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70这份配置要求集群已经能拉取 kb-cs:1.0,并已安装可供 HPA 使用的资源指标组件。生产环境应把镜像推送到正式仓库,并将 <API_KEY> 改成真实密钥管理流程,而不是把密钥提交到版本库。
首次应用清单并等待滚动完成:
kubectl apply -f deployment.yaml
kubectl rollout status deployment/kb-customer-service
kubectl get deployment kb-customer-service预期输出
configmap/kb-cs-config created
secret/kb-cs-secret created
deployment.apps/kb-customer-service created
service/kb-customer-service created
horizontalpodautoscaler.autoscaling/kb-customer-service created
deployment "kb-customer-service" successfully rolled out
NAME READY UP-TO-DATE AVAILABLE AGE
kb-customer-service 3/3 3 3 <TIME>若资源已存在,kubectl apply 会显示 configured 或 unchanged;最后一列时间也会随环境变化。
用删除副本验证真正无状态
部署成功不等于已经无状态。最关键的验收是先建立一段会话,再主动删除处理过请求的 Pod,让新请求落到其他副本;如果会话仍能从外部存储恢复,说明副本之间没有隐藏的本地依赖。
同时观察滚动升级:新 Pod 必须先通过 readiness 才进入流量,旧 Pod 再退出。HPA 只解决副本数量,不会自动解决外部 Redis、向量库或模型网关的容量瓶颈,因此扩容前还要为这些共享依赖设置连接池、限流和容量告警。
当“删任意 Pod 不丢会话、滚动期间持续可用、负载升高时副本可扩展”三个条件都成立,这个客服 API 才具备进入生产流量层的基本部署形态。