Jenkins 发布报错LFS: could not get connection for batch request 如何排查问题

问题描述

在使用Jenkins部署远程仓库代码时，系统提示以下错误信息：

git submodule update --init --recursive --depth=1 public/assets
Downloading game/red/appmanifest.json (719 B)
Error downloading object: game/red/appmanifest.json (2a0dd8d): Smudge error: Error downloading game/red/appmanifest.json (2a0dd8d0681b7badb69bf095145fa1a7a7314f4cd759c7e8743812a28edc4cb5): LFS: could not get connection for batch request
Errors logged to '/var/lib/jenkins/workspace/deploy_php_ads/.git/modules/public/assets/lfs/logs/20250429T062352.445748847.log'. Use `git lfs logs last` to view the log.
error: external filter 'git-lfs filter-process' failed
fatal: game/red/appmanifest.json: smudge filter lfs failed
fatal: Unable to checkout '0c994f9s523d8877e5edcb95d37b8c4ffc1abab60' in submodule pa

排查过程

1. 本地环境配置与测试

• 执行git lfs -v确认Git LFS已正确安装
• 运行git lfs install进行初始化
• 执行git lfs pull成功拉取所有LFS管理的文件，代码库正常克隆和运行

本地环境配置：

• 操作系统：Windows 10
• PHP版本：8.4+
• Git版本：2.44
• Git LFS版本：3.4.1

2. 发布时的问题

尽管本地环境能够正常拉取代码，但在发布到远程服务器时，系统仍然报错，提示与LFS文件相关，具体表现为某些大文件无法正确传输或解析。

3. 测试环境与生产环境的排查

在测试环境和生产环境（均为Linux系统）中进行相同操作：

环境配置：

• 操作系统：Ubuntu 20.04 LTS
• PHP版本：8.4+
• Git版本：2.34
• Git LFS版本：3.4.1

发现问题： 执行git lfs pull命令后，部分LFS文件未能正确下载，导致代码库不完整。

4. 缓存清除与重新初始化

执行以下命令排除缓存问题：

git lfs prune
git lfs fetch --all
git lfs pull

尽管清除了LFS缓存并重新初始化，问题依然存在。这表明问题可能并非由缓存引起，而是与服务器配置或网络环境有关。

5. 深入排查

• 将远程地址从SSH切换为HTTPS：git remote set-url origin https://xxxxxxxxxxxx，发现可以正常拉取
• 排查SSH无法拉取LFS大文件的原因，发现某些Git LFS服务（如Gitea）默认不开启SSH支持
• 通过命令校验项目是否开启Git LFS支持，发现Git LFS开关被误关闭（如果你有Gitea后台管理权限可以直接登录后台查看开关是否开启）
• 联系上级重新开启Git LFS功能，问题得以解决

总结

希望我本次排查经验对您有所帮助，欢迎关注获取更多技术分享和故障排查案例。