webhook 完整指南：5 分钟在服务器上搭好自动部署 Webhook

webhook 完整指南5 分钟在服务器上搭好自动部署 Webhook【免费下载链接】webhookwebhook is a lightweight incoming webhook server to run shell commands项目地址: https://gitcode.com/gh_mirrors/we/webhook如果你还在每次 push 代码后 SSH 进服务器手动跑部署脚本这个工具应该能让你省下不少重复劳动。webhook 是一个用 Go 编写的轻量级入站 Webhook 服务器它在你的机器上暴露一个 HTTP 端点请求到达且校验通过时自动执行你预先配置的 shell 命令还能把请求头、请求体、URL 参数里的值精确地交给脚本使用——没有中间队列没有重型平台一个二进制文件加一份 JSON 就能跑起来。三步跑通第一个 hook快速上手整个过程只需要三个文件、两条命令建议跟着做一遍再往下看。第 1 步拿到可执行文件。如果你有 Go 1.21 环境从源码构建最干净git clone https://gitcode.com/gh_mirrors/we/webhook cd webhook go build .Debian/Ubuntu 也可以直接sudo apt-get install webhookFreeBSD 用pkg install webhook。第 2 步写一份最小配置。新建hooks.json顶层是一个 hook 数组id和execute-command是仅有的两个必填项完整字段清单见 docs/Hook-Definition.md[ { id: redeploy, execute-command: /var/scripts/redeploy.sh, command-working-directory: /var/www } ]注意你的脚本首行要带#!/bin/sh。喜欢 YAML 的话同样支持hooks.yaml即可。第 3 步启动并验证./webhook -hooks hooks.json -verbose默认监听 9000 端口每个 hook 都会得到一个http://你的服务器:9000/hooks/id端点。发一个请求试试curl -X POST http://localhost:9000/hooks/redeploy看到日志里脚本被执行恭喜链路已经通了。端口、监听 IP、URL 前缀等都能通过启动参数覆盖详见 docs/Webhook-Parameters.md。⚠️ 此时这个 hook 是裸奔的任何知道 URL 的人都能触发你的命令。下一步必须给它加门卫。按场景选校验方式GitHub、GitLab、Bitbuckettrigger-rule触发规则就是 hook 的门卫请求必须满足规则命令才会执行。规则支持and/or/not任意嵌套组合原子匹配类型覆盖精确值、正则、HMAC 签名、IP 白名单完整语法见 docs/Hook-Rules.md。不同平台的身份证放在不同位置选型如下平台凭证位置match 类型说明GitHub / Gogs / GiteaX-Hub-Signature/X-Gogs-Signature等请求头payload-hmac-sha1/256/512用共享密钥对请求体做 HMAC 签名校验GitLabX-Gitlab-Token请求头value与后台生成的 Token 精确比对Bitbucket不提供签名ip-whitelist只能按 CIDR 段放行官方 IP 范围以 Gitea/Gogs 为例签名正确且推送到了 main 分支才能部署trigger-rule: { and: [ { match: { type: payload-hmac-sha256, secret: mysecret, parameter: { source: header, name: X-Gogs-Signature } } }, { match: { type: value, value: refs/heads/main, parameter: { source: payload, name: ref } } } ] }把第二项换成or就能同时放行 master 和 development分支名想模糊匹配比如所有feature/*用regex类型。多个分支、多个来源的复杂组合写法docs/Hook-Rules.md 的 Multi-level 一节有现成模板。Slack 这类聊天平台的场景则更简单斜杠命令或 Outgoing Webhook 的 body 里自带token字段用value匹配它再配上response-message就能即时把正在处理的反馈回显到会话里。把请求数据喂给脚本参数、环境变量与文件webhook 能引用的请求值共四类header请求头、url查询参数、requestmethod、remote-addr、payload请求体语法见 docs/Referencing-Request-Values.md。交给脚本有三种通道命令行参数pass-arguments-to-command适合短小的标识值。JSON 嵌套值用点号路径访问如head_commit.idpass-arguments-to-command: [ { source: payload, name: pusher.name }, { source: payload, name: pusher.email } ]环境变量pass-environment-to-command值多或含空格时更稳妥。不写envname时变量名自动为HOOK_参数名写了则自定义。临时文件pass-file-to-command二进制或大文件的正解。数据会先 base64 编码传输webhook 落盘成请求级临时文件文件路径通过环境变量告知脚本pass-file-to-command: [ { source: payload, name: binary, envname: FILE_DATA, base64decode: true } ]脚本里读$FILE_DATA即可不指定command-working-directory时文件放在系统临时目录命令结束自动清理。发送端一条命令就能构造请求jo binary%app.zip | curl -H Content-Type: application/json -X POST -d - \ http://localhost:9000/hooks/file-handler进阶玩法四种不标准请求的处理① JSON 套 JSON用parse-parameters-as-json二次解析。Travis CI 把 JSON 塞进payloadJSON字符串这个表单字段里发过来Plex 的 multipart 表单也是把 JSON 放在名为payload的 part 中。只需声明哪个参数是 JSON之后就能像普通对象一样用payload.state引用parse-parameters-as-json: [ { source: payload, name: payload } ]② XML 请求体属性名加-前缀元素文本用#text同类元素按数组索引。例如user id1 nameJeff/的 name 属性写app.users.user.0.-namemessage的内文写app.messages.message.#text。③ JSON 数组 body数组 payload 会被包进root对象引用一律从root.开始如root.0.event、root.1.email。④ 配置模板化-template参数。启动时加-templatehooks.json会按 Go 模板解析内置getenv、cat读本地文件、credentialsystemd credentials三个函数密钥可以彻底移出配置文件secret: {{ getenv GITHUB_SECRET | js }}细节见 docs/Templates.md。此外-secure -cert -key可让服务直接提供 HTTPSsystemd 平台还支持 socket 激活普通用户也能占用 80/443 端口见 docs/Systemd-Activation.md。排错指南现象 → 原因 → 解法现象可能原因解法curl 返回 404端点拼错、id与 URL 不一致或-urlprefix改过默认值核对启动参数默认端点形如/hooks/id请求有响应但脚本没执行trigger-rule未通过签名/分支/token 不符加-verbose看拒绝原因用or放宽分支条件做对照测试脚本拿不到参数值点号路径写错数组 payload 没加root.前缀match 规则里的数字/布尔值未加引号先用下文探针 hook打印原始 payload 核对结构反代之后ip-whitelist永远不匹配webhook 看到的是代理 IP 而非客户端 IPIP 限制改在反代层做webhook 不再重复校验想确认命令输出默认响应不会回传 stdout设置include-command-output-in-response: true成功回 200 附带输出失败回 500改了 hooks.json 不生效进程未重载启动加-hotreload自动热加载或kill -HUP/-USR1 pid手动重载调试时还有一个省时技巧仓库自带的 test/hookecho.go 是个小工具编译后它会原样打印收到的所有参数和HOOK_前缀环境变量。临时把它配成一个 hook就能立刻看清webhook 到底给了我什么。上线前的安全检查清单逐项过一遍再交付生产每个 hook 都有trigger-rule且至少包含一层签名HMAC、token 或 IP 校验密钥没有明文写在 hooks 文件里改用-templategetenv/cat/credential注入用http-methods收窄允许的 HTTP 方法多数场景只需POST进程以最小权限运行-setuid/-setgid降权command-working-directory指向尽可能小的目录生产流量走 HTTPS-secure或反代终结 TLS必要时用-tls-min-version抬高底线开启-logfile与-pidfile请求来路与进程状态可追溯下一步行动建议先用仓库里的test/hookecho.go建一个探针 hook确认平台真实发来的 payload 结构给探针 hook 加上对应平台的trigger-rule用 curl 模拟一次合法与非法请求验证门卫生效换成真实部署脚本临时开启include-command-output-in-response自查输出稳定后关掉开启-hotreload把整套配置交给 docs/Hook-Examples.md 里的更多平台样例去扩充你的自动化版图。【免费下载链接】webhookwebhook is a lightweight incoming webhook server to run shell commands项目地址: https://gitcode.com/gh_mirrors/we/webhook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考