最近在帮团队把二进制产物、安装包和设计稿纳入代码仓库管理,选型上绕不开Git LFS。我们代码审核用的是Gerrit,远程仓库地址是HTTPS形式,配置完git lfs install后我满心以为git push就能把几百MB的大文件推上去。结果第一次git lfs push就让我卡了整整一个下午:终端不停提示输入HTTPS密码,输完Gerrit账号密码没有任何反应,又开始第二轮提示。
那个下午我做了很多蠢事:改Gerrit密码、重装Git LFS、清空钥匙串、让同事把密码发我逐一试……直到我打开GIT_CURL_VERBOSE看到请求URL,才发现一个扎心的事实:我的LFS客户端压根不是在跟Gerrit要密码,它是在向Gerrit的HTTP端口发送LFS对象请求,而那里根本没有LFS服务。最后落地的方案是给这套Gerrit环境单独挂一个lfs-test-server,所有大文件对象走这个独立服务的Basic Auth,Gerrit只保存LFS指针文件。这篇文章就是把整套配置和排查过程整理出来,尤其适合用Gerrit做代码审核、又要管理大文件,并且被“git lfs push总是提示输入https密码”烦到崩溃的团队。
1. Gerrit里的大文件难题,为什么非得再挂一个lfs-test-server
1.1 Git LFS到底在做什么:指针入库,对象另存
Git LFS的全称是Git Large File Storage,它并不是Git官方内置功能,而是一个基于Git过滤器机制的外部扩展。它通过clean和smudge两个过滤器与Git核心协作:当你执行git add时,LFS的clean过滤器会把真实文件替换成一个很小的文本指针文件;当你执行git checkout时,smudge过滤器会读取指针文件并从LFS服务器把真实内容拉回来。
指针文件长这样:
code复制version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214f6f8c8b6f0b1d3d8e5c0a3f8b0f2f0b6e0d1e3a0c1f9d8e7f6a5b4c3d2e1f
size 12345678
所以整个仓库的Git对象体积不会因为大文件而膨胀,真正的大文件被存到独立的LFS对象存储里。LFS客户端与服务器的通信遵循一套Batch API:上传对象前,客户端先询问服务器“这些对象你有哪些,哪些我需要传”,服务器给出回应后,客户端再逐个上传。这个设计的好处是断点续传和去重都能交给服务器处理,但也意味着:一旦LFS端点配置错了,你的所有上传请求都会打到错误的地方,认证自然也会跟着错。
1.2 Gerrit自带LFS支持,但“支持”不等于“适合你的场景”
Gerrit从2.15版本开始内置了LFS相关插件,理论上你可以在Gerrit的HTTP端口直接处理LFS请求,对象也会落在Gerrit站点目录下。这套方案在单机小规模场景下确实能跑,但它有几个实际约束。
第一,对象与Gerrit仓库存储在同一个文件系统,大文件多了以后,备份、迁移、垃圾回收都绕不开Gerrit站点本身。第二,Gerrit的LFS插件和权限模型绑定得比较深,你很难在不想开放Gerrit账号的前提下让CI机器拉取对象。第三,Gerrit在评审流里只接受指针文件的push,如果LFS对象和指针都走同一个地址,评审被拒后对象清理也是个麻烦。
所以,当团队需要把大文件对象和代码评审平台解耦时,外部LFS服务是更清晰的架构。lfs-test-server正是Git LFS官方早期用来测试协议实现的轻量服务,一个二进制文件,启动一个端口就能提供完整的LFS Batch API和对象存取能力。它的价值在于“轻”,也在于“标准”:所有Git LFS客户端都能直接对接它。
这里回应一个经常被问到的问题:Git LFS会不会某天合并进Git主线?我的看法是大概率不会直接合并。Git本身通过filter机制已经给LFS留好了接口,LFS作为外部工具长期演进反而是更健康的模式。近年Git提出的partial clone、promisor remote实际上也在解决类似问题,但Gerrit这套偏传统的审核体系里,LFS依然是兼容性最好的大文件方案。
1.3 这套架构里的两条通道,是理解密码问题的前提
我们的目标架构可以用一句话说清楚:小指针走Gerrit,大对象走lfs-test-server。
开发者在本地提交后,git push会同时做两件事。第一件事,把仓库里的LFS指针提交和普通代码提交一起推送到Gerrit的refs/for审核分支;第二件事,git-lfs客户端会单独发起Batch API请求,把大文件对象推送到lfs-test-server。评审人在Gerrit上点击合入后,本地执行git lfs pull,从lfs-test-server拉取实际对象。
问题就在这里:这是两条完全独立的通道,两个完全独立的认证体系。Gerrit的SSH密钥和HTTP Basic Auth管的是代码通道;lfs-test-server的-user/-pass管的是对象通道。很多人碰到“git lfs push总是提示输入https密码”,就是因为客户端把对象请求发给了Gerrit,然后又把Gerrit的账号密码拿去问lfs-test-server要权限,两边谁也不认谁,只能一遍遍弹密码框。这个根因我们留到第3章详细拆。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备:从Gerrit配置到lfs-test-server启动
2.1 客户端安装Git LFS,别在版本上栽跟头
客户端安装我以macO
