机制定位
ingress-nginx 通过 Ingress 上的注解扩展 Nginx 行为：路径重写、请求体大小、超时、后端协议、强制跳转等都靠注解控制。适用平台是 Kubernetes 上的 ingress-nginx 控制器（其他控制器如 Traefik、HAProxy 的注解体系不通用）。注解的特点是不参与 schema 校验——写错名字或值不会报错，只是行为不符合预期，因此排障时要把「注解是否被正确解析」当成一个独立检查项。
基本信息
| 适用平台 | Kubernetes，ingress-nginx 控制器（注解前缀 nginx.ingress.kubernetes.io/） |
|---|---|
| 配置位置 | Ingress 的 metadata.annotations |
| 生效方式 | 控制器监听对象变更后重载 Nginx 配置 |
| 生效范围 | 默认作用于该 Ingress，部分注解可在控制器级别设默认值 |
典型使用场景
- 上传接口报 413：用 proxy-body-size 放大允许的请求体上限
- 长轮询与流式接口超时：调大 proxy-read-timeout 与 proxy-send-timeout
- 路径重写：把 /api 前缀去掉再转给后端，配合 rewrite-target 与 use-regex
- 强制 HTTPS：用 force-ssl-redirect 让 HTTP 请求统一跳转
- 后端是 HTTPS 服务：用 backend-protocol 指定转发协议，否则出现 502
常用注解示例
常用注解示例
metadata:
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
nginx.ingress.kubernetes.io/use-regex: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"核对生效情况
核对生效情况
kubectl get ingress web -o jsonpath='{.metadata.annotations}' # 注解原样内容
kubectl -n ingress-nginx logs deploy/ingress-nginx-controller --tail=50 | grep -i -E 'error|skip|invalid'
kubectl -n ingress-nginx exec deploy/ingress-nginx-controller -- cat /etc/nginx/nginx.conf | head -40
kubectl describe ingress web | tail -15 # 事件里常有解析提示注解速查
| 注解 | 作用 | 常见误区 |
|---|---|---|
| rewrite-target | 重写转发路径（常配 use-regex） | 与 pathType 组合时语义容易写错 |
| proxy-body-size | 允许的请求体上限 | 只影响该 Ingress，需逐个配置 |
| proxy-read-timeout | 后端读取超时 | 单位是秒，写成 2m 无效 |
| backend-protocol | 转发到后端的协议 | 后端是 HTTPS 时不写会 502 |
| force-ssl-redirect | HTTP 强制跳 HTTPS | 值需带引号写成字符串 |
rewrite-target 与 pathType Prefix 组合时语义微妙，先在小流量域名验证重写结果，再推广到主入口。
注解写错不会报错：名字拼错或值类型不对时控制器会忽略它，表现为「配置了但没效果」，排查时先确认注解被识别。
生效排查顺序
- 先确认注解名拼写与字符串引号，控制器对未知注解不会给出任何提示
- 再看控制器日志里的重载记录，确认配置确实被重新生成
- 接着核对重写与转发结果：用 curl 带上路径访问，观察实际落到的后端路径
- 最后排查后端自身：502 与超时类问题常常来自服务端协议与耗时，而不是注解本身