Git上传大文件时频繁失败，如何实现快速稳定上传？

Question

Git 上传大文件（如 >100MB）频繁失败，主因是 Git 原生不支持大文件版本管理：HTTP/HTTPS 协议易超时、内存溢出；SSH 推送可能被服务端限制；Git LFS 虽可托管大文件，但若未正确初始化、LFS 对象未跟踪或远程 LFS 服务不可用（如 GitHub/GitLab LFS endpoint 认证失败、带宽限速），仍会导致 push 中断、smudge/clean 失败或“LFS: Upload failed”错误。此外，网络抖动、代理干扰、Git 缓冲区不足（`http.postBuffer` 默认仅1MB）及 Windows CRLF 自动转换冲突也会加剧失败率。这些问题导致团队协作卡顿、CI 构建反复失败、历史回溯失真。根本矛盾在于：Git 设计初衷是追踪文本变更，而非二进制资产。因此，单纯调大 timeout 或重试无法根治——必须分离代码与大文件生命周期，建立分层交付机制。

Answer 1

```html

一、现象层：高频失败的表征与日志特征

• HTTP/HTTPS 推送时出现 fatal: The remote end hung up unexpectedly 或 error: RPC failed; curl 56 LibreSSL SSL_read: SSL_ERROR_SYSCALL
• Git LFS 报错典型模式：LFS: Upload failed: 413 Request Entity Too Large、smudge filter lfs failed、batch request: Unauthorized
• Windows 下伴随 CRLF conversion conflict 警告，git status 显示大量“modified”但无实质变更
• CI 日志中反复出现 fatal: early EOF 或 fatal: index-pack failed，尤其在 git clone --recursive 或 git push --all 阶段

二、协议层：传输机制与原生限制的深度解耦

Git 原生协议（HTTP(S)/SSH）本质是为小粒度文本对象（blob/tree/commit）设计的流式传输模型。其关键约束如下：

参数	默认值	影响范围	大文件场景失效原因
http.postBuffer	1 MiB	HTTP POST 载荷上限	单个 LFS pointer 提交即超限，触发 early EOF
http.lowSpeedLimit	0	低速阈值（bytes/sec）	公网上传 >100MB 时易被判定为“stalled”，强制中断
SSH MaxStartups	10:30:100	服务端并发连接数	LFS 并行上传多分片时触发拒绝连接

三、架构层：Git LFS 的工作流断裂点分析

LFS 并非“开箱即用”，其三层协作链任一环节断裂即导致全链路失败：

1. 客户端层：未执行 git lfs install → hook 缺失 → smudge/clean 不触发
2. 跟踪层：遗漏 git lfs track "*.zip" 或未提交 .gitattributes → 文件仍走原生 Git 流程
3. 服务层：GitHub/GitLab LFS endpoint 返回 401（token 过期）、429（rate limit）、503（LFS storage unready）

四、系统层：OS 与网络中间件的隐性干扰

# 典型 Windows CRLF 冲突修复（禁用自动转换）
git config --global core.autocrlf false
git config --global core.eol lf

# 代理穿透配置（如企业级 Squid/NGINX）
git config --global http.proxy http://proxy.internal:3128
git config --global http.sslVerify false  # 仅测试环境启用

五、工程层：分层交付机制的落地实践

根本解法是解耦“代码演进”与“资产交付”生命周期。推荐采用以下混合架构：

graph LR
  A[源码仓库 Git] -->|仅含 pointer| B(Git LFS)
  A -->|CI 触发| C[制品仓库 Nexus/Artifactory]
  C -->|URL 注入| D[部署脚本]
  B -->|LFS fetch on demand| E[开发机/CI runner]
  D -->|curl -O| C

六、验证层：可量化的健康度指标体系

• LFS 跟踪覆盖率：`git lfs ls-files | wc -l` / `git ls-files | wc -l` ≥ 95%
• Push 成功率 SLA：连续 7 天 CI Push 失败率 ≤ 0.5%（需排除人为误操作）
• Smudge 延迟 P95：`time git checkout HEAD~1` 中 LFS fetch 单文件平均耗时 ≤ 8s（100MB @ 50Mbps）
• Git 对象图纯净度：`git count-objects -vH` 中 size-pack 增长速率 ≤ 50MB/week（排除 LFS 后）

七、演进层：超越 LFS 的下一代资产治理范式

当资产规模达 TB 级或需跨云协同时，应启动架构升级：

• Git Partial Clone + Sparse Checkout：按需拉取子目录，规避全量 LFS fetch
• OCI Artifact Registry：将模型权重、数据集打包为 OCI image，复用 Docker registry 生态
• Delta Lake + Git Hooks：对结构化大数据集，用 Apache Iceberg/Delta Lake 管理版本，Git 仅存元数据快照

```