一次 GitLab 大仓库 Clone 中断排查

一次 GitLab 大仓库 Clone 中断排查：从 OpenVPN 到 Nginx 代理超时

写在前面

这次案例的表象很常见：研发在家连 OpenVPN 后，从自建 GitLab clone 大仓库时总是在 80% 左右中断。最开始很容易被归因为“办公室网络慢”或者“VPN 不稳定”，但实际排查后发现，问题的关键点在 Nginx 反向代理 GitLab 时的默认超时配置，以及 VPN 场景下长连接传输产生的瞬时停顿。

本文不会重点讲 GitLab 如何部署，而是围绕一次真实的故障排查过程，梳理：

1. 为什么 Web 页面正常，但git clone大仓库会失败。
2. 为什么平均下载速度不慢，仍然会触发中断。
3. proxy_read_timeout到底控制的是什么。
4. 为什么不能为了 clone 直接对整个 GitLab 站点关闭proxy_buffering。
5. 最终如何调整 Nginx 配置，并避免二次故障。

环境与脱敏说明

文中已对内部域名、公网/内网 IP、仓库路径、Nginx 日志目录等做脱敏处理，保留排查方法、故障链路和处置思路。

一、问题背景

研发同事在家通过办公室 OpenVPN访问自建 GitLab，使用HTTP方式 clone 前端等大仓库。

• 办公室内网：同一 GitLab、同一仓库，HTTP clone长期正常
• 家里 + VPN：Web 页面访问 GitLab正常，但git clone大包传到约 80% 左右中断
• 该问题很早就存在，一度被归因为「办公室网速慢限速，以及vpn不稳定的情况」；本次在家复现时平均速度约3 MiB/s，仍会在中途失败

本次复现环境：

• 客户端：Windows + Git Bash（MINGW64）
• VPN：办公室 OpenVPN 线路（UDP，端口1194，服务端<openvpn-server-ip>）
• Clone 地址：http://gitlab.example.com/example-group/example-frontend-repo.git
• 请求路径：80 端口Nginx 反代 → GitLab 内网http://10.x.x.x:80

这类问题比较迷惑的一点是：Web 页面可以正常打开，说明 VPN、DNS、登录认证看起来都没问题；但只要 clone 大仓库，就会在传输中后段失败。

二、故障现象

1. Git 客户端报错

Cloning into 'example-frontend-repo'... remote: Enumerating objects: 179, done. remote: Counting objects: 100% (179/179), done. remote: Compressing objects: 100% (103/103), done. Receiving objects: 82% (131906/159078), 781.40 MiB | 3.65 MiB/s error: RPC failed; curl 18 transfer closed with outstanding read data remaining error: 2968 bytes of body are still expected fetch-pack: unexpected disconnect while reading sideband packet fatal: early EOF fatal: fetch-pack: invalid index-pack output

2. 关键特征

从报错看，curl 18 transfer closed with outstanding read data remaining的含义是：客户端预期还应该继续收到数据，但连接被提前关闭了。它不是 Git 仓库不存在，也不是认证失败，而是典型的传输链路中断。

3. 其他同事场景（参考）

部分同事使用其他 VPN 线路时，OpenVPN 日志曾出现：

AEAD Decrypt error: bad packet ID (may be a replay)

该场景更偏向UDP 隧道丢包/乱序；本次华为 office 线路复现未出现此类日志，根因以Nginx 代理超时 + 客户端背压为主。

三、排查过程

1. 先排除 GitLab 服务端不可用

• GitLab 主机负载不高
• 办公室网络 HTTP clone同一仓库正常
• 说明 GitLab 进程、仓库数据本身无持续性故障

这一步的意义是先确定问题不在 GitLab 仓库本身。如果同一个仓库在办公室网络可以长期正常 clone，说明 GitLab 服务和仓库数据本身没有持续性故障。

2. 重新理解 Nginx 的proxy_read_timeout

Nginx 默认proxy_read_timeout为60 秒，含义是：

从 upstream（GitLab）连续 60 秒读不到任何新数据 → Nginx 主动断开

不是「整次 clone 总时长超过 60 秒才超时」。
只要数据持续流动，计时器会不断重置；中间出现 >60s 的数据空窗才会触发。

这里是本次排查的关键点。很多人看到60s，会误以为是“一次 clone 总时长超过 60 秒就会失败”，但实际不是。

proxy_read_timeout控制的是Nginx 从 upstream 读取两次数据之间允许空闲多久。只要 upstream 持续有数据返回，计时器会不断刷新；真正触发超时的是中间出现连续一段时间没有新数据。

3. 确认请求实际走的是 80 端口 Nginx

Clone 使用http://gitlab.example.com/...，对应 Nginx80的server块（非 443）。

原 80 配置片段（问题版本）：

server { listen 80; server_name gitlab.example.com; location / { client_max_body_size 800m; keepalive_timeout 600s; proxy_buffer_size 64k; proxy_buffers 32 32k; proxy_busy_buffers_size 128k; proxy_set_header X-Forwarded-Proto https; # HTTP 入口硬写 https，建议改为 $scheme proxy_pass http://10.x.x.x:80; # 缺少 proxy_read_timeout / proxy_send_timeout（使用 Nginx 默认 60s） } }

已有keepalive_timeout 600s只影响客户端和 Nginx 之间的连接保活，不能替代 Nginx 到 GitLab upstream 的读超时。

4. 查 Nginx 日志

grep-i"timed out\|upstream"/data/<company>/nginx/log/gitlab.example.com.log

access log 中未搜到 timeout 记录（失败与成功时均无）。可能原因：

• upstream timed out通常写在error.log，不在 access log
• 日志已轮转
• 改配置后问题不再复现，不再产生 timeout 日志

这一步没有直接在 access log 中找到 timeout 记录，但不能因此排除 Nginx 超时。Nginx 的 upstream timeout 通常会写到 error log，而不是 access log；如果日志已经轮转，或者调整配置后不再复现，也可能查不到历史错误。

5. 在家 VPN 环境复现对比

这组对比很关键：加大超时后 clone 可以成功，说明方向基本正确；但加入过于激进的 buffering 参数后 Web 登录 502，说明解决 clone 问题时不能粗暴影响整站请求。

四、根因分析

1. 直接原因

Nginx 反向代理 GitLab 时，使用默认proxy_read_timeout 60s，无法适应Git smart HTTP 大包 clone长连接上的阶段性停顿（中间 >60s 无新数据即断开）。clone 中断的主因是超时过短，不是必须关闭proxy_buffering。

2. 为什么 GitLab 负载不高，也会触发 60 秒无数据？

不是 GitLab 进程挂死 60 秒，而是 Nginx 在 upstream 连接上连续 60 秒没有完成一次 read。常见机制：

机制 A：客户端通过 VPN 收包变慢，引发反向背压

家里客户端 ──VPN──► Nginx ──► GitLab 收不动 缓冲满，暂停读 GitLab

1. VPN 路径偶发抖动，客户端瞬时收包变慢
2. Nginxproxy_buffers约 1MB 很快写满
3. Nginx 暂停从 GitLab 读取，GitLab 写满 TCP 窗口也暂停发送
4. upstream 连接上超过 60s 无新 read →proxy_read_timeout 触发
5. Nginx 断开 → Git 报curl 18

办公室网络稳定、客户端收包快 → 缓冲不堵 → 从不触发。
家里 VPN 平均速度可以很快，但80% 附近抖一下就足够触发。

机制 B：GitLab pack 流本身存在阶段性停顿

Git clone 的 pack 流是burst + pause（对象枚举、压缩、读盘），两批数据之间可能 tens of seconds 无新字节。默认 60s 阈值在边界上容易被踩中。

机制 C：UDP VPN 丢包或乱序会放大问题

OpenVPN UDP 出现AEAD Decrypt error时，长连接大包更容易失败；与机制 A 可叠加。本次华为线路复现未看到 AEAD 日志，但机制 A/B 已足够解释。

3. 故障链路总结

家里 OpenVPN clone 大仓库（HTTP） → 传输至 ~80% 时客户端或 pack 出现短暂 stall → Nginx proxy_buffers 满 / upstream 60s 无新数据 → Nginx proxy_read_timeout（默认 60s）断开 upstream → Git：curl 18 / early EOF

五、二次故障：clone 修好了，Web 登录却 502

1. 现象

在location /中增加以下全部参数并重载后，同事反馈 GitLab 域名登录即 502；删除后恢复正常：

proxy_connect_timeout 300s; proxy_send_timeout 3600s; proxy_read_timeout 3600s; proxy_buffering off; # ← 导致 Web 异常的高风险项 proxy_request_buffering off; # ← 同上

2. 502 原因分析

502 表示 Nginx 从 GitLab upstream 未拿到合法响应。不是超时时间「太长」导致，而是Git clone 优化参数误用在整站location /：

GitLab 同一location /同时承载：

/users/sign_in、/api/* ← Web 登录（HTML + POST + Cookie + 302） /*.git/info/refs ← git clone 大包 /assets/* ← 静态资源

将proxy_buffering off加在整站，clone 可能受益，但Web 登录链路会被破坏→ 502。
因此：clone 断线只需加大 proxy 超时，不必整站关闭 buffering。

这个二次问题也提醒我们：同一个 GitLab 域名下不仅有 Git 大包下载，还有登录、API、静态资源等不同类型的请求。不能因为一个场景需要优化，就把高风险参数直接加到整站location /中。

3. 参数必要性结论

六、最终处置方案

1. 核心调整：只增加 proxy 超时

在location /中仅增加超时，不要关闭 buffering，不要加Connection ""：

location / { # ... 原有 include、add_header、client_max_body_size 等保持不变 ... keepalive_timeout 600s; # 仅加超时（解决 git clone 中断） proxy_connect_timeout 300s; proxy_send_timeout 3600s; proxy_read_timeout 3600s; # proxy_buffering 保持默认 on，不要 off # 不要加 proxy_request_buffering off # 不要加 proxy_set_header Connection "" proxy_buffer_size 64k; proxy_buffers 32 32k; proxy_busy_buffers_size 128k; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; # 80 端口勿硬写 https proxy_pass http://10.x.x.x:80; }

80 与 443 两份 server 同步修改。

校验并重载：

nginx-t&&nginx-sreload

2. 如果未来仍偶发失败，再考虑拆分 Git 路径

仅对git 路径单独关 buffering，不要动整站location /：

location ~ ^.+\.git(/|$) { proxy_connect_timeout 300s; proxy_send_timeout 3600s; proxy_read_timeout 3600s; proxy_buffering off; proxy_request_buffering off; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://10.x.x.x:80; }

当前现网仅保留超时即可，无需此拆分，除非复测 clone 仍失败。

3. 研发/流水线侧采用分批拉取降低单次传输压力

除了调整 Nginx 代理超时外，也可以从研发或流水线打包侧降低单次git clone的数据量。对于打包场景，很多时候并不需要完整历史记录，只需要当前分支的最新代码。这时可以采用浅克隆、单分支拉取、按需拉取等方式，减少一次 clone 产生的大包传输，从而降低中途 stall 后被代理断开的概率。

常见方式如下。

只拉取指定分支的最新提交：

gitclone--depth1--single-branch-b<branch-name>http://gitlab.example.com/example-group/example-frontend-repo.git

如果流水线需要更明确地控制拉取过程，也可以拆成init + fetch + checkout：

gitinit example-frontend-repocdexample-frontend-repogitremoteaddorigin http://gitlab.example.com/example-group/example-frontend-repo.gitgitfetch--depth1origin<branch-name>gitcheckout FETCH_HEAD

如果后续确实需要更多历史记录，可以再逐步加深：

gitfetch--deepen100origin<branch-name>

对于特别大的仓库，还可以结合 partial clone 或 sparse checkout，只拉取打包需要的目录：

gitclone--filter=blob:none --no-checkout http://gitlab.example.com/example-group/example-frontend-repo.gitcdexample-frontend-repogitsparse-checkout init--conegitsparse-checkoutset<need-build-dir>gitcheckout<branch-name>

这种方式的作用是：

减少单次 clone/fetch 的数据量 -> 缩短长连接持续时间 -> 降低 VPN 抖动或代理空窗触发中断的概率

需要注意的是，分批拉取是研发/流水线侧的优化和规避手段，不能替代 Nginx 代理层的根因修复。如果代理层仍然使用默认 60s 超时，大仓库、慢网络或 VPN 抖动场景后续仍可能复现。

4. 客户端 Git 配置只能作为辅助

gitconfig--globalhttp.postBuffer524288000gitconfig--globalhttp.lowSpeedLimit1000gitconfig--globalhttp.lowSpeedTime600

不能替代 Nginx 修改，但可缓解低速 stall 被 Git 主动断开。

5. VPN 侧优化方向

6. 绕过 Nginx 做对比测试

# 仅内网/VPN 可达时gitclone http://10.x.x.x/example-group/example-frontend-repo.git

若直连 GitLab IP 成功、走域名失败 → 确认是 Nginx 层问题。

七、恢复验证

1. Clone 验证

在家 VPN 环境复测：

Receiving objects: 100% (159090/159090), 1.06 GiB | 3.17 MiB/s, done. Resolving deltas: 100% (111303/111303), done. Updating files: 100% (7002/7002), done.

同一仓库、同一路径、同一 VPN，完整 clone 成功，验证加大 proxy 超时可解决断线。

2. Web 验证

最终生效配置：location /仅保留proxy_*_timeout，不加proxy_buffering off。

八、后续建议

1. GitLab 反代标准：80/443 的location /只加大proxy_read_timeout/proxy_send_timeout，勿整站proxy_buffering off
2. 变更后必测两项：Web 登录 + 大仓库 clone，避免只验证 clone 忽略 Web
3. error.log 监控upstream timed out与502，不要只在 access log 里搜
4. 若 clone 仍偶发断，再考虑单独location ~ \.git关 buffering，不要动整站
5. 流水线打包场景优先使用--depth 1 --single-branch等浅克隆方式，减少单次大包拉取
6. VPN 问题与 Nginx 问题可叠加：无 AEAD 日志不等于 VPN 无影响

九、复盘总结

这次问题最值得记录的地方，不是简单地把proxy_read_timeout改大，而是排查过程中几个容易误判的点。

• keepalive_timeout≠proxy_read_timeout：前者是客户端到 Nginx，后者是 Nginx 到 GitLab
• proxy_read_timeout看的是「连续无数据的空窗」，不是 clone 总时长
• clone 断线主因是默认 60s 太短，加大超时即可；不必整站proxy_buffering off
• 整站关 buffering 会导致 GitLab Web 502：git 优化与 Web 登录不能混在同一location /的激进参数里
• 改 Nginx 后 clone 好了、登录 502：典型误伤，回退 buffering 相关项，只留超时
• Web 能开、git clone 大包断：长连接 + 反代默认 60s 不匹配
• 平均网速快仍可能失败：瞬时 stall + 默认 60s 即触发
• 打包流水线可以分批/浅克隆：减少单次传输数据量，降低长连接中断概率
• access log 无 timeout 不代表没超时：查 error.log，以「clone + 登录」双验证为准

整体来看，这类故障的排查思路可以概括为：

先确认问题发生在哪一段链路 → 再区分是连接问题、认证问题、传输问题还是代理超时 → 修改配置时只改最小必要项 → 验证时同时覆盖原故障场景和普通 Web 场景

对运维来说，最重要的是不要只看“改完 clone 成功了”，还要确认 GitLab 的 Web 登录、API、静态资源都没有被误伤。生产环境中的 Nginx 反向代理往往承载多类请求，配置参数的影响范围一定要控制住。

附录：GitLab 侧超时参数

若直连 GitLab 内网 IP 仍失败，再查 GitLab Omnibus：

# /etc/gitlab/gitlab.rbnginx['proxy_read_timeout']=3600nginx['proxy_send_timeout']=3600gitlab_workhorse['api_max_duration']=3600

gitlab-ctl reconfigure

本次案例在最外层 Nginx 加大 proxy 超时后 clone 恢复；去掉整站proxy_buffering off后Web 登录同步恢复。未动 GitLab 本机配置。