Docker中文

Kubernetes v1.37 正式发布：67 项增强，AI 调度与平台安全再升级

Fri, 28 Aug 2026 18:28:36 +0800

北京时间 2026 年 8 月 26 日，Kubernetes 社区正式发布 Kubernetes v1.37，版本代号为Garhwal。

本次版本共包含67 项增强：

16 项功能升级至 Stable；
23 项功能升级至 Beta；
27 项功能进入 Alpha；
1 项弃用或移除变更。

Kubernetes v1.37 的重点集中在 AI/机器学习工作负载、资源调度、集群稳定性、安全隔离、存储管理和运维体验等方向。

一、HPA 支持工作负载缩容至零

在 Kubernetes v1.37 中，HorizontalPodAutoscaler（HPA）缩容至零的能力升级至 Beta，并默认启用。

对于队列消费者、批处理任务和 GPU 工作负载，当系统处于空闲状态时，HPA 可以将 Pod 数量缩减到 0；当外部指标或对象指标再次出现工作负载时，再自动恢复 Pod。

该能力适用于：

消息队列消费者；
定时或批量处理任务；
AI 推理服务；
低频访问的后台服务；
按需运行的计算任务。

需要注意的是，基于 CPU 和内存指标无法实现缩容至零，因为这些指标依赖正在运行的 Pod。该功能主要面向外部指标和对象指标场景。

二、Gang Scheduling 升级至 Beta

随着 Kubernetes 承载越来越多 AI/ML 训练任务和 HPC 作业，多个 Pod 必须同时获得资源才能运行的场景越来越普遍。

传统调度方式会逐个调度 Pod，可能出现部分 Pod 已经运行、剩余 Pod 一直等待资源的情况，最终导致任务无法取得进展。

Kubernetes v1.37 将 Gang Scheduling，也就是组调度能力升级至 Beta。它采用“全部调度或全部等待”的策略，确保一个工作负载所需的 Pod 能够整体获得资源。

该能力可以改善：

分布式 AI 训练；
大规模模型推理；
HPC 科学计算；
分布式批处理；
多 Pod 紧密协作的工作负载。

同时，v1.37 还引入了面向工作负载的抢占和 PodGroup 排队机制，减少无效抢占和多个任务之间反复争抢资源的问题。

三、DRA 能力进一步成熟

Dynamic Resource Allocation（DRA）是 Kubernetes 面向 GPU、NPU、网络设备和其他专用硬件的资源分配机制。

v1.37 中，多项 DRA 能力升级至 Stable，包括：

ResourceClaim 设备状态；
通过 DRA 驱动处理扩展资源请求；
设备 Taint 和 Toleration；
设备 NUMA 节点属性。

这意味着 Kubernetes 可以更细致地管理异构硬件资源。

例如，Pod 可以继续使用传统扩展资源方式请求设备：

resources:  limits:    example.com/gpu: 3

同时由 DRA 驱动完成设备分配，而不一定需要单独部署传统 Device Plugin。

对于 AI 基础设施团队而言，这将有助于实现更灵活的 GPU 调度、设备隔离和 NUMA 感知调度。

四、metrics.k8s.io API 正式进入 Stable

经过近九年的 Beta 阶段，metrics.k8s.io API 在 Kubernetes v1.37 中升级至 Stable。

该 API 为 Kubernetes 提供 Pod 和节点的 CPU、内存使用指标，广泛用于：

kubectl top；
HorizontalPodAutoscaler；
集群资源监控；
基础资源利用率分析。

v1.37 不会立即移除 v1beta1，现有工作流可以继续使用。未来 Kubernetes 将逐步以稳定版 v1 API 为主要接口。

这对监控系统、自动扩缩容组件和第三方控制器来说，是一个重要的稳定性信号。

五、API Server 启动和恢复更加稳定

Kubernetes v1.37 完成了 Watch Cache 初始化增强，进一步降低 API Server 启动或恢复期间对 etcd 造成的压力。

在大型集群中，Watch Cache 初始化可能触发大量 List 和 Watch 请求。如果请求同时涌入 etcd，可能导致控制平面出现延迟甚至服务不可用。

v1.37 会对这类请求进行更合理的限制：

避免请求集中冲击 etcd；
控制 API Priority and Fairness 压力；
对无法立即处理的请求返回 HTTP 429；
通过 Retry-After 引导客户端重试。

因此，自定义 Controller 和 Operator 应正确处理 HTTP 429，并实现指数退避重试。

六、SELinuxMount 与 SELinuxChangePolicy 升级至 Stable

Kubernetes v1.37 将 SELinuxMount 和 SELinuxChangePolicy 升级至 Stable，并默认启用相关行为。

符合条件的 CSI 驱动可以使用挂载上下文：

-o context=<label>

这种方式可以避免传统的递归重新标记，从而改善部分存储卷挂载场景的性能。

不过，单个挂载只能携带一个 SELinux 上下文。如果多个使用不同 SELinux 标签的 Pod 共享同一个存储卷，升级后可能出现 Pod 无法启动的情况。

启用了 SELinux 的生产集群，升级前应检查：

CSI 驱动是否支持 SELinuxMount；
不同安全标签的 Pod 是否共享存储卷；
存储卷挂载和卸载是否正常；
是否需要为特定工作负载设置 seLinuxChangePolicy: Recursive。

未启用 SELinux 的集群通常不会受到影响。

七、StorageVersionMigration API 升级至 Stable

Kubernetes v1.37 将 StorageVersionMigration API 升级至 Stable，并默认启用。

当 API 版本发生变化，或者存储加密配置需要更新时，集群中的历史资源可能需要重新写入。

过去，管理员通常需要使用脚本执行大量 kubectl get 和 kubectl replace 操作。现在，可以通过声明式的 StorageVersionMigration 对象触发资源迁移，由 Kubernetes 控制器自动完成。

该能力适用于：

API 存储版本升级；
CRD 版本迁移；
加密配置更新；
大规模资源重新写入。

这将降低集群升级和 API 演进过程中的运维复杂度。

八、Pod 证书与集群信任包升级至 Stable

Pod Certificates 和 ClusterTrustBundles 在 Kubernetes v1.37 中升级至 Stable。

这为 Pod 提供了更加标准化的证书和信任根分发机制，支持向工作负载提供：

私钥；
X.509 证书；
集群信任包；
自动刷新后的身份凭据。

该能力可以用于服务间双向 TLS、工作负载身份认证和集群内部安全通信，减少应用自行管理证书的复杂度。

九、KYAML 正式进入 Stable

KYAML 是 Kubernetes 面向 YAML 配置推出的更加严格、明确的格式子集。

它不是 YAML 的替代品，而是 YAML 的一种更安全、更少歧义的写法。所有 KYAML 文件仍然是合法 YAML，因此现有 kubectl 和大多数 YAML 工具无需改变即可继续使用。

在 v1.37 中：

kubectl get -o kyaml

正式进入 Stable。

对于配置规模较大的团队，KYAML 有助于降低 YAML 隐式类型和格式歧义带来的问题。

十、需要关注的兼容性变化

kube-proxy 的 IPVS 模式进入弃用阶段

Kubernetes v1.37 开始对 kube-proxy 的 IPVS 模式发出弃用警告。

官方后续计划是：

v1.37：开始弃用提示；
预计 v1.40：默认禁用；
预计 v1.43：完全移除。

正在使用 IPVS 模式的集群，应提前评估 nftables 或其他网络方案。

可以通过以下命令检查当前配置：

kubectl -n kube-system get configmap kube-proxy \  -o jsonpath='{.data.config\.conf}' | grep 'mode:'

此外，Static Pod 不再允许引用 Secret 或 ConfigMap，仍使用 cgroup v1 的节点也应尽快迁移到 cgroup v2。

Docker 用户如何看待 Kubernetes v1.37？

Docker 负责容器镜像构建、开发环境运行和本地调试，Kubernetes 则负责生产环境中的容器编排、调度、扩缩容和故障自愈。

一个常见工作流是：

使用 Docker 构建应用镜像；
在 Docker 环境中完成容器测试；
使用 Kubernetes 清单或 Helm 部署应用；
通过 Kubernetes 管理生产工作负载；
使用监控、日志和策略系统完成持续运维。

Kubernetes v1.37 对 Docker 用户最直接的影响包括：

更好地支持 AI 和 GPU 工作负载；
HPA 可以将部分服务缩容到零；
metrics.k8s.io API 更加稳定；
存储和安全能力进一步增强；
集群升级时需要关注 IPVS、SELinux 和 cgroup v2。

升级建议

生产环境升级 Kubernetes v1.37 前，建议重点检查：

容器运行时和 CNI、CSI 插件的兼容性；
kube-proxy 是否使用 IPVS；
节点是否仍依赖 cgroup v1；
Static Pod 是否引用 Secret 或 ConfigMap；
SELinux 与 CSI 存储卷行为；
自定义 Controller 是否能够处理 HTTP 429；
监控系统是否兼容稳定版 metrics API；
GPU、NPU 和其他设备插件是否支持 DRA。

建议先在测试集群验证，再采用分批、灰度方式升级生产环境。

结语

Kubernetes v1.37 的正式发布，标志着 Kubernetes 在 AI 工作负载、异构资源调度、集群稳定性和安全隔离方面继续向前推进。

其中，HPA 缩容至零、Gang Scheduling、DRA 稳定化、metrics.k8s.io API GA、StorageVersionMigration GA，以及 Pod 证书能力，都是值得平台工程团队重点关注的变化。

对于 Docker 用户来说，Kubernetes v1.37 不只是一次版本升级，更是从容器运行走向智能调度、统一资源管理和平台化交付的重要一步。

官方参考资料：

Kubernetes v1.37 正式发布公告
https://kubernetes.io/blog/2026/08/26/kubernetes-v1-37-release/
Kubernetes v1.37 官方版本页面
https://kubernetes.io/releases/1.37/
Kubernetes v1.37 CHANGELOG
https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.37.md
Kubernetes 官方博客
https://kubernetes.io/blog/

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

Nginx 502 故障排查指南：日志分析与配置陷阱定位

Tue, 18 Aug 2026 18:38:00 +0800

引言

502 Bad Gateway 是 Nginx 作为反向代理服务器时最常遭遇的错误状态码。这个错误意味着 Nginx 作为网关，成功与后端 upstream 建立了连接，但后端返回了一个无效响应，或者在传输过程中连接被异常关闭。表面上 502 只是一个 HTTP 状态码，实际上它是一系列配置错误、网络故障、后端异常的综合表现。

本文基于 Nginx 1.26.x/1.27.x（截至 2026 年 4 月的稳定版本）、PHP-FPM 8.2/8.3、Node.js 20 LTS/22 LTS 等最新稳定版本，系统性地拆解 502 错误的成因、排查方法、解决方案和预防策略。文章假设读者具备基本的 Linux 运维能力、Nginx 配置文件阅读经验，以及后端应用的调试基础。

一、问题场景：为什么需要关注 502 错误

1.1 502 是最常见的 Nginx 错误

在生产环境中，Nginx 作为入口网关承接所有外部流量。一旦出现 502 错误，意味着用户请求无法正常处理，直接影响业务可用性。根据多个大型网站的运维统计，Nginx 相关故障中 502 Bad Gateway 占到了 40% 至 60%，是所有 Nginx 错误码中出现频率最高的一种。

业务影响量化

用户点击链接后遭遇 502 页面，平均停留时长不超过 3 秒即会离开。对于电商网站，这直接导致购物车 abandonment；对于金融交易系统，502 可能意味着交易中断甚至数据不一致；对于 API 服务，502 会触发客户端重试风暴，进一步压垮后端。行业通用的估算公式是：每 1% 的 502 错误率可能导致 0.5% 至 2% 的业务损失，具体取决于业务类型和用户耐心度。

根因多样性与排查复杂性

502 错误的根因涵盖多个层面：网络层（物理链路中断、DNS 解析失败、防火墙拦截）、传输层（TCP 连接被重置、端口未监听）、应用层（后端进程崩溃、超时配置不合理、缓冲区溢出）、系统层（文件描述符耗尽、内存不足、内核参数限制）、安全层（SELinux/AppArmor 强制访问控制、iptables 规则拦截）。这种多层次性导致同一个 502 症状可能对应完全不同的根因。

多层代理架构进一步增加了排查难度。现代生产环境中，请求可能经过 CDN → 边缘 Nginx → 负载均衡层 → 应用 Nginx → 后端服务，其中任何一个节点的故障都可能以 502 形式呈现。而日志分散在多个层级，request_id 串联成为必要手段而非可选项。

日志阅读能力缺失是排查失败的主因

大量工程师遇到 502 后的第一反应是重启 Nginx 或后端服务，这种做法往往只能短暂恢复问题，无法根治。更深层的问题在于：Nginx error.log 中已经记录了详细的错误原因，但工程师不知道如何解读这些日志条目。例如"upstream prematurely closed connection"和"connect() failed (111: Connection refused)"虽然都导致 502，但指向的根因完全不同，处理方式也截然不同。

1.2 502 与 504：同样的网关错误，不同的根因

理解 HTTP 502 与 504 的本质区别，是准确定位问题的前提。

502 Bad Gateway

Nginx 向 upstream 发起请求并成功建立连接，但 upstream 返回了非正常的响应。这个响应可能是：连接建立后立即关闭（无任何数据返回）、返回了无效的 HTTP 响应（格式损坏）、连接被上游设备中断（RST 包）、或者 upstream 在协议层面出现错误（Nginx 无法解析上游的响应）。

典型错误日志：

2026/04/24 08:15:32 [error] 12487#12487: *8921 upstream prematurely closed connection while reading response header of upstream, client: 203.0.113.45, server: api.example.com, request: "GET /api/v2/users HTTP/1.1", upstream: "http://127.0.0.1:8080/api/v2/users", upstream_connection: "9612", upstream_bytes_sent: 0, upstream_bytes_received: 0, upstream_trailers: "X-Request-Id: abc123"

2026/04/24 09:22:18 [error] 12487#12487: *9234 connect() failed (111: Connection refused) while connecting to upstream, client: 198.51.100.23, server: www.example.com, request: "POST /api/orders HTTP/1.1", upstream: "http://127.0.0.1:9000/api/orders", upstream_connection: "128"

504 Gateway Timeout

Nginx 向 upstream 发起请求并成功建立了 TCP 连接，但 upstream 在规定时间内没有返回任何数据。超时触发后，Nginx 主动关闭连接并向客户端返回 504。504 的根因通常是后端处理时间过长（数据库查询阻塞、第三方 API 调用卡住、计算密集型任务卡死），或者 upstream 进程处于僵死状态（不崩溃但不处理请求）。

典型错误日志：

2026/04/24 10:45:07 [error] 12487#12487: *10234 upstream timed out (110: Connection timed out) while reading response header of upstream, client: 203.0.113.89, server: api.example.com, request: "GET /api/reports HTTP/1.1", upstream: "http://127.0.0.1:8080/api/reports", upstream_connection: "15623", upstream_bytes_sent: 234, upstream_bytes_received: 0

2026/04/24 11:02:33 [error] 12487#12487: *10891 upstream timed out (110: Connection timed out) after 30000 ms (110: Connection timed out) while connecting to upstream, client: 198.51.100.67, server: www.example.com, request: "POST /api/upload HTTP/1.1", upstream: "http://127.0.0.1:9090/api/upload"

499 Client Closed Request

这不是 Nginx 返回给客户端的错误码，而是 Nginx 记录的一种状态，表示客户端在 upstream 响应完成之前主动断开了连接（可能是客户端超时、用户取消请求、Nginx 侧配置了 client_body_timeout 或lingering_timeout 强制关闭）。499 不算 upstream 的故障，但在高并发场景下大量出现 499 可能暗示 upstream 处理速度过慢，迫使客户端等待超时。

2026/04/24 12:18:45 [info] 12487#12487: *11567 client closed connection while waiting for response, client: 203.0.113.112, server: api.example.com, request: "GET /api/stream HTTP/1.1", upstream: "http://127.0.0.1:8080/api/stream"

500 vs 503 vs 502：细节差异

500 Internal Server Error：请求已经到达 upstream，upstream 在处理过程中发生了未捕获的异常或配置错误导致崩溃。这是 upstream 自身的问题，Nginx 只是转发了上游的错误响应。
503 Service Temporarily Unavailable：upstream 正常工作且能够响应，但 Nginx 的限流模块（limit_req_zone）或连接数限制（limit_conn_zone）触发了降级。503 通常带有 Retry-After 头，暗示客户端稍后重试。
502 Bad Gateway：upstream 连接失败或返回了无效响应。可能是 upstream 彻底不可用，也可能是连接建立后数据交换过程中断裂。

1.3 典型踩坑场景分类

在多年的生产环境排障经历中，502 错误可以归纳为以下典型场景。每个场景都有其特征性日志和明确的解决路径。

场景一：upstream 配置错误

最基础的配置错误是 ip:port 写错或域名解析失败。Nginx 启动时不会验证 upstream 的可到达性，只有在实际请求时才会尝试连接。如果配置中写错了 IP 地址（例如 127.0.0.18 而不是 127.0.0.1），或者端口号与实际监听不一致，Nginx 会在 error.log 中记录"Connection refused"错误。

# 错误配置示例
upstream backend {
    server 127.0.0.1:8081;  # 实际服务运行在 8080 端口
}

# 正确配置
upstream backend {
    server 127.0.0.1:8080;
}

场景二：后端服务未启动

这是最常见也最容易被忽视的场景。Nginx 进程由 systemd 托管可以保证 Nginx 自身的高可用，但后端服务（PHP-FPM、Node.js 应用、Gunicorn、Tomcat 等）可能因为各种原因退出：OOM Killer 杀死进程、代码 bug 导致崩溃、依赖的数据库或中间件不可用。Nginx 仍然在运行，请求到达后才发现 upstream 无响应。

# systemctl 检查 PHP-FPM 状态
$ systemctl status php-fpm
● php-fpm.service - PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Thu 2026-04-24 08:00:12 CST; 2h 15min ago
    Main PID: 4521 (code=exited, status=0/SUCCESS)

场景三：超时设置过短

Nginx 的默认超时值通常比较保守（proxy_connect_timeout 60s、proxy_read_timeout 60s）。对于处理时间较长的请求（如文件上传、大数据量导出、复杂数据库查询、调用外部 API），默认超时会导致正常请求被误杀。

# 默认超时配置（过短）
proxy_read_timeout 60s;  # 60秒对于复杂查询不够

# 优化后的超时配置
proxy_read_timeout 300s;  # 根据业务特点调整
proxy_connect_timeout 10s;  # 连接超时可以保持较短

场景四：缓冲区配置不当

Nginx 使用缓冲区来暂存 upstream 的响应数据。当 upstream 返回大文件或流式数据时，缓冲区配置不足会导致内存溢出或写入磁盘临时文件，极端情况下会触发 502。缓冲区满的症状是 error.log 中出现"upstream buffer is too small"或大量临时文件被写入 /var/lib/nginx/proxy。

# 缓冲区不足的典型日志
2026/04/24 14:22:15 [warn] 12487#12487: *12891 an upstream response is buffered to a temporary file /var/lib/nginx/proxy/0000000123, size: 16384 bytes, expect: 5242880 bytes

场景五：keepalive 配置缺失

HTTP/1.1 默认支持 keepalive 连接复用。如果 upstream 块中没有配置 keepalive，Nginx 会为每个请求创建新的 TCP 连接。高并发场景下，频繁的 TCP 握手/挥手消耗大量资源，可能导致 upstream 过载或连接数溢出。

# 没有 keepalive 的 upstream 配置
upstream backend {
    server 127.0.0.1:8080;
}

# 优化后：配置 keepalive 连接池
upstream backend {
    server 127.0.0.1:8080;
    keepalive 32;  # 保持 32 个空闲连接
    keepalive_requests 1000;  # 每个连接最多处理 1000 请求
    keepalive_timeout 60s;  # 空闲连接保持 60 秒
}

场景六：权限问题

当 upstream 使用 Unix Domain Socket 通信时，socket 文件的权限和所有权必须与 Nginx worker 进程的用户匹配。PHP-FPM 默认使用 www-data 用户创建 socket，而 Nginx 默认使用 nginx 用户运行 worker 进程，两者不匹配时会导致"Permission denied"错误。

# /var/log/nginx/error.log 中的权限错误
2026/04/24 15:33:27 [crit] 12487#12487: *13456 connect() to unix:/var/run/php-fpm/www.sock failed (13: Permission denied) while connecting to upstream

SELinux 强制访问控制是另一个容易忽视的权限问题。即使 socket 文件权限正确，SELinux 策略也可能阻止 Nginx 与后端通信。

二、核心原理与关键概念拆解

2.1 Nginx 处理请求的完整流程

理解 Nginx 内部处理请求的各个阶段，是准确定位 502 根因的基础。Nginx 采用模块化架构，请求处理分为 11 个阶段（phase）：post-read、server-rewrite、find-config、rewrite、post-rewrite、preaccess、access、post-access、precontent、content、log。502 错误主要发生在 content 阶段和 log 阶段之间。

连接接受阶段

Nginx master 进程监听配置的端口（80/443），worker 进程通过 accept_mutex 机制竞争接受新连接。在多核系统中，Nginx 默认使用 epoll 事件模型高效处理大量并发连接。关键配置参数：

worker_connections：每个 worker 进程可处理的最大连接数（默认 512）
multi_accept on：每个 worker 进程尽可能多地接受新连接
use epoll：使用 epoll 事件模型（Linux 高效）

# 查看当前 Nginx 连接状态
$ ss -s
Total: 298 (kernel 0)
TCP:   185 (estab 142, closed 12, orphaned 0, synrecv 0, timewait 5/0)

Transport Total     IP        IPv6
*         298       -         -
RAW       0         0         0
UDP       12        8         4
TCP       173       166       7
INET      185       174       11
FRAG      0         0         0

$ nginx -V 2>&1 | grep -o 'with-http_stub_status_module'
with-http_stub_status_module

# 启用状态页面查看连接详情
location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

$ curl http://127.0.0.1/nginx_status
Active connections: 142
server accepts handled requests
 1289345 1289345 3456782
Reading: 3 Writing: 12 Waiting: 127

请求解析与 Location 匹配

连接接受后，Nginx 解析 HTTP 请求行和请求头，根据 server_name（基于 Host header 匹配）和 location 块（精确匹配或正则匹配）确定请求的处理方式。对于反向代理配置，请求最终会进入 proxy_pass 或 fastcgi_pass 处理。

# nginx.conf 中的 server 块和 location 匹配示例
server {
    listen 80;
    server_name api.example.com;

    # 精确匹配 /api/
    location = /api/ {
        proxy_pass http://backend_api;
    }

    # 前缀匹配 /api/v2/
    location /api/v2/ {
        proxy_pass http://backend_v2;
    }

    # 正则匹配（~ 区分大小写，~* 不区分大小写）
    location ~* ^/api/v\d+/users {
        proxy_pass http://backend_users;
    }
}

代理转发阶段

请求匹配到 proxy_pass 或 fastcgi_pass 后，Nginx 作为反向代理与 upstream 通信。反向代理的核心流程：

解析 proxy_pass 指令，确定 upstream 地址
从 upstream 块中选择一个 server（默认加权轮询）
建立与 upstream 的 TCP 连接（触发 connect 事件）
发送 HTTP 请求（可能受限于 send_timeout）
接收 upstream 响应头（受限于 proxy_read_timeout）
接收 upstream 响应体（受限于 buffer 配置）
将响应转发给客户端

# 核心 proxy 配置解析
location / {
    proxy_pass http://backend;  # 指向 upstream 块

    # 以下请求头默认会被传递
    # Host: $host
    # X-Real-IP: $remote_addr
    # X-Forwarded-For: $proxy_add_x_forwarded_for
    # X-Forwarded-Proto: $scheme

    proxy_http_version 1.1;  # 默认 1.0，1.1 支持 chunked 编码
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

响应处理与缓冲区机制

Nginx 收到 upstream 响应后，先将响应头存入 proxy_buffer_size（默认 4k/8k），响应体存入 proxy_buffers 配置的缓冲区。如果响应体数据量超过可用缓冲区总和，剩余数据会写入磁盘临时文件（受 proxy_max_temp_file_size 限制，默认 1024m）。

缓冲区满或写入临时文件时，Nginx 不会立即返回 502，但如果 upstream 发送速度过快且 buffer 机制未启用（proxy_buffering off），则可能出现数据积压导致超时。

# 缓冲区配置详解
proxy_buffering on;  # 启用缓冲区（默认开启）
proxy_buffer_size 128k;  # 响应头缓冲区，通常 128k 足够
proxy_buffers 8 256k;  # 8 个 256k 缓冲区，用于响应体
proxy_busy_buffer_size 256k;  # 忙碌时使用的缓冲区大小
proxy_max_temp_file_size 1024m;  # 临时文件总大小上限
proxy_temp_file_write_size 128k;  # 每次写入临时文件的大小

连接关闭与 keepalive

HTTP/1.1 默认使用 keepalive 保持连接复用。Nginx 通过 keepalive_timeout 控制连接保持打开的空闲时间，通过 keepalive_requests 限制单个连接处理的最大请求数。proxy 模块通过 proxy_http_version 1.1 和 proxy_set_header Connection "" 来管理与 upstream 的 keepalive 连接。

# upstream keepalive 配置
upstream backend {
    server 127.0.0.1:8080;
    keepalive 32;  # 保持 32 个空闲连接
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;  # 必须使用 1.1 才能支持 keepalive
    proxy_set_header Connection "";  # 清除 Connection 头
}

2.2 upstream 健康检查机制

Nginx upstream 模块支持被动健康检查，通过 max_fails 和 fail_timeout 参数实现故障节点的自动剔除。对于需要主动探测的场景，可以使用第三方模块 nginx_upstream_check_module。

被动健康检查

Nginx 默认对每个 upstream server 进行被动健康检查。当某个 server 连续 max_fails 次连接失败（Connection refused、timeout 等），Nginx 会将该 server 标记为不可用，持续 fail_timeout 秒后重新尝试。

# upstream 被动健康检查配置
upstream backend {
    server 127.0.0.1:8080 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8081 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8082 max_fails=3 fail_timeout=10s backup;
}

参数说明：

max_fails：默认 1。设置为 0 则禁用对该 server 的健康检查。
fail_timeout：默认 10s。既是 server 被判定为不可用后持续的时间，也是统计失败次数的时间窗口。
backup：标记为备用服务器，仅在主服务器全部不可用时才启用。

# 查看 upstream 配置和状态
$ nginx -T 2>&1 | grep -A 20 "upstream backend"
upstream backend {
    server 127.0.0.1:8080 weight=5 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8081 weight=3 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:8082 backup;
}

# 观察 error.log 中标记 server 不可用的日志
2026/04/24 08:05:12 [warn] 12487#12487: *2341 upstream server temporarily disabled while connecting to upstream, client: 203.0.113.45, server: api.example.com, request: "GET /api/health HTTP/1.1", upstream: "http://127.0.0.1:8080/api/health"

主动健康检查（nginx_upstream_check_module）

官方 Nginx 不包含主动健康检查模块，需要使用阿里巴巴开源的 nginx_upstream_check_module。该模块允许 Nginx 主动向后端发送 TCP/HTTP 心跳包，根据响应判断 server 是否健康。

# 编译安装时加载模块
./configure --add-module=/path/to/nginx_upstream_check_module

# upstream 配置中添加主动健康检查
upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;

    # 每隔 3 秒对所有 server 进行检查
    # 检查类型为 HTTP，检查 URI /health
    # 超时 1 秒，连续失败 2 次则标记为不可用
    check interval=3000 rise=2 fall=2 timeout=1000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

# 状态页面查看健康检查结果
location /upstream_status {
    check_status;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

$ curl http://127.0.0.1/upstream_status
Upstream server status:
backend
  server 127.0.0.1:8080      up      1234567890 ms
  server 127.0.0.1:8081      down    0 ms (2/2)

动态 upstream 与服务发现

在容器化和微服务架构中，upstream 列表需要动态更新。常见方案：

Consul/Etcd + Consul-template 或 etcd dynamical：通过服务发现系统维护后端列表，使用模板工具动态生成 Nginx 配置文件并 reload。
OpenResty + lua-upstream-nginx-module：使用 Lua 脚本直接操作 Nginx upstream 内存结构，实现运行时更新。
Nginx Plus 商业版：原生支持 DNS 发现和 API 动态修改 upstream。

# consul-template 配置文件示例
upstream backend {
  least_conn;

  {{ range service "backend" }}
  server {{ .Address }}:{{ .Port }};
  {{ end }}
}

2.3 缓冲区机制深度解析

缓冲区是 Nginx 与 upstream 之间数据传输的核心机制。理解缓冲区的工作方式，能够解释许多看似莫名其妙的超时和 502 错误。

proxy_buffer_size：响应头缓冲区

Nginx 收到 upstream 的响应状态行和响应头后，将其存储在 proxy_buffer_size 指定的内存区域中。默认值为 4k 或 8k（取决于操作系统页大小）。对于绝大多数 HTTP 响应头，这个大小足够。如果 upstream 返回的响应头过大（如大量 Cookie、复杂 CSP 头），可能需要增大此值。

# 响应头过大时的错误日志
2026/04/24 09:15:33 [warn] 12487#12487: *4521 could not build large header, shoulder increase the size of proxy_buffer_size

# 调整响应头缓冲区
proxy_buffer_size 256k;  # 增大到 256k

proxy_buffers：响应体缓冲区

响应体数据块被缓存在 proxy_buffers 分配的内存缓冲区中。如果响应体总大小超过所有缓冲区的总容量，剩余数据会写入磁盘临时文件。临时文件路径由 proxy_temp_path 指定（默认 /var/lib/nginx/proxy）。

# 默认配置
proxy_buffers 8 4k/8k;  # 8 个缓冲区，每个 4k 或 8k

# 大文件下载场景
proxy_buffers 16 32k;
proxy_buffering on;  # 确保启用
proxy_max_temp_file_size 2048m;  # 允许最大 2G 临时文件

# 出现大量临时文件时的告警日志
2026/04/24 10:22:15 [warn] 12487#12487: *7823 upstream sent chunked body with size larger than the whole proxy buffers space while reading upstream

proxy_busy_buffer_size：忙碌缓冲区

当 Nginx 开始向客户端发送响应时，如果客户端网络速度较慢，Nginx 会继续从 upstream 读取数据并存入缓冲区。proxy_busy_buffer_size 定义了在等待客户端接收数据时可以使用的最大缓冲区总大小。默认等于 proxy_buffer_size 或 proxy_buffers 中的单个缓冲区大小。

fastcgi_buffering / uwsgi_buffering / scgi_buffering

对于 PHP-FPM 环境，使用 fastcgi_pass 时，缓冲区配置指令前缀变为 fastcgi_buffer_。原理与 proxy buffering 完全一致。

# PHP-FPM 环境缓冲区配置
fastcgi_buffering on;
fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;
fastcgi_busy_buffers_size 256k;
fastcgi_max_temp_file_size 1024m;
fastcgi_temp_file_write_size 128k;

2.4 超时体系全面解析

Nginx 的超时配置构成一个多层次的体系，不同的超时指令控制请求处理的不同阶段。错误地设置超时是导致 502 和 504 的最常见原因。

proxy_connect_timeout：建立连接的超时

Nginx 等待与 upstream 建立 TCP 握手完成的超时。如果 upstream 服务器的端口未监听或网络不通，这个超时会在第一次连接尝试时触发。默认值 60s 通常足够，但如果 upstream 位于跨地域网络或高负载环境中，可能需要适当调大。

# 默认 60 秒，跨地域场景可调大
proxy_connect_timeout 60s;

# 高延迟网络环境
proxy_connect_timeout 10s;  # 10 秒足够检测出不可达

# connect timeout 的错误日志
2026/04/24 11:05:08 [error] 12487#12487: *8921 connect() failed (110: Connection timed out) while connecting to upstream, client: 203.0.113.45, upstream: "http://10.0.1.55:8080/"

proxy_send_timeout：向后端发送请求的超时

Nginx 向 upstream 发送请求体的超时。对于 POST/PUT 请求（表单提交、文件上传、API 调用），如果请求体数据量大或上游处理慢，可能触发此超时。默认值 60s。

# 文件上传等大请求场景
proxy_send_timeout 300s;  # 5 分钟
client_max_body_size 100m;  # 允许最大请求体 100M

proxy_read_timeout：读取后端响应的超时

Nginx 从 upstream 读取响应头和响应体的总超时。这是生产环境中最常需要调整的参数。默认值 60s，对于复杂业务逻辑、数据库查询、第三方 API 调用等场景，60s 往往不够。

# 长时间处理的后端服务
proxy_read_timeout 300s;  # 5 分钟
proxy_send_timeout 300s;

# 实时性要求高的 API
proxy_read_timeout 30s;

# read timeout 的错误日志
2026/04/24 12:30:45 [error] 12487#12487: *10234 upstream timed out (110: Connection timed out) while reading response header of upstream, client: 198.51.100.23, upstream: "http://127.0.0.1:8080/api/report"

send_timeout：发送给客户端的超时

控制 Nginx 向客户端发送数据的超时，与 upstream 无关。如果客户端网络慢或客户端停滞，Nginx 在 send_timeout 期间未发送任何数据后会关闭连接。这个超时不影响 502，但可能导致客户端收到不完整的响应。

# 默认 60 秒
send_timeout 60s;

keepalive_timeout：keepalive 空呆时间

HTTP/1.1 keepalive 连接在空闲状态下保持的最大时间。超过此时间未收到任何数据，Nginx 会主动关闭连接。

# keepalive 超时设置
keepalive_timeout 75s;  # 默认 75 秒
keepalive_requests 1000;  # 单连接最大请求数

超时时间的实际计算逻辑

多个超时参数可能同时生效。Nginx 在各个阶段分别计时：

TCP 连接建立：proxy_connect_timeout
请求体发送：proxy_send_timeout（从连接建立到请求体发送完成）
等待响应头：proxy_read_timeout（从请求发送完成到收到响应头）
读取响应体：proxy_read_timeout 继续累积（从收到响应头到响应体读取完成）

三、实战步骤与常见排障路径

3.1 502 问题排查的黄金法则

502 错误的排查需要遵循系统化的步骤，从表象到根因逐层递进。下列步骤经过大量生产环境验证，可以快速定位绝大多数 502 问题。

第一步：确认是否真的是 502

使用 curl -v 查看详细的 HTTP 交互过程，观察 502 是在哪个阶段发生的。

$ curl -v http://api.example.com/api/v2/users 2>&1
* About to connect() to api.example.com port 80 (#0)
*   Trying 203.0.113.10...
* Connected to api.example.com (203.0.113.10) port 80 (#0)
> GET /api/v2/users HTTP/1.1
> User-Agent: curl/8.4.0
> Host: api.example.com
> Accept: */*
>
< HTTP/1.1 502 Bad Gateway
< Server: nginx/1.26.2
< Date: Fri, 24 Apr 2026 08:00:12 GMT
< Content-Type: text/html
< Content-Length: 157
< Connection: keep-alive
<
{ [data not shown]
* Connection #0 to host api.example.com left intact
* Closure expected

从 curl 输出可以确认：TCP 连接成功建立（Connected），Nginx 返回了 502 状态码，Server 头显示 Nginx 版本为 1.26.2。这说明问题发生在 Nginx 与 upstream 之间。

第二步：检查 Nginx 错误日志

Nginx error.log 是定位 502 根因的第一手资料。配置 error_log 级别为 info 或 debug 可以获取更详细的调试信息，但需要注意日志量激增对磁盘和性能的影响。

# 实时跟踪 error.log 中的 502 相关错误
$ tail -f /var/log/nginx/error.log | grep -E "(502|upstream|connect|timed out)"

# 统计最近 1000 条日志中各类错误的数量
$ awk '/\[error\]/ {count++} /502/ {502count++} /timed out/ {timeout++} /Connection refused/ {refused++} END {print "Total errors:", count, "502 errors:", 502count, "Timeouts:", timeout, "Connection refused:", refused}' /var/log/nginx/error.log
Total errors: 234 502 errors: 45 Timeouts: 12 Connection refused: 33

# 查看错误上下文（前后 5 行）
$ grep -C 5 "502" /var/log/nginx/error.log | head -100

# 统计 502 错误的来源 IP
$ awk '/502/ && /client: / {gsub(/,.*/, "", $6); print $6}' /var/log/nginx/error.log | sort | uniq -c | sort -rn
     23 203.0.113.45
     15 198.51.100.123
      7 192.0.2.89

# error.log 配置建议
error_log /var/log/nginx/error.log warn;  # 生产环境使用 warn 级别，调试时使用 info

# 调试时临时开启 debug（仅限测试环境）
error_log /var/log/nginx/error.log debug;
# debug 日志量极大，务必在完成调试后恢复

第三步：检查后端服务状态

后端服务未启动或异常是最常见的 502 根因。检查后端进程是否存活、端口/socket 是否监听、进程资源使用情况。

# 检查 PHP-FPM 进程状态
$ systemctl status php-fpm
● php-fpm.service - PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-04-24 06:00:00 CST; 2h 15min ago
   Main PID: 4521 (php-fpm)
     Status: "祥 system is running..."
     Tasks: 12 (limit: 32768)
     Memory: 245.6M
     CGroup: /system.slice/php-fpm.service
             ├─4521 php-fpm: master process (/etc/php-fpm.conf)
             ├─4522 php-fpm: pool www
             ├─4523 php-fpm: pool www
             └─4524 php-fpm: pool www

# 检查监听端口
$ ss -tlnp | grep -E ':(80|443|8080|9000|php)'
State    Recv-Q   Send-Q   Local Address:Port    Peer Address:Port   Process
LISTEN   0        511      127.0.0.1:9000         0.0.0.0:*           users:(("php-fpm",pid=4522,fd=9),("php-fpm",pid=4523,fd=9))
LISTEN   0        511      0.0.0.0:8080           0.0.0.0:*           users:(("node",pid=3421,fd=18))
LISTEN   0        511      0.0.0.0:80             0.0.0.0:*           users:(("nginx",pid=12487,fd=6),("nginx",pid=12488,fd=6))

# 如果使用 Unix socket
$ ls -la /var/run/php-fpm/
total 8
srwxr-xr-x 3 root www-data www-data 120 Apr 24 06:00 /var/run/php-fpm/
srwxrwxrwx 1 www-data www-data   6 Apr 24 06:00 www.sock

# 测试 socket 连接性（使用 php-fpm 官方探活接口）
$ SCRIPT_NAME=/ping SCRIPT_FILENAME=/ping REQUEST_METHOD=GET cgi-fcgi -bind -connect /var/run/php-fpm/www.sock
Content-type: text/plain
X-Powered-By: PHP 8.3.8
Status: 200 OK
X-Request-Id: abc123
Free: 1
MPool: enabled
Prober: builtin
Content-Length: 6
OK

# 检查后端进程 CPU 和内存占用
$ top -b -n 1 | head -20
top - 08:15:33 up 42 days,  3:22,  2 users,  load average: 3.45, 2.89, 2.76
Tasks: 287 total,   5 running, 282 sleeping,   0 stopped,   0 zombie
%Cpu(s): 78.5 us, 12.3 sy,  0.0 ni,  9.2 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :  32768.0 total,   4523.4 free,  18234.5 used,  10010.1 buff/cache
MiB Swap:   8192.0 total,   8192.0 free,      0.0 used.  11234.3 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
 4522 www-data  20   0  523456  28934   9212 S  45.2   0.1  234:56 php-fpm
 4523 www-data  20   0  512234  24567   8734 S  38.7   0.1  198:34 php-fpm
 3421 root      20   0 1245678 456123  23456 S  12.3   1.4   56:78 node

第四步：确认网络连通性

排除物理网络层面的问题。即使 upstream 在本机，也需要验证端口可连接性。

# telnet 测试端口连通性（交互式命令，Ctrl+] 退出）
$ telnet 127.0.0.1 8080
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

# nc 测试端口连通性（更现代的方式）
$ nc -zv 127.0.0.1 8080
Connection to 127.0.0.1 8080 port [tcp/*] succeeded!

$ nc -zv 127.0.0.1 9000 -w 3
Connection to 127.0.0.1 9000 port [tcp/*] succeeded!

# 如果是域名形式的 upstream，测试 DNS 解析
$ dig +short api-backend.internal.example.com
10.0.1.55
10.0.1.56
10.0.1.57

$ nslookup api-backend.internal.example.com

# 测试 TCP 握手时间（使用 httping）
$ httping -g http://127.0.0.1:8080/health -c 3
PING 127.0.0.1:8080 (to=127.0.0.1):
connected to 127.0.0.1:8080 (301 bytes), seq=0 time=00.35 ms
connected to 127.0.0.1:8080 (301 bytes), seq=1 time=00.31 ms
connected to 127.0.0.1:8080 (301 bytes), seq=2 time=00.28 ms
--- http://127.0.0.1:8080/ ping statistics ---
3 connects, 3 ok, 0.00% roundtrip loss, 0.0/3.0/0.3/0.4 ms min/avg/max

# iptables/firewalld 规则检查
$ iptables -L -n | grep -E '(DROP|REJECT)' | head -20
$ firewall-cmd --list-all 2>/dev/null

第五步：验证 upstream 配置是否正确

检查 nginx.conf 中 upstream 块的配置，确保 IP 地址、端口、权重、备份服务器等参数正确。

# 测试 Nginx 配置语法
$ nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

# 完整输出配置树（包含所有 include 文件）
$ nginx -T 2>&1 | head -500

# 检查特定 upstream 块的配置
$ nginx -T 2>&1 | grep -A 10 "^    upstream backend"

3.2 日志深度解读

Nginx error.log 中记录的错误信息是诊断 502 问题最直接的证据。不同的错误信息对应不同的根因和处理方式。

"upstream prematurely closed connection"

表示 Nginx 与 upstream 之间的连接在 Nginx 读取完响应头之前就被 upstream 主动关闭。这通常意味着 upstream 进程崩溃、OOM 被杀、或遭遇了致命错误。

# 典型日志
2026/04/24 08:15:32 [error] 12487#12487: *8921 upstream prematurely closed connection while reading response header of upstream, client: 203.0.113.45, server: api.example.com, request: "GET /api/v2/users HTTP/1.1", upstream: "http://127.0.0.1:8080/api/v2/users", upstream_connection: "9612", upstream_bytes_sent: 234, upstream_bytes_received: 0

关键字段解读：

upstream prematurely closed connection：根因，upstream 提前关闭了连接
upstream_connection: "9612"：Nginx 侧连接的标识符，可用于关联同一连接的多次请求
upstream_bytes_sent: 234：已发送给 upstream 的字节数
upstream_bytes_received: 0：从 upstream 收到的字节数，说明 upstream 尚未返回任何数据就被关闭了

排查步骤：

检查 upstream 服务（后端应用）的错误日志，寻找崩溃或 panic 的记录
检查系统日志（dmesg、/var/log/messages）是否有关于 OOM Killer 的记录
确认后端服务是否因为代码 bug、资源耗尽而崩溃

# 检查 dmesg 中的 OOM Killer 记录
$ dmesg -T | grep -i "oom\|killed process" | tail -20
[Thu Apr 24 08:15:00 2026] php-fpm[4522]: oom_reaper: reaped process 4522 (php-fpm), now anon-rss: 0kb, file-rss: 0kb

# 检查 /var/log/messages 中的相关记录
$ grep -i "oom\|kill\|php-fpm" /var/log/messages | tail -30

"connect() failed (111: Connection refused)"

Nginx 尝试连接 upstream 时，目标端口无进程监听。这是配置错误或后端服务未启动的明确信号。

# 典型日志
2026/04/24 09:22:18 [error] 12487#12487: *9234 connect() failed (111: Connection refused) while connecting to upstream, client: 198.51.100.23, server: www.example.com, request: "POST /api/orders HTTP/1.1", upstream: "http://127.0.0.1:9000/api/orders", upstream_connection: "128"

关键字段解读：

connect() failed：连接建立失败
(111: Connection refused)：系统级 errno，111 = ECONNREFUSED，表示目标地址有响应但端口未监听（对比 ENETUNREACH = Network unreachable）

排查步骤：

确认 upstream 服务进程是否运行：systemctl status php-fpm 或 ss -tlnp
确认 upstream 配置的 IP:端口是否正确
如果是 Unix socket，确认 socket 文件是否存在且权限正确

# 模拟 Nginx 的连接行为
$ strace -e trace=connect -s 200 nginx -s reload 2>&1 | grep -i "connection refused"
# 或者对已知的后端端口抓包
$ tcpdump -i lo port 9000 -nn 2>&1

"no live upstreams while connecting"

所有 upstream server 都不可用，Nginx 找不到可用的后端节点。

# 典型日志
2026/04/24 10:45:07 [error] 12487#12487: *10234 no live upstreams while connecting to upstream, client: 203.0.113.89, server: api.example.com, request: "GET /api/health HTTP/1.1"

排查步骤：

检查 upstream 块中所有 server 的健康状态
可能是所有 server 都触发了 max_fails 阈值被暂时禁用
检查 Nginx 配置中是否有语法错误导致 upstream 块无效

# 检查 upstream 配置
$ nginx -T 2>&1 | grep -A 15 "upstream backend"

# 检查所有 upstream server 是否都被标记为 down
# 在 error.log 中搜索 upstream server 状态变化
$ grep "upstream.*server.*down\|upstream.*server.*disabled" /var/log/nginx/error.log | tail -20
2026/04/24 08:00:12 [warn] 12487#12487: *234 upstream server 127.0.0.1:8080 is marked as down
2026/04/24 08:00:15 [warn] 12487#12487: *235 upstream server 127.0.0.1:8081 is marked as down

"upstream timed out (110: Connection timed out)"

与 upstream 的连接建立成功，但在 proxy_read_timeout 规定的时间内未收到响应，Nginx 主动关闭连接。

# 典型日志 - 响应头超时
2026/04/24 11:02:33 [error] 12487#12487: *10891 upstream timed out (110: Connection timed out) after 30000 ms (110: Connection timed out) while connecting to upstream, client: 198.51.100.67, server: www.example.com, request: "POST /api/upload HTTP/1.1", upstream: "http://127.0.0.1:9090/api/upload"

# 典型日志 - 读取响应超时
2026/04/24 12:15:44 [error] 12487#12487: *11567 upstream timed out (110: Connection timed out) while reading response header of upstream, client: 203.0.113.112, server: api.example.com, request: "GET /api/reports HTTP/1.1", upstream: "http://127.0.0.1:8080/api/reports", upstream_connection: "15623"

排查步骤：

检查后端服务的处理时间（数据库查询、文件 I/O、第三方 API 调用）
确认 proxy_read_timeout 设置是否合理
使用后端应用自身的慢查询日志定位瓶颈

# PHP-FPM 慢查询日志
$ grep -i "slow" /var/log/php-fpm/www-slow.log | tail -20
[24-Apr-2026 11:00:12]  [pool www] pid 5534
script: /var/www/html/api/report.php
call: mysqli_query
time: 45.234567 s
memory: 128.00M

# Node.js 慢日志（使用 --inspect 配合 APM 工具）
$ journalctl -u node-backend --since "2026-04-24 11:00:00" | grep -i "slow\|timeout"

access.log 的 502 占比统计

通过分析 access.log 中各类状态码的分布，可以量化 502 错误的严重程度和变化趋势。

# 统计 access.log 中各状态码的数量
$ awk '{code[$9]++} END {for (c in code) print c, code[c]}' /var/log/nginx/access.log | sort -k2 -rn
200 1289345
502 4523
499 1234
304 890
404 567
500 234
503 89

# 计算 502 错误率
$ total=$(wc -l < /var/log/nginx/access.log); errors502=$(grep -c " 502 " /var/log/nginx/access.log); echo"scale=4; $errors502 / $total * 100" | bc
0.3489%

# 按时间段统计 502 错误
$ awk '$4 ~ /\[24\/Apr\/2026:1[0-2]/ && $9 == 502 {hour[$4]++} END {for (h in hour) print h, hour[h]}' /var/log/nginx/access.log
[24/Apr/2026:10:00:00 +0800] 23
[24/Apr/2026:11:00:00 +0800] 45
[24/Apr/2026:12:00:00 +0800] 12

# 统计产生 502 错误最多的请求路径
$ awk '$9 == 502 {path[$7]++} END {for (p in path) print path[p], p}' /var/log/nginx/access.log | sort -rn | head -10
234 /api/v2/users
189 /api/orders/submit
123 /api/reports/generate
67 /api/payments/callback

日志级别配置与影响

Nginx 日志级别从低到高：debug、info、notice、warn、error、crit、alert、emerg。生产环境建议使用 warn 或 error 级别，避免 debug 级别产生过大的日志量。

# 日志级别说明
debug: 调试信息，仅在编译时 --with-debug 启用
info:  一般信息
notice: 需要注意的信息
warn:  警告信息，可能存在问题但不影响运行
error: 错误信息
crit:  严重错误，部分功能不可用
alert: 必须立即处理
emerg: 系统不可用

# 配置示例
error_log /var/log/nginx/error.log warn;

# 临时开启 debug（测试环境）
error_log /var/log/nginx/error.log debug;

# debug 级别的连接追踪
events {
    debug_connection 203.0.113.0/24;  # 仅对特定 IP 开启 debug
    debug_connection 127.0.0.1;
}

分布式 trace：request_id 串联日志

在多层代理架构中，单个请求可能经过多个 Nginx 节点。使用 request_id 将各层日志串联起来，可以实现端到端的请求追踪。

# Nginx 自动生成 $request_id（1.11.0+）
# 格式：16 字节的十六进制随机数

# 在请求头中传递 request_id
location / {
    proxy_pass http://backend;
    proxy_set_header X-Request-ID $request_id;
}

# 在 PHP 中获取 request_id
$requestId = $_SERVER['HTTP_X_REQUEST_ID'] ?? '';

# 在 Node.js 中获取 request_id
const requestId = req.headers['x-request-id'];

# 查询串联后的日志
$ grep "X-Request-Id: abc12345" /var/log/nginx/error.log
2026/04/24 08:15:32 [error] 12487#12487: *8921 upstream prematurely closed connection..., request_id: "abc12345"
2026/04/24 08:15:33 [error] 4522#4522: *8921 php-fpm: pool www: child exited..., request_id: "abc12345"

$ grep "abc12345" /var/log/php-fpm/www-error.log
[24-Apr-2026 08:15:32 UTC] PHP Fatal error: Allowed memory size of 128M exhausted in /var/www/html/api/v2/users.php on line 234, request_id: abc12345

3.3 常见场景的排障路径

场景一：PHP-FPM 进程全挂

PHP-FPM 是最常见的后端服务之一，PHP-FPM 进程异常退出是导致 502 的高频原因。

症状识别：

error.log 大量"connect() failed (111: Connection refused) while connecting to upstream"
upstream 指向 php-fpm socket 或端口
curl 测试直接连接后端也失败

排查步骤：

# 1. 检查 PHP-FPM 服务状态
$ systemctl status php-fpm
● php-fpm.service - PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Thu 2026-04-24 08:00:12 CST; 2h 15min ago
  Main PID: 4521 (code=exited, status=0/SUCCESS)

# 2. 检查 PHP-FPM 主进程退出原因
$ journalctl -u php-fpm --since "2026-04-24 08:00:00" --until "2026-04-24 08:05:00"
Apr 24 08:00:12 web01 systemd[1]: php-fpm.service: Main process exited, code=killed, status=9/KILL
Apr 24 08:00:12 web01 systemd[1]: php-fpm.service: Failed with result 'signal'.

# 3. 检查 dmesg 中是否有 OOM Killer 记录
$ dmesg -T | grep -E "php|oom|killed" | tail -10
[Thu Apr 24 08:00:11 2026] php-fpm[4522]: memory usage 256MB exceeds limit 256MB, terminated
[Thu Apr 24 08:00:11 2026] Out of memory: Killed process 4522 total-vm:512MB, anon-rss:256MB file-rss:0KB

# 4. 检查 PHP-FPM 配置中的进程管理参数
$ grep -E "^pm|^proces|child|memory" /etc/php-fpm/www.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500
;emergency_restart_threshold = 10
;emergency_restart_interval = 1m
;process_control_timeout = 10s
php_admin_value[memory_limit] = 256M

# 5. 检查 PHP-FPM 错误日志
$ cat /var/log/php-fpm/www-error.log | tail -30
[24-Apr-2026 08:00:10 UTC] PHP Fatal error:  Allowed memory size of 268435456 bytes exhausted (tried to allocate 16384 bytes) in /var/www/html/api/v2/users.php on line 145
[24-Apr-2026 08:00:11 UTC] PHP Fatal error:  Allowed memory size of 268435456 bytes exhausted (tried to allocate 32768 bytes) in /var/www/html/api/v2/users.php on line 234

解决方案：

临时恢复服务：重启 PHP-FPM

$ systemctl restart php-fpm
$ systemctl status php-fpm
● php-fpm.service - PHP FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php-fpm.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-04-24 10:20:00 CST; 5s ago

长期优化：根据 OOM 日志定位内存消耗最大的 PHP 脚本，优化代码或上调 memory_limit

# 临时调高 memory_limit（不推荐作为长期方案）
$ sed -i 's/php_admin_value\[memory_limit\] = 256M/php_admin_value[memory_limit] = 512M/' /etc/php-fpm/www.conf
$ systemctl restart php-fpm

# 优化 pm.max_children（根据可用内存计算）
# 公式：max_children = (总内存 - 操作系统预留 - 其他服务内存) / 单个 PHP 进程内存
# 假设服务器 32G 内存，OS 预留 4G，MySQL 占用 8G，单个 PHP 进程平均 64M
# max_children = (32 - 4 - 8) * 1024 / 64 = 320

根因预防：

配置 PHP-FPM emergency_restart_threshold，当进程在规定时间内异常退出次数超过阈值时自动重启
配置 OOM Score Adj，使 PHP-FPM 进程更容易被 OOM Killer 先选中
使用 PHP 内存分析工具（xdebug、memprof）定位内存泄漏

场景二：Node.js/Python 后端 CPU 跑满

后端服务 CPU 跑满时，请求处理速度急剧下降，Nginx 等待后端响应超时，最终导致 502。

症状识别：

error.log 出现"upstream timed out"
502 错误持续出现，但后端进程仍在运行
系统 load average 显著升高

排查步骤：

# 1. 检查 CPU 使用情况
$ top -b -n 1 -p $(pgrep -d',' node)
top - 08:30:15 up 42 days,  3:37,  2 users,  load average: 8.45, 6.89, 5.76
Tasks:  12 total,   9 running,   3 sleeping,   0 stopped,   0 zombie
%Cpu(s): 95.5 us,  3.2 sy,  0.0 ni,  1.3 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+    COMMAND
 3421 root      20   0 1245678 456123  23456 R  78.5   1.4   2345:56 node
 3422 root      20   0  234567  123456   8901 R  15.2   0.4    456:34 node
 3423 root      20   0  212345  112234   7802 R   1.2   0.3    123:45 node

# 2. 检查 Node.js 进程的请求队列长度
$ curl -s http://127.0.0.1:8080/metrics | grep -E "nodejs_active_requests|eventloop_lag"
# HELP nodejs_active_requests Number of active requests
# TYPE nodejs_active_requests gauge
nodejs_active_requests 150
# HELP nodejs_eventloop_lag Lag in the Node.js event loop in milliseconds
# TYPE nodejs_eventloop_lag gauge
nodejs_eventloop_lag 5234

# 3. 分析 Node.js 慢日志（如果有）
$ cat /var/log/node-backend/slow.log | tail -20
[SLOW] 2026-04-24T08:25:12.234Z - 5034ms - /api/v2/report - Database query slow
[SLOW] 2026-04-24T08:25:15.567Z - 6123ms - /api/v2/report - Memory allocation high

# 4. Python (Gunicorn) 场景：检查 worker 状态
$ ps aux | grep gunicorn | grep -v grep
root      5621  0.0  2.1 245678  456789  ?        S    Apr23   0:30 gunicorn: master [app]
www-data  5622 95.0  3.2 267890  567890  ?        R    Apr24   234:56 gunicorn: worker [/var/www/app]
www-data  5623 92.0  3.1 259876  543210  ?        R    Apr24   198:34 gunicorn: worker [/var/www/app]

$ curl http://127.0.0.1:8000/syncdict  # Gunicorn 同步模式下单个请求阻塞整个 worker

解决方案：

快速止血：增加 worker 进程数量或切换到异步模式

# Node.js: 临时增加 cluster worker 数量
# 编辑 app.js，将 worker 数量从 4 增加到 8
$ sed -i 's/workers: 4/workers: 8/' /etc/node-backend/config.js
$ systemctl restart node-backend

# Python: 增加 Gunicorn worker 数量，使用异步 worker
$ sed -i 's/workers=4/workers=8/' /etc/gunicorn/config.py
$ sed -i 's/worker-class=sync/worker-class=uvicorn.workers.UvicornWorker/' /etc/gunicorn/config.py
$ systemctl restart gunicorn

定位瓶颈：使用 profiler 找到 CPU 热点代码

# Node.js: 使用 --prof 生成 V8 profiling 数据
$ kill -USR2 $(pgrep node)  # 触发 profiling
$ sleep 30
$ kill -USR2 $(pgrep node)  # 停止 profiling
$ node --prof-process isolate-*.log | head -30

优化超时配置：根据后端处理能力调整 Nginx 超时

# upstream 块中添加合理的超时配置
upstream backend {
    server 127.0.0.1:8080;
    keepalive 16;
}

location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # 根据后端处理能力调整超时
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 60s;
}

场景三：数据库连接池耗尽

后端服务依赖数据库，当数据库连接池耗尽时，后端请求在等待数据库连接时阻塞，间接导致 Nginx 侧超时。

症状识别：

502 错误呈现周期性（如每 30 分钟出现一次高峰）
后端应用日志中大量"connection timeout"或"pool exhausted"
数据库服务器 CPU/内存正常，但连接数达到上限

排查步骤：

# 1. 检查 MySQL 连接数
$ mysql -e "SHOW PROCESSLIST;" | wc -l
145

$ mysql -e "SHOW PROCESSLIST;" | grep -E "Sleep|Query" | head -20
+----+------+-----------+--------------------+---------+------+----------+-----------------------+
| Id | User | Host      | db                 | Command | Time | State    | Info                  |
+----+------+-----------+--------------------+---------+------+----------+-----------------------+
|  1 | root | localhost | information_schema | Query   |    0 | starting | SHOW PROCESSLIST      |
| 45 | app  | web01:456 | myapp_production   | Sleep   |  892 |          | NULL                  |
| 46 | app  | web01:457 | myapp_production   | Sleep   |  891 |          | NULL                  |
| 47 | app  | web01:458 | myapp_production   | Sleep   |  890 |          | NULL                  |
| 48 | app  | web02:123 | myapp_production   | Sleep   |  892 |          | NULL                  |
+----+------+-----------+--------------------+---------+------+----------+-----------------------+

# 2. 检查 MySQL 最大连接数配置
$ mysql -e "SHOW VARIABLES LIKE 'max_connections';"
+-----------------+-------+
| Variable_name   | Value |
+-----------------+-------+
| max_connections | 151   |
+-----------------+-------+

# 3. 检查 PHP/Python 应用的数据库连接池配置
$ grep -E "max_connections|pool_size|connection_pool" /var/www/html/config/database.php
$connPool = new PDO($dsn, $user, $pass, [
    PDO::ATTR_POOL => true,
    PDO::ATTR_POOL_SIZE => 20,
]);

# 4. 检查慢查询日志（长时间运行的 Query 会占用连接）
$ mysql -e "SHOW GLOBAL STATUS LIKE 'Slow_queries';"
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| Slow_queries  | 1234  |
+---------------+-------+

$ cat /var/log/mysql/slow-query.log | head -30

解决方案：

数据库端优化：增加 max_connections，调优 wait_timeout

-- 临时增加连接数上限
SET GLOBAL max_connections = 500;

-- 检查并调优 wait_timeout（避免 Sleep 连接长期占用）
SHOW GLOBAL VARIABLES LIKE 'wait_timeout';
SET GLOBAL wait_timeout = 600;
SET GLOBAL interactive_timeout = 600;

应用端优化：使用连接池管理，设置连接超时，快速失败

// PHP: 使用 Doctrine DBAL 连接池，设置短超时
$config = new \Doctrine\DBAL\Configuration();
$config->setDriverChain(['adapter' => 'pdo_mysql']);
$connection = \Doctrine\DBAL\ManagerRegistry::getConnection([
    'driver' => 'pdo_mysql',
    'host' => '10.0.1.100',
    'dbname' => 'myapp',
    'user' => 'app',
    'password' => 'xxx',
    'options' => [
        PDO::ATTR_TIMEOUT => 5,  // 5 秒超时
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ],
]);

Nginx 端配置：使用短超时和快速失败，避免请求堆积

location / {
    proxy_pass http://backend;
    proxy_connect_timeout 3s;
    proxy_send_timeout 10s;
    proxy_read_timeout 30s;

    # 后端处理过慢时立即返回 502，不累积请求
    proxy_next_upstream error timeout http_502;
}

场景四：Socket 文件权限问题

PHP-FPM 使用 Unix Domain Socket 与 Nginx 通信时，socket 文件的权限和所有权必须正确配置，否则 Nginx 无法连接 PHP-FPM。

症状识别：

error.log 中出现"connect() to unix:/var/run/php-fpm/www.sock failed (13: Permission denied)"
PHP-FPM 进程正常运行，但 Nginx 返回 502
直接测试 socket 连通性失败

排查步骤：

# 1. 检查 socket 文件权限
$ ls -la /var/run/php-fpm/
total 8
srwxr-xr-x 3 root www-data www-data 120 Apr 24 06:00 /var/run/php-fpm/
srwxrwxrwx 1 www-data www-data   6 Apr 24 06:00 www.sock

# 2. 检查 Nginx worker 进程的用户
$ ps aux | grep "nginx: worker" | head -3
root     12487  0.0  0.3  56789  23456  ?  S    Apr23   0:12 nginx: worker process
root     12488  0.0  0.3  56790  23457  ?  S    Apr23   0:11 nginx: worker process

# nginx.conf 中 user 指令
$ grep "^user" /etc/nginx/nginx.conf
user nginx nginx;

# 3. 检查 PHP-FPM pool 配置中的 listen.owner 和 listen.group
$ grep -E "^listen\.|listen\.owner|listen\.group|listen\.mode" /etc/php-fpm/www.conf
listen = /var/run/php-fpm/www.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

# 4. 测试 socket 连接性
$ sudo -u nginx php-fpm-test-connection /var/run/php-fpm/www.sock
# 或使用 ss 查看 socket 状态
$ ss -x | grep php-fpm
u_str LISTEN 0 511 /var/run/php-fpm/www.sock 12345 users:(("php-fpm",pid=4522,fd=9))

SELinux/AppArmor 拦截检查：

# 检查 SELinux 状态
$ getenforce
Enforcing

# 查看 SELinux 阻止的访问
$ grep nginx /var/log/audit/audit.log | grep -i "denied\|refused" | tail -10
type=AVC msg=audit(1713936000.234:5678): avc:  denied  { connectto } for  pid=12487 comm="nginx" path="/var/run/php-fpm/www.sock" scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:system_r:php-fpm_t:s0 tclass=unix_stream_socket permissive=0

# 临时解决：设置 SELinux 允许 nginx 连接 php-fpm socket
$ setsebool -P httpd_can_network_connect 1

# 永久解决：添加 SELinux 策略
$ cat > /etc/selinux/local/nginx_php_fpm.te << 'EOF'
module nginx_php_fpm 1.0;

require {
    type httpd_t;
    type php-fpm_t;
    class unix_stream_socket connectto;
}

allow httpd_t php-fpm_t:unix_stream_socket connectto;
EOF

$ checkmodule -M -m -o nginx_php_fpm.mod nginx_php_fpm.te
$ semodule_package -o nginx_php_fpm.pp -m nginx_php_fpm.mod
$ semodule -i nginx_php_fpm.pp

解决方案：

统一用户和组

# 方案一：让 Nginx 和 PHP-FPM 使用相同的用户
# /etc/php-fpm/www.conf
listen.owner = nginx
listen.group = nginx
listen.mode = 0660

# /etc/nginx/nginx.conf
user nginx nginx;

# 方案二：使用 TCP 连接而非 Unix socket
# /etc/php-fpm/www.conf
listen = 127.0.0.1:9000

# /etc/nginx/nginx.conf
location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
}

修复 socket 权限

$ chown www-data:www-data /var/run/php-fpm
$ chmod 0775 /var/run/php-fpm
$ systemctl restart php-fpm

场景五：反代到 Docker 容器

Docker 容器的网络模式、容器健康状态、容器重启策略等都会影响 Nginx 对容器的代理行为。

症状识别：

upstream 指向 Docker 容器 IP 或映射端口
502 错误在容器重启后突然出现
docker ps 显示容器状态不稳定

排查步骤：

# 1. 检查容器状态
$ docker ps -a
CONTAINER ID   IMAGE           STATUS          PORTS                  NAMES
abc123def456   myapp:latest    Up 2 hours      0.0.0.0:8080->8080/tcp web01
def456ghi789   myapp:latest    Restarting      0.0.0.0:8081->8080/tcp web02
ghi789jkl012   myapp:latest    Exited (1) 5m   0.0.0.0:8082->8080/tcp web03

# 2. 检查容器日志
$ docker logs def456ghi789 --tail 50
[2026-04-24 08:00:00] INFO: Starting server on port 8080
[2026-04-24 08:00:01] ERROR: Database connection failed: connection timeout
[2026-04-24 08:00:01] INFO: Retrying in 5 seconds...
[2026-04-24 08:00:06] ERROR: Database connection failed: connection timeout
[2026-04-24 08:00:06] FATAL: Could not connect to database after 5 attempts, exiting

# 3. 检查 Docker 网络模式
$ docker inspect def456ghi789 | grep -A 10 "NetworkSettings"
"NetworkSettings": {
    "Bridge": "",
    "SandboxID": "xyz123",
    "Gateway": "172.17.0.1",
    "IPAddress": "172.17.0.8",
    "Ports": {
        "8080/tcp": [
            {
                "HostIp": "0.0.0.0",
                "HostPort": "8081"
            }
        ]
    }
}

# 4. 测试容器网络连通性
$ docker exec -it abc123def456 ping -c 3 db.internal.example.com
PING db.internal.example.com (10.0.1.100) 56(84) bytes of data.
64 bytes from db.internal.example.com (10.0.1.100): icmp_seq=1 ttl=63 time=0.5 ms

$ docker exec -it abc123def456 curl -v http://localhost:8080/health
* Connected to localhost:8080 (127.0.0.1) port 8080
< HTTP/1.1 200 OK

# 5. 检查 Docker daemon 日志
$ journalctl -u docker --since "2026-04-24 08:00:00" | tail -50

解决方案：

使用 Docker Compose 健康检查和 depends_on 确保启动顺序

# docker-compose.yml
version:'3.8'
services:
db:
    image:mysql:8.0
    healthcheck:
      test:["CMD","mysqladmin","ping","-h","localhost"]
      interval:10s
      timeout:5s
      retries:5

app:
    image:myapp:latest
    depends_on:
      db:
        condition:service_healthy
    healthcheck:
      test:["CMD","curl","-f","http://localhost:8080/health"]
      interval:15s
      timeout:5s
      retries:3
    restart:on-failure

在 Nginx upstream 中使用容器名称（Docker Compose 网络内）

upstream backend {
    server web01:8080;
    server web02:8080;
    server web03:8080 backup;
}

location / {
    proxy_pass http://backend;
    resolver 127.0.0.11 valid=10s;  # Docker 内置 DNS
    proxy_set_header Host $host;
}

配置 Nginx upstream 主动健康检查

upstream backend {
    server web01:8080;
    server web02:8080;
    server web03:8080 backup;

    check interval=5000 rise=2 fall=3 timeout=3000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

3.4 配置优化实战

超时参数调优

超时配置是 502 问题的核心配置项。根据业务特点合理设置超时，可以在保护后端和保证可用性之间取得平衡。

# 生产环境推荐的超时配置
proxy_connect_timeout 10s;   # 连接超时，短即可
proxy_send_timeout 60s;      # 发送请求超时，根据请求体大小调整
proxy_read_timeout 120s;     # 读取响应超时，根据业务处理时间调整

# 上传/下载大文件的场景
client_max_body_size 500m;   # 允许最大请求体 500M
proxy_read_timeout 600s;      # 大文件处理需要更长超时

# API 服务的超时配置
location /api/ {
    proxy_pass http://backend_api;
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 60s;

    # 启用请求缓冲，用于大请求体
    proxy_request_buffering on;
    proxy_buffer_size 256k;
}

# 验证超时配置生效
$ nginx -T 2>&1 | grep -E "proxy_(connect|send|read)_timeout"
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 120s;

# 通过压力测试验证超时行为
$ ab -n 100 -c 10 -s 30 http://api.example.com/api/v2/report
# 观察是否会因为超时导致 502

缓冲区优化

缓冲区配置直接影响 Nginx 转发大量数据时的效率。配置不当可能导致内存占用过高或频繁写入临时文件。

# 大流量站点推荐缓冲区配置
proxy_buffering on;
proxy_buffer_size 256k;      # 响应头缓冲区
proxy_buffers 16 256k;       # 响应体缓冲区，16 * 256k = 4M
proxy_busy_buffer_size 512k;  # 忙碌时缓冲区

# 临时文件配置（用于超过内存缓冲区的响应）
proxy_max_temp_file_size 2048m;  # 临时文件总大小上限
proxy_temp_file_write_size 256k; # 单次写入大小

# 静态文件代理（减少后端压力）
location /static/ {
    proxy_pass http://backend_static;
    proxy_buffering on;
    proxy_cache_valid 200 60m;  # 缓存 200 响应 60 分钟
    proxy_cache_valid 404 1m;
}

# 监控缓冲区使用情况
$ watch -n 1 'cat /proc/$(pgrep nginx | head -1)/status | grep -E "VmPeak|VmSize|Rss"'
Every 1.0s: cat /proc/12487/status | grep -E "VmPeak|VmSize|Rss"

VmPeak:  524288 kB
VmSize:  498234 kB
Rss:     123456 kB

# 检查是否有大量临时文件
$ ls -lah /var/lib/nginx/proxy/ | wc -l
23
$ du -sh /var/lib/nginx/proxy/
1.2G

Keepalive 配置

HTTP keepalive 可以复用 TCP 连接，显著减少连接建立的开销。在高并发场景中，合理配置 upstream keepalive 是保护后端的重要手段。

# upstream keepalive 配置
upstream backend {
    server 127.0.0.1:8080 weight=5;
    server 127.0.0.1:8081 weight=3;
    server 127.0.0.1:8082 backup;

    # keepalive 配置
    keepalive 32;              # 保持 32 个空闲连接
    keepalive_requests 1000;   # 单连接最大请求数
    keepalive_timeout 60s;      # 空闲连接超时
}

# location 中启用 HTTP/1.1 和清除 Connection 头
location / {
    proxy_pass http://backend;

    # 必须使用 HTTP/1.1 才能支持 keepalive
    proxy_http_version 1.1;

    # 清除 Connection 头，否则 nginx 会保持短连接
    proxy_set_header Connection "";

    # 可选：添加存活探测
    proxy_connect_timeout 10s;
}

# 对比有无 keepalive 的性能差异
# 无 keepalive
$ wrk -t4 -c100 -d30s http://127.0.0.1/api/test
Requests/sec:  1234.56
Latency avg:   45.67ms

# 有 keepalive（32 连接）
$ wrk -t4 -c100 -d30s http://127.0.0.1/api/test
Requests/sec:  4567.89
Latency avg:   12.34ms

# 性能提升约 3.7 倍

3.5 预防性监控

502 错误率告警

#!/bin/bash
# 监控 502 错误率，超过阈值则告警

LOG_FILE="/var/log/nginx/access.log"
THRESHOLD=1.0  # 阈值 1%

calculate_502_rate() {
    total=$(wc -l < "$LOG_FILE")
    errors502=$(grep -c " 502 ""$LOG_FILE" 2>/dev/null || echo 0)

    if [ "$total" -eq 0 ]; then
        echo"0"
        return
    fi

    rate=$(echo"scale=4; $errors502 / $total * 100" | bc)
    echo"$rate"
}

rate=$(calculate_502_rate)
result=$(echo"$rate > $THRESHOLD" | bc)

if [ "$result" -eq 1 ]; then
    echo"CRITICAL: 502 error rate is ${rate}%, threshold is ${THRESHOLD}%"
    # 触发告警（对接 Prometheus Alertmanager / Grafana / PagerDuty 等）
    curl -X POST "http://alertmanager:9093/api/v1/alerts" \
        -H "Content-Type: application/json" \
        -d '[{"labels":{"alertname":"Nginx502High","severity":"critical"}}]'
fi

Prometheus + Grafana 监控配置

# prometheus.yml - scrape 配置
scrape_configs:
-job_name:'nginx'
    static_configs:
      -targets:['127.0.0.1:9100']# nginx-vts 或 nginx-exporter

# Grafana 查询 - 502 错误率
# Nginx upstream response time (5xx)
sum(rate(nginx_upstream_response_seconds_count{upstream=~".*",status=~"5.."}[5m]))by(upstream)

# Nginx upstream request errors
sum(rate(nginx_upstream_request_errors_total[5m]))by(upstream)

# Nginx connection status
nginx_connections_total{status="active"}
nginx_connections_total{status="reading"}
nginx_connections_total{status="writing"}
nginx_connections_total{status="waiting"}

upstream 响应时间分布

# 使用 awk 分析 access.log 中 upstream 响应时间分布
$ awk -F'"' '$2 ~ /upstream/ {
    split($2, parts, " ")
    for (i=1; i<=length(parts); i++) {
        if (parts[i] ~ /upstream_response_time/) {
            split(parts[i], kv, ":")
            time = kv[3] + 0
            if (time < 0.1) bucket["<100ms"]++
            else if (time < 0.5) bucket["100-500ms"]++
            else if (time < 1) bucket["500ms-1s"]++
            else if (time < 5) bucket["1-5s"]++
            else if (time < 30) bucket["5-30s"]++
            else bucket[">30s"]++
            total++
            break
        }
    }
}
END {
    for (b in bucket) {
        pct = int(bucket[b] / total * 100)
        printf "%s: %d (%d%%)\n", b, bucket[b], pct
    }
}' /var/log/nginx/access.log

<100ms: 12345 (45%)
100-500ms: 9876 (36%)
500ms-1s: 2345 (9%)
1-5s: 1234 (5%)
5-30s: 567 (2%)
>30s: 33 (1%)

四、生产环境最佳实践

4.1 架构优化

多层 Nginx 架构

在大型生产环境中，建议部署两层 Nginx：边缘代理层（Edge Proxy）和应用代理层（Application Proxy）。边缘代理负责 SSL 终结、请求日志、基础安全过滤、静态资源缓存；应用代理负责业务路由、upstream 健康检查、负载均衡、故障转移。

                    Internet
                        |
                Edge Proxy (NLB)
                1.1.1.1 / 1.1.1.2
                SSL Termination
                Static Cache
                Rate Limiting
                        |
                Application Proxy Cluster
                10.0.1.10 / 10.0.1.11 / 10.0.1.12
                Upstream Health Check
                Load Balancing
                Business Routing
                        |
                Backend Services
                +------------+------------+
                |            |            |
            PHP-FPM      Node.js      Python
                |            |            |
            Database    Redis       PostgreSQL

# 边缘代理层配置 - /etc/nginx/edge.conf
# 处理 SSL 终结和静态资源
server {
    listen 443 ssl http2;
    server_name www.example.com;

    ssl_certificate /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # 静态资源缓存
    location /static/ {
        proxy_pass http://cdn_backend;
        proxy_cache static_cache;
        proxy_cache_valid 200 7d;
        add_header X-Cache-Status $upstream_cache_status;
    }

    # 动态请求转发到应用代理层
    location / {
        proxy_pass http://app_proxy_cluster;
        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;

        # 限流配置
        limit_req zone=api_limit burst=100 nodelay;
        limit_conn_status 429;
    }
}

# 应用代理层配置 - /etc/nginx/app.conf
# 负责 upstream 健康检查和负载均衡
upstream backend_php {
    least_conn;

    server 10.0.1.20:9000 weight=5;
    server 10.0.1.21:9000 weight=5;
    server 10.0.1.22:9000 backup;

    # 主动健康检查
    check interval=3000 rise=2 fall=2 timeout=1000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

upstream backend_node {
    ip_hash;

    server 10.0.1.30:8080 weight=3;
    server 10.0.1.31:8080 weight=3;
    server 10.0.1.32:8080 weight=3;
}

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

    location /api/v1/ {
        proxy_pass http://backend_php;
        include /etc/nginx/conf.d/proxy_params.conf;
    }

    location /api/node/ {
        proxy_pass http://backend_node;
        include /etc/nginx/conf.d/proxy_params.conf;
    }
}

主动健康检查配置

使用 nginx_upstream_check_module 实现主动健康检查，比被动检查更早发现故障节点，避免将请求发往已故障的后端。

# 加载模块（编译时添加）
# ./configure --add-module=/path/to/nginx_upstream_check_module

upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    server 127.0.0.1:8082 backup;

    # 主动健康检查配置
    # interval: 检查间隔 3 秒
    # rise: 连续 2 次成功则标记为 up
    # fall: 连续 3 次失败则标记为 down
    # timeout: 检查超时 1 秒
    # type: 检查类型为 HTTP
    check interval=3000 rise=2 fall=3 timeout=1000 type=http;

    # 发送的 HTTP 请求
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";

    # 期望的响应状态码
    check_http_expect_alive http_2xx http_3xx;
}

# 健康检查状态页面
server {
    listen 8080;
    server_name localhost;

    location /upstream_status {
        check_status;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }

    location /health {
        return 200 "OK";
        add_header Content-Type text/plain;
    }
}

# 验证健康检查状态
$ curl http://127.0.0.1:8080/upstream_status
Upstream server status:
backend
  server 127.0.0.1:8080      up      1234567890 ms
  server 127.0.0.1:8081      down    5000 ms (3/3)
  server 127.0.0.1:8082      backup
Total connections: 2345
upstream alive connections: 1234

灰度发布与权重调整

在升级后端服务时，使用 Nginx 的权重调整实现流量切换，而非直接替换。新版本接收小部分流量，观察无异常后逐步增加权重。

# 金丝雀发布配置
upstream backend_stable {
    server 127.0.0.1:8080;  # 当前稳定版本
}

upstream backend_canary {
    server 127.0.0.1:8081;  # 新版本，权重为 1
}

# 90% 流量到稳定版，10% 到金丝雀
upstream backend {
    server 127.0.0.1:8080 weight=9;
    server 127.0.0.1:8081 weight=1;
}

# 或者根据请求特征（如 Cookie、Header）分流
map $cookie_canary_version $backend_pool {
    default http://backend_stable;
    "v2" http://backend_canary;
}

location / {
    proxy_pass $backend_pool;
    include /etc/nginx/conf.d/proxy_params.conf;
}

# 监控金丝雀版本的错误率
$ awk '$9 ~ /5../ && /127.0.0.1:8081/ {count++} END {print "Canary 5xx:", count}' /var/log/nginx/access.log
Canary 5xx: 12

$ awk '$9 ~ /5../ && /127.0.0.1:8080/ {count++} END {print "Stable 5xx:", count}' /var/log/nginx/access.log
Stable 5xx: 3

# 金丝雀错误率略高，继续观察

限流与熔断

在 upstream 压力过大或响应变慢时，主动拒绝部分请求，防止雪崩效应。

# 限流配置
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/s;
limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

server {
    location /api/ {
        # 令牌桶限流，burst=200 表示突发最多接受 200 个请求
        # nodelay 不延迟处理，直接返回 503
        limit_req zone=api_limit burst=200 nodelay;

        # 连接数限制
        limit_conn conn_limit 10;

        proxy_pass http://backend;
        proxy_next_upstream error timeout http_502 http_503;
    }
}

# 熔断配置：基于响应时间自动降级
# 当 upstream 平均响应时间超过阈值时，返回降级响应
proxy_cache_bypass $upstream_http_x_downgrade;

4.2 配置模板

生产环境完整配置示例

# /etc/nginx/nginx.conf
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

events {
    worker_connections 65535;
    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" '
                    'request_id="$request_id"';

    access_log /var/log/nginx/access.log main buffer=16k flush=2s;

    # 基础优化
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    server_tokens off;

    # 超时配置
    keepalive_timeout 65;
    keepalive_requests 1000;
    client_header_timeout 15s;
    client_body_timeout 15s;
    send_timeout 60s;

    # 缓冲区配置
    client_max_body_size 100m;
    client_body_buffer_size 256k;
    client_header_buffer_size 4k;
    large_client_header_buffers 4 16k;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml application/json application/javascript application/xml+rss application/rss+xml font/truetype font/opentype application/vnd.ms-fontobject image/svg+xml;

    # 隐藏 Nginx 版本号
    server_tokens off;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # upstream 块定义
    include /etc/nginx/conf.d/upstream/*.conf;

    # 引入各站点的 server 配置
    include /etc/nginx/sites-enabled/*.conf;
}

# /etc/nginx/conf.d/upstream/backend.conf
upstream backend_php {
    least_conn;

    server 127.0.0.1:9000 weight=5 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:9001 weight=5 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:9002 backup;

    keepalive 32;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

upstream backend_static {
    server 127.0.0.1:8080 weight=5;
    server 127.0.0.1:8081 weight=5;
    server 127.0.0.1:8082 backup;

    keepalive 32;
}

upstream backend_api {
    ip_hash;

    server 10.0.1.20:8080;
    server 10.0.1.21:8080;
    server 10.0.1.22:8080;

    # 主动健康检查
    check interval=3000 rise=2 fall=2 timeout=1000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

# /etc/nginx/sites-enabled/api.example.com.conf
server {
    listen 80;
    server_name api.example.com;

    # 将 HTTP 请求重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/nginx/ssl/api.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # 安全头
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 访问日志
    access_log /var/log/nginx/api.example.com.access.log main buffer=16k;

    # 健康检查端点（不经过限流）
    location = /health {
        access_log off;
        return 200 "OK\n";
        add_header Content-Type text/plain;
    }

    # API 路由
    location /api/v1/ {
        # 限流
        limit_req zone=api_limit burst=100 nodelay;
        limit_req_status 429;

        # proxy 配置
        proxy_pass http://backend_php;
        proxy_http_version 1.1;
        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_set_header Connection "";

        # 超时配置
        proxy_connect_timeout 10s;
        proxy_send_timeout 60s;
        proxy_read_timeout 120s;

        # 缓冲区配置
        proxy_buffering on;
        proxy_buffer_size 128k;
        proxy_buffers 8 256k;
        proxy_busy_buffer_size 256k;

        # 错误处理：后端故障时返回降级响应
        error_page 502 503 = @fallback;
    }

    # 静态资源
    location /static/ {
        proxy_pass http://backend_static;
        proxy_cache static_cache;
        proxy_cache_valid 200 60m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating;
        add_header X-Cache-Status $upstream_cache_status;
        expires 7d;
        add_header Cache-Control "public, immutable";
    }

    # 降级响应
    location @fallback {
        default_type application/json;
        return 503 '{"code":503,"message":"Service temporarily unavailable","request_id":"$request_id"}';
    }

    # 429 Too Many Requests 响应
    location = /429.html {
        internal;
        default_type application/json;
        return 429 '{"code":429,"message":"Rate limit exceeded","retry_after":1}';
    }
}

日志切割配置

# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 0640 nginx adm
    sharedscripts
    postrotate
        [ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
    endscript
}

# 手动测试日志切割
$ logrotate -f /etc/logrotate.d/nginx
$ ls -la /var/log/nginx/
total 1234
-rw-r----- 1 nginx adm   45678 Apr 24 00:00 access.log
-rw-r----- 1 nginx adm   12345 Apr 24 00:00 access.log-20260424.gz
-rw-r----- 1 nginx adm   23456 Apr 24 00:00 error.log
-rw-r----- 1 nginx adm    8901 Apr 24 00:00 error.log-20260424.gz

性能测试基线

# 使用 wrk 进行基准性能测试
$ wrk -t4 -c100 -d60s --latency http://api.example.com/api/v1/health

Running 1m test @ http://api.example.com/api/v1/health
  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     12.34ms    2.15ms  45.67ms   90.12%
    Req/Sec    2345.67     89.23  2500.00    85.00%
  Latency Distribution
     50%    11.89ms
     75%    13.45ms
     90%    15.23ms
     99%    25.67ms
  1234567 requests in 60.00s, 234.56MB read
Requests/sec:  20576.12
Transfer/sec:    3.91MB

# 使用 ab 进行连接测试
$ ab -n 10000 -c 1000 -g ab_results.tsv http://api.example.com/api/v1/health

This is ApacheBench, Version 2.3 <$Revision: 1879490 $>
Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Licensed to The Apache Software Foundation, http://www.apache.org/

Benchmarking api.example.com (be patient)
Completed 1000 requests
Completed 2000 requests
Completed 3000 requests
Completed 4000 requests
Completed 5000 requests
Completed 6000 requests
Completed 7000 requests
Completed 8000 requests
Completed 9000 requests
Completed 10000 requests
Finished 10000 requests

Server Software:        nginx/1.26.2
Server Hostname:        api.example.com
Server Port:            443
SSL/TLS Protocol:       TLSv1.3, ECDHE-RSA-AES256-GCM-SHA384, 256bit

Document Path:          /api/v1/health
Document Length:        3 bytes

Concurrency Level:      1000
Time taken for tests:   12.345 seconds
Complete requests:      10000
Failed requests:        0
Non-2xx responses:      0
Total transferred:      2340000 bytes
HTML transferred:       30000 bytes
Requests per second:    810.23 [#/sec] (mean)
Time per request:       1234.567 [ms] (mean)
Time per request:       1.235 [ms] (mean, across all concurrent requests)
Transfer rate:          185.23 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       0
Processing:    123  456  78.9    434    1234
Waiting:       123  455  78.9    433    1233
Total:         123  456  78.9    434    1234

Percentage of the requests served within a certain time (ms)
  50%    434
  66%    456
  75%    478
  80%    489
  90%    534
  95%    612
  98%    723
  99%    789
 100%   1234 (longest request)

4.3 故障应急

502 故障的快速止血

故障发生时，第一目标是快速恢复服务，最小化业务影响。

# 1. 立即检查 error.log，确认 502 根因类型
$ tail -100 /var/log/nginx/error.log | grep -E "\[error\]" | tail -20

# 2. 快速检查后端服务状态
$ systemctl status php-fpm node-backend gunicorn 2>&1 | grep -E "Active:|Main PID:"

# 3. 如果后端服务挂了，立即重启
$ systemctl restart php-fpm
$ systemctl restart node-backend

# 4. 如果是单个 upstream server 故障，临时从 upstream 中移除
$ vim /etc/nginx/conf.d/upstream/backend.conf
# 注释掉故障 server，保留可用的
upstream backend {
    server 127.0.0.1:9000;
    # server 127.0.0.1:9001;  # 临时禁用
}

$ nginx -t && nginx -s reload

# 5. 如果所有后端都不可用，启动备用服务
$ systemctl start emergency-backend

# 6. 扩大上游超时时间，减少 502 触发
$ sed -i 's/proxy_read_timeout 120s;/proxy_read_timeout 300s;/' /etc/nginx/conf.d/upstream/*.conf
$ nginx -s reload

后端切换的手动操作

# 手动切换流量到备用后端
# 场景：主数据库故障，需要切换到从库

# 1. 备份当前 upstream 配置
$ cp /etc/nginx/conf.d/upstream/app.conf /etc/nginx/conf.d/upstream/app.conf.bak.$(date +%Y%m%d%H%M%S)

# 2. 修改 upstream 指向备用后端
$ cat > /etc/nginx/conf.d/upstream/app_standby.conf << 'EOF'
upstream backend_app {
    server 10.0.2.20:8080 weight=5;
    server 10.0.2.21:8080 weight=5;
    server 10.0.2.22:8080 backup;
}
EOF

# 3. 测试配置语法
$ nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

# 4. 优雅reload，不中断现有连接
$ nginx -s reload

# 5. 监控错误率变化
$ watch -n 1 'grep -c " 502 " /var/log/nginx/access.log'

# 6. 验证备用后端可用性
$ curl -s http://10.0.2.20:8080/health | grep OK
$ curl -s http://10.0.2.21:8080/health | grep OK

业务降级方案

当后端无法处理请求时，返回预设的降级响应而非 502，提升用户体验。

# 降级配置示例
upstream backend_primary {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081 backup;
}

# 主服务不可用时返回缓存或静态降级内容
proxy_cache_key "$host$request_uri";
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid 500 502 503 504 1m;

location /api/ {
    # 尝试主后端
    proxy_pass http://backend_primary;

    # 后端返回 502/503 时使用缓存
    proxy_cache_use_stale error timeout updating http_502 http_503 http_504;

    # 后端响应慢时使用缓存
    proxy_cache_use_stale error timeout updating;

    # 缓存刷新时间
    proxy_cache_background_update on;
    proxy_cache_lock on;

    # 降级响应：如果缓存也没有，返回静态 JSON
    error_page 502 503 504 = @degraded_response;
}

location @degraded_response {
    default_type application/json;
    # 返回最近缓存的响应（由 proxy_cache_valid 控制）
    add_header X-Cache-Status "DEGRADED";
    return 200 '{"code":200,"message":"Cached response","data":null,"degraded":true}';
}

五、扩展阅读与证据链

5.1 官方文档

Nginx 官方文档

Nginx 官方文档（英文）：https://nginx.org/en/docs/
Nginx upstream 模块文档：https://nginx.org/en/docs/http/ngx_http_upstream_module.html
Nginx proxy 模块文档：https://nginx.org/en/docs/http/ngx_http_proxy_module.html
Nginx 故障排查指南：https://nginx.org/en/docs/support.html

PHP-FPM 官方文档

PHP-FPM 配置说明：https://www.php.net/manual/en/install.fpm.configuration.php
PHP-FPM 进程管理：https://www.php.net/manual/en/install.fpm.pm.php

第三方模块文档

nginx_upstream_check_module（阿里巴巴）：https://github.com/yaoweibin/nginx_upstream_check_module
OpenResty + lua-upstream：https://github.com/openresty/lua-upstream-nginx-module

5.2 关键配置文件参考

nginx.conf 完整模板

# Nginx 1.26.x / 1.27.x 完整配置模板
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
worker_rlimit_sigpending 65535;

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

events {
    worker_connections 65535;
    use epoll;
    multi_accept on;
    accept_mutex on;
    accept_mutex_delay 500ms;
}

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

    # 字符集
    charset utf-8;
    charset_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml;

    # 日志格式（包含 upstream 详细信息）
    log_format main_ext '$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" '
                        'request_id="$request_id" '
                        'upstream_addr="$upstream_addr" '
                        'upstream_status="$upstream_status"';

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

    # 基础优化
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    # 超时配置
    keepalive_timeout 65;
    keepalive_requests 1000;
    client_header_timeout 15s;
    client_body_timeout 15s;
    send_timeout 60s;
    lingering_timeout 5s;
    reset_timedout_connection on;

    # 缓冲区配置
    client_max_body_size 100m;
    client_body_buffer_size 256k;
    client_header_buffer_size 4k;
    large_client_header_buffers 4 32k;
    connection_pool_size 256;
    request_pool_size 4k;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml application/json application/javascript application/xml application/atom+xml application/rss+xml image/svg+xml;

    # 安全配置
    server_tokens off;
    hide_server_token on;

    # Open file cache
    open_file_cache max=65535 inactive=60s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    # 限制请求
    limit_req_zone $binary_remote_addr zone=general:10m rate=100r/s;
    limit_req_zone $binary_remote_addr zone=api:10m rate=1000r/s;
    limit_conn_zone $binary_remote_addr zone=conn:10m;

    # 引入 upstream 配置
    include /etc/nginx/conf.d/upstream/*.conf;

    # 引入站点配置
    include /etc/nginx/sites-enabled/*.conf;
}

PHP-FPM 配置参数说明

; /etc/php-fpm/www.conf 关键参数说明

; 进程管理器类型
; static - 固定数量的子进程
; dynamic - 动态数量的子进程
; ondemand - 按需创建子进程
pm = dynamic

; 子进程最大数量
pm.max_children = 50

; 启动时创建的子进程数（dynamic 模式）
pm.start_servers = 10

; 最小空闲子进程数（dynamic 模式）
pm.min_spare_servers = 5

; 最大空闲子进程数（dynamic 模式）
pm.max_spare_servers = 20

; 子进程处理请求数上限，达到后重启（防止内存泄漏累积）
pm.max_requests = 500

; 子进程空闲超时
pm.process_idle_timeout = 10s

; 紧急重启阈值
emergency_restart_threshold = 10
emergency_restart_interval = 1m

; 进程控制超时（处理 SIGTERM 需要的时间）
process_control_timeout = 10s

; PHP 内存限制
php_admin_value[memory_limit] = 256M
php_admin_flag[log_errors] = on

; 慢查询日志
slowlog = /var/log/php-fpm/www-slow.log
request_slowlog_timeout = 10s
request_slowlog_trace_depth = 20

; 健康检查
ping.path = /ping
ping.response = pong

; Socket 配置
listen = /var/run/php-fpm/www.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

systemd Service 文件

; /etc/systemd/system/php-fpm.service
[Unit]
Description=PHP FastCGI Process Manager
Documentation=man:php-fpm(8)
After=network.target

[Service]
Type=notify
PIDFile=/run/php-fpm/php-fpm.pid
ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php-fpm.conf
ExecReload=/bin/kill -USR2 $MAINPID
ExecStop=/bin/kill -SIGINT $MAINPID
PrivateTmp=true
Restart=always
RestartSec=10s
TimeoutStartSec=30s
TimeoutStopSec=30s

; 资源限制
LimitNOFILE=65535
LimitNPROC=8192

; OOM 策略 - 不阻止 OOM Killer
OOMScoreAdjust=-500

[Install]
WantedBy=multi-user.target

; /etc/systemd/system/nginx.service
[Unit]
Description=nginx - high performance web server
Documentation=https://nginx.org/en/docs/
After=network.target remote-fs.target nss-lookup.target

[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStartPre=/usr/sbin/nginx -t -c /etc/nginx/nginx.conf
ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s QUIT $MAINPID
PrivateTmp=true
Restart=always
RestartSec=5s

; 资源限制
LimitNOFILE=65535
LimitCORE=infinity

[Install]
WantedBy=multi-user.target

5.3 常见错误码速查表

errno	系统调用错误	含义	常见场景
111	ECONNREFUSED	连接被拒绝	upstream 端口未监听
110	ETIMEDOUT	连接超时	upstream 无响应，防火墙拦截
113	EHOSTUNREACH	主机不可达	IP 地址错误，网络不通
111	ECONNREFUSED	连接被拒绝	PHP-FPM socket 权限错误
104	ECONNRESET	连接被重置	upstream 进程崩溃
32	EPIPE	管道破裂	upstream 提前关闭连接
2	ENOENT	文件不存在	Unix socket 文件不存在

5.4 502 排查流程图（文字版）

发现 502 错误
    |
    v
检查 error.log 中的具体错误信息
    |
    +---> "connect() failed (111)" ---> upstream 端口未监听
    |     |
    |     +---> 检查后端服务是否运行: systemctl status php-fpm/node-backend
    |     +---> 检查端口/socket 是否监听: ss -tlnp | grep 9000
    |     +---> 检查配置中 IP:端口是否正确
    |
    +---> "upstream prematurely closed" ---> upstream 进程崩溃
    |     |
    |     +---> 检查 dmesg | grep -i oom（内存不足）
    |     +---> 检查后端错误日志（PHP fatal error、core dump）
    |     +---> 检查 upstream 是否被 OOM Killer 杀死
    |
    +---> "upstream timed out" ---> 后端处理超时
    |     |
    |     +---> 检查后端处理时间（数据库查询、外部 API）
    |     +---> 调整 proxy_read_timeout
    |     +---> 优化后端性能或增加资源
    |
    +---> "no live upstreams" ---> 所有 upstream 都不可用
          |
          +---> 检查所有 upstream server 的健康状态
          +---> 可能是 max_fails 导致所有节点被暂时禁用
          +-----> 等待 fail_timeout 过去或重启 upstream

六、自检清单

6.1 部署前检查清单

[ ] Nginx 配置文件语法验证通过：nginx -t
[ ] 后端服务已启动并监听正确端口
[ ] upstream 配置的 IP:端口与实际一致
[ ] 超时参数（proxy_connect_timeout、proxy_read_timeout）已根据业务调整
[ ] 缓冲区参数（proxy_buffer_size、proxy_buffers）已配置
[ ] keepalive 配置已启用（proxy_http_version 1.1 + Connection ""）
[ ] socket 文件权限正确（listen.owner/listen.group）
[ ] SELinux/AppArmor 策略允许 Nginx 与后端通信
[ ] 日志级别设置为 warn 或 error
[ ] 健康检查已配置（被动或主动）

6.2 故障发生时的快速检查项

[ ] 查看 error.log，确认具体错误信息
[ ] 确认后端服务进程存活：systemctl status php-fpm
[ ] 确认端口/socket 监听：ss -tlnp | grep 9000
[ ] 测试后端可连接性：curl -v http://127.0.0.1:9000/health
[ ] 检查系统资源（CPU、内存、磁盘IO）
[ ] 检查 dmesg 中是否有 OOM Killer 记录
[ ] 检查 upstream 是否被标记为 down

6.3 复盘与预防检查项

[ ] 错误是否可复现
[ ] 根因是否已定位并解决
[ ] 是否有监控告警覆盖同类问题
[ ] 是否需要调整超时/缓冲区等参数
[ ] 是否需要增加资源或优化架构
[ ] 是否更新了 SOP 和运维文档

附录 A：错误日志关键字索引

关键字	根因	处理优先级
connect() failed (111)	upstream 未监听端口	P0 - 立即处理
upstream prematurely closed	upstream 崩溃	P0 - 立即处理
upstream timed out	后端响应超时	P1 - 优化超时
no live upstreams	所有 upstream 不可用	P0 - 立即处理
buffer is too small	缓冲区配置不足	P1 - 调整缓冲区
Permission denied	权限问题	P0 - 立即处理
connection reset	upstream 强制断开	P1 - 检查 upstream 健康
broken header	upstream 返回损坏响应	P1 - 检查 upstream

附录 B：命令速查卡片

# Nginx 基础操作
nginx -t                    # 测试配置语法
nginx -s reload            # 优雅重载配置
nginx -s stop              # 快速关闭
nginx -s quit              # 优雅关闭
nginx -V                   # 查看版本和编译参数

# 日志分析
tail -f /var/log/nginx/error.log | grep 502
awk '$9==502 {count++} END {print count}' /var/log/nginx/access.log
grep -C 5 "502" /var/log/nginx/error.log

# 后端服务检查
systemctl status php-fpm
ss -tlnp | grep -E ':(80|443|9000)'
ps aux | grep php-fpm
netstat -ant | grep :8080 | wc -l

# 健康检查
curl -v http://127.0.0.1:8080/health
SCRIPT_NAME=/ping cgi-fcgi -bind -connect /var/run/php-fpm/www.sock
nc -zv 127.0.0.1 9000 -w 3

# 性能监控
ss -s                          # 连接统计
top -b -n 1 | head -20         # 系统资源
nginx -s reopen               # 重新打开日志文件（配合 logrotate）

附录 C：配置参数参考表

upstream 指令

指令	默认值	说明
server	-	定义 upstream server，格式：address [parameters]
weight	1	权重，用于加权轮询
max_fails	1	失败次数阈值，超过后标记为不可用
fail_timeout	10s	失败超时时间，同时也是不可用持续时间
backup	-	标记为备用服务器
down	-	标记为永久不可用
keepalive	-	keepalive 连接池大小
keepalive_requests	1000	单连接最大请求数
keepalive_timeout	60s	keepalive 空闲超时
slow_start	0	慢启动时间（商业版 Nginx Plus）

proxy 指令

指令	默认值	说明
proxy_pass	-	指定 upstream 或 URL
proxy_http_version	1.0	HTTP 版本
proxy_connect_timeout	60s	连接超时
proxy_send_timeout	60s	发送请求超时
proxy_read_timeout	60s	读取响应超时
proxy_buffer_size	4k/8k	响应头缓冲区
proxy_buffers	8 4k/8k	响应体缓冲区
proxy_busy_buffer_size	proxy_buffer_size	忙碌缓冲区
proxy_buffering	on	是否启用缓冲
proxy_max_temp_file_size	1024m	临时文件总大小
proxy_temp_file_write_size	proxy_buffer_size	单次写入临时文件大小
proxy_set_header	Host $proxy_host	设置请求头
proxy_next_upstream	error timeout	故障转移条件

本文档由运维团队基于多年生产环境排障经验整理，涵盖 Nginx 502 错误的识别、诊断、处理的完整方法论。如有补充或修正，请提交 PR 至内部文档仓库。

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

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

Docker 最新动态：Docker Desktop 4.84 发布，AI、本地模型与安全镜像成为主线

Thu, 06 Aug 2026 18:33:36 +0800

截至 2026 年 8 月，Docker 生态最近几个月的变化非常密集。Docker Desktop、Docker Engine、Docker Hardened Images、Docker Model Runner、Gordon AI Agent、Docker Offload 都在持续更新。

如果用一句话概括 Docker 当前的方向：Docker 正在从“容器开发工具”升级为面向 AI 原生应用、供应链安全和企业开发环境的一体化平台。

1. Docker Desktop 4.84 发布：继续强化桌面端开发体验

根据 Docker 官方文档，Docker Desktop 最新版本已更新到4.84.0，发布时间为2026 年 7 月 27 日。

这一版本主要更新包括：

Docker Agent v1.111.0
Docker Hardened Images CLI dhictl v0.0.7
Docker Desktop CLI v0.4.3
Kubernetes 组件更新，包括 cri-dockerd v0.4.4
修复无效 ~/.docker/config.json 导致 Docker Desktop 高 CPU / 高内存占用并卡住的问题

在此前的 4.83.0 和 4.80.0 中，Docker Desktop 还更新了 Docker Engine、Docker Compose、Docker Model Runner、Docker Offload、Buildx、containerd、runc 以及内置 Kubernetes 版本。

这说明 Docker Desktop 已经不只是一个本地容器 GUI，它正在成为 Docker AI、模型运行、Kubernetes、本地构建、安全扫描和企业策略控制的统一入口。

2. Docker Engine 29.6.2：重点修复安全漏洞

Docker Engine 最新 29.x 分支中，29.6.2 于 2026 年 7 月 16 日发布。这个版本的重点是安全修复。

官方发布说明中列出了多项安全漏洞修复，包括：

Git source checkout 相关命令注入风险
构建前端参数导致 panic 的问题
LLB 文件操作可能误删 /tmp 内容的问题
上传本地 source 时目录校验绕过问题
Windows 容器缓存挂载中 NTFS junction 解析问题

此外，Docker Engine 29.6.2 还更新了：

containerd 静态二进制到 v2.2.6
Go runtime 到 1.26.5
RootlessKit 到 v3.0.2

对生产环境来说，这类版本非常值得关注。它不是“功能炫技型更新”，而是直接关系到构建链路、镜像处理、Windows 容器和 rootless 场景的安全性。

建议企业用户优先评估升级，尤其是 CI/CD 构建节点、共享构建平台和多租户容器环境。

3. Docker Hardened Images：安全镜像正在成为默认起点

过去一年，Docker 在安全镜像方向投入明显加速。Docker Hardened Images（DHI）已经成为 Docker 生态中最重要的新产品线之一。

Docker 官方在 2026 年多篇文章中持续强调 DHI 的定位：它不是简单的 slim 镜像，而是面向生产环境的安全基础镜像，特点包括：

更小攻击面
持续修复 CVE
SBOM 软件物料清单
SLSA Build Level 3 provenance
OpenVEX 数据
加密签名
基于 Alpine 和 Debian 等常见发行版
Community 版本免费开放，Apache 2.0 许可

Docker 官方还表示，DHI Catalog 已经扩展到数千个镜像、MCP server、Helm chart 和 ELS 镜像，并且日拉取量已经达到较高规模。

对开发者来说，最直接的变化是：以后选择基础镜像时，不应只看体积小不小，还要看它是否可验证、是否持续维护、是否有 SBOM 和签名。

换句话说，FROM debian:slim 这类传统选择，未来可能会逐步被更安全的 hardened image 替代。

4. Docker Model Runner：Docker 正在进入本地 AI 模型工作流

AI 是 Docker 近期最明显的产品方向之一。

Docker Model Runner 已经进入 GA 阶段，它允许开发者用熟悉的 Docker 工作流运行本地大模型。它支持：

从 Docker Hub 拉取 OCI 格式模型
从 Hugging Face 获取 GGUF 模型
使用 OpenAI 兼容 API 调用本地模型
在 Docker Desktop 和 CLI 中管理模型
支持本地 GPU 加速
与 Compose、MCP、AI 应用开发流程集成

这对开发者的意义很直接：以前本地跑模型往往需要安装 Python 环境、推理框架、驱动、模型管理工具；现在 Docker 希望把模型也变成一种“可分发、可运行、可管理”的制品。

容器镜像解决了应用分发问题，OCI Artifact 正在进一步承载模型分发问题。

5. Gordon GA：Docker 的 AI Agent 已进入正式可用阶段

Docker 的 AI AgentGordon也已经 GA。

Gordon 的定位不是通用聊天机器人，而是理解 Docker 工作流的 AI 助手。它可以在 Docker Desktop 和 CLI 中使用，帮助开发者处理：

容器启动失败
镜像构建报错
Compose 服务连接问题
Dockerfile 优化
本地环境排查
容器化建议
部署前检查

它的关键点是：Gordon 可以读取当前 Docker 环境上下文，并在用户批准后执行操作。

这和普通 AI 编程助手不同。普通助手可以解释错误，但未必知道你当前有哪些容器、镜像、网络、volume、Compose 项目。Gordon 的优势就是贴近 Docker 实际运行环境。

6. Docker Offload GA：本地跑不动，也能用 Docker

Docker Offload 已于 2026 年 4 月进入 GA。

这个功能主要解决一个企业开发痛点：很多开发者处在 VDI、托管桌面、低配置电脑或受限环境中，本地无法完整运行 Docker Desktop 或大型构建任务。

Docker Offload 的思路是：保留本地 Docker 开发体验，但把重负载放到远程资源上执行。

这对企业团队很有价值，尤其是：

远程办公团队
外包和受控终端环境
低配置开发机
需要更快构建资源的团队
安全策略限制本地虚拟化的公司

Docker 的方向很明确：开发者仍然使用熟悉的 Docker 命令，但计算资源不一定必须在本机。

7. 对国内开发者和企业的建议

结合 Docker 近期动态，建议关注几个实践方向。

第一，尽快升级 Docker Engine 和 Docker Desktop，尤其是涉及构建平台、安全扫描、共享开发环境的场景。

第二，评估 Docker Hardened Images。基础镜像安全已经不只是安全团队的问题，它会直接影响每一个业务镜像的漏洞数量和修复成本。

第三，AI 应用开发者可以关注 Docker Model Runner。对于本地调试 AI 应用、验证 OpenAI 兼容接口、测试模型服务，它正在变成一个低门槛入口。

第四，仍在维护复杂 Compose 项目的团队，可以关注 Docker AI、Gordon、Model Runner、MCP Toolkit 之间的组合能力。Docker 正在把容器、模型、工具调用和 AI Agent 串成一个开发闭环。

第五，企业环境可以关注 Docker Offload。未来“本地 Docker 体验 + 云端/远端执行资源”可能会成为企业开发环境的新常态。

结语

2026 年的 Docker，已经不只是我们熟悉的 docker run 和 docker build。

它正在围绕三个方向重新组织产品能力：

AI 原生开发：Model Runner、Gordon、MCP Toolkit
供应链安全：Docker Hardened Images、SBOM、签名、VEX、SLSA provenance
企业级开发体验：Docker Desktop、Docker Offload、统一 CLI 和远程执行能力

对开发者来说，Docker 仍然是那个最熟悉的容器工具；但对平台团队和企业来说，Docker 正在成为连接本地开发、AI 模型、安全镜像和生产交付的重要基础设施。

参考来源：

Docker Desktop Release Notes：
https://docs.docker.com/desktop/release-notes/
Docker Engine 29 Release Notes：
https://docs.docker.com/engine/release-notes/29/
Docker Hardened Images：
https://www.docker.com/products/hardened-images/
Docker Model Runner：
https://www.docker.com/products/model-runner/
Gordon：
https://www.docker.com/products/gordon/
Docker Offload GA：
https://www.docker.com/blog/docker-offload-now-generally-available-the-full-power-of-docker-for-every-developer-everywhere/

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

Kubernetes 最新动态：v1.36 发布，AI、GPU、安全与流量治理成为主线

Mon, 29 Jun 2026 17:17:50 +0800

截至 2026 年 6 月，Kubernetes 最新稳定版本已经来到 v1.36.2。根据 Kubernetes 官方发布页，v1.36 当前处于活跃支持状态，最新补丁版本 v1.36.2 于 2026 年 6 月 9 日发布，维护周期预计持续到 2027 年 6 月 28 日。

这次 v1.36 版本代号为 Haru，官方发布于 2026 年 4 月 22 日。相比单纯的功能堆叠，v1.36 更像是 Kubernetes 面向下一阶段基础设施需求的一次集中推进：更强的安全隔离、更成熟的 GPU/AI 资源管理、更稳定的存储能力，以及更现代的流量入口体系。

1. Kubernetes v1.36：70 项增强，18 项进入稳定版

Kubernetes v1.36 共包含 70 项增强，其中 18 项进入 Stable/GA，25 项进入 Beta，25 项进入 Alpha。

几个值得重点关注的方向包括：

User Namespaces 正式 GA

User Namespaces 在 v1.36 中进入稳定版。它允许容器内的 root 用户映射为宿主机上的非特权用户。简单说，即使容器内进程以 root 身份运行，它在宿主机上也不再天然拥有 root 权限。

这对多租户集群、安全敏感型业务、边缘节点和平台团队都很关键。容器逃逸风险无法只靠“不要出漏洞”来解决，Kubernetes 正在把更强的隔离能力做成默认可依赖的基础能力。

细粒度 Kubelet API 授权 GA

过去很多监控和排障场景需要较宽泛的 nodes/proxy 权限。v1.36 中细粒度 Kubelet API 授权进入 GA，可以让平台团队按最小权限原则授予访问能力，降低观测工具、自动化组件或内部平台被滥用后的影响面。

PSI 指标 GA：更准确地判断节点压力

基于 cgroup v2 的 PSI（Pressure Stall Information）指标进入稳定版。它能帮助 kubelet 暴露 CPU、内存、I/O 等资源压力信号。

这类指标比单纯的资源使用率更接近真实体验：一个节点可能“看起来 CPU 没满”，但应用已经因为资源竞争出现等待和抖动。PSI 对容量规划、自动扩缩容、性能诊断都有直接价值。

2. AI 与 GPU 工作负载：DRA 继续成熟

Dynamic Resource Allocation（DRA，动态资源分配）是 Kubernetes 近几个版本最值得关注的方向之一。到了 v1.36，DRA 生态中部分治理和选择能力已经进入 Stable，同时更多能力进入 Beta。

这背后的趋势很清晰：Kubernetes 正在从“调度 CPU 和内存”走向“调度 GPU、DPU、专用加速卡、可切分设备和复杂硬件拓扑”。

对 AI 平台来说，这意味着未来 Kubernetes 可以更原生地表达：

GPU 等专用设备的分配和健康状态
多租户场景下的资源隔离与优先级
设备容量、分区、污点和容忍度
大模型训练、推理、HPC 任务中的硬件编排

v1.36 中 Pod 的 allocatedResourcesStatus 字段也进入 Beta，用户可以通过 kubectl describe pod 更直接地看到已分配设备是否处于 Unhealthy 或 Unknown 状态。这对定位 GPU 故障导致的 CrashLoop 非常实用。

3. 存储能力继续补齐：卷组快照 GA

VolumeGroupSnapshot 在 v1.36 中进入 GA。它允许用户对多个 PVC 同时创建崩溃一致性快照。

这对数据库、中间件、分布式存储和多卷应用尤其重要。很多真实业务并不是一个 Pod 只挂一个卷，恢复时也不能只恢复其中一块盘。卷组快照进入稳定版，意味着 Kubernetes 在有状态应用备份恢复方面继续补齐生产能力。

同时，Mutable CSINode Allocatable 也进入稳定版。CSI 驱动可以动态更新节点可挂载卷数量，kubelet 无需重启即可刷新相关信息，调度器也能获得更准确的存储容量视图。

4. OCI 不只装镜像：OCI Volume Source GA

v1.36 中 OCI Volume Source 进入稳定版。开发者可以把模型文件、静态资源、配置包等只读内容打包成 OCI Artifact，然后像使用镜像仓库一样分发给 Pod。

这对 AI 模型分发、边缘节点内容同步、静态资源版本化都很有想象空间。过去我们习惯把 OCI Registry 当作“镜像仓库”，但现在它正在变成更通用的软件制品分发基础设施。

5. 流量入口变局：Gateway API v1.5 与 Ingress NGINX 退役

除了 Kubernetes v1.36 本身，流量治理领域也有两个重要变化。

Gateway API v1.5 已发布

Gateway API v1.5 于 2026 年 2 月 27 日发布，官方称这是目前最大的一次 Gateway API 发布。v1.5 将 6 个常用功能推进到 Standard/Stable 通道，包括 ListenerSet、TLSRoute、HTTPRoute CORS Filter、客户端证书校验、Gateway TLS Origination 证书选择、ReferenceGrant 等。

其中 ListenerSet 对多团队共享网关很有价值。平台团队可以维护统一 Gateway，应用团队通过 ListenerSet 独立扩展自己的监听配置，减少多个团队直接修改同一个 Gateway 对象带来的协作风险。

Ingress NGINX 已进入退役阶段

Kubernetes SIG Network 和安全响应委员会此前宣布，Ingress NGINX 的最佳努力维护持续到 2026 年 3 月。之后将不再发布新版本、Bugfix 或安全漏洞修复。现有部署不会立刻失效，镜像和 Helm Chart 等制品仍会保留，但官方建议用户尽快迁移到 Gateway API 或其他 Ingress Controller。

这对很多生产集群是一个必须排期处理的事项。尤其是仍在使用 ingress-nginx 的团队，应尽快盘点集群并制定迁移方案。

可用以下命令初步检查是否部署了 Ingress NGINX：

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

6. 升级建议：先盘点，再分阶段推进

对生产环境来说，不建议只因为“新版本发布”就立刻升级。但 v1.36 带来的变化值得提前评估。

建议重点检查：

当前 Kubernetes 版本是否仍在支持周期内
是否仍依赖 Service spec.externalIPs
是否使用已经移除的 gitRepo volume
是否部署了 Ingress NGINX
是否有 GPU、AI、HPC 等专用硬件调度需求
是否准备启用 Gateway API 替代传统 Ingress
是否有多租户安全隔离需求，可评估 User Namespaces

尤其要注意，v1.36 已废弃 Service spec.externalIPs，并计划在未来版本移除；gitRepo volume driver 在 v1.36 中已经被永久禁用。

结语

Kubernetes v1.36 的关键词不是“更多功能”，而是“更适合现代基础设施”。

它把安全隔离、硬件资源管理、存储快照、流量治理和制品分发继续往生产级推进。对于正在建设云原生平台、AI 平台或多租户 PaaS 的团队来说，v1.36 值得重点关注；对于仍在使用 Ingress NGINX 的团队，迁移计划也应该尽快提上日程。

Kubernetes 已经不只是容器编排系统，它正在成为 AI 时代基础设施调度和治理的核心底座。

参考来源：

Kubernetes Releases：
https://kubernetes.io/releases/
Kubernetes v1.36 发布公告：
https://kubernetes.io/blog/2026/04/22/kubernetes-v1-36-release/
Gateway API v1.5：
https://kubernetes.io/blog/2026/04/21/gateway-api-v1-5/
Ingress NGINX Retirement：
https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/

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