宝塔面板 Git 拉取代码失败

学完这篇，你能拿着宝塔面板给出的 Git 报错原文，一步步定位到底是权限、密钥、路径还是网络的问题，并把它修到能正常拉取。

第一步：先拿到完整报错原文，不要靠猜

这一步的目标是把面板吞掉的那句 fatal: xxx 挖出来，因为宝塔面板的 Git 部署界面经常只显示「拉取失败」四个字。

面板入口在：网站 → 找到你的站点 → 点击站点名进设置 → 左侧「Git 部署」（宝塔面板 8.x／9.x 的位置；老版本 7.x 是 软件商店 → 安装「Git 管理器」插件后使用）。

更可靠的办法是 SSH 登录服务器，用面板同一个执行身份手工复现：

su -s /bin/bash www -c "cd /www/wwwroot/example.com && git pull 2>&1"

注意：宝塔面板执行 Git 命令时用的是 www 用户，不是 root。你用 root 在终端里 git pull 成功，完全不代表面板能成功——这是排查时最容易走偏的地方。

第二步：确认 www 用户能不能找到 git 命令

这一步要排除「命令没装」和「PATH 找不到」两种情况。执行：

which git
su -s /bin/bash www -c "git --version"

如果 root 下能显示版本、www 下提示 git: command not found，那就是环境变量问题，把面板里的命令由 git pull 改成全路径 /usr/bin/git pull 即可。如果两边都没有，先装：

yum install -y git
# Ubuntu / Debian
apt install -y git

第三步：修目录属主和权限（最高频原因）

这一步解决的是 Permission denied 类报错，做完后 www 用户能正常写入 .git 目录。

典型报错长这样：

fatal: Unable to create '/www/wwwroot/example.com/.git/index.lock': Permission denied

原因通常是之前有人用 root 跑过 git pull 或 git clone，导致 .git 归属变成 root。检查并修复：

ls -ld /www/wwwroot/example.com/.git
chown -R www:www /www/wwwroot/example.com
find /www/wwwroot/example.com -type d -exec chmod 755 {} \;
find /www/wwwroot/example.com -type f -exec chmod 644 {} \;

第四步：配置 www 用户的 SSH 密钥

这一步针对私有仓库、且用 git@github.com:xxx/yyy.git 这种 SSH 地址的情况。宝塔里 www 用户的家目录默认是 /home/www，密钥要放在它自己的 .ssh 下，放 root 的 /root/.ssh 是没用的。

mkdir -p /home/www/.ssh
ssh-keygen -t ed25519 -C "deploy@example.com" -f /home/www/.ssh/id_rsa -N ""
cat /home/www/.ssh/id_rsa.pub

把输出的公钥内容，粘贴到 GitHub 仓库的 Settings → Deploy keys → Add deploy key，或 Gitee 的 仓库 → 管理 → 部署公钥管理。

然后把主机指纹写进 known_hosts，否则首次连接会卡在 yes/no 交互上：

su -s /bin/bash www -c "ssh-keyscan github.com >> /home/www/.ssh/known_hosts"
chown -R www:www /home/www/.ssh
chmod 700 /home/www/.ssh && chmod 600 /home/www/.ssh/id_rsa

注意：Deploy Key 默认只读。如果你在面板里还要做 push（比如拉取后回写），必须勾选「允许写入／Allow write access」。

第五步：HTTPS 方式认证失败怎么办

如果远程地址是 https:// 开头的私有仓库，Git 会弹交互式输入账号密码，而面板是非交互环境，结果是直接失败或长时间卡住。两个选择：改成上面的 SSH 方式，或者把令牌写进地址：

cd /www/wwwroot/example.com
git remote set-url origin https://用户名:PersonalAccessToken@github.com/用户名/仓库.git
git remote -v   # 确认改成功

第六步：网络连不上（国内服务器常见）

报错特征：Failed to connect to github.com port 443: Connection timed out。先用 www 身份测一下：

su -s /bin/bash www -c "curl -I https://github.com"

不通的话，可以考虑把仓库迁到 Gitee 再拉、给 www 用户单独配置代理（注意配置文件在 /home/www/.gitconfig，不是 root 的）：

su -s /bin/bash www -c "git config --global http.proxy http://127.0.0.1:7890"

第七步：目录非空、分支不对的兜底做法

报 destination path already exists and is not an empty directory 时，不要删站点目录，用 init 方式接管：

cd /www/wwwroot/example.com
git init
git remote add origin git@github.com:用户名/仓库.git
git fetch --all
git reset --hard origin/main   # main 换成你的实际分支名

分支名不确定就先 git branch -a 看一遍。

第八步：用计划任务做备用拉取通道

面板 Git 部署偶尔有插件层的问题，可以在 面板 → 计划任务 → 添加任务，任务类型选「Shell 脚本」，执行周期按需（如每 5 分钟），执行用户选 www，脚本内容：

cd /www/wwwroot/example.com && /usr/bin/git pull origin main >> /www/wwwroot/pull.log 2>&1

日志在 /www/server/cron/ 下可查。

小结

• 面板用 www 用户 执行 Git，一切排查都要用 su -s /bin/bash www -c "..." 复现，别用 root 验证。
• 报 Permission denied 先看 .git 属主，chown -R www:www 解决大半问题。
• 密钥放 /home/www/.ssh，公钥加到仓库 Deploy Key，并写好 known_hosts 免交互。
• HTTPS 私有仓库改用 Token 或直接转 SSH，避免交互式卡死。
• 连不上 GitHub 是网络问题，不是配置问题，用 curl 先验证再决定换源或挂代理。