掌握这10个配置项，NGINX Ingress 不再只是"能跑就行"。

在现代 Kubernetes 集群中，Ingress Controller 扮演着"流量调度员"的角色——它决定了外部请求如何路由到集群内部的服务。虽然 Kubernetes 本身不自带 Ingress Controller，但社区提供了多种实现方案，其中 NGINX Ingress Controller 知名度无疑是最高的。虽然2026年3月24日NGINX Ingress Controller的Github仓库已处于归档状态，但还是有不少存量使用。

很多团队安装完 NGINX Ingress 之后，只用了最基础的路由功能，白白浪费了它强大的配置能力。今天我们就来聊聊 10 个最实用的 NGINX Ingress 配置技巧，帮你把流量管理打磨得更精细、更安全、更高效，也为其他Ingress Controller的使用提供参考。

---

两种配置方式：Annotations vs ConfigMap

在开始之前，先了解 NGINX Ingress 的两种配置途径：

• Annotations（注解）：针对单个 Ingress 规则的配置，灵活精准
• ConfigMap：全局配置，作用于整个 NGINX Ingress Controller

注意：Annotations 的优先级通常高于 ConfigMap。也就是说，如果同一个配置项在两个地方都有定义，以 Annotations 为准。

---

1. WWW 域名重定向

很多网站需要处理 www.example.com 和 example.com 之间的跳转。NGINX Ingress 一行注解就能搞定：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    nginx.ingress.kubernetes.io/from-to-www-redirect: "true"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: my-service
            port:
              number: 4000

开启后，www.example.com 会自动重定向到 example.com（或反向），再也不用额外写 Nginx 配置。

---

2. SSL/HTTPS 重定向

安全永远是第一位的。强制 HTTP 流量走 HTTPS（目标 HTTPS 服务必须可用），是生产环境的标配：

annotations:
  # 强制使用 HTTPS，即使没有配置 TLS 证书也会重定向
  nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
  # 启用 SSL 重定向（通常与上面配合使用）
  nginx.ingress.kubernetes.io/ssl-redirect: "true"
  # 保留路径末尾的斜杠
  nginx.ingress.kubernetes.io/preserve-trailing-slash: "true"

如果某个内部服务暂时不需要 HTTPS，可以设 ssl-redirect: "false" 关闭。

---

3. 超时时间调优

后端服务响应慢？合理设置超时可以避免不必要的连接堆积：

配置项	说明	默认值
proxy-connect-timeout	与后端建立连接的超时	60s
proxy-read-timeout	等待后端响应的超时	60s
proxy-send-timeout	向后端发送请求的超时	60s

annotations:
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "30s"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "20s"

对于长轮询、流式响应等场景，适当调大 proxy-read-timeout 可以避免连接被提前断开。

---

4. CORS 跨域配置

前后端分离、微服务架构中，跨域问题是绕不开的。NGINX Ingress 直接在 Ingress 层面就能处理：

annotations:
  # 启用 CORS
  nginx.ingress.kubernetes.io/enable-cors: "true"
  # 允许的 HTTP 方法
  nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"
  # 允许的请求头
  nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-Custom-Header"
  # 允许暴露的响应头
  nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"
  # 预检请求缓存时间（秒）
  nginx.ingress.kubernetes.io/cors-max-age: "600"
  # 是否允许携带凭证
  nginx.ingress.kubernetes.io/cors-allow-credentials: "false"

不用在代码里加 @CrossOrigin，也不用每个微服务都配置一遍，统一在 Ingress 层管理，清爽多了。

---

5. 限流（Rate Limiting）

防刷、防 DDoS、保护后端不被突发流量打垮——限流是生产环境必配的安全措施：

annotations:
  # 每秒请求数限制
  nginx.ingress.kubernetes.io/limit-rps: "5"
  # 每分钟请求数限制
  nginx.ingress.kubernetes.io/limit-rpm: "300"
  # 单 IP 最大并发连接数
  nginx.ingress.kubernetes.io/limit-connections: "10"

注意：如果同时设置了 limit-rps 和 limit-rpm，两者同时生效。

默认返回 503 Service Temporarily Unavailable （可通过 NGINX 配置调整为429），有效保护后端服务。

---

6. 请求体大小限制

文件上传、大 payload 提交场景，默认的请求体大小限制可能不够用：

annotations:
  nginx.ingress.kubernetes.io/proxy-body-size: "8m"

超过这个限制，NGINX 会直接返回 413 Request Entity Too Large。根据业务需求调整这个值，既不能太小（正常上传被拦截），也不能太大（恶意请求撑爆内存）。

---

7. IP 白名单

只允许特定 IP 或 IP 段访问？这对内部管理系统、预发环境特别有用：

annotations:
  nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/24,172.16.10.1/32"

配置后，只有来自 10.0.0.0/24 网段和 172.16.10.1 的请求能通过，其他来源直接拒绝。

小贴士：如果白名单 IP 无法访问资源，可能需要检查 Service 定义中的 externalTrafficPolicy 配置，确保源 IP 能正确传递。

---

8. 默认后端（Default Backend）

当请求没有匹配到任何 Ingress 规则时怎么办？NGINX Ingress 支持设置默认后端来处理这些"迷路"的请求：

annotations:
  nginx.ingress.kubernetes.io/default-backend: "custom-error-handler"

通常的做法是配置一个友好的 404 页面服务，或者统一错误处理服务，而不是返回默认的 NGINX 404 页面。

---

9. 访问日志开关

NGINX Ingress 默认会记录访问日志。但对于高频的健康检查请求、内部探针，大量无意义的日志会占用磁盘空间：

annotations:
  nginx.ingress.kubernetes.io/enable-access-log: "false"

可以在特定的 Ingress 上关闭访问日志，或者在 ConfigMap 中全局关闭后，只在需要的 Ingress 上单独开启。

---

10. 后端协议指定

NGINX 与后端服务的通信协议默认是 HTTP，但如果你的后端用的是 HTTPS、gRPC 或其他协议呢？

annotations:
  nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

支持的值包括：HTTP、HTTPS、GRPC、GRPCS、AJP、FCGI。当后端服务配置了 TLS 或者使用 gRPC 时，这个配置是必须的。

---

最佳实践小结

把上面这些配置用好，再加上几条最佳实践，你的 NGINX Ingress 就足够在生产环境稳稳运行了：

1. 限流必配——保护后端不被突发流量打垮
2. 强制 HTTPS——安全底线
3. 合理设置资源限制——给 Ingress Controller 的 Pod 设置 resource requests/limits
4. 配合 HPA 自动扩缩容——根据 CPU/请求量自动调整 Controller Pod 数量
5. 非 root 运行——NGINX Ingress 默认以非 root 用户运行，配合只读文件系统进一步提升安全性

---

写在最后

NGINX Ingress Controller 的强大之处就在于：它既是流量入口，也是安全屏障，还是性能调优的关键节点。安装只是第一步，真正用好这些配置项，才能让 Kubernetes 的流量管理发挥出最大价值。

如果你有常用的"神仙配置"，欢迎在评论区分享交流！

---

参考来源：Kubernetes NGINX Ingress: 10 Useful Configuration Options