中文

网站托管

使用 Plesk 从 GitHub 或 GitLab 部署

将 GitHub 或 GitLab 仓库连接到 Plesk,手动部署网站或通过 Webhook 在每次 push 时自动部署,并解决最常见的错误。

阅读约 8 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何将 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 中添加仓库

  1. 进入 网站与域名,找到您的域名。
  2. 点击 Git。如果已存在仓库,请点击 添加 Repository。
  3. 选择 GitHub 或 BitBucket 等远程 git 主机。此选项同样适用于 GitLab。
  4. 在远程仓库字段中,输入您的仓库地址。
仓库类型 地址格式
公开 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 上:

  1. 打开仓库,然后进入 Settings > Deploy keys。
  2. 点击 Add deploy key。
  3. 在 Title 中为密钥命名,例如 Plesk,并将密钥粘贴到 Key 中。
  4. 不要勾选 Allow write access:Plesk 只需要读取仓库。
  5. 点击 Add key。

在 GitLab 上:

  1. 打开项目,然后进入 Settings > Repository。
  2. 展开 Deploy keys,然后选择 Add new key。
  3. 为密钥命名并粘贴密钥。
  4. 不要勾选 Grant write permissions to this key,然后保存。

步骤 4:选择部署模式

返回 Plesk,在 您的网站 部分:

  1. 选择 部署模式:

    模式 效果
    自动部署 拉取到的提交会立即发布
    手动部署 提交会被拉取,但只有在您发出指令时才会发布
    无部署(repository 主机) 不发布任何内容
  2. 检查 目标目录。普通网站保留 /httpdocs 即可。

  3. 点击 确定。Plesk 随即克隆该仓库。

对于生产环境中的网站,在您的流程得到充分验证之前,手动模式更为稳妥:使用自动模式时,推送到活动分支的任何错误都会立即上线。

步骤 5:选择分支并部署

  1. 在 Git 页面上,点击 更改 branch 和路径。
  2. 在 Branch 中选择您的生产分支,例如 main,然后确认。
  3. 点击 以 Pull 方式更新。
  4. 在手动模式下,点击 从 Repository 部署(或 Deploy)。

只有活动分支会被部署。

步骤 6:通过 Webhook 实现自动化

没有 Webhook 时,Plesk 无法得知有新的提交,您必须点击 以 Pull 方式更新。Webhook 会在每次 git push 时通知 Plesk。

在 Plesk 中,点击 Repository 设置 并复制 Webhook URL。请将其视为机密信息:任何知道此 URL 的人都可以触发拉取操作。

在 GitHub 上:

  1. 打开 Settings > Webhooks,然后点击 Add webhook。
  2. 将地址粘贴到 Payload URL 中。
  3. 在 Content type 中选择 application/json。
  4. 仅保留发送 push 事件(Just the push event)。
  5. 确认已勾选 Active,然后点击 Add webhook。

在 GitLab 上:

  1. 打开 Settings > Webhooks,然后选择 Add new webhook。
  2. 将地址粘贴到 URL 中。
  3. 在 Trigger 中勾选 Push events。
  4. 如果 Plesk 的证书有效,请保持启用 Enable SSL verification。
  5. 选择 Add webhook。

步骤 7:在部署后执行操作

某些项目在文件复制完成后还需要执行操作,例如重启应用程序或清除缓存。

  1. 在 Repository 设置 中,勾选 启用其它的部署操作。
  2. 输入命令,每行一条。

例如,要重启目录为 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 网站。

检查结果

  1. 修改一个可见的文件,然后推送修改:

    终端
    git add .
    git commit -m "测试部署"
    git push origin main
  2. 在 Plesk 的 Git 页面上,确认显示的最新提交是您的提交。Commit 日志 中列出了提交历史。

  3. 重新加载 https://您的域名.com/ 并检查修改。

  4. 检查 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 环境。