搭建支持Git LFS的个人Git服务器遇推送错误求排查

一、服务器端LFS配置验证 #

• 登录服务器的Git专用用户，进入裸仓库目录，执行以下命令确认LFS已正确初始化：

  git config --local -l | grep lfs
  

  需确保输出包含filter.lfs.smudge、filter.lfs.clean、filter.lfs.process三项配置。如果缺失，在仓库内执行：

  git lfs install --local
  

• 检查服务器端是否强制启用锁定：执行git config --local lfs.requiredlocks，若输出为true，则会强制要求锁定文件，即使客户端关闭锁定也会报错，需关闭：

  git config --local lfs.requiredlocks false
  

二、客户端配置与文件追踪修正 #

• 修正UE5文件追踪规则：删除错误的*.*filetype*追踪规则，替换为UE5核心大文件的精准匹配，编辑本地仓库的.gitattributes文件：

  *.uasset filter=lfs diff=lfs merge=lfs -text
  *.umap filter=lfs diff=lfs merge=lfs -text
  *.fbx filter=lfs diff=lfs merge=lfs -text
  *.png filter=lfs diff=lfs merge=lfs -text
  *.wav filter=lfs diff=lfs merge=lfs -text
  

  保存后提交该文件到仓库：

  git add .gitattributes
  git commit -m "fix LFS track rules for UE5"
  

• 关闭客户端锁定验证：执行以下命令确保推送时不校验锁：

  git config --global lfs.locksverify false
  

三、仓库损坏修复 #

本地仓库修复 #

1. 检查LFS对象完整性：

   git lfs fsck
   

2. 清理无效LFS对象：

   git lfs prune
   

3. 重置本地仓库到服务器未损坏版本（若服务器仓库还可用）：

   git fetch origin
   git reset --hard origin/main
   

服务器端仓库修复 #

1. 进入裸仓库目录，执行LFS完整性检查：

   git lfs fsck
   

2. 若存在缺失对象，从本地仓库的.git/lfs/objects目录复制对应对象到服务器裸仓库的.git/lfs/objects目录，确保Git用户对该目录有读写权限：

   # 本地执行，替换为服务器地址和仓库路径
   scp -r .git/lfs/objects/ git@your-server:/path/to/repo/.git/lfs/objects/
   

3. 修复仓库权限：确保Git专用用户拥有仓库目录的完整权限：

   sudo chown -R git:git /path/to/repo
   sudo chmod -R 755 /path/to/repo
   

四、推送日志排查 #

推送时开启详细日志，定位具体错误点：

GIT_TRACE=1 GIT_TRANSFER_TRACE=1 git push origin main

查看日志中报错的具体阶段（如LFS对象上传、锁校验、权限验证等），针对性解决。

内容的提问来源于stack exchange，提问作者Darkonode