#如何调整 Webservice Ingress 超时和正文大小

本文介绍如何配置 gitlab.webservice.ingress 下公开的三个 NGINX Ingress 参数、何时需要调整它们，以及如何在其他 Ingress controller 上应用相同意图。

适用场景：

• 推送大型仓库、LFS 对象或容器镜像时失败，并报出 413 Request Entity Too Large。
• 对大型仓库执行 git clone / git push / 项目导入时，在约 10 分钟后超时并报出 502 Bad Gateway。
• 升级或重启 webservice 后，短暂出现 502 Bad Gateway。

#背景

GitLab webservice 通过 NGINX Ingress 暴露。随附的 Helm chart 在 GitlabOfficial CR 的 spec.helmValues.gitlab.webservice.ingress 下公开了三个参数。它们会被渲染到 <RELEASE>-webservice-default Ingress 对象上的 NGINX Ingress 注解中：

apiVersion: operator.alaudadevops.io/v1alpha1
kind: GitlabOfficial
metadata:
  name: sample
spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          proxyConnectTimeout: 15    # seconds, -> nginx.ingress.kubernetes.io/proxy-connect-timeout
          proxyReadTimeout: 600      # seconds, -> nginx.ingress.kubernetes.io/proxy-read-timeout
          proxyBodySize: "512m"      # size,    -> nginx.ingress.kubernetes.io/proxy-body-size

这些默认值适用于大多数安装环境。这三个参数彼此密切相关——大型仓库通常既需要更大的正文大小，也需要更长的读取超时——因此通常应当一起调整，而不是一次只调一个。

#前提条件

• 有权限编辑 GitlabOfficial CR （kubectl edit gitlabofficial <NAME> -n <NS>）。
• 只有当集群使用社区版 ingress-nginx controller （kubernetes/ingress-nginx）时，proxyConnectTimeout / proxyReadTimeout / proxyBodySize 这些字段才会生效，因为该 chart 会将它们渲染到 nginx.ingress.kubernetes.io/* 注解命名空间下。对于其他 controller，请参见下面的 配置其他 Ingress controller。
• 检查请求路径中的每一跳。 如果在 GitLab 自身的 Ingress 前面还有平台级 LB 或反向代理，那么也必须在这些位置提高相同限制——有效限制取决于整条链路中的最小值。

#为大型仓库 / 上传调优（ingress-nginx）

对于托管大型仓库、LFS 对象或 container/package registry 流量的安装，通常会同时出现三种症状，并且它们的修复方式相同——将这三个参数一起调大：

对于具有大型仓库 / LFS / Registry 的 GitLab 实例，建议从以下值开始：

spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          proxyConnectTimeout: 30      # 15 -> 30; modest bump to absorb pod-restart jitter
          proxyReadTimeout: 1800       # 600 -> 1800; 30 min for large clone/push/import
          proxyBodySize: "5g"          # 512m -> 5g;  fits LFS / registry blobs

请根据实际使用情况选择数值：

proxyConnectTimeout 通常是症状，而不是调优旋钮。 rollout 期间短暂出现 502，通常意味着 webservice Pod 启动较慢，或者 readiness probe 配置不正确——应先修复这些问题。只有在环境中 TCP 建连确实较慢时，例如跨 AZ 网络，才应将其调大到 30–60s。把它设成 600 之类的大值只会掩盖真实的后端故障，并堆积 NGINX worker 线程。

proxyBodySize 只控制 Ingress 层。 GitLab 自身在 Admin Area → Settings → General → Account and limit 下配置了应用层限制（max push size、max attachment size、max import size 等）。如有需要，请同步调大这些限制。

提示： 对于非常大的 Git 操作，优先使用 SSH（git@）而不是 HTTPS。SSH 流量不会经过 HTTP Ingress，因此不受这三个参数的影响。

#配置其他 Ingress controllers

上面的三个顶层字段只会在 nginx.ingress.kubernetes.io/* 命名空间下生成注解，并会被以下 controller 忽略：

• Traefik、HAProxy、Contour、Istio Gateway 以及其他非 NGINX controller。
• F5 NGINX Inc. 的 nginxinc/kubernetes-ingress —— 它使用不同的注解命名空间（nginx.org/*）。

对于这些 controller，请通过 gitlab.webservice.ingress.annotations 直接设置等效注解；该字段会合并到渲染出的 Ingress 对象中。

F5 NGINX Inc.（nginx.org/*）示例：

spec:
  helmValues:
    gitlab:
      webservice:
        ingress:
          annotations:
            nginx.org/client-max-body-size: "5g"
            nginx.org/proxy-read-timeout: "1800s"
            nginx.org/proxy-connect-timeout: "30s"

对于 Traefik，proxyBodySize 的等效项是 Middleware 资源中的 buffering.maxRequestBodyBytes，而超时则是在 IngressRoute / EntryPoint 级别配置，而不是通过逐个 Ingress 的注解配置。请单独定义这些资源，并可选地通过 annotations 中的 traefik.ingress.kubernetes.io/router.middlewares 引用它们。

当 global.ingress.provider 设置为 nginx 以外的值时，不会注入 nginx.ingress.kubernetes.io/* 注解，但仍会渲染 Ingress 资源本身——annotations 中的值会被保留。如果所选 controller 根本不支持针对这些限制的逐个 Ingress 注解，请在 controller 本身上进行配置。

#验证已应用的配置

更新 CR 并等待 reconciliation 之后，请检查 Ingress 对象上的注解：

kubectl -n <NAMESPACE> get ingress <RELEASE>-webservice-default \
  -o jsonpath='{.metadata.annotations}' | tr ',' '\n' \
  | grep -E 'body-size|read-timeout|connect-timeout'

预期输出（ingress-nginx 示例）：

"nginx.ingress.kubernetes.io/proxy-body-size":"5g"
"nginx.ingress.kubernetes.io/proxy-connect-timeout":"30"
"nginx.ingress.kubernetes.io/proxy-read-timeout":"1800"

如果这些值不匹配：

• 确认 CR 已在 spec.helmValues.gitlab.webservice.ingress 下更新（不是在 spec.helmValues.nginx-ingress.controller.* 下，后者是不同层级）。
• 检查 operator 是否成功完成 reconciliation： kubectl describe gitlabofficial <NAME> -n <NS>。
• 确认 GitLab 自身 Ingress 前面没有上游 Ingress / LB 正在强制执行更严格的限制。

#更大的值总是更好吗？

不是。每个参数都有代价：

• proxyBodySize 过大——NGINX 会缓冲（或流式传输）整个正文；单个超大上传可能会使 Ingress Controller 节点的内存和磁盘使用量飙升。请将其设置为略高于你的真实最大值，而不是任意调得很高。
• proxyReadTimeout 过大——缓慢或卡住的上游连接会长期占用 NGINX worker slot，降低其他用户可用的并发能力。应选择与最大合法请求相匹配的值，而不是“尽可能大”。
• proxyConnectTimeout 过大——会通过等待很多分钟才返回错误来掩盖真实的后端故障（Pod 未就绪、网络故障）。应保持较小值（15–60s），并修复后端问题。

#参考

• NGINX Ingress annotations: https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/
• F5 NGINX Inc. annotations: https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/