281 lines
14 KiB
Markdown
281 lines
14 KiB
Markdown
# Next.js 项目基于 GitHub Webhook 与宝塔面板的自动化部署流程文档
|
||
|
||
## I. 概述
|
||
|
||
本流程文档详细介绍了如何通过 GitHub 的 Webhook 功能与宝塔面板相结合，实现 Next.js 项目代码的自动化部署。当您向 GitHub 仓库提交代码后，服务器将自动拉取最新代码、安装依赖、构建项目并重启应用，从而实现持续集成与部署（CI/CD），极大地提升开发效率和部署的可靠性。
|
||
|
||
**核心理念：** 一次性配置宝塔面板的基础环境和网站，后续代码更新通过 GitHub Webhook 触发宝塔面板执行自动化部署脚本。
|
||
|
||
## II. 前提条件
|
||
|
||
在开始配置之前，请确保您已具备以下条件：
|
||
|
||
1. **GitHub 账号**：并已拥有一个托管 Next.js 项目代码的仓库。
|
||
2. **宝塔面板服务器**：一台已安装宝塔面板的 Linux 服务器。
|
||
3. **已安装环境**：服务器上已通过宝塔面板的软件商店安装了 **Nginx (或 Apache)**、**Node.js (推荐 LTS 版本)** 和 **PM2 管理器**。
|
||
4. **Git 环境**：服务器上已安装 Git（通常宝塔面板会自带或可通过软件商店安装）。
|
||
5. **域名解析**：您的域名已正确解析到宝塔面板服务器的 IP 地址。
|
||
|
||
## III. 整体部署流程概览
|
||
|
||
以下是整个自动化部署流程的高层概览图：
|
||
|
||
\`\`\`mermaid
|
||
graph TD
|
||
A[开发者 Push 代码到 GitHub 仓库] --> B(GitHub 仓库);
|
||
B -- 代码更新 --> C{GitHub Webhook 触发};
|
||
C -- Payload URL & Secret --> D[宝塔面板服务器];
|
||
D -- 执行 deploy_webhook.php 脚本 --> E[自动部署脚本: <br/> git pull <br/> npm install <br/> npm run build <br/> pm2 restart];
|
||
E --> F[Next.js 应用更新并重启];
|
||
F --> G[用户通过域名访问最新网站];
|
||
\`\`\`
|
||
|
||
## IV. 各环节详细流程与配置
|
||
|
||
### A. 阶段一：开发者本地代码提交与推送
|
||
|
||
这是您日常开发的工作流程。
|
||
|
||
\`\`\`mermaid
|
||
graph TD
|
||
A[开发者本地修改 Next.js 代码] --> B[git add];
|
||
B --> C[git commit -m "更新了新功能"];
|
||
C --> D[git push origin main];
|
||
D --> E(代码推送到 GitHub 远程仓库);
|
||
\`\`\`
|
||
|
||
**操作说明：**
|
||
您在本地完成 Next.js 项目开发后，通过标准的 Git 命令将代码提交并推送到 GitHub 仓库的指定分支（例如 `main` 或 `master`）。
|
||
|
||
### B. 阶段二：宝塔面板服务器环境与网站配置（由您手动完成，一次性）
|
||
|
||
这是实现自动化部署的基础，需要您在宝塔面板上进行一次性设置。
|
||
|
||
1. **登录宝塔面板。**
|
||
|
||
2. **安装 Node.js 和 PM2 管理器：**
|
||
* 在宝塔面板左侧菜单选择 `软件商店`。
|
||
* 搜索并安装 `Node.js` (推荐安装 LTS 版本，例如 16.x, 18.x, 20.x)。
|
||
* 搜索并安装 `PM2 管理器`。PM2 是 Node.js 应用程序的生产级进程管理器，能确保您的 Next.js 应用在服务器上持续运行，并在代码更新后平滑重启。
|
||
|
||
3. **创建网站与域名：**
|
||
* 在宝塔面板左侧菜单选择 `网站` -> `添加站点`。
|
||
* 填写您的**域名**（根据截图推测，可能是 `touzhi.quwanzhi.com` 或您实际绑定的域名）。
|
||
* `FTP` 和 `数据库` 可以选择不创建（如果您的 Next.js 项目是纯前端或后端分离的）。
|
||
* `PHP 版本` 选择 `纯静态`。
|
||
* `网站目录`：根据截图，您的项目可能在 `/www/wwwroot/tongzhi`。**请确认并记住这个目录。** 稍后它将是您的 Git 仓库克隆和 `deploy_webhook.php` 脚本存放的目录。
|
||
* 点击 `提交`。
|
||
|
||
4. **配置 Nginx 反向代理 Next.js 应用：**
|
||
Next.js 应用通常运行在 Node.js 服务器上，并通过 Nginx 进行反向代理实现外网访问。
|
||
* 在宝塔面板 `网站` 列表中，找到您刚刚创建的网站，点击右侧的 `设置`。
|
||
* 切换到 `配置文件` 选项卡。
|
||
* 在 `server` 配置块中，添加以下 `location` 配置（请将 `3000` 替换为 Next.js 应用实际监听的端口）：
|
||
\`\`\`nginx
|
||
# Nginx 配置示例 (添加到 server 段内)
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000; # <--- 替换为 PM2 启动的 Next.js 应用监听的实际端口
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
proxy_set_header Host $host;
|
||
proxy_cache_bypass $http_upgrade;
|
||
# 如果您的 Next.js 应用有特殊路由需求，可能需要添加其他配置
|
||
}
|
||
\`\`\`
|
||
* 点击 `保存`。
|
||
|
||
5. **使用 PM2 管理 Next.js 应用：**
|
||
* 在宝塔面板左侧菜单选择 `PM2管理器`。
|
||
* 点击 `添加项目`。
|
||
* `项目目录`：选择您的网站根目录（根据截图可能是 `/www/wwwroot/tongzhi`）。
|
||
* `启动文件`：填写 `node_modules/next/dist/bin/next`。
|
||
* `项目名称`：根据截图，您的 PM2 项目名称可能是 `tongzhi` (**请务必记住这个名称，稍后在 Webhook 脚本中会用到**)。
|
||
* `启动参数`：填写 `start -p 3000` (这里的 `3000` 是您的 Next.js 应用监听的端口，请与 Nginx 反向代理中的端口保持一致)。
|
||
* 点击 `提交`。
|
||
* PM2 会自动启动您的 Next.js 应用。您可以点击 `日志` 查看应用启动情况。
|
||
|
||
6. **配置 Git 部署：**
|
||
宝塔面板内置的 Git 部署功能是接收 GitHub Webhook 通知并触发部署脚本的关键。
|
||
* 在宝塔面板 `网站` 列表中，找到对应的网站，点击右侧的 `设置`。
|
||
* 在网站设置窗口中，找到 `Git` 选项卡，点击进入。
|
||
* 勾选 `启用Git部署`。
|
||
* `平台` 选择 `Github`。
|
||
* `项目地址`：填写您的 GitHub 仓库的 HTTPS 地址。例如：`https://github.com/fnvtk/wztouzhi.git`。
|
||
* `分支`：填写您希望自动部署的分支名称，通常是 `main` 或 `master`。
|
||
* `Token`：**设置一个随机且复杂的字符串作为密钥**，例如 `your_custom_deploy_secret_wztouzhi_bt`。请务必牢记这个密钥，稍后在 GitHub Webhook 配置和部署脚本中会用到。
|
||
* `项目部署目录`：宝塔会自动填写网站的根目录（例如 `/www/wwwroot/tongzhi`），请确保它是您项目代码实际要部署的路径。
|
||
* `部署类型`：选择 `拉取`。
|
||
* **重要：`部署完成后执行的命令`：这里暂时留空，您将在后续步骤中将我为您生成的脚本内容粘贴到此处。**
|
||
* **获取 WebHook 地址：** 配置完上述信息并点击 `保存` 后，宝塔面板会为您生成一个 `WebHook地址`。**复制这个 URL！**
|
||
|
||
### C. 阶段三：GitHub 仓库 Webhook 配置（由您手动完成，一次性）
|
||
|
||
这个配置将使得 GitHub 在您推送代码时通知宝塔面板。
|
||
|
||
\`\`\`mermaid
|
||
graph TD
|
||
A[登录 GitHub 仓库] --> B[Settings];
|
||
B --> C[Webhooks];
|
||
C --> D[Add webhook];
|
||
D --> E[填写 Payload URL];
|
||
E --> F[设置 Secret];
|
||
F --> G[选择 'Just the push event'];
|
||
G --> H[Add webhook];
|
||
H --> I(Webhook 配置完成);
|
||
\`\`\`
|
||
|
||
**操作说明：**
|
||
1. **登录 GitHub**，进入您的 `wztouzhi` 项目仓库。
|
||
2. 点击仓库顶部的 `Settings`（设置）。
|
||
3. 在左侧导航栏中，点击 `Webhooks`。
|
||
4. 点击 `Add webhook`（添加 Webhook）。
|
||
5. 填写以下信息：
|
||
* **Payload URL**：粘贴您在宝塔面板 Git 部署设置中复制的 `WebHook地址`。
|
||
* **Content type**：选择 `application/json`。
|
||
* **Secret (可选，但强烈推荐)**：粘贴您在宝塔面板 Git 部署中设置的 `Token` (那个强密码)。
|
||
* **Which events would you like to trigger this webhook?**：选择 `Just the push event.`（仅推送事件）。
|
||
* `Active`：确保此选项被勾选。
|
||
6. 点击 `Add webhook` 完成添加。
|
||
|
||
### D. 阶段四：自动化部署脚本 `deploy_webhook.php` （由我提供，您粘贴到宝塔）
|
||
|
||
为了实现自动化构建和重启 Next.js 应用，我们需要一个 PHP 脚本来作为宝塔面板 Git 部署的"部署完成后执行的命令"。
|
||
|
||
我为您生成了以下 `deploy_webhook.php` 脚本。**您需要将此脚本的内容复制，并粘贴到宝塔面板网站设置中 Git 部署的"部署完成后执行的命令"文本框内。**
|
||
|
||
**脚本内容（已根据您的截图信息优化，请务必根据您的实际情况修改 `SECRET`）：**
|
||
|
||
\`\`\`php
|
||
<?php
|
||
// deploy_webhook.php
|
||
// GitHub Webhook for Next.js (React) project deployment on Baota Panel
|
||
|
||
// --- 安全配置 ---
|
||
// 建议在宝塔面板的环境变量中设置此密钥，或者从配置文件读取，避免直接硬编码
|
||
$SECRET = 'your_deploy_secret_wztouzhi_bt'; // **请替换为你在宝塔面板Git部署中设置的Token**
|
||
$PROJECT_ROOT = '/www/wwwroot/tongzhi'; // **已根据截图更新为 `/www/wwwroot/tongzhi`**
|
||
$LOG_FILE = $PROJECT_ROOT . '/deploy.log'; // 部署日志文件，用于记录部署过程
|
||
|
||
// --- 函数定义 ---
|
||
function log_message($message) {
|
||
global $LOG_FILE;
|
||
file_put_contents($LOG_FILE, date('[Y-m-d H:i:s]') . ' ' . $message . PHP_EOL, FILE_APPEND);
|
||
}
|
||
|
||
function verify_signature($payload, $signature, $secret) {
|
||
$hash = 'sha1=' . hash_hmac('sha1', $payload, $secret);
|
||
return hash_equals($signature, $hash);
|
||
}
|
||
|
||
// --- 请求处理 ---
|
||
log_message('Webhook triggered.');
|
||
|
||
// 获取 GitHub 请求头
|
||
$github_signature = $_SERVER['HTTP_X_HUB_SIGNATURE'] ?? '';
|
||
$github_event = $_SERVER['HTTP_X_GITHUB_EVENT'] ?? '';
|
||
$payload = file_get_contents('php://input');
|
||
|
||
// 验证 Secret
|
||
if (empty($github_signature) || !verify_signature($payload, $github_signature, $SECRET)) {
|
||
log_message('Invalid signature. Aborting deployment.');
|
||
http_response_code(401);
|
||
die('Invalid signature');
|
||
}
|
||
|
||
log_message("GitHub Event: {$github_event}");
|
||
|
||
// 只处理 push 事件
|
||
if ($github_event === 'push') {
|
||
log_message('Processing push event...');
|
||
|
||
// 切换到项目根目录
|
||
chdir($PROJECT_ROOT);
|
||
log_message("Changed directory to: " . getcwd());
|
||
|
||
// 执行 Git Pull
|
||
log_message('Executing git pull...');
|
||
$output = shell_exec('git pull 2>&1');
|
||
log_message("Git Pull Output:\n" . $output);
|
||
|
||
// 检查 Next.js 项目文件 (package.json)
|
||
if (file_exists('package.json')) {
|
||
log_message('Detected Next.js project. Installing dependencies and building...');
|
||
|
||
// 安装 Node.js 依赖
|
||
log_message('Executing npm install...');
|
||
// 使用 --force 强制安装，避免因包版本冲突导致安装失败
|
||
$output = shell_exec('npm install --force 2>&1');
|
||
log_message("npm install Output:\n" . $output);
|
||
|
||
// 构建 Next.js 项目
|
||
log_message('Executing npm run build...');
|
||
$output = shell_exec('npm run build 2>&1');
|
||
log_message("npm run build Output:\n" . $output);
|
||
|
||
// 重启 PM2 进程 (已根据截图更新应用名为 'tongzhi')
|
||
$PM2_APP_NAME = 'tongzhi'; // **已根据截图更新：请替换为你在PM2管理器中设置的项目名称**
|
||
log_message("Restarting PM2 process '{$PM2_APP_NAME}'...");
|
||
$output = shell_exec("pm2 restart {$PM2_APP_NAME} 2>&1");
|
||
log_message("PM2 Restart Output:\n" . $output);
|
||
|
||
} else {
|
||
log_message('No package.json found. Skipping Node.js specific commands.');
|
||
}
|
||
|
||
log_message('Deployment completed.');
|
||
echo 'Deployment successful!';
|
||
|
||
} else {
|
||
log_message('Event not supported. Only "push" events are processed.');
|
||
echo 'Event not supported.';
|
||
}
|
||
|
||
http_response_code(200);
|
||
?>
|
||
\`\`\`
|
||
|
||
**脚本流程图：**
|
||
|
||
\`\`\`mermaid
|
||
graph TD
|
||
A[GitHub Webhook 请求] --> B{deploy_webhook.php 接收};
|
||
B -- 获取 Payload & Headers --> C{验证 Secret};
|
||
C -- 签名不匹配 --> D[401 Unauthorised];
|
||
C -- 签名匹配 --> E{事件类型为 Push?};
|
||
E -- 否 --> F[跳过，不处理];
|
||
E -- 是 --> G[切换到项目根目录];
|
||
G --> H[执行 git pull];
|
||
H --> I{检查 package.json 存在?};
|
||
I -- 否 --> J[跳过 Node.js 命令];
|
||
I -- 是 --> K[执行 npm install];
|
||
K --> L[执行 npm run build];
|
||
L --> M[执行 pm2 restart 应用名];
|
||
M --> N(部署成功，返回 200 OK);
|
||
\`\`\`
|
||
|
||
### V. 自动化部署完成与验证
|
||
|
||
完成以上所有配置后，每次您向 GitHub 仓库的指定分支推送代码，就会自动触发部署流程：
|
||
|
||
1. GitHub 发送 Webhook 请求到宝塔面板。
|
||
2. 宝塔面板接收请求并执行 `deploy_webhook.php` 脚本。
|
||
3. 脚本在服务器上拉取最新代码，安装/更新 Node.js 依赖，构建 Next.js 项目。
|
||
4. PM2 自动重启您的 Next.js 应用。
|
||
5. 您的网站内容更新，并能通过您绑定的域名在外网访问到最新版本。
|
||
|
||
**验证方法：**
|
||
* **查看 GitHub Webhook 记录：** 在 GitHub 仓库的 Webhook 设置页面，查看 `Recent Deliveries`，确保每次推送都有成功的绿色勾选。
|
||
* **查看宝塔面板 Git 部署日志：** 在宝塔面板网站设置的 `Git` 选项卡中，通常会有部署日志，可以查看详细的执行情况。
|
||
* **查看 `deploy.log` 文件：** 脚本会在项目根目录生成 `deploy.log` 文件，记录每次部署的详细信息，方便排查问题。
|
||
* **访问您的网站：** 通过域名访问您的网站，确认内容是否已更新到最新。
|
||
|
||
### VI. 注意事项与优化
|
||
|
||
* **安全性**：`Secret` 密钥是关键，请妥善保管，不要泄露。
|
||
* **权限问题**：确保宝塔面板运行的用户（通常是 `www` 用户）对项目目录有足够的读写权限，以便 `git pull`、`npm install`、`npm run build` 等命令能够正常执行。
|
||
* **依赖缓存**：在部署脚本中，`npm install` 会在每次部署时运行。如果您的项目依赖较多，可以考虑在 `Dockerfile` 中构建一个包含依赖的镜像，或者在服务器上对 `node_modules` 进行缓存处理，以加快部署速度（此文档以直接安装为默认）。
|
||
* **错误处理**：脚本中已加入了日志记录，您可以通过查看 `deploy.log` 文件来排查部署失败的原因。
|
||
* **生产模式**：确保您的 Next.js 应用在 `npm run build` 后是以生产模式构建的。
|
||
* **持续学习**：自动化部署是一个持续优化的过程，您可以根据项目需求和服务器性能，不断调整部署脚本。
|