宝塔面板下 Koa 项目结合 GitHub Webhook 实现自动部署
本文记录了在宝塔面板中集成 Koa 与 GitHub Webhook 实现自动部署的完整实践，涵盖架构设计与常见故障排查。
整体架构设计
graph TD
A[GitHub Push] -->|Webhook| B[Koa 接口 /webhook/deploy]
B -->|exec| C[deploy.sh]
C --> D[git pull]
C --> E[yarn install]
C --> F[pm2 reload]
核心原则：
Webhook 响应需迅速，部署逻辑应异步
宝塔与 PM2 的兼容性问题
PM2 环境变量缺失
启动时若遇到如下报错：
[PM2][Initialization] Environment variable HOME are not set
这通常是因为宝塔 Node 项目的运行环境未继承系统级变量。PM2 依赖 HOME 路径来存储配置和日志。
解决方案：
在启动脚本或环境变量设置中显式指定：
export HOME=/root
export PM2_HOME=/root/.pm2
或者更推荐的做法是直接使用宝塔自带的「Node 项目管理」功能启动项目，它会自动处理这些基础环境配置。
PM2 进程识别异常
有时执行管理命令会提示找不到进程：
[PM2][ERROR] Process or Namespace xxx not found
原因分析：
手动创建的 PM2 进程名与宝塔面板中配置的进程名称不一致，导致管理指令无法匹配。
解决思路：
- 统一进程命名规范，确保代码中的
name字段与宝塔界面一致。 - 优先使用宝塔 Node 项目管理模块，避免混用命令行工具与图形界面操作，减少状态不同步的风险。
注：实际部署中请根据具体业务调整 webhook 鉴权逻辑及脚本权限。
