使用 Plesk 从 GitHub 或 GitLab 部署
将 GitHub 或 GitLab 仓库连接到 Plesk,手动部署网站或通过 Webhook 在每次 push 时自动部署,并解决最常见的错误。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何将 GitHub 或 GitLab 仓库关联到您的 Plesk 网站。配置完成后,只需执行一次 git push 即可更新网站。
其原理如下:您将修改推送到 GitHub 或 GitLab,Plesk 拉取新的提交,然后将活动分支的文件复制到网站目录。
前提条件
- 能够访问您的 Plesk 面板(参见连接到 Plesk 界面)。
- 一个包含您网站内容的 GitHub 或 GitLab 仓库。
- 该仓库的管理权限,以便添加密钥和 Webhook。在 GitLab 上,需要 Maintainer 或 Owner 角色。
本指南使用 httpdocs,这是主域名通常使用的目录。附加域名的目录可能不同:请在 主机与 DNS > 主机 中查看 文档根目录。
步骤 1:准备仓库
仓库根目录的内容会复制到目标目录,默认为 /httpdocs。因此,仓库根目录下的 index.html 文件会变成 httpdocs/index.html。
切勿将机密信息或生成的文件纳入版本控制。以下是 .gitignore 示例:
.env
node_modules/
vendor/
*.log被 Git 忽略的文件不会被部署。因此,.env 文件必须直接在服务器上创建。
步骤 2:在 Plesk 中添加仓库
- 进入 网站与域名,找到您的域名。
- 点击 Git。如果已存在仓库,请点击 添加 Repository。
- 选择 GitHub 或 BitBucket 等远程 git 主机。此选项同样适用于 GitLab。
- 在远程仓库字段中,输入您的仓库地址。
| 仓库类型 | 地址格式 |
|---|---|
| 公开 | https://github.com/your-account/my-site.git |
| 私有,GitHub | git@github.com:your-account/my-site.git |
| 私有,GitLab | git@gitlab.com:your-account/my-site.git |
对于私有仓库,建议使用 SSH 格式:Plesk 会生成密钥并显示 SSH 公共密钥 字段。请先不要确认,继续执行步骤 3。
步骤 3:授权 Plesk 读取私有仓库
复制 SSH 公共密钥 字段的内容,然后将其添加为部署密钥。
在 GitHub 上:
- 打开仓库,然后进入 Settings > Deploy keys。
- 点击 Add deploy key。
- 在 Title 中为密钥命名,例如
Plesk,并将密钥粘贴到 Key 中。 - 不要勾选 Allow write access:Plesk 只需要读取仓库。
- 点击 Add key。
在 GitLab 上:
- 打开项目,然后进入 Settings > Repository。
- 展开 Deploy keys,然后选择 Add new key。
- 为密钥命名并粘贴密钥。
- 不要勾选 Grant write permissions to this key,然后保存。
步骤 4:选择部署模式
返回 Plesk,在 您的网站 部分:
-
选择 部署模式:
模式 效果 自动部署 拉取到的提交会立即发布 手动部署 提交会被拉取,但只有在您发出指令时才会发布 无部署(repository 主机) 不发布任何内容 -
检查 目标目录。普通网站保留
/httpdocs即可。 -
点击 确定。Plesk 随即克隆该仓库。
对于生产环境中的网站,在您的流程得到充分验证之前,手动模式更为稳妥:使用自动模式时,推送到活动分支的任何错误都会立即上线。
步骤 5:选择分支并部署
- 在 Git 页面上,点击 更改 branch 和路径。
- 在 Branch 中选择您的生产分支,例如
main,然后确认。 - 点击 以 Pull 方式更新。
- 在手动模式下,点击 从 Repository 部署(或 Deploy)。
只有活动分支会被部署。
步骤 6:通过 Webhook 实现自动化
没有 Webhook 时,Plesk 无法得知有新的提交,您必须点击 以 Pull 方式更新。Webhook 会在每次 git push 时通知 Plesk。
在 Plesk 中,点击 Repository 设置 并复制 Webhook URL。请将其视为机密信息:任何知道此 URL 的人都可以触发拉取操作。
在 GitHub 上:
- 打开 Settings > Webhooks,然后点击 Add webhook。
- 将地址粘贴到 Payload URL 中。
- 在 Content type 中选择
application/json。 - 仅保留发送
push事件(Just the push event)。 - 确认已勾选 Active,然后点击 Add webhook。
在 GitLab 上:
- 打开 Settings > Webhooks,然后选择 Add new webhook。
- 将地址粘贴到 URL 中。
- 在 Trigger 中勾选 Push events。
- 如果 Plesk 的证书有效,请保持启用 Enable SSL verification。
- 选择 Add webhook。
步骤 7:在部署后执行操作
某些项目在文件复制完成后还需要执行操作,例如重启应用程序或清除缓存。
- 在 Repository 设置 中,勾选 启用其它的部署操作。
- 输入命令,每行一条。
例如,要重启目录为 httpdocs 的 Node.js 应用程序:
cd httpdocs
mkdir -p tmp
touch tmp/restart.txt要为同一项目安装依赖项并进行编译,请将 24 替换为您使用的 Node.js 版本:
export PATH=/opt/plesk/node/24/bin:$PATH
cd httpdocs
npm ci
npm run build
mkdir -p tmp
touch tmp/restart.txt对于 Laravel 项目,请参阅在 Plesk 上托管 Laravel 网站。
检查结果
-
修改一个可见的文件,然后推送修改:
终端git add . git commit -m "测试部署" git push origin main -
在 Plesk 的 Git 页面上,确认显示的最新提交是您的提交。Commit 日志 中列出了提交历史。
-
重新加载
https://您的域名.com/并检查修改。 -
检查 Webhook 的投递情况:
- GitHub:Settings > Webhooks,打开该 Webhook,然后查看 Recent deliveries;
- GitLab:Settings > Webhooks,点击 Edit,然后查看 Recent events。您也可以通过 Test > Push events 按钮发送一次测试。
回退到之前的版本
撤销有问题的提交,然后推送结果:
git revert HEAD
git push origin main新的部署会恢复这些文件。如果已执行数据库迁移,此操作不会将其撤销。
故障排除
Permission denied (publickey)
Plesk 的公钥尚未添加到仓库,或被添加到了其他仓库。请从 Plesk 重新复制公钥,并检查部署密钥列表。
GitHub 上出现 Key is already in use
此部署密钥已关联到另一个仓库。请将其从该仓库中移除,或将其添加到专用的 GitHub 账户。
Repository not found 或 Authentication failed
地址不正确、仓库为私有但您使用了不带凭据的 HTTPS 地址,或者令牌已过期。由于无法在 Plesk 中修改仓库地址,请通过 移除 Repository 将其删除,然后重新添加。已发布的文件会保留。
推送后网站没有更新
请依次检查:
- 提交是否已推送到活动分支;
- 模式是否不是 手动部署 或 无部署;
- GitHub 或 GitLab 的历史记录中是否显示 Webhook 已被成功接收。
Webhook 因证书错误而失败
如果 Plesk 面板使用自签名证书,HTTPS 连接可能会失败。此时 Plesk 建议在 Webhook URL 开头使用 http://。由于 URL 随后会以未加密方式传输,请仅将此方案作为临时措施,并向技术支持报告该问题。
GitLab 提示 Webhook 已被禁用
连续失败 4 次后,GitLab 会暂时禁用 Webhook;连续失败 40 次后则会永久禁用。请先解决问题,然后发送一次成功的测试以重新启用它。
网站上的文件消失了
从仓库中删除的文件在部署时也会从网站上删除。请将用户上传的文件存放在不受版本控制的目录中,并通过备份恢复丢失的文件。
目标目录被拒绝
同一域名的两个仓库不能共用同一个部署目录。请选择其他 目标目录。
仍然显示旧页面
index.html 文件的优先级可能高于您的 index.php,尤其是 Plesk 默认创建的页面。如果该文件不属于您的项目,请将其从 httpdocs 中删除,然后清除浏览器缓存。
部署操作中出现 npm: command not found
在此环境中未加载工具路径。请添加 export PATH=/opt/plesk/node/24/bin:$PATH 这一行,并根据实际情况调整版本。如果错误仍然存在,则该环境很可能是 chroot 环境。