Jenkins Day 3-4 错误总结与解决方案

Jenkins Day 3-4 错误总结与解决方案

问题一：本地 file:// 仓库检出被阻止

错误日志

1
2
3
4
ERROR: Checkout of Git remote 'file:///home/LX/jenkins_demo/demo-java-app'
aborted because it references a local directory, which may be insecure.
You can allow local checkouts anyway by setting the system property
'hudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT' to true.

原因分析

1
2
3
Jenkins 的 Git 插件从某个版本开始，默认禁止从本地 file:// 路径检出代码。
这是出于安全考虑 —— 如果 Jenkins 被攻击者控制，
攻击者可能通过配置 file:// 路径读取服务器上的任意文件。

解决方案

第一步：找到 Jenkins 的 systemd 服务文件

1
2
3
4
5
6
grep -rn "JAVA_OPTS\|JENKINS_JAVA" \
    /etc/sysconfig/jenkins \
    /etc/default/jenkins \
    /usr/lib/systemd/system/jenkins.service \
    /etc/systemd/system/jenkins.service \
    2>/dev/null

第二步：创建 override 文件（不要直接编辑系统文件）

直接编辑系统文件，更新时会被覆盖

1
2
3
4
5
6
sudo mkdir -p /etc/systemd/system/jenkins.service.d/

cat << 'EOF' | sudo tee /etc/systemd/system/jenkins.service.d/override.conf
[Service]
Environment="JAVA_OPTS=-Djava.awt.headless=true -Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true"
EOF

第三步：重启 Jenkins

1
2
sudo systemctl daemon-reload
sudo systemctl restart jenkins

第四步：验证参数已生效

1
ps aux | grep jenkins | grep ALLOW_LOCAL_CHECKOUT

看到输出中包含 -Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true 即成功。

注意事项

1
2
3
4
5
├── 仅在学习环境使用此方案（用本地 Git 仓库）
├── 企业环境应使用 Git 服务（Gitea/GitLab/GitHub），通过 HTTP/SSH 协议访问
├── 不要直接编辑 /usr/lib/systemd/system/jenkins.service
│   （系统更新时会被覆盖）
└── 使用 override.conf 才是正确的做法

问题二：jenkins 用户无权访问 home 目录

错误日志

1
2
3
4
5
ERROR: Error cloning remote repo 'origin'
stderr: 致命错误：'/home/LX/jenkins_demo/demo-java-app'
does not appear to be a git repository
致命错误：无法读取远程仓库。
请确认您有正确的访问权限并且仓库存在。

原因分析

1
2
3
Jenkins 以 jenkins 系统用户身份运行。
Linux 中 /home/LX/ 目录默认权限是 700（仅 LX 用户可访问），
jenkins 用户无法"穿越"这个目录，所以报错说找不到仓库。

解决方案

1
2
3
4
5
6
7
8
9
10
11
# 查看当前权限
ls -ld /home/LX/
# 输出类似：drwx------  ... /home/LX/    ← 700，其他用户无法进入

# 给 home 目录添加执行权限（让其他用户能穿越目录）
sudo chmod 755 /home/LX/
sudo chmod 755 /home/LX/jenkins_demo/
sudo chmod -R 755 /home/LX/jenkins_demo/demo-java-app/

# 验证：用 jenkins 用户尝试访问
sudo -u jenkins ls /home/LX/jenkins_demo/demo-java-app/

看到文件列表即成功。

权限说明

1
2
3
4
5
6
7
8
9
10
chmod 755 的含义：

  7 (rwx) — 所有者（LX）：可读、可写、可进入
  5 (r-x) — 同组用户：可读、可进入
  5 (r-x) — 其他用户：可读、可进入

目录的执行权限（x）= "可以进入这个目录"
├── 没有 x 权限 → 即使有 r 权限也无法 cd 进去
├── 有 x 权限 → 可以穿越（cd）这个目录
└── 700 → 只有所有者能进入，jenkins 用户被挡在外面

注意事项

1
2
3
4
5
├── 学习环境：chmod 755 简单有效
├── 生产环境：不建议开放 home 目录权限
│   更好的做法是把仓库放到 Jenkins 有权限的目录
│   比如：/var/lib/jenkins/repos/demo-java-app
└── 最佳实践：使用 Git 服务（Gitea/GitLab），通过 HTTP 协议访问

问题三：Git safe.directory 所有权检查

错误日志

1
2
3
4
5
6
7
stderr: 致命错误：在 '/home/LX/jenkins_demo/demo-java-app/.git'
检测到可疑的仓库所有权
要为本仓库创建特例，请运行：

   git config --global --add safe.directory /home/LX/jenkins_demo/demo-java-app/.git

致命错误：无法读取远程仓库。

原因分析

1
2
3
4
5
6
7
8
9
10
11
12
Git 从 2.35.2 版本开始引入了 safe.directory 安全机制。

原理：
├── Git 检测仓库目录的所有者
├── 如果仓库所有者（LX）≠ 当前执行 Git 的用户（jenkins）
├── Git 拒绝操作，认为"可能是恶意仓库"
└── 这是为了防止在多用户系统中，一个用户篡改另一个用户的仓库

为什么 --global 没生效：
├── Jenkins 执行 Git 时可能没有读取 jenkins 用户的 ~/.gitconfig
├── 或者 Jenkins 的 Git 插件以不同方式调用 Git
└── 使用 --system 级别配置更可靠（写入 /etc/gitconfig）

解决方案

1
2
3
4
5
6
# 用通配符 * 允许所有目录（学习环境最省事）
sudo git config --system --add safe.directory '*'

# 验证
sudo git config --system --list | grep safe.directory
# 输出：safe.directory=*

如果只想允许特定目录（更安全）：

1
sudo git config --system --add safe.directory /home/LX/jenkins_demo/demo-java-app

配置级别对比

1
2
3
4
5
6
7
8
9
10
配置级别          配置文件位置                    影响范围
─────────────────────────────────────────────────────────
--local          仓库内 .git/config               仅当前仓库
--global         ~/.gitconfig                    仅当前用户
--system         /etc/gitconfig                  所有用户 ⭐

Jenkins 场景下推荐 --system：
├── Jenkins 的 Git 插件可能不读取 jenkins 用户的 home 目录
├── --system 对所有用户生效，最可靠
└── 生产环境中应只添加具体路径，不要用 '*'

三个问题的关联关系

1
2
3
4
5
6
7
8
9
10
11
12
Jenkins 用本地 Git 仓库构建时，需要同时满足三个条件：

条件 1：Jenkins 允许 file:// 协议
        → 解决：-Dhudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true

条件 2：jenkins 用户能访问仓库目录
        → 解决：chmod 755 目录路径

条件 3：Git 信任该仓库的所有权
        → 解决：git config --system safe.directory '*'

三个条件缺一不可，所以需要逐步排查，逐一解决。

企业环境最佳实践

1
2
3
4
5
6
学习环境              				企业环境（推荐）
────────────────────────────────────────────────────
本地 file:// 仓库                  Gitea / GitLab / GitHub
chmod 755 开放目录权限              HTTP/SSH 协议访问
safe.directory '*'               不需要（远程仓库无此问题）
手动复制代码到服务器                 Webhook 自动触发
linux > Jenkins
#linux #Jenkins
Jenkins Day 3-4 错误总结与解决方案
http://bote798.github.io/2026/04/02/Jenkins Day 3-4 错误总结与解决方法/
作者
bote798
发布于
2026年4月2日
更新于
2026年4月2日
许可协议