Docker中文

Docker 最新动态观察：容器平台正在向 AI Runtime 与开发治理平台演进

Wed, 17 Jun 2026 09:37:46 +0800

截至 2026 年 6 月，Docker 的产品路线已经出现明显变化。相比过去围绕容器构建、分发与本地开发体验的传统叙事，Docker 近期更强调三个方向：

1. AI Agent 的运行时安全治理

2. 软件供应链与基础镜像可信能力

3. 本地开发环境的可审计与可控性

这意味着 Docker 正在从“容器工具链”向“面向 AI 开发时代的运行平台”演进。

一、Docker Desktop 4.77.0 发布，持续强化开发环境控制面

2026 年 6 月 8 日，Docker Desktop 4.77.0 发布。更新点包括：

Logs 视图支持日志导出
Docker Engine 升级至 v29.5.3
Buildx 升级至 v0.34.1
Docker Agent、Docker MCP Gateway、containerd 等组件同步更新
Marketplace 扩展采用固定 manifest digest 进行安装与更新

这些变更说明 Docker 正在持续补强 Desktop 作为“开发控制平面”的属性，而不仅仅是容器运行器。尤其是扩展安装链路的可验证性提升，反映出 Docker 对开发者工作站供应链风险的持续重视。

二、Docker AI Governance 说明 Docker 已将 Agent 安全作为核心命题

2026 年 5 月，Docker 推出 Docker AI Governance。

该能力的核心背景在于：AI Agent 已从代码补全工具，逐步演变为具备执行能力的任务代理。它们可以读写文件、访问网络、调用本地 shell、连接 MCP 工具，甚至接触企业内部凭据。

在这一前提下，开发者终端不再只是个人工作设备，而成为高权限执行环境。Docker AI Governance 试图围绕以下四个维度建立约束：

网络访问策略
文件系统挂载与读写范围限制
凭据暴露面控制
MCP Server 与工具调用治理

这意味着 Docker 试图在容器、开发环境与 AI Agent 之间，建立统一的运行时权限边界。

三、Docker Sandboxes 的重点不是便利，而是失误隔离

Docker 近期也持续强调 Sandboxes 的现实价值，尤其是在 AI 编程助手误执行危险命令的场景下。

典型案例是 Agent 误执行 `rm -rf ~/`，直接删除用户主目录。该案例揭示的问题是：当 Agent 具备真实执行权限时，错误将不再停留在“代码质量”层面，而可能直接上升为“本地环境破坏”。

Docker Sandboxes 的价值在于：

将 Agent 执行环境与宿主机隔离
限制其可访问目录、网络与工具边界
在默认假设模型会犯错的前提下，以工程隔离替代主观信任

这套思路与传统生产环境安全设计一致，本质上是把最小权限原则引入 AI 开发工作流。

四、Docker Hardened Images 持续补强企业供应链安全能力

2026 年 6 月 11 日，Docker 宣布 Docker Hardened Images 与 Aikido 的漏洞扫描集成增强，重点是支持 VEX 信息。

VEX 的意义在于，可以区分“存在于 SBOM 中”与“真实可利用”的漏洞，从而降低大量误报对企业安全团队的干扰。

这说明 Docker Hardened Images 的价值不只在于镜像瘦身，更在于：

降低基础镜像攻击面
提供更可信的镜像来源
通过 SBOM、VEX 等元数据增强漏洞判断精度
改善企业在 DevSecOps 流程中的风险优先级决策

对企业用户而言，这比单纯的镜像体积优化更有实际意义。

五、Copy Fail 漏洞再次提醒：容器安全仍以宿主机安全为基础

2026 年 5 月 27 日，Docker 针对 Linux 内核漏洞 CVE-2026-31431（Copy Fail）发布缓解建议。

Docker 的建议包括：

升级 Docker Engine 至 v29.4.3 或更高版本
优先应用宿主机内核补丁
在发行版尚未发布修复时，先通过 Engine 升级降低风险暴露

这一事件再次证明：容器隔离能力并非脱离宿主机内核独立存在。Docker 安全能力的上限，仍然受 Linux 内核与相关安全机制约束。

六、总结

从近期动作来看，Docker 的定位正在发生明显变化。其产品叙事已经从“容器化工具链”逐步延伸到以下几个层面：

AI Agent Runtime
本地开发环境治理
MCP 工具权限控制
软件供应链与可信镜像
企业级研发安全平台

因此，Docker 的下一阶段竞争力，未必只体现在容器技术本身，而更可能体现在它能否成为企业接入 AI 编程与自动化研发流程时的标准运行底座。

资料来源：

Docker Desktop 4.77.0 Release Notes

https://docs.docker.com/desktop/release-notes/

Docker AI Governance

https://www.docker.com/blog/docker-ai-governance-unlock-agent-autonomy-safely/

Docker Hardened Images + Aikidohttps://www.docker.com/blog/docker-hardened-images-enhanced-vulnerability-scanning-with-docker-and-aikido/

Docker Sandboxes and AI Agent Incident

https://www.docker.com/blog/coding-agent-horror-stories-the-rm-rf-incident/

CVE-2026-31431 Copy Fail Mitigation

https://www.docker.com/blog/mitigating-cve-2026-31431-copy-fail-in-docker-engine/

免责声明：本文内容来源于网络，所载内容仅供参考。转载仅为学习和交流之目的，如无意中侵犯您的合法权益，请及时联系Docker中文社区！

Docker最新技术观察：漏洞数据库变动，正在影响容器安全治理

Fri, 05 Jun 2026 09:40:06 +0800

最近，Docker 官方发布了一篇面向容器安全团队的技术文章，讨论了一个看起来不像“功能更新”、但实际影响可能不小的话题：NIST 正在调整 NVD（National Vulnerability Database，国家漏洞数据库）的补充信息策略，容器安全体系需要重新评估。

对于长期依赖 CVSS、CPE、CWE 等字段来做漏洞筛选、风险排序和合规检查的团队来说，这不是一次普通的数据源变化，更像是一次方法论提醒：

未来的容器安全，不能只依赖“漏洞数据是否完整”，而要更多回到运行时风险、镜像上下文和实际可利用性本身。

对关注 Docker、Kubernetes、软件供应链安全和 DevSecOps 的同学来说，这篇文章值得认真看一遍。

发生了什么？

根据 Docker 官方文章介绍，2026 年 4 月 15 日，NIST 宣布对 NVD 采用新的优先级补充模式。

简单来说：

大多数 CVE 仍会继续发布。

但并不是所有漏洞都会像过去那样持续附带完整的补充信息。

包括很多团队常用的 CVSS 评分、CPE 映射、CWE 分类，未来覆盖可能不再像过去那样稳定。

这意味着，很多基于这些字段构建起来的自动化安全流程，可能都会受到影响。

如果你的漏洞扫描、准入规则、告警排序、合规报表，严重依赖 NVD 的这些结构化字段，那么现在就该重新检查你的流程设计了。

为什么这件事会影响容器安全？

很多团队做镜像漏洞治理时，表面上是在“扫镜像”，但实际上依赖的是一整套漏洞元数据解释系统。

常见流程大致是这样的：

扫描镜像中的软件包和依赖组件。

将结果映射到 CVE。

再利用 CVSS、CPE、CWE 等字段做分级、归因和规则判断。

最终输出告警、阻断策略、修复优先级或审计结果。

这套方法过去几年几乎成了默认做法。问题在于，它有一个很强的前提：

外部漏洞数据源要足够完整、足够标准、足够持续。

而这次 NVD 的变化，恰恰说明这个前提并不总是成立。

尤其在容器场景里，漏洞管理本来就不只是“有没有这个 CVE”这么简单，还包括：

这个组件是否真的会在运行时被使用。

这个漏洞是否处于可达路径上。

这个问题对当前镜像构建方式是否真正有影响。

这个风险和基础镜像、应用层、运行配置之间是什么关系。

如果过度依赖 NVD 补充字段，团队就很容易把“数据完整”误当成“风险判断准确”。

Docker 这篇文章释放了哪些信号？

1. 漏洞治理不能再只靠 CVSS 分数驱动

很多团队习惯把 CVSS 分数作为修复优先级的主要依据，高分先修、低分靠后，流程上简单直接。

但在容器环境里，这种做法本来就有局限。

一个高分漏洞，如果对应组件并不在实际运行路径中，风险未必真的高；反过来，一个分数不算最高的问题，如果正好处在关键暴露面，影响可能更直接。

这次 Docker 官方文章传递出的一个重要信号就是：

安全团队需要减少对单一评分体系的机械依赖，转而更多结合运行上下文和可利用性来判断风险。

2. CPE 映射不稳定后，很多老式扫描逻辑会更脆弱

很多扫描工具和内部规则引擎，会基于 CPE 做匹配、归类和关联分析。

但如果这类补充数据今后不再稳定，那么很多依赖固定字段的逻辑都可能出现：

漏扫。

误报。

分级不一致。

历史趋势失真。

这对依赖自动化报表、准入门禁和合规流水线的团队来说，影响并不小。

3. 容器安全的重点，正在从“发现更多漏洞”转向“更准确理解风险”

这几年大家已经逐渐意识到，漏洞扫描里的“噪音”问题越来越严重。

镜像越复杂、依赖越多，扫描结果越容易失控。很多团队其实并不缺告警，缺的是能支撑决策的高质量判断。

从这个角度看，NVD 的变化虽然会带来短期不适，但也可能倒逼整个行业往更务实的方向走：

少一点字段依赖，多一点上下文分析。

对 Docker / Kubernetes 团队意味着什么？

如果你所在团队正在维护容器平台、Kubernetes 集群或者镜像供应链，建议重点检查以下几个方面。

一是检查你的漏洞处理流程，是否过度依赖 NVD 补充字段

如果你的分级规则、阻断条件、例外审批、合规证明严重依赖 CVSS、CPE、CWE 的完整性，那就需要尽快评估替代方案或补充判断机制。

二是重新审视“镜像安全”到底在解决什么问题

很多时候，团队陷入的是“漏洞数量治理”，而不是“真实风险治理”。

如果指标只剩下“高危多少个、严重多少个”，却没有结合镜像用途、服务暴露面、运行权限和依赖上下文，那么治理质量其实并不高。

三是把镜像上下文和运行时视角纳入判断链路

安全不应该只停留在静态包扫描，还应该结合：

镜像构成。

实际运行组件。

可达攻击面。

构建来源可信度。

修复路径是否可执行。

对于 Kubernetes 场景尤其如此，因为很多问题并不是“镜像里有漏洞”本身，而是“漏洞出现在什么样的工作负载里”。

写在最后

对 Docker 和 Kubernetes 社区来说，这篇 Docker 官方文章的价值，不在于给出一个立刻可套用的工具答案，而在于指出了一个必须正视的趋势：

当漏洞数据库的补充信息不再像过去那样稳定时，安全团队需要升级自己的判断方法。

如果你的团队今天还主要依赖“扫出多少 CVE、按多少分处理、报多少高危”来管理容器风险，那么现在可能正是一个重新校准方法的时候。

你怎么看这次 NVD 补充策略变化？在你的团队里，漏洞治理更依赖评分，还是更依赖运行上下文判断？欢迎留言交流。

参考来源：Docker 官方博客《NIST Narrows the NVD: What Container Security Programs Should Reassess》
发布日期：2026 年 5 月 13 日
官网：https://www.docker.com/blog/

（版权归原作者所有，侵删）

免责声明：本文内容来源于网络，所载内容仅供参考。转载仅为学习和交流之目的，如无意中侵犯您的合法权益，请及时联系Docker中文社区！

建议收藏：Kubernetes 生产环境 10 大高频故障排查实战

Fri, 15 May 2026 09:46:37 +0800

Kubernetes 在测试环境里，往往表现得很稳定；可一旦进入生产环境，随着业务规模扩大、应用数量增多、节点运行时间拉长，各种问题就会陆续冒出来。

有些故障表面看只是一个 Pod 起不来，背后却可能牵涉到调度器、容器运行时、网络、存储、DNS，甚至控制面本身。
如果没有一套稳定的排查思路，遇到问题时就很容易陷入“到处看日志、四处改配置、越改越乱”的状态。

其实，大多数 Kubernetes 问题都有比较固定的定位路径：

先看状态，再看 Events；先缩小范围，再查日志；最后再回到配置本身。

本文结合生产环境中的典型案例，整理出 10 个最常见的 Kubernetes 高频故障场景，覆盖：

Pod Pending
CrashLoopBackOff
Service 无法访问
镜像拉取失败
Node NotReady
存储卷挂载异常
资源限制与驱逐
etcd 故障
DNS 解析异常
权限与安全上下文问题

如果你平时负责 Kubernetes 集群运维，这篇文章建议直接收藏，关键时刻真能省不少时间。

一、先记住一条通用排障思路

很多人排查 Kubernetes 故障时，上来就改 YAML，或者只盯着 Pod 状态不放。
实际上，更高效的顺序应该是：

1）先看对象状态

先搞清楚出问题的是谁：

Pod 异常
Node 异常
PVC 异常
Service 不通
CoreDNS 异常
控制面异常

常用命令：

kubectl get pods -A
kubectl get nodes
kubectl get svc -A
kubectl get pvc -A

2）再看 describe 和 Events

绝大多数常见问题，都会在事件里留下线索。
尤其是调度失败、挂载失败、探针失败、镜像拉取失败，先看 Events 往往比先翻日志更高效。

kubectl describe pod -n <namespace> <pod-name>
kubectl describe node <node-name>
kubectl describe pvc -n <namespace> <pvc-name>

3）再看相关组件日志

如果事件只能告诉你“失败了”，但原因仍然不够清楚，就继续下钻到组件：

kubelet
containerd
kube-proxy
CoreDNS
CSI
etcd

4）最后回到配置本身

等故障范围缩小以后，再去核对：

资源配置
标签和选择器
镜像地址
探针
安全上下文
存储配置
网络策略

这套方法很朴素，但真正在生产环境里非常有效。

二、问题 1：Pod 一直处于 Pending 状态

问题现象

Pod 创建后长时间停留在 Pending，始终没有进入 Running。

常见场景

新部署的应用起不来
扩容后副本仍调度失败
集群资源紧张时无法重新调度

排查思路

Pending 往往表示 Pod 还没有进入正常运行阶段。
最常见的原因主要有三类：

调度器找不到可用节点
Pod 被污点、亲和性或资源约束挡住了
PVC 未成功绑定，导致 Pod 无法继续推进

排查步骤

先看 Pod 详情

kubectl get pod -n <namespace> <pod-name> -o wide
kubectl describe pod -n <namespace> <pod-name>

重点看 Events。例如：

Warning  FailedScheduling  default-scheduler  0/5 nodes are available: 1 Insufficient cpu, 3 node(s) had taints that the pod didn't tolerate.

再看节点资源

kubectl top nodes
kubectl describe node <node-name>
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.allocatable.cpu}{" CPU\t"}{.status.allocatable.memory}{"\t"}{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}'

重点关注 Allocatable，不要只看机器总资源。

检查污点

kubectl get node -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

检查 PVC 状态

kubectl get pvc -n <namespace>
kubectl describe pvc -n <namespace> <pvc-name>

常见根因与修复

1）资源不足

常见报错：

Insufficient cpu
Insufficient memory

处理方式：

扩容节点
降低 Pod 的 requests
优化资源占用
清理低优先级工作负载

resources:
requests:
memory:"128Mi"
cpu:"100m"
limits:
memory:"256Mi"
cpu:"200m"

2）节点污点限制

临时处理可以移除污点：

kubectl taint node <node-name> key=value:NoSchedule-

更稳妥的方式是在 Pod 里增加容忍：

tolerations:
-key:"key"
operator:"Exists"
effect:"NoSchedule"

3）PVC 绑定失败

重点检查：

StorageClass 是否存在
PV / PVC 是否匹配
CSI 驱动是否正常
存储后端是否可达

验证方法

kubectl get pod -n <namespace> <pod-name> -w

风险提示

移除节点污点会改变整个节点的调度行为，操作前先确认该节点是否承担专用角色。

三、问题 2：Pod 一直处于 CrashLoopBackOff 状态

问题现象

Pod 能调度到节点，但容器启动后很快退出，并反复重启。

常见场景

新版本上线后立即崩溃
依赖服务未就绪导致应用退出
健康检查过严，容器还没启动完就被杀掉

排查思路

CrashLoopBackOff 的核心不是“起不来”，而是：

容器启动了，但启动后很快崩了。

重点看这 5 个方向：

退出码
崩溃前日志
启动命令
外部依赖
健康检查

排查步骤

看退出信息

kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.status.containerStatuses[*]}{"\n"}'
kubectl describe pod -n <namespace> <pod-name> | grep -A 20 "Last State"

看上一次崩溃日志

kubectl logs -n <namespace> <pod-name> --previous

看启动命令和环境变量

kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.containers[*].command}'
kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.containers[*].args}'
kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.containers[*].env}'

看探针配置

kubectl describe pod -n <namespace> <pod-name> | grep -A 5 "Liveness"
kubectl describe pod -n <namespace> <pod-name> | grep -A 5 "Readiness"
kubectl describe pod -n <namespace> <pod-name> | grep -A 5 "Startup"

测试依赖连通性

kubectl exec -it -n <namespace> <pod-name> -- nc -zv <service-name> 3306
kubectl exec -it -n <namespace> <pod-name> -- nslookup <service-name>

常见根因与修复

1）启动命令错误

command: ["/bin/sh", "-c"]
args: ["node app.js && sleep infinity"]

2）依赖服务不可达

数据库、Redis、MQ 等依赖异常时，应用常常直接退出。

3）ConfigMap / Secret 缺失

kubectl get configmap -n <namespace> <configmap-name>
kubectl get secret -n <namespace> <secret-name>

4）目录权限不足

kubectl exec -it -n <namespace> <pod-name> -- ls -la /data
kubectl exec -it -n <namespace> <pod-name> -- id

5）探针过早失败

更合理的做法是给启动较慢的应用配置 startupProbe：

startupProbe:
httpGet:
path:/healthz
port:8080
failureThreshold:30
periodSeconds:10

验证方法

kubectl get pod -n <namespace> <pod-name> -w
kubectl exec -it -n <namespace> <pod-name> -- ps aux

回滚方案

kubectl rollout undo deployment <deployment-name> -n <namespace>
kubectl rollout status deployment <deployment-name> -n <namespace>

四、问题 3：Pod 无法通过 Service 访问

问题现象

Pod 之间通过 Service 名称访问失败，curl 超时，或者 Ingress 流量无法转发到后端。

排查思路

Service 通信链路通常可以拆成三层：

DNS 解析
Service 到后端的转发
后端 Pod 端口监听

排查步骤

确认对象存在

kubectl get pod -n <namespace> -o wide
kubectl get svc -n <namespace> <svc-name>

从其他 Pod 发起访问测试

kubectl exec -it -n <namespace> <source-pod> -- curl -v http://<svc-name>:<port>/

检查 Endpoints 和 EndpointSlice

kubectl get endpoints -n <namespace> <svc-name>
kubectl get endpointslice -n <namespace> -l kubernetes.io/service-name=<svc-name>
kubectl describe svc -n <namespace> <svc-name>

如果 Endpoints 为空，说明 Service 没匹配到后端。

检查 kube-proxy

kubectl get pod -n kube-system -l k8s-app=kube-proxy -o wide
kubectl logs -n kube-system <kube-proxy-pod> --tail=100

测试 ClusterIP

kubectl exec -it -n <namespace> <source-pod> -- curl -v http://<cluster-ip>:<port>/

必要时到节点侧看规则

登录节点执行：

iptables -t nat -L -n | grep <cluster-ip>
ipvsadm -Ln

常见根因与修复

1）selector 不匹配

kubectl get pod -n <namespace> --show-labels

2）Pod 没 Ready

Service 默认不会把未 Ready 的 Pod 加进后端。

3）kube-proxy 异常

kubectl delete pod -n kube-system -l k8s-app=kube-proxy

4）DNS 异常

kubectl exec -it -n <namespace> <pod-name> -- nslookup <svc-name>
kubectl exec -it -n <namespace> <pod-name> -- cat /etc/resolv.conf

5）NetworkPolicy 阻断

kubectl get networkpolicy -n <namespace>
kubectl describe networkpolicy -n <namespace> <policy-name>

风险提示

重启 kube-proxy 和修改 NetworkPolicy 都可能影响业务流量，生产环境必须分批观察。

五、问题 4：镜像拉取失败

问题现象

Pod 调度成功，但镜像下载失败，状态显示 ImagePullBackOff 或 ErrImagePull。

排查思路

这类问题通常集中在 4 个方向：

镜像地址写错
tag 不存在
认证失败
节点到仓库网络或 TLS 异常

排查步骤

看事件

kubectl describe pod -n <namespace> <pod-name> | grep -A 15 "Events"

节点侧手动拉取测试

crictl pull <registry>/<image>:<tag>
ctr -n k8s.io images pull <registry>/<image>:<tag>

检查镜像仓库认证

kubectl get secret -n <namespace>
kubectl describe secret -n <namespace> <registry-secret-name>

检查仓库网络与证书

curl -I https://<registry>/v2/

常见根因与修复

1）镜像地址或 tag 错误

最常见，也最容易忽略。

2）认证凭据错误

kubectl create secret docker-registry <secret-name> \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<password> \
  --docker-email=<email> \
  -n <namespace>

Pod 里引用：

spec:
imagePullSecrets:
-name:<secret-name>

3）TLS 证书不被信任

私有仓库常见问题是内部 CA 没有安装到节点信任链里。

4）节点网络不通

例如 DNS 不通、防火墙阻断、代理配置缺失。

验证方法

kubectl delete pod -n <namespace> <pod-name>
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20

风险提示

删除 Pod 前先确认副本数是否足够，避免直接影响线上流量。

六、问题 5：Node 变成 NotReady

问题现象

节点状态显示 NotReady，新 Pod 无法继续调度到该节点。

排查思路

优先排查这 4 个方向：

kubelet 是否正常
containerd 是否正常
系统资源是否耗尽
节点与 API Server 是否连通

排查步骤

看节点状态

kubectl get nodes
kubectl describe node <node-name>
kubectl get node <node-name> -o jsonpath='{.status.conditions[*]}'

登录节点检查 kubelet

systemctl status kubelet
journalctl -u kubelet -n 100 --no-pager

检查系统资源

free -h
df -h
top -bn1 | head -20

检查 containerd

systemctl status containerd

检查与 API Server 连通性

ping <api-server-ip>
curl -k https://<api-server-ip>:6443/healthz

检查 kubelet 证书

openssl x509 -in /var/lib/kubelet/pki/kubelet-client-current.pem -noout -dates
openssl x509 -in /var/lib/kubelet/pki/kubelet-server-current.pem -noout -dates

常见根因与修复

1）kubelet 异常

systemctl restart kubelet

2）磁盘或内存耗尽

journalctl --vacuum-size=500M
crictl image prune

3）containerd 异常

systemctl restart containerd
systemctl restart kubelet

4）节点到控制面网络不通

重点查路由、防火墙、安全组和 LB 配置。

隔离与恢复

如果一时修不好，先隔离节点：

kubectl cordon <node-name>
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

恢复后再：

kubectl uncordon <node-name>

七、问题 6：存储卷挂载异常

问题现象

PVC 长期 Pending
Pod 启动后无法读写数据目录
有状态服务无法正常挂载卷

排查思路

重点检查四层链路：

StorageClass
PVC
PV
CSI 驱动 / 存储后端

排查步骤

看 PVC

kubectl get pvc -n <namespace>
kubectl describe pvc -n <namespace> <pvc-name>

看 PV

kubectl get pv
kubectl describe pv <pv-name>

看 StorageClass

kubectl get storageclass
kubectl describe storageclass <sc-name>

看 CSI

kubectl get pod -n kube-system | grep csi
kubectl logs -n kube-system <csi-driver-pod> --tail=100
kubectl get csidrivers

到节点检查挂载

登录节点执行：

mount | grep <pv-name>
df -h | grep <mount-path>

常见根因与修复

1）StorageClass 不存在或 provisioner 错误

2）PVC 与 PV 不匹配

3）CSI 驱动异常

kubectl delete pod -n kube-system <csi-driver-pod>

4）节点无法访问存储后端

比如 NFS：

showmount -e <nfs-server>

5）目录权限不匹配

securityContext:
fsGroup:2000
runAsUser:1000

验证方法

kubectl exec -it -n <namespace> <pod-name> -- sh -c "echo test > /data/test.txt && cat /data/test.txt"

风险提示

删除 PVC 可能导致数据永久丢失，生产环境必须先确认备份。

八、问题 7：资源限制或节点压力导致 Pod 异常

问题现象

Pod 被杀掉、被驱逐，或者根本创建失败。
常见表现包括：

OOMKilled
Evicted
ResourceQuota 超限

排查思路

这类问题要分开看：

OOMKilled：通常是容器超过内存 limit
Evicted：通常是节点压力触发驱逐
创建失败：通常是 quota / limitrange 限制

排查步骤

kubectl get pod -n <namespace>
kubectl describe pod -n <namespace> <pod-name>
kubectl get resourcequota -n <namespace>
kubectl describe resourcequota -n <namespace>
kubectl get limitrange -n <namespace>
kubectl describe limitrange -n <namespace>
kubectl top pod -n <namespace>
kubectl top nodes
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -30

常见根因与修复

1）内存 limit 太小

resources:
requests:
memory:"512Mi"
limits:
memory:"1Gi"

2）节点资源压力

如果是 Evicted，不要只盯 Pod，更要看节点层面的容量。

3）命名空间配额耗尽

可以适当调整：

apiVersion:v1
kind:ResourceQuota
metadata:
name:increase-quota
spec:
hard:
requests.cpu:"20"
requests.memory:40Gi
limits.cpu:"40"
limits.memory:80Gi

4）LimitRange 默认限制不合理

很多应用一上线就 OOM，问题根本不在代码，而在命名空间默认 limit 太小。

九、问题 8：etcd 集群故障

问题现象

kubectl 请求超时
API Server 不稳定
控制面整体异常

排查思路

etcd 出问题时，表面看起来常常像“整个集群都怪怪的”。
这时优先确认：

etcd 进程是否健康
endpoint 是否健康
member 是否完整
磁盘是否满了
证书是否过期

排查步骤

看 etcd 状态

如果是静态 Pod：

kubectl -n kube-system get pod -l component=etcd -o wide
kubectl -n kube-system logs <etcd-pod> --tail=100

如果是 systemd：

systemctl status etcd
journalctl -u etcd -n 100 --no-pager

看健康状态

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health --cluster

看成员状态

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  member list -w table

看磁盘和证书

df -h /var/lib/etcd
du -sh /var/lib/etcd/*
openssl x509 -in /etc/kubernetes/pki/etcd/server.crt -noout -dates
kubeadm certs check-expiration

常见根因与修复

1）磁盘空间不足

可以先做 defrag：

ETCDCTL_API=3 etcdctl defrag --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

2）成员异常或网络分区

涉及 member remove 时一定要慎重。

3）证书过期

先用：

kubeadm certs check-expiration

确认是否真是证书问题。

风险提示

etcd 是集群最核心的组件之一。涉及成员变更、证书续期、快照恢复前，务必先做备份。

备份示例：

ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-$(date +%F-%H%M).db

十、问题 9：DNS 解析异常

问题现象

Pod 无法通过服务名访问目标服务，nslookup 超时或返回异常结果。

排查思路

DNS 问题优先看三件事：

CoreDNS 是否健康
Pod 的 resolv.conf 是否正确
53 端口流量是否被拦截

排查步骤

看 CoreDNS 状态

kubectl get pod -n kube-system -l k8s-app=kube-dns -o wide
kubectl logs -n kube-system <coredns-pod> --tail=100

起一个测试 Pod 做解析验证

kubectl run -it --rm debug --image=busybox -n default --restart=Never -- nslookup kubernetes.default
kubectl run -it --rm debug --image=busybox -n default --restart=Never -- nslookup <svc-name>.<namespace>.svc.cluster.local

看业务 Pod 的 resolv.conf

kubectl exec -it -n <namespace> <pod-name> -- cat /etc/resolv.conf

看 CoreDNS 配置

kubectl get configmap -n kube-system coredns -o yaml

看网络策略

kubectl get networkpolicy -A

常见根因与修复

1）CoreDNS Pod 异常

kubectl rollout restart deployment coredns -n kube-system

2）上游 DNS 配置错误

3）Headless Service 结果与预期不一致

clusterIP: None 返回的是 Pod IP 列表，不是单个 VIP。

4）NetworkPolicy 阻断 53 端口

这是生产环境里很常见的误伤点。

十一、问题 10：安全上下文导致权限不足

问题现象

应用报 Permission denied，常见表现包括：

无法写目录
无法绑定低位端口
某些系统调用被拒绝

排查思路

在 Kubernetes 1.28 中，重点关注：

securityContext
Pod Security Admission
SELinux / AppArmor / seccomp
宿主机目录权限

排查步骤

kubectl get pod -n <namespace> <pod-name> -o yaml | grep -A 30 securityContext
kubectl describe pod -n <namespace> <pod-name>
kubectl get ns <namespace> --show-labels
kubectl exec -it -n <namespace> <pod-name> -- id
kubectl exec -it -n <namespace> <pod-name> -- ls -la /data

节点侧检查：

getenforce
apparmor_status

seccomp 检查：

kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.seccompProfile}'
kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.containers[*].securityContext.seccompProfile}'

常见根因与修复

1）非 root 用户无法写目录

推荐修目录权限，而不是直接切 root：

securityContext:
runAsUser:1000
fsGroup:1000
initContainers:
-name:fix-permission
image:busybox
command: ["sh", "-c", "chown -R 1000:1000 /data"]

2）缺少能力绑定低位端口

securityContext:
capabilities:
drop: ["ALL"]
add: ["NET_BIND_SERVICE"]

3）只读根文件系统与应用行为冲突

4）命名空间安全策略限制

风险提示

不要轻易把容器改成 privileged: true 或 runAsUser: 0，生产环境应尽量遵循最小权限原则。

十二、10 大高频问题排查矩阵

问题现象	首选排查命令	常见根因
Pod Pending	`kubectl describe pod`	资源不足、污点、PVC 未绑定
CrashLoopBackOff	`kubectl logs --previous`	启动命令错误、依赖不可达、探针失败
Service 不通	`kubectl get endpoints`	selector 不匹配、Pod 未 Ready、kube-proxy 异常
镜像拉取失败	`kubectl describe pod`	镜像不存在、认证失败、TLS/网络问题
Node NotReady	`systemctl status kubelet`	kubelet 异常、containerd 故障、磁盘满
存储卷异常	`kubectl describe pvc`	StorageClass/CSI/权限问题
OOM / Evicted / 配额失败	`kubectl describe pod`	limit 不合理、节点压力、Quota 超限
etcd 故障	`etcdctl endpoint health`	磁盘满、证书过期、成员异常
DNS 异常	`nslookup` + CoreDNS 日志	CoreDNS 异常、配置错误、策略阻断
权限不足	`kubectl describe pod` + `securityContext`	runAsUser、capabilities、PSA 限制

十三、建议长期保留的一份巡检清单

# 节点健康
kubectl get nodes -o wide
kubectl top nodes

# 异常 Pod
kubectl get pods -A | egrep -v 'Running|Completed'
kubectl get pods -A | grep -i Evicted

# 资源配额
kubectl get resourcequota -A
kubectl get limitrange -A

# 存储状态
kubectl get pvc -A
kubectl get pv

# 核心组件
kubectl get pods -n kube-system

# 最近事件
kubectl get events -A --sort-by='.lastTimestamp' | tail -50

如果条件允许，建议同时对以下指标配置监控告警：

Node NotReady
Pod 重启次数异常
Pending Pod 数量
PVC Pending 数量
CoreDNS 错误率
etcd 延迟与空间使用率
镜像拉取失败次数

十四、写在最后

Kubernetes 的问题之所以让人觉得“复杂”，很多时候并不是因为它真的无从下手，而是因为故障表象和真实根因之间隔了几层。

一个 Pod 起不来，可能是资源问题；
一个 Service 不通，可能是 DNS、selector、探针，甚至网络策略；
一次 API 超时，背后也可能不是 apiserver 本身，而是 etcd 已经开始出问题。

所以，排障最怕的不是问题复杂，而是没顺序。
只要记住这条主线：

先看状态，再看 Events；先缩小范围，再查日志；最后回到配置。

大部分生产环境里的常见故障，基本都能更快收敛。

如果你也在维护 Kubernetes 集群，建议把这篇文章先收藏起来。
很多问题平时看着不常见，但真到线上出故障的时候，能不能第一时间找到排查路径，差别会非常大。

你在生产环境里踩过最离谱的 Kubernetes 坑是什么？欢迎留言聊聊。

（版权归原作者所有，侵删）

免责声明：本文内容来源于网络，所载内容仅供参考。转载仅为学习和交流之目的，如无意中侵犯您的合法权益，请及时联系Docker中文社区！

打造生产级 Nginx 高性能体系：反向代理、负载均衡与缓存优化实践

Mon, 27 Apr 2026 09:54:34 +0800

一、概述

1.1 背景介绍

Nginx 1.26.x 是当前 mainline 分支的最新稳定线，在 HTTP/3 支持、动态模块加载和内存管理上相比 1.24.x 有明显改进。1.24.x 已进入维护模式，新项目直接选 1.26.x，旧项目建议在下次维护窗口升级。

在现代微服务架构中，Nginx 承担的角色已远超传统 Web 服务器。它是流量入口的第一道关卡：接收外部请求、终止 TLS、执行负载均衡、缓存上游响应、转发到后端服务集群。一个配置不当的 Nginx 实例，即便后端服务性能再好，也会成为整个系统的瓶颈。

高性能配置的核心矛盾在于：默认配置面向通用场景，而生产环境需要针对具体硬件、流量模式和业务特征做定向调优。worker 进程数、连接数上限、缓冲区大小、缓存策略——每一项参数背后都有对应的系统资源约束，盲目调大不会带来性能提升，反而可能引发内存压力或文件描述符耗尽。

1.2 技术特点

Nginx 采用事件驱动的异步非阻塞架构，与 Apache 的 prefork/worker 多进程模型有本质区别：

事件驱动模型：基于 epoll（Linux）/ kqueue（BSD），单个 worker 进程可同时处理数万并发连接，不依赖线程切换
异步非阻塞 I/O：磁盘读写、网络 I/O 均不阻塞 worker 进程，配合 aio threads 可将文件 I/O 卸载到线程池
低内存占用：每个连接消耗约 10-20KB 内存，10000 并发连接约占用 200MB，远低于线程模型
零拷贝传输：sendfile 系统调用直接在内核态完成文件到网络的数据传输，绕过用户态缓冲区
模块化架构：核心功能精简，通过编译时模块或动态模块扩展，避免加载不必要的功能

1.3 适用场景

反向代理：将外部 HTTP/HTTPS 请求转发到内网应用服务器，隐藏后端拓扑，统一入口管理
负载均衡：在多个后端实例间分发流量，支持轮询、加权、IP 哈希、最少连接等策略
静态资源服务：直接服务 CSS/JS/图片等静态文件，性能远超应用服务器
API 网关：结合 Lua（OpenResty）或 njs 模块实现认证、限流、路由等网关功能
缓存加速：缓存上游响应，降低后端压力，提升响应速度
SSL 终止：集中处理 TLS 握手，后端服务使用明文 HTTP，简化证书管理

1.4 环境要求

组件	版本要求	说明
操作系统	Ubuntu 22.04+ / CentOS Stream 8+	CentOS 7 已 EOL，不建议新部署
Nginx	1.26.x mainline	1.24.x stable 可用，1.22.x 及以下避免
OpenSSL	3.0+	支持 TLS 1.3，Ubuntu 22.04 默认满足
CPU	4核+	worker 进程数建议与物理核心数一致
内存	4GB+	缓存配置需预留足够内存，建议 8GB+
磁盘	SSD，50GB+	proxy_cache 路径建议独立挂载点

二、详细步骤

2.1 编译安装与基础调优

2.1.1 编译参数选择

包管理器安装的 Nginx 通常缺少部分高性能模块，生产环境建议从源码编译以获得完整控制权。

# /opt/scripts/build-nginx.sh - Nginx 编译安装脚本
#!/bin/bash
set -euo pipefail

NGINX_VERSION="1.26.2"
BUILD_DIR="/tmp/nginx-build"
INSTALL_PREFIX="/etc/nginx"

# 安装编译依赖
apt-get install -y \
    build-essential \
    libpcre3-dev \
    libssl-dev \
    zlib1g-dev \
    libgd-dev \
    libgeoip-dev

mkdir -p "${BUILD_DIR}"
cd"${BUILD_DIR}"

wget "http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz"
tar -xzf "nginx-${NGINX_VERSION}.tar.gz"
cd"nginx-${NGINX_VERSION}"

./configure \
    --prefix=/etc/nginx \
    --sbin-path=/usr/sbin/nginx \
    --modules-path=/usr/lib64/nginx/modules \
    --conf-path=/etc/nginx/nginx.conf \
    --error-log-path=/var/log/nginx/error.log \
    --http-log-path=/var/log/nginx/access.log \
    --pid-path=/var/run/nginx.pid \
    --with-threads \               # 启用线程池，支持 aio threads
    --with-file-aio \              # 异步文件 I/O，大文件传输性能提升明显
    --with-http_v2_module \        # HTTP/2 支持
    --with-http_v3_module \        # HTTP/3 / QUIC 支持（1.25.0+ 正式支持）
    --with-http_ssl_module \
    --with-http_realip_module \    # 获取真实客户端 IP（CDN/代理场景必须）
    --with-http_stub_status_module \ # 监控状态页
    --with-http_gzip_static_module \ # 预压缩静态文件，避免每次请求重复压缩
    --with-http_cache_purge_module \ # 缓存主动清理（需第三方模块）
    --with-stream \                # TCP/UDP 代理（数据库代理、DNS 负载均衡）
    --with-stream_ssl_module \
    --with-pcre-jit \              # PCRE JIT 加速正则匹配，location 规则多时效果显著
    --with-ld-opt="-Wl,-rpath,/usr/local/lib"

make -j"$(nproc)"
make install

2.1.2 worker 进程与连接数配置

# /etc/nginx/nginx.conf - 主配置文件全局段
user nginx;

# auto 自动检测 CPU 核心数，等价于手动写核心数
# 绑定 worker 到具体 CPU 核心可减少上下文切换，8核机器写 auto
worker_processes auto;
worker_cpu_affinity auto;

# 单个 worker 可打开的最大文件描述符数
# 必须 >= worker_connections * 2（每个连接占用2个fd：客户端+上游）
worker_rlimit_nofile 65536;

# 错误日志级别：生产用 warn，调试用 debug（debug 会产生大量日志，影响性能）
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

# 动态模块加载（如需要）
load_module modules/ngx_http_geoip_module.so;

events {
    # 单 worker 最大并发连接数
    # 总并发 = worker_processes * worker_connections
    # 4核机器设 16384，总并发约 65536
    worker_connections 16384;

    # 使用 epoll（Linux 最高效的 I/O 多路复用）
    use epoll;

    # 允许 worker 一次性接受所有新连接，而非逐个接受
    # 高并发场景下减少系统调用次数，低流量场景意义不大
    multi_accept on;
}

2.1.3 内核参数调优

Nginx 性能上限受内核参数约束，应用层配置再好也无法突破内核限制。

# /etc/sysctl.d/99-nginx-tuning.conf - 内核参数调优
# 修改后执行 sysctl -p /etc/sysctl.d/99-nginx-tuning.conf 生效

# TCP 连接队列长度，默认 128 远不够用，高并发场景必须调大
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535

# 允许 TIME_WAIT 状态的 socket 被新连接复用
# 反向代理场景下大量短连接会产生 TIME_WAIT，不开启会导致端口耗尽
net.ipv4.tcp_tw_reuse = 1

# 系统最大文件描述符数，必须大于 worker_rlimit_nofile * worker_processes
fs.file-max = 1000000

# 网卡接收队列长度，10Gbps 网卡建议调大
net.core.netdev_max_backlog = 65535

# TCP 接收/发送缓冲区，影响大文件传输和高延迟链路性能
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

# 本地端口范围，反向代理向上游发起连接时使用
# 默认 32768-60999，约 28000 个端口，高并发场景可能不够
net.ipv4.ip_local_port_range = 10000 65535

# 应用内核参数并验证
sysctl -p /etc/sysctl.d/99-nginx-tuning.conf

# 验证关键参数
sysctl net.core.somaxconn net.ipv4.tcp_tw_reuse fs.file-max

# 设置系统级文件描述符限制（/etc/security/limits.conf）
echo"nginx soft nofile 65536" >> /etc/security/limits.conf
echo"nginx hard nofile 65536" >> /etc/security/limits.conf

2.2 反向代理配置

2.2.1 upstream 配置与健康检查

# /etc/nginx/conf.d/upstream.conf - upstream 定义文件

upstream backend_api {
    # keepalive 保持与上游的长连接池，避免每次请求重新建立 TCP 连接
    # 值为连接池中保持的空闲连接数，不是最大连接数上限
    # 后端是 HTTP/1.1 应用时，32-64 是合理起点
    keepalive 64;

    # keepalive_requests：单个长连接最多处理的请求数，防止连接老化
    keepalive_requests 1000;

    # keepalive_timeout：空闲连接保持时间
    keepalive_timeout 60s;

    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 weight=2 max_fails=3 fail_timeout=30s;

    # backup 服务器：仅在所有主服务器不可用时启用
    server 10.0.1.14:8080 backup;
}

upstream backend_static {
    # 静态资源服务器，使用最少连接策略
    least_conn;
    keepalive 32;

    server 10.0.1.21:80 weight=1;
    server 10.0.1.22:80 weight=1;
}

2.2.2 proxy_pass 细节

proxy_pass 的 trailing slash 是最常见的配置错误来源。proxy_pass http://backend/ 和 proxy_pass http://backend 行为完全不同：前者会截断 location 前缀，后者保留完整 URI。

# /etc/nginx/conf.d/proxy-detail.conf

server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        # 末尾有斜杠：/api/users -> http://backend/users（截断 /api 前缀）
        # 末尾无斜杠：/api/users -> http://backend/api/users（保留完整路径）
        proxy_pass http://backend_api/;

        # 必须传递 Host，否则后端无法识别虚拟主机
        proxy_set_header Host $host;

        # 传递真实客户端 IP，后端日志和业务逻辑依赖此值
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 使用 HTTP/1.1 与上游通信，keepalive 必须配合此设置
        proxy_http_version 1.1;

        # 清除 Connection 头，防止 keep-alive 信息传递到上游导致连接管理混乱
        proxy_set_header Connection "";

        # 连接超时：Nginx 与上游建立 TCP 连接的超时时间
        # 内网服务设 5s 足够，超过说明上游有问题
        proxy_connect_timeout 5s;

        # 读取超时：等待上游响应的超时时间（两次读操作之间的间隔）
        # 根据业务最慢接口设定，不是总响应时间
        proxy_read_timeout 60s;

        # 发送超时：向上游发送请求的超时时间
        proxy_send_timeout 60s;

        # 缓冲区配置：响应先缓冲到 Nginx，再发给客户端
        # 关闭缓冲（proxy_buffering off）适合 SSE/流式响应
        proxy_buffering on;
        proxy_buffer_size 16k;       # 响应头缓冲区，通常 4k-16k 足够
        proxy_buffers 8 32k;         # 响应体缓冲区数量和大小
        proxy_busy_buffers_size 64k; # 同时向客户端发送的最大缓冲量
    }
}

2.2.3 WebSocket 代理与长连接保持

# /etc/nginx/conf.d/websocket.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
    # 当客户端不发送 Upgrade 头时，Connection 设为 close
    # 避免普通 HTTP 请求被错误地保持为长连接
}

server {
    listen 443 ssl;
    server_name ws.example.com;

    location /ws/ {
        proxy_pass http://backend_ws;

        # WebSocket 升级握手必须的头
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # WebSocket 连接通常长时间保持，读取超时需要设长
        # 或设为 0（永不超时），但要配合心跳机制
        proxy_read_timeout 3600s;

        # 关闭缓冲，WebSocket 消息需要实时传递
        proxy_buffering off;
    }
}

2.2.4 gRPC 反向代理配置

# /etc/nginx/conf.d/grpc.conf

upstream grpc_backend {
    server 10.0.1.11:50051;
    server 10.0.1.12:50051;
    keepalive 32;
}

server {
    listen 443 ssl http2;  # gRPC 依赖 HTTP/2
    server_name grpc.example.com;

    ssl_certificate /etc/nginx/ssl/grpc.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/grpc.example.com.key;

    location / {
        # grpc_pass 替代 proxy_pass，专用于 gRPC 协议
        grpc_pass grpc://grpc_backend;

        # gRPC 错误处理
        error_page 502 = /error502grpc;
    }

    location = /error502grpc {
        internal;
        default_type application/grpc;
        # gRPC 状态码：14 = UNAVAILABLE
        add_header grpc-status 14;
        add_header content-length 0;
        return 204;
    }
}

2.3 负载均衡策略

2.3.1 轮询、加权轮询与 ip_hash

# /etc/nginx/conf.d/lb-strategies.conf

# 默认轮询：请求依次分发到每个 server，适合无状态服务
upstream rr_backend {
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}

# 加权轮询：按 weight 比例分发，适合服务器配置不均的场景
# 下例中 .11 处理 50% 流量，.12 和 .13 各处理 25%
upstream weighted_backend {
    server 10.0.1.11:8080 weight=2;
    server 10.0.1.12:8080 weight=1;
    server 10.0.1.13:8080 weight=1;
}

# ip_hash：同一客户端 IP 始终路由到同一后端
# 实现简单的会话保持，但存在热点问题（大量用户来自同一 NAT IP）
# 不支持与 weight 同时使用（1.26.x 已支持，但行为需验证）
upstream iphash_backend {
    ip_hash;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}

2.3.2 least_conn 与一致性哈希

# /etc/nginx/conf.d/lb-advanced.conf

# least_conn：将请求发送到当前活跃连接数最少的 server
# 适合请求处理时间差异大的场景（如混合快慢接口）
# 比轮询更能避免慢请求堆积在某个 server 上
upstream leastconn_backend {
    least_conn;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
    keepalive 32;
}

# hash：基于自定义 key 的一致性哈希
# 适合缓存场景：相同 URL 始终路由到同一后端，提高后端缓存命中率
# consistent 参数启用一致性哈希，server 增减时只有少量请求重新分配
upstream hash_backend {
    hash $request_uri consistent;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}

# 基于请求头的哈希（适合 API 网关按用户 ID 路由）
upstream user_hash_backend {
    hash $http_x_user_id consistent;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

2.3.3 被动健康检查与主动健康检查

开源版 Nginx 只支持被动健康检查（请求失败后标记 server 不可用），主动健康检查是商业版 Nginx Plus 的功能。开源替代方案是 nginx_upstream_check_module 第三方模块。

# /etc/nginx/conf.d/health-check.conf

upstream backend_with_check {
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 max_fails=3 fail_timeout=30s;

    # max_fails：在 fail_timeout 时间窗口内，失败次数达到此值则标记为不可用
    # fail_timeout：不可用状态持续时间，同时也是统计失败次数的时间窗口
    # 上例：30秒内失败3次，则该 server 被下线30秒后重新尝试

    keepalive 32;
}

# 如果编译了 nginx_upstream_check_module，可配置主动健康检查
# upstream backend_active_check {
#     server 10.0.1.11:8080;
#     server 10.0.1.12:8080;
#     check interval=3000 rise=2 fall=3 timeout=1000 type=http;
#     check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
#     check_http_expect_alive http_2xx http_3xx;
# }

2.3.4 会话保持方案对比

方案	实现方式	优点	缺点	适用场景
ip_hash	客户端 IP 哈希	配置简单，无需后端改造	NAT 环境下负载不均，server 下线时会话丢失	小规模、无 CDN 场景
hash $cookie_session	Cookie 哈希	比 ip_hash 更精准	需要客户端支持 Cookie	有登录态的 Web 应用
sticky cookie（Plus）	Nginx 注入 Cookie	精确绑定，支持 server 下线迁移	商业版功能	企业级有状态应用
应用层共享 Session	Redis/Memcached	彻底无状态，水平扩展	需要改造应用代码	推荐方案，新项目首选

2.4 缓存优化

2.4.1 proxy_cache 配置

# /etc/nginx/nginx.conf - http 段缓存路径定义

http {
    # 缓存路径配置
    # levels=1:2：两级目录结构，避免单目录文件过多影响文件系统性能
    # keys_zone=cache_main:100m：共享内存区名称和大小，100m 约存储 80万个 key
    # max_size=10g：缓存文件总大小上限，超出时 LRU 淘汰
    # inactive=60m：60分钟内未被访问的缓存自动删除
    # use_temp_path=off：直接写入缓存目录，避免跨文件系统 rename 操作
    proxy_cache_path /data/nginx/cache
        levels=1:2
        keys_zone=cache_main:100m
        max_size=10g
        inactive=60m
        use_temp_path=off;

    # 第二个缓存区，用于静态资源（更大的 inactive 时间）
    proxy_cache_path /data/nginx/cache_static
        levels=1:2
        keys_zone=cache_static:50m
        max_size=20g
        inactive=7d
        use_temp_path=off;
}

2.4.2 缓存策略

# /etc/nginx/conf.d/cache-policy.conf

server {
    listen 80;
    server_name www.example.com;

    # API 接口缓存
    location /api/ {
        proxy_pass http://backend_api/;
        proxy_cache cache_main;

        # 缓存 key 设计：包含 scheme、host、URI 和查询参数
        # 如果接口有用户态，需要加入 Cookie 或 Authorization 头
        proxy_cache_key "$scheme$host$request_uri";

        # 不同响应码的缓存时间
        proxy_cache_valid 200 302 10m;  # 成功响应缓存10分钟
        proxy_cache_valid 404 1m;       # 404 缓存1分钟，防止穿透攻击
        proxy_cache_valid any 30s;      # 其他响应码缓存30秒

        # 绕过缓存的条件：有 Cookie 或特定请求头时不使用缓存
        # $cookie_session 非空时，认为是登录用户，不走缓存
        proxy_cache_bypass $cookie_session $http_authorization;
        proxy_no_cache $cookie_session $http_authorization;

        # stale 配置：上游故障时，允许使用过期缓存响应
        # 这是提升可用性的关键配置，避免上游抖动直接影响用户
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

        # 防止缓存击穿：同一 key 只允许一个请求回源，其他请求等待
        proxy_cache_lock on;
        proxy_cache_lock_timeout 5s;

        # 在响应头中暴露缓存状态，便于调试（生产可关闭）
        add_header X-Cache-Status $upstream_cache_status;

        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
    }
}

2.4.3 静态文件缓存与 expires/Cache-Control

# /etc/nginx/conf.d/static-cache.conf

server {
    listen 80;
    server_name static.example.com;
    root /var/www/static;

    # 带哈希指纹的静态资源（如 app.a1b2c3d4.js）可永久缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        # 浏览器缓存1年，CDN 缓存1年
        expires 1y;
        add_header Cache-Control "public, immutable";

        # 开启 gzip 静态压缩（需要预先生成 .gz 文件）
        gzip_static on;

        # sendfile 零拷贝传输，静态文件服务必开
        sendfile on;
        tcp_nopush on;  # 配合 sendfile，批量发送响应头和文件内容
    }

    # HTML 文件不缓存或短时缓存（内容会更新）
    location ~* \.html$ {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # API 响应：私有缓存，不允许 CDN 缓存
    location /api/ {
        proxy_pass http://backend_api;
        add_header Cache-Control "private, no-cache";
    }
}

2.4.4 缓存预热与清理

# /opt/scripts/cache-warm.sh - 缓存预热脚本
#!/bin/bash
set -euo pipefail

NGINX_HOST="http://127.0.0.1"
URL_LIST="/opt/scripts/warm-urls.txt"
CONCURRENCY=10  # 并发预热请求数

warm_cache() {
    local url="$1"
    # 通过 curl 访问触发缓存，-s 静默，-o /dev/null 丢弃响应体
    curl -s -o /dev/null -w "%{http_code} %{url_effective}\n" \
        -H "Host: www.example.com" \
        "${NGINX_HOST}${url}"
}

export -f warm_cache

# 使用 xargs 并发执行预热
cat "${URL_LIST}" | xargs -P "${CONCURRENCY}" -I{} bash -c 'warm_cache "$@"' _ {}

echo"Cache warm-up completed"

# /etc/nginx/conf.d/cache-purge.conf
# 需要编译 ngx_cache_purge 模块

server {
    listen 80;
    server_name cache-admin.internal;

    # 限制只有内网可以访问清理接口
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;

    location ~ /purge(/.*) {
        proxy_cache_purge cache_main "$scheme$host$1";
    }
}

2.5 SSL/TLS 优化

2.5.1 TLS 1.3 配置与密码套件选择

# /etc/nginx/conf.d/ssl-base.conf - SSL 基础配置（include 到各 server 块）

# 只启用 TLS 1.2 和 1.3，TLS 1.0/1.1 已被 RFC 8996 废弃
ssl_protocols TLSv1.2 TLSv1.3;

# TLS 1.2 密码套件：优先 ECDHE（前向保密），禁用 RC4、3DES、MD5
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

# 服务端优先选择密码套件（TLS 1.3 中此设置被忽略）
ssl_prefer_server_ciphers off;

# DH 参数文件，防止 Logjam 攻击
# 生成命令：openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048
ssl_dhparam /etc/nginx/ssl/dhparam.pem;

# 椭圆曲线选择：X25519 性能最好，P-256 兼容性最广
ssl_ecdh_curve X25519:prime256v1:secp384r1;

2.5.2 OCSP Stapling 与会话复用

# /etc/nginx/conf.d/ssl-performance.conf

# SSL 会话缓存：shared 在所有 worker 间共享，10m 约缓存 40000 个会话
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;  # 会话有效期1天，平衡安全性和性能

# TLS 1.3 会话票据（Session Tickets）
# 允许客户端恢复会话，避免完整握手，减少延迟
# 注意：多台 Nginx 需要共享相同的 ticket key，否则跨机器无法复用
ssl_session_tickets off;  # 单机可开启，集群环境需要同步 key 或关闭

# OCSP Stapling：Nginx 主动获取证书吊销状态并缓存
# 客户端无需单独查询 OCSP 服务器，减少握手延迟
ssl_stapling on;
ssl_stapling_verify on;

# 完整证书链（包含中间证书）
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;

# DNS 解析器，用于 OCSP 查询
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;

2.5.3 HTTP/2 与 HTTP/3(QUIC) 启用

# /etc/nginx/conf.d/http2-http3.conf

server {
    # HTTP/2：在 listen 指令中添加 http2 参数（Nginx 1.25.1+ 语法）
    listen 443 ssl;
    http2 on;

    # HTTP/3 / QUIC：基于 UDP，需要 1.25.0+ 且编译了 --with-http_v3_module
    listen 443 quic reuseport;

    server_name www.example.com;

    ssl_certificate /etc/nginx/ssl/www.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/www.example.com.key;

    include /etc/nginx/conf.d/ssl-base.conf;
    include /etc/nginx/conf.d/ssl-performance.conf;

    # 告知客户端支持 HTTP/3，浏览器下次请求会尝试 QUIC
    add_header Alt-Svc 'h3=":443"; ma=86400';

    # HSTS：强制浏览器使用 HTTPS，max-age 建议至少 6个月
    add_header Strict-Transport-Security "max-age=15768000; includeSubDomains" always;

    location / {
        proxy_pass http://backend_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
    }
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name www.example.com;
    return 301 https://$host$request_uri;
}

三、示例代码和配置

3.1 完整的生产级 nginx.conf

# /etc/nginx/nginx.conf - 生产级主配置文件

user nginx;
worker_processes auto;
worker_cpu_affinity auto;
worker_rlimit_nofile 65536;

error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 16384;
    use epoll;
    multi_accept on;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # 自定义日志格式，包含响应时间和上游信息，便于性能分析
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    'rt=$request_time uct=$upstream_connect_time '
                    'uht=$upstream_header_time urt=$upstream_response_time';

    access_log /var/log/nginx/access.log main buffer=32k flush=5s;

    # 零拷贝文件传输，静态文件服务必开
    sendfile on;

    # sendfile 开启后才有效：将多个小包合并成一个 TCP 包发送，减少网络开销
    tcp_nopush on;

    # 禁用 Nagle 算法，减少小包延迟，对实时性要求高的场景有效
    tcp_nodelay on;

    # 客户端连接保持时间，65s 是经验值，CDN 场景可适当调长
    keepalive_timeout 65;
    keepalive_requests 1000;

    # 隐藏 Nginx 版本号，减少信息泄露
    server_tokens off;

    # 客户端请求体大小限制，防止大文件上传耗尽内存
    client_max_body_size 100m;
    client_body_buffer_size 128k;

    # 请求头缓冲区，大 Cookie 或 JWT Token 场景需要调大
    client_header_buffer_size 4k;
    large_client_header_buffers 4 16k;

    # Gzip 压缩配置
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;       # 1-9，6 是压缩率和 CPU 消耗的平衡点
    gzip_min_length 1024;    # 小于 1KB 的响应不压缩，压缩收益低于开销
    gzip_types text/plain text/css text/xml text/javascript
               application/json application/javascript application/xml
               application/rss+xml application/atom+xml image/svg+xml;

    # 线程池：将阻塞的文件 I/O 操作卸载到独立线程，避免阻塞 worker
    thread_pool default threads=32 max_queue=65536;

    # 缓存区域定义（供各 server 块引用）
    proxy_cache_path /data/nginx/cache
        levels=1:2
        keys_zone=cache_main:100m
        max_size=10g
        inactive=60m
        use_temp_path=off;

    include /etc/nginx/conf.d/*.conf;
}

3.2 多站点反向代理 + 负载均衡完整配置

# /etc/nginx/conf.d/production.conf - 生产多站点配置

# API 服务集群
upstream api_cluster {
    least_conn;
    keepalive 64;
    keepalive_requests 1000;
    keepalive_timeout 60s;

    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 weight=2 max_fails=3 fail_timeout=30s;
    server 10.0.1.14:8080 backup;
}

# 静态资源服务器
upstream static_cluster {
    server 10.0.1.21:80;
    server 10.0.1.22:80;
    keepalive 32;
}

# API 网关
server {
    listen 443 ssl;
    http2 on;
    listen 443 quic reuseport;
    server_name api.example.com;

    ssl_certificate /etc/nginx/ssl/api.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
    include /etc/nginx/conf.d/ssl-base.conf;
    include /etc/nginx/conf.d/ssl-performance.conf;

    add_header Alt-Svc 'h3=":443"; ma=86400';
    add_header Strict-Transport-Security "max-age=15768000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;

    # 限流：每个 IP 每秒最多 100 个请求
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/s;
    limit_req zone=api_limit burst=200 nodelay;

    location /api/v1/ {
        proxy_pass http://api_cluster/;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 5s;
        proxy_read_timeout 30s;
        proxy_send_timeout 30s;

        # 启用缓存（GET 请求）
        proxy_cache cache_main;
        proxy_cache_key "$scheme$host$request_uri";
        proxy_cache_valid 200 5m;
        proxy_cache_valid 404 1m;
        proxy_cache_bypass $http_cache_control;
        proxy_no_cache $http_pragma $http_authorization;

        # 缓存命中状态头，便于调试
        add_header X-Cache-Status $upstream_cache_status;
    }

    # 健康检查端点不缓存
    location /health {
        proxy_pass http://api_cluster;
        proxy_cache off;
        access_log off;
    }
}

# 静态资源站点
server {
    listen 443 ssl;
    http2 on;
    server_name static.example.com;

    ssl_certificate /etc/nginx/ssl/static.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/static.example.com.key;
    include /etc/nginx/conf.d/ssl-base.conf;

    location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2|svg)$ {
        proxy_pass http://static_cluster;
        proxy_cache cache_main;
        proxy_cache_valid 200 7d;

        # 浏览器缓存：静态资源设置长期缓存，配合文件名哈希实现缓存破坏
        expires 30d;
        add_header Cache-Control "public, immutable";

        # 预压缩文件优先（需要 gzip_static 模块）
        gzip_static on;
    }
}

3.3 缓存集群配置示例

# /etc/nginx/conf.d/cache-cluster.conf - 多级缓存配置

# 定义多个缓存区域，按内容类型分离
proxy_cache_path /data/nginx/cache/api
    levels=1:2
    keys_zone=cache_api:50m
    max_size=5g
    inactive=30m
    use_temp_path=off;

proxy_cache_path /data/nginx/cache/static
    levels=1:2
    keys_zone=cache_static:100m
    max_size=20g
    inactive=7d
    use_temp_path=off;

# 缓存锁：防止缓存击穿（多个请求同时穿透到上游）
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_lock_age 5s;

# 后台更新：缓存过期时先返回旧内容，后台异步更新
# 避免缓存过期瞬间大量请求打到上游
proxy_cache_background_update on;

# 上游不可用时使用过期缓存（降级策略）
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

server {
    listen 80;
    server_name cache.example.com;

    location /api/ {
        proxy_pass http://api_cluster;
        proxy_cache cache_api;
        proxy_cache_key "$scheme$host$uri$is_args$args";
        proxy_cache_valid 200 302 5m;
        proxy_cache_valid 404 1m;

        # 忽略上游的 Set-Cookie，防止带 Cookie 的响应被缓存
        proxy_ignore_headers Set-Cookie;
        proxy_hide_header Set-Cookie;

        add_header X-Cache-Status $upstream_cache_status;
        add_header X-Cache-Date $upstream_http_date;
    }

    location /static/ {
        proxy_pass http://static_cluster;
        proxy_cache cache_static;
        proxy_cache_key "$uri";  # 静态资源 key 不含 scheme/host，跨域共享缓存
        proxy_cache_valid 200 7d;
        proxy_cache_use_stale error timeout updating;

        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable";
    }
}

四、最佳实践和注意事项

4.1 最佳实践

4.1.1 性能优化

# /etc/nginx/conf.d/performance.conf - 性能优化配置集合

http {
    # sendfile + tcp_nopush 组合：零拷贝传输 + 批量发送
    # sendfile 让内核直接将文件数据发送到网络，不经过用户态
    sendfile on;
    tcp_nopush on;

    # tcp_nodelay 禁用 Nagle 算法，减少小包延迟
    # 与 tcp_nopush 同时开启时，Nginx 会先积累数据（tcp_nopush），
    # 连接进入 keepalive 状态后再启用 tcp_nodelay 刷新剩余数据
    tcp_nodelay on;

    # 线程池异步文件 I/O，避免磁盘读写阻塞 worker 进程
    # 适合大文件下载场景，小文件场景收益不明显
    aio threads=default;
    aio_write on;

    # 直接 I/O：绕过操作系统页缓存，适合大文件且不需要重复读取的场景
    # 小文件或频繁访问的文件不要开启，会降低性能
    # directio 512;

    # open_file_cache：缓存文件描述符、文件大小和修改时间
    # 避免每次请求都调用 stat() 系统调用
    open_file_cache max=10000 inactive=30s;
    open_file_cache_valid 60s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    # Gzip 压缩：文本内容压缩率通常 60-80%，显著减少传输量
    gzip on;
    gzip_comp_level 6;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_proxied any;
    gzip_types
        text/plain text/css text/xml text/javascript
        application/json application/javascript application/xml
        application/rss+xml application/atom+xml image/svg+xml
        font/truetype font/opentype application/vnd.ms-fontobject;
}

4.1.2 安全加固

# /etc/nginx/conf.d/security.conf - 安全加固配置

server {
    # 隐藏 Nginx 版本号，攻击者无法针对特定版本漏洞
    server_tokens off;

    # 限制请求方法，只允许 GET/POST/HEAD
    if ($request_method !~ ^(GET|POST|HEAD|PUT|DELETE|PATCH|OPTIONS)$) {
        return 405;
    }

    # 防止点击劫持
    add_header X-Frame-Options SAMEORIGIN always;

    # 禁止 MIME 类型嗅探，防止 XSS 攻击
    add_header X-Content-Type-Options nosniff always;

    # XSS 保护（现代浏览器已内置，但旧版浏览器需要此头）
    add_header X-XSS-Protection "1; mode=block" always;

    # 限制请求体大小，防止大文件上传耗尽内存
    client_max_body_size 10m;

    # 限制请求头大小，防止 Header 注入攻击
    large_client_header_buffers 4 8k;

    # 限流：防止暴力破解和 DDoS
    limit_req_zone $binary_remote_addr zone=login_limit:10m rate=5r/m;
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    location /login {
        limit_req zone=login_limit burst=10 nodelay;
        limit_conn conn_limit 5;
        proxy_pass http://backend_api;
    }

    # 禁止访问隐藏文件（.git、.env 等）
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }

    # 禁止访问备份文件
    location ~* \.(bak|conf|dist|fla|inc|ini|log|psd|sh|sql|swp)$ {
        deny all;
    }
}

4.1.3 高可用配置（Keepalived + Nginx 双主）

# /etc/keepalived/keepalived.conf - 主节点（192.168.1.11）配置

vrrp_script check_nginx {
    script "/opt/scripts/check-nginx.sh"
    interval 2    # 每2秒检查一次
    weight -20    # 检查失败时优先级降低20，触发 VIP 漂移
    fall 2        # 连续失败2次才认为服务异常
    rise 2        # 连续成功2次才认为服务恢复
}

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100              # 主节点优先级高于备节点
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass nginx_ha_2024
    }
    virtual_ipaddress {
        192.168.1.100/24      # VIP，对外提供服务的 IP
    }
    track_script {
        check_nginx
    }
}

# /opt/scripts/check-nginx.sh - Nginx 健康检查脚本
#!/bin/bash
set -euo pipefail

# 检查 Nginx 进程是否存在
if ! pgrep -x nginx > /dev/null; then
    # 尝试重启 Nginx
    systemctl start nginx
    sleep 2
    # 重启后再次检查，失败则退出非零状态触发 VIP 漂移
    pgrep -x nginx > /dev/null || exit 1
fi

# 检查 Nginx 是否能正常响应请求
http_code=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1/health)
if [ "${http_code}" != "200" ]; then
    exit 1
fi

exit 0

4.2 注意事项

4.2.1 配置注意事项

proxy_pass 末尾斜杠是最常见的配置错误：proxy_pass http://backend/ 会截断 location 前缀，proxy_pass http://backend 则保留完整 URI。在 location 使用正则表达式时，proxy_pass 不能带 URI 部分（即不能有斜杠后的路径），否则 Nginx 会拒绝启动。

worker_connections 设置的是单个 worker 的连接数上限，包含客户端连接和上游连接。作为反向代理时，每个客户端请求至少占用 2 个连接（客户端 + 上游），实际并发客户端数约为 worker_connections / 2。

proxy_cache_path 的 keys_zone 内存区只存储缓存 key 的索引，不存储缓存内容本身。100m 的 keys_zone 约能存储 80 万个 key，缓存内容存储在磁盘上。

4.2.2 常见错误

错误现象	原因分析	解决方案
502 Bad Gateway	上游服务不可用或连接超时	检查上游服务状态，调整 proxy_connect_timeout
504 Gateway Timeout	上游响应超时	增大 proxy_read_timeout，或优化上游接口性能
413 Request Entity Too Large	请求体超过 client_max_body_size	调大 client_max_body_size 或在上游处理
499 Client Closed Request	客户端在响应前断开连接	通常是客户端超时，检查客户端超时设置
upstream timed out (110)	上游连接超时	检查上游服务负载，调整超时参数
no live upstreams while connecting	所有上游节点不可用	检查上游服务，调整 max_fails/fail_timeout
worker_connections are not enough	连接数耗尽	增大 worker_connections 和 worker_rlimit_nofile
open() failed (24: Too many open files)	文件描述符耗尽	增大 worker_rlimit_nofile 和系统 ulimit

4.2.3 兼容性问题

HTTP/3 (QUIC) 需要防火墙放行 UDP 443 端口，许多企业网络默认封锁 UDP，导致 HTTP/3 降级到 HTTP/2。Alt-Svc 响应头告知浏览器支持 HTTP/3，浏览器会在后续请求中尝试 QUIC，失败后自动回退，不影响功能。

http2 on 指令是 1.25.1 引入的新语法，旧版本使用 listen 443 ssl http2。两种语法不能混用，升级 Nginx 版本后需要统一迁移。

五、故障排查和监控

5.1 故障排查

5.1.1 日志分析

# /etc/nginx/nginx.conf - 自定义日志格式

http {
    # 详细日志格式，包含所有关键性能指标
    log_format detailed '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent" '
                        'rt=$request_time '           # 总请求处理时间
                        'uct=$upstream_connect_time ' # 与上游建立连接时间
                        'uht=$upstream_header_time '  # 收到上游响应头时间
                        'urt=$upstream_response_time ' # 上游响应总时间
                        'cs=$upstream_cache_status '  # 缓存命中状态
                        'ua=$upstream_addr';          # 实际处理请求的上游地址

    # 生产环境使用缓冲写入，减少磁盘 I/O
    access_log /var/log/nginx/access.log detailed buffer=64k flush=10s;

    # 错误日志：warn 级别记录重要错误，不记录 notice/info 级别的噪音
    error_log /var/log/nginx/error.log warn;
}

# 常用日志分析命令

# 统计响应状态码分布
awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn

# 找出响应时间最慢的10个请求
awk '{print $NF, $7}' /var/log/nginx/access.log | sort -rn | head -10

# 统计每分钟请求量（流量趋势）
awk '{print $4}' /var/log/nginx/access.log | cut -d: -f1-3 | uniq -c

# 找出请求量最大的 IP（排查 DDoS）
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20

# 实时监控错误日志
tail -f /var/log/nginx/error.log | grep -E "error|crit|alert|emerg"

5.1.2 常见问题排查

502 Bad Gateway 排查流程：

# 1. 确认上游服务是否存活
curl -v http://10.0.1.11:8080/health

# 2. 检查 Nginx 错误日志中的具体错误信息
tail -100 /var/log/nginx/error.log | grep "upstream"

# 3. 检查上游连接数是否耗尽
ss -s  # 查看 TCP 连接统计
ss -tn state established | grep :8080 | wc -l

# 4. 检查上游服务的文件描述符限制
cat /proc/$(pgrep -f "java")/limits | grep "open files"

连接数耗尽排查：

# 查看当前连接数
ss -s

# 查看 TIME_WAIT 连接数（过多说明短连接频繁）
ss -tn state time-wait | wc -l

# 查看 Nginx worker 打开的文件描述符数
ls /proc/$(pgrep nginx | head -1)/fd | wc -l

# 检查系统文件描述符使用情况
cat /proc/sys/fs/file-nr

5.1.3 调试模式

# /etc/nginx/conf.d/debug.conf - 临时调试配置（生产环境用完立即删除）

# 针对特定 IP 开启 debug 日志，避免全量 debug 影响性能
error_log /var/log/nginx/debug.log debug;

events {
    debug_connection 192.168.1.100;  # 只对此 IP 的连接输出 debug 日志
}

# 测试配置文件语法
nginx -t

# 查看编译参数和模块列表
nginx -V 2>&1 | tr ' ''\n'

# 重载配置（不中断现有连接）
nginx -s reload

# 查看 Nginx 进程树
ps aux | grep nginx

# 实时查看连接状态（需要 stub_status 模块）
curl http://127.0.0.1/nginx_status

5.2 性能监控

5.2.1 stub_status 模块

# /etc/nginx/conf.d/status.conf - 监控状态页

server {
    listen 127.0.0.1:8080;  # 只监听本地，不对外暴露
    server_name localhost;

    location /nginx_status {
        stub_status;
        access_log off;

        # 只允许本机和监控服务器访问
        allow 127.0.0.1;
        allow 10.0.1.0/24;
        deny all;
    }
}

# stub_status 输出示例及含义
# Active connections: 291        # 当前活跃连接数
# server accepts handled requests
#  16630948 16630948 31070465   # 总接受连接数 / 总处理连接数 / 总请求数
# Reading: 6 Writing: 179 Waiting: 106
# Reading: 正在读取请求头的连接数
# Writing: 正在向客户端发送响应的连接数
# Waiting: keepalive 空闲连接数（等待下一个请求）

5.2.2 Prometheus + nginx-exporter 监控

# 安装 nginx-prometheus-exporter
wget https://github.com/nginxinc/nginx-prometheus-exporter/releases/download/v1.3.0/nginx-prometheus-exporter_1.3.0_linux_amd64.tar.gz
tar -xzf nginx-prometheus-exporter_1.3.0_linux_amd64.tar.gz

# 启动 exporter（读取 stub_status 并转换为 Prometheus 格式）
./nginx-prometheus-exporter \
    -nginx.scrape-uri=http://127.0.0.1:8080/nginx_status \
    -web.listen-address=:9113

# /etc/prometheus/rules/nginx.yml - Prometheus 告警规则

groups:
-name:nginx
    rules:
      -alert:NginxHighActiveConnections
        expr:nginx_connections_active>10000
        for:5m
        labels:
          severity:warning
        annotations:
          summary:"Nginx 活跃连接数过高"
          description:"当前活跃连接数 {{ $value }}，超过阈值 10000"

      -alert:NginxHighErrorRate
        # 5xx 错误率超过 5%
        expr:rate(nginx_http_requests_total{status=~"5.."}[5m])/rate(nginx_http_requests_total[5m])>0.05
        for:2m
        labels:
          severity:critical
        annotations:
          summary:"Nginx 5xx 错误率过高"

5.2.3 关键指标与告警阈值

指标名称	正常范围	告警阈值	说明
活跃连接数	< 5000	> 10000	接近 worker_connections 上限时需扩容
请求处理时间	< 200ms	> 1000ms	P99 超过1秒需排查上游或缓存
5xx 错误率	< 0.1%	> 1%	上游服务异常的直接体现
上游响应时间	< 100ms	> 500ms	上游服务性能问题
缓存命中率	> 80%	< 50%	缓存策略需要优化
连接等待数(Waiting)	< 1000	> 5000	keepalive 连接过多，可能需要调小 keepalive_timeout

5.3 备份与恢复

5.3.1 配置备份脚本

# /opt/scripts/nginx-backup.sh - Nginx 配置备份脚本
#!/bin/bash
set -euo pipefail

BACKUP_DIR="/opt/backups/nginx"
NGINX_CONF_DIR="/etc/nginx"
RETENTION_DAYS=30
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/nginx_conf_${TIMESTAMP}.tar.gz"

backup_nginx_config() {
    mkdir -p "${BACKUP_DIR}"

    # 打包 Nginx 配置目录
    tar -czf "${BACKUP_FILE}" \
        --exclude="${NGINX_CONF_DIR}/ssl/*.key" \  # 私钥单独备份，不放在普通备份中
        "${NGINX_CONF_DIR}"

    echo"备份完成：${BACKUP_FILE}"
    echo"备份大小：$(du -sh "${BACKUP_FILE}" | cut -f1)"
}

cleanup_old_backups() {
    # 删除超过保留期的备份文件
    find "${BACKUP_DIR}" -name "nginx_conf_*.tar.gz" \
        -mtime "+${RETENTION_DAYS}" -delete

    echo"已清理 ${RETENTION_DAYS} 天前的备份"
}

verify_backup() {
    # 验证备份文件完整性
    if tar -tzf "${BACKUP_FILE}" > /dev/null 2>&1; then
        echo"备份验证通过"
    else
        echo"备份文件损坏！" >&2
        exit 1
    fi
}

backup_nginx_config
verify_backup
cleanup_old_backups

5.3.2 灰度发布与配置回滚

# /opt/scripts/nginx-deploy.sh - 配置灰度发布脚本
#!/bin/bash
set -euo pipefail

NGINX_CONF_DIR="/etc/nginx"
BACKUP_DIR="/opt/backups/nginx"

deploy_config() {
    local new_config_dir="$1"
    local timestamp
    timestamp=$(date +%Y%m%d_%H%M%S)

    # 备份当前配置
    cp -r "${NGINX_CONF_DIR}""${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}"
    echo"当前配置已备份到：${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}"

    # 复制新配置
    rsync -av --delete "${new_config_dir}/""${NGINX_CONF_DIR}/"

    # 测试新配置语法
    if ! nginx -t; then
        echo"新配置语法错误，回滚..." >&2
        rsync -av --delete "${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}/""${NGINX_CONF_DIR}/"
        exit 1
    fi

    # 热重载（不中断现有连接）
    nginx -s reload
    echo"配置部署成功，已热重载"
}

rollback_config() {
    local backup_path="$1"

    if [ ! -d "${backup_path}" ]; then
        echo"备份目录不存在：${backup_path}" >&2
        exit 1
    fi

    rsync -av --delete "${backup_path}/""${NGINX_CONF_DIR}/"

    if nginx -t && nginx -s reload; then
        echo"回滚成功"
    else
        echo"回滚失败，请手动检查配置" >&2
        exit 1
    fi
}

case"${1:-}"in
    deploy)   deploy_config "${2}" ;;
    rollback) rollback_config "${2}" ;;
    *)        echo"用法：$0 {deploy <config_dir>|rollback <backup_dir>}" ;;
esac

六、总结

6.1 技术要点回顾

worker 配置：worker_processes auto + worker_cpu_affinity auto + worker_rlimit_nofile 65536，三者配合才能充分利用多核并支撑高并发
内核参数：somaxconn、tcp_tw_reuse、file-max 是必须调整的三个参数，不调整会在中等流量下触发瓶颈
反向代理：proxy_http_version 1.1 + proxy_set_header Connection "" + keepalive 是启用上游长连接的完整组合，缺一不可
缓存设计：proxy_cache_use_stale 配置上游降级策略，proxy_cache_lock 防止缓存击穿，proxy_cache_background_update 避免缓存过期时的流量尖刺
TLS 优化：TLS 1.3 + OCSP Stapling + 会话缓存，三者叠加可将 TLS 握手延迟降低 50% 以上

6.2 进阶学习方向

OpenResty / njs：在 Nginx 中嵌入 Lua 或 JavaScript 逻辑，实现 JWT 验证、动态路由、A/B 测试等 API 网关功能，无需引入独立网关组件
Nginx Unit：Nginx 官方的应用服务器，支持动态配置（无需重载），可直接运行 Python/PHP/Node.js 应用，适合替代 uWSGI/Gunicorn
eBPF + Nginx：使用 eBPF 在内核层面监控 Nginx 的网络行为，实现零侵入的性能分析和安全审计

6.3 参考资料

Nginx 官方文档 - 权威参考，指令说明以此为准
Nginx 源码 - 理解内部实现的最直接途径
nginx-prometheus-exporter - 官方 Prometheus 集成
Mozilla SSL Configuration Generator - TLS 配置生成工具，覆盖主流浏览器兼容性

附录

A. 命令速查表

# 配置测试与重载
nginx -t                          # 测试配置文件语法
nginx -T                          # 测试并输出完整配置（含 include 文件）
nginx -s reload                   # 热重载配置（不中断连接）
nginx -s reopen                   # 重新打开日志文件（日志切割后使用）
nginx -s quit                     # 优雅停止（等待现有请求完成）
nginx -s stop                     # 立即停止

# 进程管理
systemctl start nginx             # 启动
systemctl stop nginx              # 停止
systemctl reload nginx            # 重载（等同于 nginx -s reload）
systemctl status nginx            # 查看状态

# 日志分析
tail -f /var/log/nginx/error.log  # 实时查看错误日志
nginx -V 2>&1 | tr ' ''\n'       # 查看编译参数

# 连接状态
ss -tn state established dst :80  # 查看到80端口的连接
ss -s                             # 连接统计摘要
curl http://127.0.0.1/nginx_status # 查看 stub_status

# 缓存管理
find /data/nginx/cache -type f | wc -l  # 统计缓存文件数量
du -sh /data/nginx/cache                # 查看缓存占用空间

B. 配置参数详解

参数	默认值	推荐值	说明
worker_processes	1	auto	worker 进程数，auto 自动匹配 CPU 核数
worker_connections	512	16384	单 worker 最大连接数
worker_rlimit_nofile	系统默认	65536	worker 进程文件描述符上限
keepalive_timeout	75s	65s	客户端 keepalive 超时
proxy_connect_timeout	60s	5s	与上游建立连接超时
proxy_read_timeout	60s	60s	等待上游响应超时
client_max_body_size	1m	10m-100m	请求体大小限制
gzip_comp_level	1	6	压缩级别，6 是性能与压缩率平衡点
proxy_cache_lock	off	on	防止缓存击穿
open_file_cache max	-	10000	文件描述符缓存条目数

C. 术语表

术语	英文	解释
反向代理	Reverse Proxy	代表后端服务接收客户端请求，客户端不直接访问后端
负载均衡	Load Balancing	将流量分发到多个后端实例，提升吞吐量和可用性
上游	Upstream	Nginx 转发请求的目标服务器或服务器组
缓存击穿	Cache Breakdown	热点 key 过期瞬间大量请求同时穿透到上游
缓存穿透	Cache Penetration	请求不存在的数据，每次都穿透缓存打到上游
惊群效应	Thundering Herd	多个进程/线程同时被唤醒竞争同一资源
前向保密	Forward Secrecy	即使私钥泄露，历史会话数据也无法被解密
OCSP 装订	OCSP Stapling	服务端预先获取证书吊销状态并附在 TLS 握手中
零拷贝	Zero-Copy	数据在内核态直接传输，不经过用户态缓冲区
事件驱动	Event-Driven	通过事件通知机制处理 I/O，而非为每个连接分配线程

（版权归原作者所有，侵删）

免责声明：本文内容来源于网络，所载内容仅供参考。转载仅为学习和交流之目的，如无意中侵犯您的合法权益，请及时联系Docker中文社区！

大模型服务稳定性实战：超时、限流、OOM 排查全攻略

Fri, 10 Apr 2026 09:57:30 +0800

一、概述

1.1 背景介绍

大模型服务上线后，最让运维头疼的不是部署——部署有文档照着走就行。真正折腾人的是上线之后各种花式报错：用户反馈"接口超时了"，告警群里跳出"GPU OOM"，API 日志里一堆 429 Too Many Requests。

这三类问题——超时、限流、OOM——占了大模型服务日常故障的 80% 以上。实测在一套跑了 Qwen/Qwen3.5-35B-A3B-FP8 的 vLLM 集群上，上线头两个月的 200 多次告警中，超时占 45%，OOM 占 30%，限流占 15%，其他杂项占 10%。

这篇文章把排查方法论和具体操作步骤都写清楚。不讲理论，直接给命令、给配置、给实际案例。每个错误类型从"看到什么现象"开始，到"怎么定位根因"，再到"怎么解决"，完整链路走一遍。

1.2 技术特点

这篇文章的组织方式：

系统化排错方法论：不是头痛医头脚痛医脚，而是建立一套从症状到根因的判断链
按错误类型分类：超时、限流、OOM、CUDA 错误、模型加载错误，每类独立成章
从症状到根因：先看到什么，再查什么，最后改什么。每一步都给具体命令
覆盖多层排查：客户端 → API 网关 → 推理引擎 → GPU/系统，逐层定位

1.3 适用场景

vLLM 0.8.x 推理服务：目前生产环境用得最多的推理引擎，本文重点覆盖
TGI（Text Generation Inference）：HuggingFace 出品，部分排查方法通用
Ollama：开发测试环境常用，OOM 问题最多
API 网关层：Nginx、Envoy、Kong 等反向代理的超时和限流配置
客户端调用层：Python requests / aiohttp / OpenAI SDK 的超时处理

二、详细步骤

2.1 报错分类体系

大模型服务的报错可以按照五大类来组织。先看清全局，再逐个击破。

大模型服务报错
├── 超时类
│   ├── TTFT 超时（首 token 延迟过高）
│   ├── TPS 下降（生成速度变慢）
│   ├── 连接超时（TCP 握手/HTTP 连接失败）
│   └── 网络超时（请求在网络层丢失）
├── 限流类
│   ├── HTTP 429 Too Many Requests
│   ├── 推理引擎内部队列满
│   └── Token 配额耗尽
├── OOM 类
│   ├── GPU OOM（显存不足）
│   ├── CPU OOM（主机内存不足）
│   └── 容器 OOM Killed（cgroup 限制触发）
├── CUDA 错误类
│   ├── CUDA OOM（和 GPU OOM 有区别）
│   ├── NCCL 通信错误（多卡场景）
│   ├── CUDA device-side assert
│   └── CUDA 版本不兼容
└── 模型加载类
    ├── 权重文件损坏/校验失败
    ├── 显存不足无法加载
    ├── safetensors 格式错误
    └── 磁盘空间不足

下面逐一详解。

2.2 超时问题排查

超时是最常见的问题，也是最容易被误判的。用户说"超时了"，可能是 TTFT 慢、可能是 TPS 低、可能是连接都建不上。第一步要区分到底是哪种超时。

2.2.1 快速区分超时类型

# 用 curl 测试端到端延迟，看各阶段耗时
curl -o /dev/null -s -w "\
  DNS:        %{time_namelookup}s\n\
  Connect:    %{time_connect}s\n\
  TLS:        %{time_appconnect}s\n\
  TTFB:       %{time_starttransfer}s\n\
  Total:      %{time_total}s\n" \
  -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-35B-A3B-FP8","messages":[{"role":"user","content":"hello"}],"max_tokens":50}'

输出示例：

DNS:        0.001s
Connect:    0.002s
TLS:        0.000s
TTFB:       1.234s     ← 这就是 TTFT
Total:      3.456s

判断规则：

Connect > 1s → 连接超时，查网络
TTFB > 5s → TTFT 超时，查推理引擎
Total - TTFB 过大 → TPS 低，生成阶段慢
请求直接失败 → 看错误码，连接拒绝或超时

2.2.2 TTFT 超时排查

TTFT（Time To First Token）是用户发出请求到收到第一个 token 的时间。这个阶段主要是 prefill（预填充），计算量和 prompt 长度成正比。

正常基线（vLLM 0.7.x，单卡 A100 80G，Qwen/Qwen3.5-35B-A3B-FP8）：

Prompt 长度	TTFT 正常值	需要关注	需要告警
100 tokens	100-300ms	500ms+	1s+
1000 tokens	300-800ms	1.5s+	3s+
4000 tokens	1-3s	5s+	10s+
16000 tokens	3-8s	15s+	30s+

原因分析：

KV Cache 碎片化

vLLM 用 PagedAttention 管理 KV Cache，但长时间运行后会产生碎片，导致新请求分配 KV Cache 变慢。

# 检查 vLLM 的 KV Cache 使用情况
curl http://localhost:8000/metrics 2>/dev/null | grep "vllm:gpu_cache_usage_perc"

# 输出示例：
# vllm:gpu_cache_usage_perc 0.87
# 超过 0.9 就要注意了

解决：降低 gpu-memory-utilization 参数，给 KV Cache 更多空间，或者降低 max-num-seqs（最大并发请求数）。

长 Prompt Prefill 慢

Prefill 阶段的计算量和 prompt 长度的平方成正比（attention 计算）。一个 16K token 的 prompt 比 1K token 的 prompt 慢 16 倍不止。

# 监控 prefill 耗时
curl http://localhost:8000/metrics 2>/dev/null | grep "vllm:e2e_request_latency"

解决：

启用 chunked prefill（vLLM 0.7.x 默认启用）
对于超长 prompt，考虑拆分或摘要

GPU 算力不足

同时跑了太多并发请求，GPU 被压满。

# 实时看 GPU 利用率
nvidia-smi dmon -s u -d 1

# 输出字段说明：
# sm: SM 利用率（Streaming Multiprocessor）
# mem: 显存带宽利用率
# enc/dec: 编解码器利用率

# 看到 sm 持续 > 95% 说明 GPU 计算已经打满

解决：横向扩容（加 GPU），或降低 max-num-seqs 限制并发。

调度延迟

请求在 vLLM 的 scheduler 队列中等待时间过长。

# 检查等待队列长度
curl http://localhost:8000/metrics 2>/dev/null | grep "vllm:num_requests_waiting"

# 如果 waiting > 10，说明队列积压了

2.2.3 TPS 下降排查

TPS（Tokens Per Second）是生成阶段每秒输出的 token 数。TPS 下降意味着用户要等更长时间才能拿到完整回复。

正常基线（单卡 A100 80G，Qwen/Qwen3.5-35B-A3B-FP8）：

并发数	单请求 TPS	总 TPS	说明
1	60-80	60-80	单请求性能
10	30-50	300-500	batching 效果明显
50	15-25	750-1250	接近饱和
100	8-15	800-1500	超过最优点，单请求体验下降

原因分析：

Batch 队列满

# 检查当前 batch 中的请求数
curl http://localhost:8000/metrics 2>/dev/null | grep "vllm:num_requests_running"

# running 接近 max-num-seqs 就说明 batch 满了

显存不足触发 swap

vLLM 支持将 KV Cache swap 到 CPU 内存，但 swap 后 TPS 会暴跌。

# 检查 swap 次数
curl http://localhost:8000/metrics 2>/dev/null | grep "vllm:cpu_cache_usage_perc"

# 如果 cpu_cache_usage > 0，说明在 swap

解决：降低 max-num-seqs 或 max-model-len，减少 KV Cache 需求。

GPU 温度降频

A100 在 85°C 以上会自动降频，TPS 直接打折。

# 检查 GPU 温度
nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader,nounits

# 正常工作温度：60-80°C
# > 83°C：开始降频
# > 90°C：严重降频或关机保护

解决：检查散热系统、风扇转速、机房温度。数据中心环境一般不会有这个问题，但用 RTX 4090 的工作站经常遇到。

NUMA 亲和性问题

多路 CPU 服务器上，如果 vLLM 进程和 GPU 不在同一个 NUMA 节点，PCIe 传输走跨 NUMA 路径，带宽减半。

# 查看 GPU 所在 NUMA 节点
nvidia-smi topo -m

# 查看进程的 NUMA 绑定
numactl -s

# 绑定到 GPU 所在 NUMA 节点启动 vLLM
numactl --cpunodebind=0 --membind=0 python -m vllm.entrypoints.openai.api_server ...

2.2.4 连接超时排查

连接超时意味着请求根本没到推理引擎。排查路径是从客户端到服务端逐层检查。

# 第一步：检查服务端口是否在监听
ss -tlnp | grep 8000

# 预期输出：
# LISTEN  0  128  0.0.0.0:8000  0.0.0.0:*  users:(("python",pid=12345,fd=7))

# 如果没有输出，说明 vLLM 没启动或端口不对

# 第二步：检查防火墙
iptables -L -n | grep 8000
# 或者用 firewalld
firewall-cmd --list-all

# 第三步：检查网络连通性
# 从客户端机器测试
telnet <server_ip> 8000
# 或
nc -zv <server_ip> 8000

# 第四步：如果通过反向代理，检查 Nginx/Envoy 状态
curl -I http://localhost:80/v1/models
# 看返回状态码和 upstream 信息

vLLM 服务未就绪的常见原因：

# 检查 vLLM 进程是否存在
ps aux | grep "vllm.entrypoints" | grep -v grep

# 如果进程存在但端口没监听，说明还在加载模型
# 查看 vLLM 日志
journalctl -u vllm -f
# 或
docker logs vllm-server -f 2>&1 | tail -50

# 模型加载中的典型日志：
# INFO: Loading model weights...
# INFO: Loading model weights took 45.23 seconds
# INFO: Uvicorn running on http://0.0.0.0:8000
# 看到 Uvicorn running 才说明服务就绪

2.2.5 超时参数调优指南

大模型服务的超时配置涉及三层：客户端、网关、推理引擎。三层要配合，否则会出现"客户端已经超时了，但服务端还在算"的资源浪费问题。

超时链路示意：

客户端超时 > 网关超时 > 推理引擎超时（应从外到内递减）

等等，这个逻辑是反过来的——外层的超时应该大于或等于内层，否则内层还没超时外层就断了。

正确的配置：

推理引擎内部超时: 120s（最长允许执行时间）
Nginx proxy_read_timeout: 150s（留 30s 缓冲）
客户端 timeout: 180s（再留 30s 缓冲）

vLLM 超时参数：

# vLLM 启动参数
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9 \
  --max-num-seqs 64 \
  --request-timeout 120        # 单请求最大处理时间（秒）

Nginx 超时配置：

# /etc/nginx/conf.d/llm-proxy.conf
upstream vllm_backend {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 80;
    server_name llm.example.com;

    # 客户端相关超时
    client_body_timeout 30s;
    client_header_timeout 10s;

    # 代理相关超时
    proxy_connect_timeout 10s;     # 连接后端的超时
    proxy_send_timeout 30s;        # 发送请求到后端的超时
    proxy_read_timeout 150s;       # 等待后端响应的超时（要大于 vLLM 的 request-timeout）

    # SSE（Server-Sent Events）支持，stream 模式必须
    proxy_buffering off;
    proxy_cache off;

    location /v1/ {
        proxy_pass http://vllm_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding on;
    }
}

Python 客户端超时配置：

import openai

client = openai.OpenAI(
    base_url="http://llm.example.com/v1",
    api_key="not-needed",
    timeout=openai.Timeout(
        connect=10.0,   # 连接超时
        read=180.0,     # 读取超时（等待响应）
        write=30.0,     # 写入超时（发送请求）
        pool=10.0,      # 连接池超时
    ),
    max_retries=3,       # 自动重试次数
)

# stream 模式下的超时配置
response = client.chat.completions.create(
    model="Qwen/Qwen3.5-35B-A3B-FP8",
    messages=[{"role": "user", "content": "写一首诗"}],
    max_tokens=500,
    stream=True,
    timeout=180,
)

2.3 限流问题排查

2.3.1 HTTP 429 Too Many Requests 排查

看到 429 状态码，先确认是哪一层返回的。

# 测试请求，看响应头
curl -v -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-35B-A3B-FP8","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
  2>&1 | grep -E "^< (HTTP|X-|Retry|RateLimit)"

# 关键响应头：
# Retry-After: 5                 → 几秒后重试
# X-RateLimit-Limit: 100         → 速率上限
# X-RateLimit-Remaining: 0       → 剩余配额
# X-RateLimit-Reset: 1710300000  → 配额重置时间

判断限流来源：

响应头特征	来源	处理方式
`X-RateLimit-*` 头	API 网关层	调整网关限流配置
响应体包含 `vllm` 关键字	vLLM 引擎	调整 vLLM 并发参数
`Server: nginx` 或 `Server: envoy`	反向代理层	调整代理限流配置
响应体包含 `token quota`	Token 计费层	充值或联系管理员

2.3.2 vLLM 内部队列限制

vLLM 有几个参数直接控制了它能同时处理多少请求：

# 查看当前运行的 vLLM 启动参数
ps aux | grep vllm | grep -v grep

# 关键参数说明：
# --max-num-seqs 256        : 最大同时处理的序列数
# --max-num-batched-tokens 32768 : 每个 batch 最大 token 数
# --max-model-len 32768     : 单请求最大上下文长度

max-num-seqs 调优：

这个参数控制 vLLM 同时处理的最大请求数。设太小会限流，设太大会 OOM。

推荐计算公式：
max-num-seqs = 可用显存 / (平均 KV Cache per request)

A100 80G，gpu-memory-utilization=0.9，Qwen3.5-35B-A3B-FP8 模型占 18GB：
可用 KV Cache = 80 × 0.9 - 18 = 54 GB
假设平均每请求用 200MB KV Cache（平均 context 2048 tokens）：
max-num-seqs ≈ 54000 / 200 = 270

实际要留安全裕量，建议设 200-256

max-num-batched-tokens 调优：

# 这个参数限制每个调度周期中所有请求的 token 总数
# 设太小：GPU 利用率低，吞吐量差
# 设太大：prefill 延迟高，因为一个长请求可能占满整个 batch

# 推荐值：
# 短对话场景（平均 < 2K tokens）：max-num-batched-tokens = 16384
# 长文档场景（平均 > 4K tokens）：max-num-batched-tokens = 32768
# RAG 场景（prompt 长、response 短）：max-num-batched-tokens = 65536

2.3.3 Nginx 层限流配置

# /etc/nginx/conf.d/llm-ratelimit.conf

# 定义限流区域
# rate=50r/s 表示每秒 50 个请求
# zone=llm_limit:10m 表示用 10MB 内存存储状态（约能跟踪 16万个 IP）
limit_req_zone $binary_remote_addr zone=llm_limit:10m rate=50r/s;

# 基于 API Key 的限流（更细粒度）
map $http_authorization $api_key {
    default "";
    "~Bearer (.+)" $1;
}
limit_req_zone $api_key zone=llm_key_limit:10m rate=20r/s;

server {
    listen 80;

    location /v1/chat/completions {
        # 允许突发 20 个请求，不延迟
        limit_req zone=llm_limit burst=20 nodelay;

        # 基于 API Key 的限流
        limit_req zone=llm_key_limit burst=10 nodelay;

        # 限流时返回 429 而不是默认的 503
        limit_req_status 429;

        proxy_pass http://vllm_backend;
    }
}

2.3.4 Token Bucket 机制说明

限流最常用的算法是 Token Bucket（令牌桶），理解这个机制有助于调参：

令牌桶工作原理：
1. 桶以固定速率 rate 填充令牌
2. 桶最多容纳 burst 个令牌（突发容量）
3. 每个请求消耗一个令牌
4. 桶空时，新请求被拒绝（返回 429）

示例：rate=50r/s, burst=20
- 正常情况：每秒稳定处理 50 个请求
- 突发情况：瞬间可处理 50+20=70 个请求
- 持续高压：稳定在 50r/s，超出的被 429

2.3.5 限流配置调优建议

场景	rate 建议	burst 建议	说明
内部 RAG 系统	100r/s per IP	50	用户量小，单用户可能连续查询
对外 API 服务	10r/s per API Key	20	防止单用户打爆
批量处理	200r/s 全局	100	后端处理能力的 80%
开发测试	不限流	-	测试环境放开

2.4 OOM 问题排查

OOM 是最头疼的问题，因为它通常导致服务直接挂掉，而且重启后如果不改配置还会继续挂。

2.4.1 GPU OOM 排查

症状：vLLM 日志出现 torch.cuda.OutOfMemoryError 或 CUDA error: out of memory，服务崩溃或卡死。

第一步：看显存占用

# 实时监控显存
nvidia-smi -l 1

# 或者更详细的显存分配
nvidia-smi --query-gpu=index,name,memory.total,memory.used,memory.free,utilization.gpu --format=csv

# 输出示例：
# 0, NVIDIA A100-SXM4-80GB, 81920 MiB, 72448 MiB, 9472 MiB, 95 %

# 看每个进程的显存占用
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv

# 输出示例：
# 12345, python, 71680 MiB

第二步：检查 vLLM 的显存分配

# vLLM 启动日志中会打印显存分配信息
docker logs vllm-server 2>&1 | grep -E "GPU|memory|cache"

# 典型输出：
# INFO: GPU 0: NVIDIA A100-SXM4-80GB (80 GiB)
# INFO: Model weights: 18.2 GiB
# INFO: KV cache: 54.0 GiB (gpu_memory_utilization=0.9)
# INFO: Available KV cache blocks: 27648

第三步：分析 OOM 原因

GPU 显存的构成：

总显存 = 模型权重 + KV Cache + 激活值 + CUDA 上下文 + 碎片

A100 80GB 的典型分配（Qwen/Qwen3.5-35B-A3B-FP8）：
  模型权重:  ~18 GB（FP8 量化后）
  CUDA 上下文: ~2 GB
  可用空间:  ~60 GB
  gpu-memory-utilization=0.9 时：
    KV Cache: 60 × 0.9 = 54 GB
    预留:     60 × 0.1 = 6 GB（给激活值和碎片）

OOM 场景分析：

场景	原因	典型日志
启动时 OOM	模型太大，显存装不下	`OutOfMemoryError: CUDA out of memory. Tried to allocate 2.00 GiB`
运行时 OOM	KV Cache 耗尽	`No available memory for the request`
长对话 OOM	单请求 context 超长	`Request exceeds max_model_len`
并发高时 OOM	同时请求太多	`All cache blocks are allocated`

第四步：解决方案

启动时 OOM — 模型太大

# 方案 A：降低精度（如果模型支持）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --dtype auto \
  --quantization fp8   # FP8 量化

# 方案 B：多卡张量并行
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --tensor-parallel-size 2   # 用 2 张卡

# 方案 C：降低 gpu-memory-utilization
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --gpu-memory-utilization 0.85   # 从 0.9 降到 0.85

运行时 OOM — KV Cache 不够

# 降低最大并发
--max-num-seqs 128          # 从 256 降到 128

# 降低最大上下文长度
--max-model-len 16384       # 从 32768 降到 16384

# 或者两个都降
--max-num-seqs 128 --max-model-len 16384

长对话 OOM — 限制单请求长度

# vLLM 启动参数限制
--max-model-len 8192

# 应用层也要做限制，别完全依赖 vLLM
# 在 API 网关层截断超长请求

2.4.2 CPU OOM 排查

症状：服务器响应缓慢或被 OOM Killer 杀死，dmesg 中有 Out of memory: Killed process 日志。

# 第一步：检查 OOM 日志
dmesg | grep -i "oom\|killed" | tail -20

# 输出示例：
# [123456.789] Out of memory: Killed process 12345 (python) total-vm:98765432kB, anon-rss:65432100kB, file-rss:1234kB
# 注意 anon-rss 就是进程实际使用的物理内存

# 第二步：检查当前内存状况
free -h

# 输出示例：
#               total        used        free      shared  buff/cache   available
# Mem:           125Gi       98Gi       2.1Gi       1.2Gi        25Gi        24Gi
# Swap:            0B          0B          0B

# 第三步：查看内存大户
ps aux --sort=-%mem | head -10

# 第四步：查看详细内存分配
cat /proc/meminfo | grep -E "MemTotal|MemFree|MemAvailable|SwapTotal|SwapFree|Cached|Buffers"

CPU OOM 的常见原因：

模型加载时的内存峰值

vLLM 加载模型时需要先在 CPU 内存中读取权重文件，然后再传到 GPU。一个 35B 参数的 FP8 模型，CPU 侧需要约 35GB 内存。如果同时还跑了其他服务，很容易 OOM。

# 查看模型文件大小（估算 CPU 内存需求）
du -sh /models/Qwen3.5-35B-A3B-FP8/

# 预留 CPU 内存 = 模型文件大小 × 1.5 + 操作系统和其他服务需求

Tokenizer 内存泄漏

部分 tokenizer 在处理大量请求后会出现内存缓慢增长的问题。线上跑了 3 天后 CPU 内存从 20GB 涨到 45GB 就是这个坑。

# 监控进程内存变化趋势
while true; do
    echo "$(date) $(ps aux | grep 'vllm' | grep -v grep | awk '{print $6}') KB"
    sleep 60
done >> /var/log/vllm_mem_monitor.log

解决：定期重启 vLLM 服务（比如每天凌晨），或者升级到最新版本看是否修复。

swap 未配置

生产环境的 GPU 服务器经常不配 swap，内存一满就直接 OOM Kill。

# 临时添加 swap（应急）
sudo fallocate -l 32G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

但要注意：swap 会严重影响性能，只适合兜底，不能当常态。

2.4.3 容器 OOM Killed 排查

症状：kubectl describe pod 或 docker inspect 显示 OOMKilled。

# Kubernetes 环境
kubectl describe pod vllm-pod-xxxxx | grep -A5 "Last State"

# 输出示例：
#     Last State:     Terminated
#       Reason:       OOMKilled
#       Exit Code:    137
#       Started:      Mon, 10 Mar 2026 14:00:00 +0800
#       Finished:     Mon, 10 Mar 2026 16:32:15 +0800

# 查看容器内存限制
kubectl get pod vllm-pod-xxxxx -o jsonpath='{.spec.containers[*].resources}'

# Docker 环境
docker inspect vllm-server --format='{{.State.OOMKilled}}'
docker inspect vllm-server --format='{{.HostConfig.Memory}}'

根因：容器内存限制（resources.limits.memory）设得比实际需求小。

容器内存需求计算：

容器内存 = CPU 内存（模型加载 + tokenizer + 请求缓冲）+ 系统开销

实测 Qwen/Qwen3.5-35B-A3B-FP8 的 CPU 内存需求：
  模型加载峰值: ~35 GB
  运行时稳态:   ~20 GB
  tokenizer:    ~2 GB
  请求缓冲:     ~3 GB
  系统开销:     ~3 GB
  总计:         ~63 GB（峰值）/ ~28 GB（稳态）

解决方案：

# Kubernetes Pod 资源配置
resources:
requests:
    memory:"32Gi"        # 稳态需求
    cpu:"8"
    nvidia.com/gpu:"1"
limits:
    memory:"72Gi"        # 峰值需求 + 20% 缓冲
    cpu:"16"
    nvidia.com/gpu:"1"

# Docker 环境
docker run -d \
  --gpus '"device=0"' \
  --memory=72g \
  --memory-swap=72g \
  --shm-size=8g \
  --name vllm-server \
  vllm/vllm-openai:v0.7.6 \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --gpu-memory-utilization 0.9

2.4.4 OOM 根因速查表

症状	检查命令	根因	解决方案
vLLM 日志 `OutOfMemoryError`	`nvidia-smi`	GPU 显存不足	降低 gpu-memory-utilization / 减少 max-num-seqs
dmesg `Killed process`	`dmesg \| grep oom`	CPU 内存不足	加内存 / 加 swap / 减少并发
Pod OOMKilled	`kubectl describe pod`	容器内存限制太小	调大 resources.limits.memory
vLLM `All cache blocks are allocated`	查看 metrics	KV Cache 用完	降低 max-num-seqs 或 max-model-len
内存持续增长	持续监控 RSS	内存泄漏	定期重启 / 升级版本
启动时 OOM	`du -sh model/`	模型太大	用量化版本 / 多卡并行

2.5 其他常见错误

2.5.1 CUDA Error: out of memory vs GPU OOM

很多人分不清 CUDA error: out of memory 和 torch.cuda.OutOfMemoryError 的区别。

torch.cuda.OutOfMemoryError：PyTorch 层面的内存分配失败，通常是 KV Cache 或激活值分配不到显存。vLLM 通常能捕获这个错误并优雅降级（拒绝新请求，不会崩溃）。
CUDA error: out of memory：CUDA 驱动层面的错误，更底层。一旦出现，整个 CUDA context 可能损坏，需要重启进程。

# 如果 CUDA context 损坏，需要重置 GPU
nvidia-smi --gpu-reset -i 0

# 注意：gpu-reset 会杀死该 GPU 上所有进程
# 先确认没有其他重要进程在用这张卡
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv -i 0

2.5.2 CUDA Error: device-side assert triggered

RuntimeError: CUDA error: device-side assert triggered
CUDA kernel errors might be asynchronously reported at some other API call, so the stacktrace below might be incorrect.

这个错误通常是模型推理过程中的数值异常（NaN/Inf）触发了 CUDA kernel 的 assert。

常见原因：

模型权重文件损坏
输入数据中有异常值
FP16 精度溢出

# 排查步骤

# 1. 检查模型文件完整性
python -c "
from safetensors import safe_open
import os
model_dir = '/models/Qwen3.5-35B-A3B-FP8'
for f in os.listdir(model_dir):
    if f.endswith('.safetensors'):
        try:
            with safe_open(os.path.join(model_dir, f), framework='pt') as sf:
                for key in sf.keys():
                    tensor = sf.get_tensor(key)
                    if tensor.isnan().any() or tensor.isinf().any():
                        print(f'WARNING: {f}/{key} contains NaN/Inf!')
            print(f'OK: {f}')
        except Exception as e:
            print(f'ERROR: {f}: {e}')
"

# 2. 启用 CUDA_LAUNCH_BLOCKING 获取精确堆栈
CUDA_LAUNCH_BLOCKING=1 python -m vllm.entrypoints.openai.api_server ...

# 3. 如果是 FP16 溢出，尝试用 BF16
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --dtype bfloat16

2.5.3 RuntimeError: NCCL communicator was aborted

多卡推理（tensor parallel）时 NCCL 通信失败。

RuntimeError: NCCL communicator was aborted on rank 1. Original reason: ...

常见原因和解决方案：

# 1. GPU 之间的 NVLink/PCIe 通信故障
# 检查 GPU 拓扑
nvidia-smi topo -m

# 2. NCCL 版本和 CUDA 版本不匹配
python -c "import torch; print(torch.cuda.nccl.version())"

# 3. 进程间通信端口冲突
# 设置 NCCL 使用不同端口
export NCCL_SOCKET_IFNAME=eth0
export NCCL_IB_DISABLE=1    # 禁用 InfiniBand（如果没有 IB 网卡）

# 4. 共享内存不足
# 检查 /dev/shm 大小
df -h /dev/shm

# Docker 环境需要加大 shm-size
docker run --shm-size=8g ...

# Kubernetes 环境
# volumes:
#   - name: dshm
#     emptyDir:
#       medium: Memory
#       sizeLimit: 8Gi

2.5.4 模型加载失败

权重文件损坏：

# 检查文件 hash
sha256sum /models/Qwen3.5-35B-A3B-FP8/*.safetensors

# 和 HuggingFace 上的 hash 对比
# 如果不一致，重新下载

# 使用 huggingface-cli 下载（支持断点续传和校验）
pip install huggingface_hub
huggingface-cli download Qwen/Qwen3.5-35B-A3B-FP8 \
  --local-dir /models/Qwen3.5-35B-A3B-FP8 \
  --local-dir-use-symlinks False

磁盘空间不足：

# 检查模型目录所在磁盘空间
df -h /models/

# 模型文件大小参考：
# Qwen3.5-35B-A3B-FP8:  ~35 GB
# Qwen3-Coder-30B-A3B-FP8: ~30 GB
# 加上 tokenizer 和配置文件，预留 40-50 GB

# 清理旧模型释放空间
du -sh /models/*/  | sort -h

safetensors 格式错误：

# 验证 safetensors 文件
python -c "
from safetensors import safe_open
try:
    with safe_open('/models/Qwen3.5-35B-A3B-FP8/model-00001-of-00008.safetensors', framework='pt') as f:
        print('Keys:', list(f.keys())[:5])
        print('File is valid')
except Exception as e:
    print(f'File is corrupted: {e}')
"

2.5.5 torch.cuda.OutOfMemoryError 具体处理

这是最常见的 CUDA 错误，具体处理流程：

# 完整的排查流程脚本
#!/bin/bash

echo"=== GPU Memory Status ==="
nvidia-smi --query-gpu=index,memory.total,memory.used,memory.free --format=csv

echo""
echo"=== GPU Processes ==="
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv

echo""
echo"=== vLLM Config Check ==="
ps aux | grep vllm | grep -v grep | sed 's/.*python/python/'

echo""
echo"=== Recent OOM Logs ==="
if [ -f /var/log/vllm/vllm.log ]; then
    grep -i "OutOfMemory\|out of memory\|OOM" /var/log/vllm/vllm.log | tail -5
else
    journalctl -u vllm --since "1 hour ago" | grep -i "OutOfMemory\|out of memory\|OOM" | tail -5
fi

echo""
echo"=== System Memory ==="
free -h

echo""
echo"=== Recommendation ==="
GPU_USED=$(nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits -i 0)
GPU_TOTAL=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i 0)
USAGE_PCT=$((GPU_USED * 100 / GPU_TOTAL))

if [ "$USAGE_PCT" -gt 95 ]; then
    echo"GPU memory usage ${USAGE_PCT}% - CRITICAL"
    echo"Suggestions:"
    echo"  1. Reduce --max-num-seqs"
    echo"  2. Reduce --max-model-len"
    echo"  3. Reduce --gpu-memory-utilization"
    echo"  4. Use tensor parallelism (--tensor-parallel-size 2)"
elif [ "$USAGE_PCT" -gt 85 ]; then
    echo"GPU memory usage ${USAGE_PCT}% - WARNING"
    echo"Consider reducing max-num-seqs by 20%"
else
    echo"GPU memory usage ${USAGE_PCT}% - OK"
fi

三、示例代码和配置

3.1 OOM 自动恢复脚本

#!/bin/bash
# vllm_watchdog.sh - vLLM OOM 自动恢复 + 告警
# 部署方式：systemd service 或 supervisor

VLLM_CMD="python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.88 \
  --max-num-seqs 200 \
  --max-model-len 16384 \
  --dtype auto"

HEALTH_URL="http://localhost:8000/health"
ALERT_WEBHOOK="http://alertmanager:9093/api/v1/alerts"
LOG_FILE="/var/log/vllm/watchdog.log"
MAX_RESTARTS=5
RESTART_COUNT=0
COOLDOWN=60

log() {
    echo"[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

send_alert() {
    local severity=$1
    local message=$2
    curl -s -X POST "$ALERT_WEBHOOK" \
      -H "Content-Type: application/json" \
      -d "[{
        \"labels\": {
          \"alertname\": \"VLLMWatchdog\",
          \"severity\": \"$severity\",
          \"instance\": \"$(hostname)\"
        },
        \"annotations\": {
          \"summary\": \"$message\"
        }
      }]" > /dev/null 2>&1
    log"ALERT [$severity]: $message"
}

check_gpu_health() {
    # 检查 GPU 是否正常
    if ! nvidia-smi > /dev/null 2>&1; then
        log"GPU health check failed - nvidia-smi error"
        return 1
    fi

    # 检查 GPU 温度
    local temp
    temp=$(nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader,nounits -i 0)
    if [ "$temp" -gt 90 ]; then
        log"GPU temperature too high: ${temp}°C"
        send_alert "critical""GPU temperature ${temp}°C exceeds 90°C threshold"
        return 1
    fi

    return 0
}

start_vllm() {
    log"Starting vLLM..."
    $VLLM_CMD >> /var/log/vllm/vllm.log 2>&1 &
    VLLM_PID=$!
    log"vLLM started with PID $VLLM_PID"

    # 等待服务就绪（模型加载需要时间）
    local wait_count=0
    local max_wait=300  # 最多等 5 分钟
    while [ $wait_count -lt $max_wait ]; do
        if curl -s "$HEALTH_URL" > /dev/null 2>&1; then
            log"vLLM service is ready"
            return 0
        fi
        sleep 2
        wait_count=$((wait_count + 2))
    done

    log"vLLM failed to start within ${max_wait}s"
    kill$VLLM_PID 2>/dev/null
    return 1
}

# 主循环
log"=== vLLM Watchdog Started ==="

whiletrue; do
    # 检查 GPU 健康
    if ! check_gpu_health; then
        log"GPU unhealthy, waiting for recovery..."
        sleep 30
        continue
    fi

    # 启动 vLLM
    if start_vllm; then
        RESTART_COUNT=0
        send_alert "info""vLLM service started successfully"

        # 健康检查循环
        whiletrue; do
            sleep 15

            if ! kill -0 $VLLM_PID 2>/dev/null; then
                # 进程不存在了
                log"vLLM process $VLLM_PID is gone"

                # 检查是否 OOM
                if dmesg | tail -20 | grep -qi "oom.*$VLLM_PID\|killed.*$VLLM_PID"; then
                    log"OOM detected!"
                    send_alert "critical""vLLM OOM Killed, PID=$VLLM_PID, restarting..."
                else
                    log"vLLM exited unexpectedly"
                    send_alert "warning""vLLM process died, PID=$VLLM_PID, restarting..."
                fi
                break
            fi

            # HTTP 健康检查
            if ! curl -s --max-time 10 "$HEALTH_URL" > /dev/null 2>&1; then
                log"Health check failed, checking process..."
                sleep 5
                if ! curl -s --max-time 10 "$HEALTH_URL" > /dev/null 2>&1; then
                    log"Health check failed twice, killing vLLM"
                    send_alert "warning""vLLM health check failed, restarting..."
                    kill -9 $VLLM_PID 2>/dev/null
                    sleep 5
                    break
                fi
            fi
        done
    fi

    # 重启次数限制
    RESTART_COUNT=$((RESTART_COUNT + 1))
    if [ $RESTART_COUNT -ge $MAX_RESTARTS ]; then
        send_alert "critical""vLLM exceeded max restarts ($MAX_RESTARTS), giving up"
        log"Max restarts reached, exiting watchdog"
        exit 1
    fi

    log"Restarting in ${COOLDOWN}s (attempt $RESTART_COUNT/$MAX_RESTARTS)"
    sleep $COOLDOWN
done

配套的 systemd service：

# /etc/systemd/system/vllm-watchdog.service
[Unit]
Description=vLLM Watchdog Service
After=network.target nvidia-persistenced.service

[Service]
Type=simple
User=root
ExecStart=/opt/scripts/vllm_watchdog.sh
Restart=on-failure
RestartSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable vllm-watchdog
sudo systemctl start vllm-watchdog

# 查看状态
sudo systemctl status vllm-watchdog
journalctl -u vllm-watchdog -f

3.2 限流配置模板

Nginx rate_limit 完整模板：

# /etc/nginx/conf.d/llm-gateway.conf

# 限流配置
limit_req_zone $binary_remote_addr zone=per_ip:10m rate=30r/s;
limit_req_zone $api_key zone=per_key:10m rate=10r/s;
limit_conn_zone $binary_remote_addr zone=per_ip_conn:10m;

# API Key 提取
map $http_authorization $api_key {
    default "anonymous";
    "~*Bearer\s+(.+)" $1;
}

# 请求大小限制（防止超长 prompt）
client_max_body_size 10m;

upstream vllm_servers {
    server 10.0.1.10:8000 weight=1;
    server 10.0.1.11:8000 weight=1;
    keepalive 64;
}

server {
    listen 443 ssl;
    server_name llm-api.example.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    # 全局超时
    proxy_connect_timeout 10s;
    proxy_send_timeout 30s;
    proxy_read_timeout 180s;

    # SSE 支持
    proxy_buffering off;

    # Chat Completions（最常用，重点限流）
    location /v1/chat/completions {
        limit_req zone=per_ip burst=20 nodelay;
        limit_req zone=per_key burst=5 nodelay;
        limit_conn per_ip_conn 10;    # 单 IP 最大 10 个并发连接
        limit_req_status 429;
        limit_conn_status 429;

        proxy_pass http://vllm_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
    }

    # Completions
    location /v1/completions {
        limit_req zone=per_ip burst=20 nodelay;
        limit_req zone=per_key burst=5 nodelay;
        limit_req_status 429;

        proxy_pass http://vllm_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
    }

    # Embeddings（计算量小，可以放宽）
    location /v1/embeddings {
        limit_req zone=per_ip burst=50 nodelay;
        limit_req_status 429;

        proxy_pass http://vllm_servers;
        proxy_set_header Host $host;
    }

    # Models list（不限流）
    location /v1/models {
        proxy_pass http://vllm_servers;
    }

    # Health check（不限流）
    location /health {
        proxy_pass http://vllm_servers;
    }

    # 自定义 429 响应体（符合 OpenAI API 格式）
    error_page 429 @rate_limited;
    location @rate_limited {
        default_type application/json;
        return 429 '{"error":{"message":"Rate limit exceeded. Please retry after a short wait.","type":"rate_limit_error","code":"rate_limit_exceeded"}}';
    }
}

vLLM 参数调优配置：

# 中等负载配置（单卡 A100 80G，Qwen3.5-35B-A3B-FP8）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --gpu-memory-utilization 0.88 \
  --max-num-seqs 200 \
  --max-num-batched-tokens 32768 \
  --max-model-len 16384 \
  --enable-chunked-prefill \
  --disable-log-requests

# 高吞吐配置（牺牲单请求延迟换总吞吐）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --gpu-memory-utilization 0.92 \
  --max-num-seqs 512 \
  --max-num-batched-tokens 65536 \
  --max-model-len 8192 \
  --enable-chunked-prefill \
  --disable-log-requests

# 低延迟配置（牺牲吞吐换单请求速度）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --gpu-memory-utilization 0.85 \
  --max-num-seqs 32 \
  --max-num-batched-tokens 8192 \
  --max-model-len 32768 \
  --disable-log-requests

3.3 超时参数调优配置

三层超时的完整配置模板：

# client_config.py - Python 客户端最佳配置

import openai
import httpx

# 标准配置
client = openai.OpenAI(
    base_url="https://llm-api.example.com/v1",
    api_key="your-api-key",
    timeout=openai.Timeout(
        connect=10.0,
        read=180.0,
        write=30.0,
        pool=10.0,
    ),
    max_retries=3,
    http_client=httpx.Client(
        limits=httpx.Limits(
            max_connections=100,
            max_keepalive_connections=20,
            keepalive_expiry=30,
        ),
    ),
)

# 异步客户端
async_client = openai.AsyncOpenAI(
    base_url="https://llm-api.example.com/v1",
    api_key="your-api-key",
    timeout=openai.Timeout(
        connect=10.0,
        read=180.0,
        write=30.0,
        pool=10.0,
    ),
    max_retries=3,
    http_client=httpx.AsyncClient(
        limits=httpx.Limits(
            max_connections=200,
            max_keepalive_connections=50,
            keepalive_expiry=30,
        ),
    ),
)


# 带重试和降级的调用封装
import time
import logging

logger = logging.getLogger(__name__)


def call_llm_with_fallback(
    messages: list,
    model: str = "Qwen/Qwen3.5-35B-A3B-FP8",
    max_tokens: int = 2048,
    max_retries: int = 3,
    fallback_model: str = "Qwen/Qwen3-Coder-30B-A3B-FP8",
) -> str:
    """带重试和降级的 LLM 调用"""

    last_error = None

    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                max_tokens=max_tokens,
                timeout=120,
            )
            return response.choices[0].message.content

        except openai.RateLimitError as e:
            # 429 限流，等待后重试
            retry_after = int(e.response.headers.get("Retry-After", 5))
            logger.warning(f"Rate limited, retry after {retry_after}s (attempt {attempt + 1})")
            time.sleep(retry_after)
            last_error = e

        except openai.APITimeoutError as e:
            # 超时，指数退避重试
            wait_time = 2 ** attempt
            logger.warning(f"Timeout, retry after {wait_time}s (attempt {attempt + 1})")
            time.sleep(wait_time)
            last_error = e

        except openai.APIConnectionError as e:
            # 连接错误，快速重试
            logger.warning(f"Connection error, retry (attempt {attempt + 1}): {e}")
            time.sleep(1)
            last_error = e

        except openai.InternalServerError as e:
            # 500 错误，可能是 OOM，切换备用模型
            logger.error(f"Server error: {e}")
            if fallback_model and model != fallback_model:
                logger.info(f"Falling back to {fallback_model}")
                model = fallback_model
            last_error = e

    # 所有重试失败
    logger.error(f"All retries failed: {last_error}")
    raise last_error

3.4 案例 1：生产环境 GPU OOM 完整排查

时间线：

2026年2月15日，周六凌晨 3 点，告警群收到：

[CRITICAL] vLLM service down on gpu-server-03
Process exited with code 137 (OOM Killed)

排查过程：

03:05 - 登录服务器，确认服务状态

ssh gpu-server-03

# 查看进程
ps aux | grep vllm
# 没有 vLLM 进程

# 查看 docker 状态
docker ps -a | grep vllm
# STATUS: Exited (137) 3 minutes ago

# 确认是 OOM
docker inspect vllm-server --format='{{.State.OOMKilled}}'
# true

03:08 - 查看系统日志确认 OOM 详情

dmesg | tail -30
# [Sat Feb 15 02:58:32 2026] oom-kill: constraint=CONSTRAINT_MEMCG, ...
# [Sat Feb 15 02:58:32 2026] Memory cgroup out of memory: Killed process 28456 (python)
#   total-vm:156789012kB, anon-rss:73400320kB

# 73GB RSS，容器限制是 72GB

03:10 - 查看 GPU 显存（此时 GPU 应该已释放）

nvidia-smi
# GPU 0: A100 80GB, 0MiB / 81920MiB used
# 正常，进程已经死了

03:12 - 查看 vLLM 日志，找 OOM 前的线索

docker logs vllm-server 2>&1 | tail -100

# 关键日志：
# [02:55:10] INFO: Received request cmpl-abc123, prompt_tokens=28672, max_tokens=4096
# [02:55:11] INFO: Received request cmpl-abc124, prompt_tokens=31000, max_tokens=2048
# [02:55:12] WARNING: Preempting 3 sequences due to insufficient KV cache
# [02:57:45] INFO: Received request cmpl-abc189, prompt_tokens=30500, max_tokens=8192
# [02:58:30] ERROR: torch.cuda.OutOfMemoryError: CUDA out of memory
# [02:58:31] CRITICAL: Fatal error, shutting down

03:15 - 定位根因

凌晨 2:55-2:58 期间，大量超长 prompt 请求涌入。这些请求的 prompt 长度都在 28K-31K tokens，接近 max-model-len=32768 的上限。

查看启动参数：

docker logs vllm-server 2>&1 | head -20
# --max-model-len 32768
# --max-num-seqs 256
# --gpu-memory-utilization 0.9

问题出在 max-model-len=32768 和 max-num-seqs=256 的组合。虽然平时大部分请求的 prompt 都在 2K-4K，KV Cache 足够。但凌晨有个批量任务在跑长文档摘要，prompt 长度 30K+，每个请求消耗的 KV Cache 是平时的 10 倍。

正常请求 KV Cache: 2K tokens × 每 token 约 0.8MB = 1.6MB
长文档请求 KV Cache: 30K tokens × 每 token 约 0.8MB = 24MB

KV Cache 总量: 54GB
正常情况 256 并发: 256 × 1.6MB = 410MB，绰绰有余
长文档 30 并发: 30 × 24MB = 720MB，也没问题
但如果 200 个长文档并发: 200 × 24MB = 4.8GB...

等等，不对。重新算：
Qwen3.5-35B-A3B-FP8，FP8 量化，KV Cache 每 token:
= num_layers × 2 × num_heads × head_dim × 2 bytes(FP16 KV cache)
= 64 × 2 × 8 × 128 × 2 = 262,144 bytes ≈ 0.25 MB/token

30K prompt: 30000 × 0.25MB = 7.5GB per request
如果同时来了 8 个这样的请求: 8 × 7.5 = 60GB > 54GB 可用 KV Cache

根因确认：批量长文档任务同时发起 8+ 个 30K token 的请求，KV Cache 总需求超过可用显存。

03:25 - 修复和重启

# 临时方案：降低 max-model-len，限制单请求长度
docker run -d \
  --gpus '"device=0"' \
  --memory=72g \
  --shm-size=8g \
  --name vllm-server \
  vllm/vllm-openai:v0.7.6 \
  --model Qwen/Qwen3.5-35B-A3B-FP8 \
  --gpu-memory-utilization 0.9 \
  --max-num-seqs 200 \
  --max-model-len 16384      # 从 32768 降到 16384

# 验证服务启动
sleep 120
curl http://localhost:8000/v1/models
# 正常返回模型列表

03:40 - 长期方案（第二天工作日处理）

批量任务改为排队执行，不并发
API 网关增加 prompt 长度检查，超过 16K 的走专用队列
容器内存限制从 72G 调到 96G
增加 KV Cache 水位监控告警

3.5 案例 2：间歇性超时根因定位

问题现象：

每天下午 2:00-2:30，API 超时率从 0.1% 飙到 15%。其他时间段正常。持续了一周。

排查过程：

第一步，确认超时模式

# 从 Prometheus 拉数据，按小时统计超时率
curl -s 'http://prometheus:9090/api/v1/query_range' \
  --data-urlencode 'query=sum(rate(vllm_request_failure_total{error="timeout"}[5m])) / sum(rate(vllm_request_success_total[5m])) * 100' \
  --data-urlencode 'start=2026-03-06T00:00:00Z' \
  --data-urlencode 'end=2026-03-12T23:59:59Z' \
  --data-urlencode 'step=300' | python -m json.tool

确认了每天 14:00-14:30 有明显的超时高峰。

第二步，看这个时段的 GPU 指标

# GPU 利用率
curl -s 'http://prometheus:9090/api/v1/query_range' \
  --data-urlencode 'query=nvidia_gpu_utilization{gpu="0"}' \
  --data-urlencode 'start=2026-03-12T13:50:00Z' \
  --data-urlencode 'end=2026-03-12T14:40:00Z' \
  --data-urlencode 'step=30'

GPU 利用率在 14:00 从 60% 突然飙到 100% 并持续 30 分钟。

第三步，看请求量

# QPS 变化
# 14:00 之前：稳定 30 QPS
# 14:00-14:30：飙到 150 QPS
# 14:30 之后：回落到 30 QPS

QPS 突增 5 倍，GPU 被打满，正常请求排不上队导致超时。

第四步，定位请求来源

# 查看 Nginx access log，按来源 IP 统计 14:00-14:30 的请求量
awk '$4 ~ /12\/Mar\/2026:14:0/ || $4 ~ /12\/Mar\/2026:14:1/ || $4 ~ /12\/Mar\/2026:14:2/' \
  /var/log/nginx/llm-access.log | \
  awk '{print $1}' | sort | uniq -c | sort -rn | head -10

# 输出：
# 3847 10.0.2.55
# 3201 10.0.2.56
#  245 10.0.3.12
#  189 10.0.3.15
#   ...

10.0.2.55 和 10.0.2.56 贡献了超过 90% 的请求。

第五步，找到元凶

# 查看这两个 IP 是什么服务
nslookup 10.0.2.55
# batch-worker-01.internal

nslookup 10.0.2.56
# batch-worker-02.internal

是批量处理服务。查看它们的 crontab：

ssh batch-worker-01 "crontab -l"
# 0 14 * * * /opt/scripts/daily_summary.sh

每天下午 2 点，两台批量处理服务器同时启动日报摘要任务，对 1000+ 篇文章做摘要，并发发送请求到 LLM 服务。瞬间打满了推理引擎。

解决方案：

批量任务错峰执行

# 改 crontab，两台机器错开 30 分钟
# batch-worker-01
0 2 * * * /opt/scripts/daily_summary.sh   # 改到凌晨 2 点

# batch-worker-02
30 2 * * * /opt/scripts/daily_summary.sh  # 改到凌晨 2:30

批量任务增加并发限制和限速

# daily_summary.py 增加限速
import asyncio
import aiohttp

CONCURRENCY = 5# 最多 5 个并发
RATE_LIMIT = 10# 每秒最多 10 个请求

semaphore = asyncio.Semaphore(CONCURRENCY)

asyncdef summarize_article(session, article):
    asyncwith semaphore:
        await asyncio.sleep(1.0 / RATE_LIMIT)  # 简单限速
        asyncwith session.post(
            "http://llm-api.example.com/v1/chat/completions",
            json={
                "model": "Qwen/Qwen3.5-35B-A3B-FP8",
                "messages": [{"role": "user", "content": f"Summarize: {article}"}],
                "max_tokens": 500,
            },
            timeout=aiohttp.ClientTimeout(total=120),
        ) as resp:
            if resp.status == 429:
                retry_after = int(resp.headers.get("Retry-After", 5))
                await asyncio.sleep(retry_after)
                # 重试逻辑...
            returnawait resp.json()

API 网关增加批量任务专用限流

# 批量任务 IP 段单独限流
geo $is_batch_worker {
    default 0;
    10.0.2.0/24 1;
}

map $is_batch_worker $batch_limit_key {
    0 "";
    1 $binary_remote_addr;
}

limit_req_zone $batch_limit_key zone=batch_limit:1m rate=10r/s;

location /v1/chat/completions {
    limit_req zone=batch_limit burst=5 nodelay;
    # ... 其他配置
}

修复后超时率降到 0.05% 以下，连续跑了一个月没再出现。

四、最佳实践和注意事项

4.1 最佳实践

4.1.1 预防性配置清单

部署大模型服务前，过一遍这个清单：

#!/bin/bash
# pre_deploy_check.sh - 部署前检查脚本

echo"=== Pre-deployment Checklist ==="

# 1. GPU 驱动版本
echo -n "[1] GPU Driver: "
DRIVER=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader | head -1)
if [[ $(echo"$DRIVER >= 560" | bc -l 2>/dev/null || echo"0") == "1" ]] || [[ "$DRIVER" > "560" ]]; then
    echo"OK ($DRIVER)"
else
    echo"FAIL ($DRIVER < 560)"
fi

# 2. CUDA 版本
echo -n "[2] CUDA Version: "
CUDA=$(nvcc --version 2>/dev/null | grep "release" | awk '{print $5}' | tr -d ',')
echo"$CUDA"

# 3. 显存大小
echo -n "[3] GPU Memory: "
nvidia-smi --query-gpu=name,memory.total --format=csv,noheader

# 4. CPU 内存
echo -n "[4] System Memory: "
free -h | awk '/Mem:/{print $2}'

# 5. 磁盘空间（模型目录）
echo -n "[5] Model Dir Space: "
df -h /models/ | awk 'NR==2{print $4, "available"}'

# 6. 模型文件完整性
echo -n "[6] Model Files: "
MODEL_DIR="/models/Qwen3.5-35B-A3B-FP8"
if [ -f "$MODEL_DIR/config.json" ] && [ -f "$MODEL_DIR/tokenizer.json" ]; then
    SAFETENSORS=$(ls "$MODEL_DIR"/*.safetensors 2>/dev/null | wc -l)
    echo"OK ($SAFETENSORS safetensors files)"
else
    echo"FAIL (missing config/tokenizer)"
fi

# 7. Docker 版本
echo -n "[7] Docker: "
docker --version 2>/dev/null | awk '{print $3}'

# 8. 网络端口
echo -n "[8] Port 8000: "
if ss -tlnp | grep -q ':8000'; then
    echo"IN USE (conflict!)"
else
    echo"Available"
fi

# 9. /dev/shm 大小
echo -n "[9] Shared Memory: "
df -h /dev/shm | awk 'NR==2{print $2}'

# 10. NUMA 拓扑
echo"[10] NUMA Topology:"
nvidia-smi topo -m 2>/dev/null | head -5

echo"=== Check Complete ==="

4.1.2 错误信息脱敏

生产环境的 API 不能把内部错误信息直接暴露给客户端。

# Nginx 配置：拦截并替换错误响应
location /v1/ {
    proxy_pass http://vllm_backend;

    # 拦截 500 错误
    proxy_intercept_errors on;

    error_page 500 502 503 504 @internal_error;
}

location @internal_error {
    default_type application/json;
    return 500 '{"error":{"message":"Internal server error. Please retry later.","type":"server_error","code":"internal_error"}}';
}

# Python API 层面的错误脱敏
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
import traceback
import logging

app = FastAPI()
logger = logging.getLogger(__name__)

@app.exception_handler(Exception)
asyncdef global_exception_handler(request, exc):
    # 内部记录完整错误
    logger.error(f"Unhandled exception: {traceback.format_exc()}")

    # 返回给客户端的脱敏信息
    if"CUDA"in str(exc) or"OutOfMemory"in str(exc):
        return JSONResponse(
            status_code=503,
            content={"error": {"message": "Service temporarily unavailable. Please retry.", "type": "server_error"}}
        )
    elif"timeout"in str(exc).lower():
        return JSONResponse(
            status_code=504,
            content={"error": {"message": "Request timeout. Please reduce input length or retry.", "type": "timeout_error"}}
        )
    else:
        return JSONResponse(
            status_code=500,
            content={"error": {"message": "Internal server error.", "type": "server_error"}}
        )

4.1.3 故障自愈机制

健康检查 + 自动重启 + 优雅降级的三层防护：

# Kubernetes 健康检查配置
apiVersion:apps/v1
kind:Deployment
metadata:
name:vllm-server
spec:
replicas:2
template:
    spec:
      containers:
        -name:vllm
          image:vllm/vllm-openai:v0.7.6
          args:
            -"--model"
            -"Qwen/Qwen3.5-35B-A3B-FP8"
            -"--gpu-memory-utilization"
            -"0.88"
            -"--max-num-seqs"
            -"200"

          # 存活探针：检测进程是否存活
          livenessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:300   # 模型加载需要时间
            periodSeconds:30
            timeoutSeconds:10
            failureThreshold:3        # 连续 3 次失败则重启

          # 就绪探针：检测服务是否准备好接收流量
          readinessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:300
            periodSeconds:10
            timeoutSeconds:5
            failureThreshold:2        # 连续 2 次失败则从 Service 摘除

          # 启动探针：加载模型的等待时间
          startupProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:60
            periodSeconds:10
            failureThreshold:30       # 最多等 60 + 30×10 = 360 秒

          resources:
            requests:
              memory:"32Gi"
              cpu:"8"
              nvidia.com/gpu:"1"
            limits:
              memory:"96Gi"
              cpu:"16"
              nvidia.com/gpu:"1"

4.1.4 Graceful Degradation 策略

当主模型不可用时，自动切换到轻量级模型：

# graceful_degradation.py

import time
import logging
from dataclasses import dataclass

logger = logging.getLogger(__name__)


@dataclass
class ModelEndpoint:
    name: str
    url: str
    model: str
    priority: int       # 越小优先级越高
    max_tokens: int
    healthy: bool = True
    last_check: float = 0
    failure_count: int = 0


class ModelRouter:
    def __init__(self):
        self.endpoints = [
            ModelEndpoint(
                name="primary",
                url="http://gpu-server-01:8000",
                model="Qwen/Qwen3.5-35B-A3B-FP8",
                priority=1,
                max_tokens=4096,
            ),
            ModelEndpoint(
                name="secondary",
                url="http://gpu-server-02:8000",
                model="Qwen/Qwen3.5-35B-A3B-FP8",
                priority=2,
                max_tokens=4096,
            ),
            ModelEndpoint(
                name="fallback",
                url="http://gpu-server-03:8000",
                model="Qwen/Qwen3-Coder-30B-A3B-FP8",
                priority=3,
                max_tokens=2048,
            ),
        ]

    def get_healthy_endpoint(self) -> ModelEndpoint:
        """返回优先级最高的健康端点"""
        healthy = [ep for ep in self.endpoints if ep.healthy]
        ifnot healthy:
            # 所有端点都不健康，强制重试主端点
            logger.critical("All endpoints unhealthy, forcing primary")
            self.endpoints[0].healthy = True
            return self.endpoints[0]
        return sorted(healthy, key=lambda x: x.priority)[0]

    def mark_unhealthy(self, endpoint: ModelEndpoint):
        endpoint.healthy = False
        endpoint.failure_count += 1
        logger.warning(f"Marked {endpoint.name} as unhealthy (failures: {endpoint.failure_count})")

    def mark_healthy(self, endpoint: ModelEndpoint):
        endpoint.healthy = True
        endpoint.failure_count = 0

    def health_check_all(self):
        """定期健康检查，恢复已修复的端点"""
        import requests
        for ep in self.endpoints:
            try:
                resp = requests.get(f"{ep.url}/health", timeout=5)
                if resp.status_code == 200:
                    ifnot ep.healthy:
                        logger.info(f"Endpoint {ep.name} recovered")
                    self.mark_healthy(ep)
                else:
                    self.mark_unhealthy(ep)
            except Exception:
                self.mark_unhealthy(ep)

4.2 注意事项

4.2.1 常见错误汇总表

错误信息	错误码	原因	解决方案
`torch.cuda.OutOfMemoryError: CUDA out of memory`	-	GPU 显存不足	降低 gpu-memory-utilization / max-num-seqs / max-model-len
`CUDA error: device-side assert triggered`	-	模型权重损坏或数值异常	重新下载模型，用 CUDA_LAUNCH_BLOCKING=1 调试
`RuntimeError: NCCL communicator was aborted`	-	多卡通信失败	检查 NVLink/PCIe，增大 shm-size
`HTTP 429 Too Many Requests`	429	请求限流	增加 rate limit 或 burst，客户端加重试
`HTTP 503 Service Unavailable`	503	服务不可用（加载中/崩溃）	检查服务进程和日志
`HTTP 504 Gateway Timeout`	504	请求超时	调大超时参数，检查 prompt 长度
`Connection refused`	-	服务未启动或端口错误	检查进程状态和端口监听
`OSError: [Errno 28] No space left on device`	-	磁盘空间不足	清理磁盘，扩容
`ValueError: The model's max seq len (X) is larger than...`	-	max-model-len 超过模型支持的上限	降低 max-model-len
`KeyError: 'model'`	400	请求体缺少 model 字段	检查客户端请求格式
`Model not found: xxx`	404	模型名不匹配	调用 /v1/models 确认模型名
`Tokenizer initialization error`	-	tokenizer 文件缺失或损坏	重新下载 tokenizer.json 和 tokenizer_config.json
`AssertionError: assert googly_batch_size > 0`	-	vLLM 内部错误（batch 为空）	升级 vLLM 版本，通常是已知 bug
`RuntimeError: expected scalar type Float but found Half`	-	精度类型不匹配	指定 --dtype float16 或 --dtype bfloat16
`CUDA error: no kernel image is available`	-	GPU 架构不支持	检查 GPU 是否是 Ampere+，更新 PyTorch

五、故障排查和监控

5.1 系统化排错决策树

文字版决策树，从症状开始逐步定位根因：

用户报告"大模型服务异常"
│
├── 症状：请求返回错误
│   ├── HTTP 429 → 限流问题
│   │   ├── 检查 Nginx 限流配置 → 调大 rate/burst
│   │   ├── 检查 vLLM 队列 → 调大 max-num-seqs
│   │   └── 检查 Token 配额 → 充值/调额度
│   │
│   ├── HTTP 500/502/503 → 服务端错误
│   │   ├── 进程存活？
│   │   │   ├── 不存在 → 检查 OOM Kill (dmesg) → 调大内存/降低负载
│   │   │   └── 存在 → 查 vLLM 日志 → 根据错误类型处理
│   │   └── 多个实例？检查负载均衡健康检查
│   │
│   ├── HTTP 504 → 超时
│   │   ├── TTFB 大？→ TTFT 超时
│   │   │   ├── GPU 利用率 > 95%？→ 扩容或限流
│   │   │   ├── 等待队列长？→ 降低并发
│   │   │   └── prompt 太长？→ 限制输入长度
│   │   └── Total 大但 TTFB 正常？→ TPS 低
│   │       ├── GPU 温度 > 83°C？→ 散热问题
│   │       └── KV Cache swap？→ 降低 max-num-seqs
│   │
│   └── 连接拒绝 → 服务未启动
│       ├── 端口监听？→ ss -tlnp
│       ├── 防火墙？→ iptables -L
│       └── 模型加载中？→ 看启动日志
│
├── 症状：请求变慢（没报错但延迟高）
│   ├── 全部请求都慢 → 全局问题
│   │   ├── GPU 利用率 → 负载过高
│   │   ├── segment compaction → 等待完成
│   │   └── 内存 swap → 加内存
│   └── 部分请求慢 → 个别请求问题
│       ├── 长 prompt → 正常现象，优化 prefill
│       └── 特定用户 → 检查是否触发限流
│
└── 症状：服务进程消失
    ├── Exit code 137 → OOM Killed
    │   ├── 容器 OOM → 调大 memory limit
    │   └── 系统 OOM → 加内存/加 swap
    ├── Exit code 134 → SIGABRT (assertion)
    │   └── CUDA error → 检查 GPU 状态和驱动
    └── Exit code 139 → SIGSEGV (段错误)
        └── 通常是 bug → 升级版本，提交 issue

5.2 日志关键字速查

在 vLLM 日志中 grep 这些关键字可以快速定位问题类型：

# OOM 相关
grep -i "OutOfMemory\|out of memory\|OOM\|oom_kill" /var/log/vllm/vllm.log

# CUDA 错误
grep -i "CUDA error\|cuda.*error\|RuntimeError.*CUDA" /var/log/vllm/vllm.log

# 超时相关
grep -i "timeout\|timed out\|deadline exceeded" /var/log/vllm/vllm.log

# 限流相关
grep -i "rate limit\|too many\|queue full\|preempting" /var/log/vllm/vllm.log

# 模型加载
grep -i "loading model\|model loaded\|weight.*load\|safetensors" /var/log/vllm/vllm.log

# KV Cache
grep -i "cache.*block\|kv cache\|cache_usage\|swap" /var/log/vllm/vllm.log

# NCCL（多卡）
grep -i "NCCL\|nccl\|communicator\|all_reduce" /var/log/vllm/vllm.log

# 进程退出
grep -i "fatal\|shutting down\|exit\|signal\|killed" /var/log/vllm/vllm.log

每个关键字对应的问题域：

关键字	问题域	紧急程度
`OutOfMemory`	GPU/CPU 内存不足	高 - 服务可能崩溃
`CUDA error`	GPU 异常	高 - 需要重启
`timeout`	请求超时	中 - 影响用户体验
`preempting`	KV Cache 不足，抢占	中 - 部分请求被中断
`queue full`	并发过高	中 - 新请求被拒绝
`NCCL`	多卡通信	高 - 可能导致卡死
`swap`	KV Cache 换出到 CPU	低 - 性能下降但不影响正确性

5.3 监控指标和告警配置

5.3.1 Prometheus 监控指标

vLLM 0.7.x 暴露的关键 metrics（通过 /metrics 端点）：

# 请求延迟
histogram_quantile(0.99, sum(rate(vllm:e2e_request_latency_seconds_bucket[5m])) by (le))

# TTFT（Time To First Token）
histogram_quantile(0.99, sum(rate(vllm:time_to_first_token_seconds_bucket[5m])) by (le))

# TPS（Time Per Output Token）
histogram_quantile(0.50, sum(rate(vllm:time_per_output_token_seconds_bucket[5m])) by (le))

# GPU 缓存使用率
vllm:gpu_cache_usage_perc

# CPU 缓存使用率（swap）
vllm:cpu_cache_usage_perc

# 等待队列长度
vllm:num_requests_waiting

# 正在处理的请求数
vllm:num_requests_running

# 请求成功/失败计数
rate(vllm:request_success_total[5m])
rate(vllm:request_failure_total[5m])

# Prompt Token 吞吐
rate(vllm:prompt_tokens_total[5m])

# Generation Token 吞吐
rate(vllm:generation_tokens_total[5m])

5.3.2 Prometheus 告警规则

# /etc/prometheus/rules/vllm_alerts.yml
groups:
-name:vllm_critical
    rules:
      # GPU OOM 风险
      -alert:VLLMGPUCacheNearFull
        expr:vllm:gpu_cache_usage_perc>0.95
        for:2m
        labels:
          severity:critical
        annotations:
          summary:"GPU KV Cache 使用率超过 95%"
          description:"实例 {{ $labels.instance }}，当前使用率 {{ $value | humanizePercentage }}，即将 OOM"
          runbook:"降低 max-num-seqs 或重启服务"

      # 服务不可用
      -alert:VLLMServiceDown
        expr:up{job="vllm"}==0
        for:1m
        labels:
          severity:critical
        annotations:
          summary:"vLLM 服务不可用"
          description:"实例 {{ $labels.instance }} 已经 1 分钟无法访问"

      # 请求失败率
      -alert:VLLMHighErrorRate
        expr:|
          sum(rate(vllm:request_failure_total[5m]))
          /
          (sum(rate(vllm:request_success_total[5m])) + sum(rate(vllm:request_failure_total[5m])))
          > 0.05
        for:5m
        labels:
          severity:critical
        annotations:
          summary:"vLLM 请求失败率超过 5%"
          description:"当前失败率 {{ $value | humanizePercentage }}"

-name:vllm_warning
    rules:
      # TTFT 过高
      -alert:VLLMHighTTFT
        expr:histogram_quantile(0.99,sum(rate(vllm:time_to_first_token_seconds_bucket[5m]))by(le))>5
        for:5m
        labels:
          severity:warning
        annotations:
          summary:"TTFT P99 超过 5 秒"
          description:"当前 TTFT P99: {{ $value }}s"

      # 等待队列过长
      -alert:VLLMQueueBacklog
        expr:vllm:num_requests_waiting>50
        for:3m
        labels:
          severity:warning
        annotations:
          summary:"等待队列积压超过 50 个请求"
          description:"当前等待: {{ $value }}，考虑扩容或限流"

      # GPU 温度
      -alert:GPUTemperatureHigh
        expr:nvidia_smi_temperature_gpu>83
        for:5m
        labels:
          severity:warning
        annotations:
          summary:"GPU 温度超过 83°C"
          description:"GPU {{ $labels.gpu }}: {{ $value }}°C，可能触发降频"

      # KV Cache swap 发生
      -alert:VLLMKVCacheSwap
        expr:vllm:cpu_cache_usage_perc>0
        for:5m
        labels:
          severity:warning
        annotations:
          summary:"检测到 KV Cache swap 到 CPU"
          description:"CPU cache 使用率: {{ $value | humanizePercentage }}，TPS 会下降"

      # E2E 延迟过高
      -alert:VLLMHighLatency
        expr:histogram_quantile(0.99,sum(rate(vllm:e2e_request_latency_seconds_bucket[5m]))by(le))>30
        for:5m
        labels:
          severity:warning
        annotations:
          summary:"端到端 P99 延迟超过 30 秒"
          description:"当前 P99: {{ $value }}s"

5.3.3 Grafana Dashboard 面板建议

推荐创建以下面板（按行排列）：

第一行：概览

服务状态（Up/Down 指示灯）
当前 QPS（实时数字）
请求成功率（百分比）
等待队列长度

第二行：延迟

TTFT P50/P95/P99 时序图
E2E Latency P50/P95/P99 时序图
每请求 Token 输出速度

第三行：资源

GPU 显存使用率
GPU KV Cache 使用率
GPU 利用率和温度
CPU 内存使用

第四行：吞吐

Prompt Tokens/s
Generation Tokens/s
Running requests vs Waiting requests

六、总结

6.1 技术要点回顾

大模型服务的故障 80% 集中在超时、限流、OOM 三类。系统化的排错方法比经验更可靠——从症状出发，逐层排查，到根因止步
超时问题要分清是 TTFT 慢（prefill 阶段）还是 TPS 低（decode 阶段）还是连接超时（网络层），三者的排查路径完全不同
GPU OOM 的根因通常是 max-num-seqs、max-model-len、gpu-memory-utilization 三个参数的组合不合理。不要凭感觉调，用公式算出 KV Cache 的实际需求
限流配置要分层：Nginx 做第一层粗粒度限流，vLLM 的 max-num-seqs 做第二层保护，客户端做重试和降级。三层配合才能既保护服务又不影响用户
容器环境的 OOM Killed 和 GPU OOM 是两回事：前者是 CPU 内存不够（cgroup limit），后者是显存不够。区分清楚才能对症下药
预防大于治疗：部署前过检查清单，运行时盯核心监控，故障时靠自愈机制兜底

6.2 进阶学习方向

vLLM 源码分析：了解 PagedAttention、Continuous Batching、Speculative Decoding 的实现原理，有助于理解性能瓶颈的本质。推荐从 vllm/core/scheduler.py 开始读。
GPU 性能调优：CUDA Profiler（nsys/ncu）的使用、kernel 级别的性能分析。这块对排查"GPU 利用率高但吞吐上不去"的问题很有帮助。
分布式推理：Pipeline Parallelism、Tensor Parallelism、Expert Parallelism 的运维差异，多机多卡环境下 NCCL 的故障排查。

6.3 参考资料

vLLM 官方文档 - 配置参数和 API 参考
vLLM GitHub - Issue tracker 是排查已知 bug 的好地方
NVIDIA GPU 故障排查指南 - CUDA 错误排查
NCCL 官方文档 - 多卡通信故障排查
Prometheus Alerting Rules - 告警规则语法参考

附录

A. 报错速查表


错误码/信息                                     → 原因                          → 解决方案
─────────────────────────────────────────────────────────────────────────────────────────────
HTTP 429 Too Many Requests                     → 请求速率超过限流配置            → 调大 rate limit 或 burst
HTTP 500 Internal Server Error                 → 服务端内部错误                  → 查看 vLLM 日志定位具体错误
HTTP 502 Bad Gateway                           → 后端服务不可用                  → 检查 vLLM 进程是否存活
HTTP 503 Service Unavailable                   → 服务过载或维护中                → 检查负载和健康检查
HTTP 504 Gateway Timeout                       → 请求处理超时                    → 调大超时参数或降低 prompt 长度
torch.cuda.OutOfMemoryError                    → GPU 显存不足                    → 降低 gpu-memory-utilization/max-num-seqs
CUDA error: out of memory                      → CUDA 内存分配失败               → 重启进程，调整显存参数
CUDA error: device-side assert triggered       → GPU 计算异常                    → 检查模型文件，用 BF16
RuntimeError: NCCL communicator was aborted    → 多卡通信断开                    → 检查 GPU 拓扑和 shm-size
OSError: No space left on device               → 磁盘满                          → 清理日志和临时文件
ConnectionRefusedError                         → 服务未启动                      → 检查进程和端口
ValueError: max_model_len too large            → 上下文长度超过模型支持           → 降低 max-model-len
OOM Killed (exit code 137)                     → 容器/系统内存限制               → 调大 memory limit
SIGABRT (exit code 134)                        → 致命 assertion 失败             → 查日志，通常是 CUDA/NCCL 错误
KeyError: 'choices'                            → 响应格式异常                    → 服务端可能返回了错误，检查完整响应
asyncio.TimeoutError                           → 客户端异步超时                  → 调大 aiohttp/httpx timeout
ssl.SSLError                                   → TLS 证书问题                    → 检查证书有效期和配置

B. vLLM 关键参数速查

# 模型相关
--model <path_or_name>           # 模型路径或 HuggingFace 名称
--dtype auto|float16|bfloat16    # 推理精度，auto 自动选择
--quantization fp8|awq|gptq     # 量化方式
--max-model-len <int>            # 最大上下文长度（prompt + generation）
--trust-remote-code              # 允许执行模型仓库中的自定义代码

# 显存和缓存
--gpu-memory-utilization <0-1>   # GPU 显存使用比例（默认 0.9）
--swap-space <GB>                # CPU swap 空间大小（默认 4）
--kv-cache-dtype auto|fp8        # KV Cache 精度

# 并发和调度
--max-num-seqs <int>             # 最大并发序列数（默认 256）
--max-num-batched-tokens <int>   # 每个 batch 最大 token 数
--enable-chunked-prefill          # 启用分块预填充（推荐）
--max-paddings <int>             # 最大 padding 数

# 多卡
--tensor-parallel-size <int>     # 张量并行度（用多少张卡）
--pipeline-parallel-size <int>   # 流水线并行度

# 服务
--host <ip>                      # 监听地址（默认 localhost）
--port <int>                     # 监听端口（默认 8000）
--request-timeout <seconds>      # 单请求超时
--disable-log-requests           # 不记录每个请求（生产环境推荐）

# 监控
--enable-metrics                 # 启用 Prometheus metrics（默认启用）

常用参数组合速查：

# 小模型（< 10B），单卡，追求低延迟
--gpu-memory-utilization 0.85 --max-num-seqs 32 --max-model-len 32768

# 中模型（10-30B），单卡 A100 80G，平衡配置
--gpu-memory-utilization 0.88 --max-num-seqs 128 --max-model-len 16384 --enable-chunked-prefill

# 大模型（30-70B），双卡 A100 80G
--tensor-parallel-size 2 --gpu-memory-utilization 0.9 --max-num-seqs 200 --max-model-len 16384

# 超大模型（> 70B），4 卡 A100 80G
--tensor-parallel-size 4 --gpu-memory-utilization 0.92 --max-num-seqs 256 --max-model-len 8192

（版权归原作者所有，侵删）

免责声明：本文内容来源于网络，所载内容仅供参考。转载仅为学习和交流之目的，如无意中侵犯您的合法权益，请及时联系Docker中文社区！