webhook-general-tool
项目摘要
webhook-general-tool 是面向多项目部署的轻量入口网关。它接收 Git 平台或自定义系统的回调，按 Hook 配置校验鉴权、事件、仓库和分支，再执行受控部署脚本，并在管理后台保留运行状态与日志。该工具解决的是发布入口治理，不替代完整 CI 平台。
作者职责
- 设计 Hook 模型、匹配规则、鉴权方式和执行记录。
- 实现 Express 服务、管理会话、MySQL 持久化和管理页面。
- 建立脚本超时、环境变量白名单和运行日志收口。
- 处理服务自更新、CNB 回调和服务器进程托管问题。
系统架构
Express 同时承载管理页面、登录 API 和 Webhook 接口。MySQL 保存用户、会话、Hook 与运行记录。每次执行记录触发来源、开始结束时间、退出码、标准输出、标准错误和合并日志。生产环境由进程管理器托管，Nginx 只代理回环端口。
安全边界
管理后台使用用户名密码和 HttpOnly 会话 Cookie；Webhook 单独使用全局 HMAC 或每 Hook Token。两层鉴权不能互相替代。生产模式要求安全 Cookie，公开入口不应配置为无鉴权。
执行边界
部署脚本只继承 PATH、HOME、语言和终端等基础环境变量，不继承数据库密码、管理员密码或 Webhook 主密钥。Hook 工作目录、超时和匹配条件均为显式配置。后台派生进程不受主脚本超时自动回收，因此只能用于已评估的重启场景。
关键设计决策
- 服务自更新先完成 HTTP 响应和运行记录，再延迟重启当前进程，避免请求被自身中断。
- 回调失败按构建、网络、鉴权、Hook 配置和脚本执行分层诊断，不把所有 500 视为构建失败。
- 运行日志写入持久化存储，页面只作为读取入口，不依赖进程内存保留历史。
- 旧 JSON 配置只做一次性导入，后续以数据库为运行真值。
验证证据
- 构建脚本对服务端和公开脚本执行 JavaScript 语法检查。
- 登录、Hook、用户和运行记录接口均有明确鉴权边界。
- 生产配置要求回环端口、HTTPS、安全 Cookie 和独立私有配置文件。
已知限制
- 轻量脚本执行不提供容器级隔离，Hook 配置者仍拥有较高服务器权限。
- 后台孤儿进程需要部署者自行控制生命周期。
- 当前案例不公开实际回调地址、仓库匹配规则和服务器日志。
后续演进
后续可将部署执行迁移到隔离 runner，并增加更严格的命令模板、审批和审计导出。