Skip to content
BranchesTags

Repository files navigation

🌉 HookBridge

自托管 WebHook 网关 · 单二进制 · 零依赖 · 数据不出内网

Go Version License Version Build QPS Binary Size Docker Acceptance

English | 中文

接收 → 持久化 → 实时推送 → 调试重放 → 转发 / Mock / 签名验证，一个二进制全搞定。
下载即用，无需 Docker、无需数据库、无需 CGO。从本地开发到企业内网网关全覆盖。

HookBridge 把 WebHook 全流程打包成一个可执行文件，专为"追求强大功能但拒绝复杂运维"的工程师打造。

✨ 为什么选择 HookBridge

  • 🚀 单二进制零安装 — 12MB，无运行时，无依赖，下载即用
  • 🔒 数据不出内网 — 全部数据落本地 SQLite，零外发通道
  • ⚡ 单核 11,796 QPS — 工业级性能开箱即用
  • 🎯 12 个内置协议模板 — Stripe / GitHub / 支付宝 / 微信支付 / GB28181 / 海康 / 大华 自动识别
  • 🛠️ 完整调试工具链 — 重放（单条 / 批量 / 修改后）/ 对比 / Mock / 签名验证
  • 🌐 内置 Web UI — embed.FS 单页应用，WebSocket 实时推送，< 100KB
  • 🏢 企业级能力 — 多目标转发、负载均衡、指数退避重试
  • 🔐 安全加固 — CSRF 防护、IP 白名单、敏感头脱敏、请求体大小限制

📦 功能特性

社区版核心

  • 任意 WebHook 接收 — 任意路径、任意方法、任意 Content-Type
  • SQLite 持久化 — 纯 Go 驱动 modernc.org/sqlite，零 CGO 依赖
  • 协议模板匹配 — 内置 12 个主流平台模板，自动字段提取
  • Web UI — embed.FS 内嵌单页应用，零外部文件
  • WebSocket 推送 — 秒级送达，30 秒心跳保活
  • 自签名 TLS — -auto-tls 一键启用本地 HTTPS（ECDSA P-256）
  • 全文搜索 — 路径 / Header / Body / Query 全字段搜索
  • 自动清理 — retention_days 自动过期清理

调试与企业版

  • 重放引擎 — 一键 / 修改后 / 批量重放（最多 500 条）/ 请求对比
  • Mock 引擎 — 动态规则（热重载），按 path / method / header / body 匹配
  • 多目标转发 — 负载均衡（round-robin）/ 主备（故障转移），指数退避重试
  • 签名验证 — Stripe / GitHub (HMAC-SHA256) / Alipay (RSA2) / WeChatPay (V3+V2) / 自定义 HMAC-RSA
  • 自定义模板 — YAML 注入企业私有协议
  • 统计数据 — 按方法 / 状态码 / Content-Type / IP / 模板 / 小时分布聚合

安全

  • ECDSA P-256 自签名证书（更小、更快、更现代）
  • 管理 API Bearer Token 鉴权
  • IP 白名单（CIDR，IPv4/IPv6 双栈）
  • 请求体 10MB 限制（可配置）
  • CSRF Origin 校验
  • 敏感头脱敏（Authorization / Cookie / Set-Cookie）
  • 数据不出内网 — 零外发通道

🚀 快速开始（小白三步走）

第 1 步 — 下载或编译

方式 A：直接下载预编译二进制（推荐新手）

到 Releases 发布页 选择对应平台：

文件 平台 体积
hookbridge-windows-amd64.exe Windows x64 ~12 MB
hookbridge-linux-amd64 Linux x64 ~12 MB
hookbridge-linux-arm64 Linux ARM64 ~11 MB
hookbridge-darwin-arm64 macOS Apple Silicon ~11 MB
hookbridge-darwin-amd64 macOS Intel ~12 MB

💡 小白提示：不知道选哪个？Windows 选 .exe，Mac 选 darwin-arm64（M 系列）或 darwin-amd64（Intel），Linux 服务器选 linux-amd64。

方式 B：从源码编译（需要 Go 1.22+）

git clone https://gitee.com/suoten/HookBridge.git
cd HookBridge
make build           # 编译当前平台
make build-all       # 编译全平台 5 个二进制

第 2 步 — 启动服务

Windows 小白操作：

  1. 把下载的 hookbridge-windows-amd64.exe 放到任意目录（如 D:\hookbridge\）
  2. 双击运行，或打开 PowerShell 进入该目录执行： 
    .\hookbridge-windows-amd64.exe

Linux / macOS：

chmod +x hookbridge-linux-amd64        # 赋予执行权限
./hookbridge-linux-amd64               # 启动

启动成功会看到：

[INFO] HookBridge v1.0.0-final starting
[INFO] HTTP listening on 0.0.0.0:9876

打开浏览器访问 http://localhost:9876 即可看到 Web UI。🎉

第 3 步 — 发送第一个 WebHook

在浏览器打开 Web UI 后，可以用 curl 模拟一个 WebHook：

curl -X POST http://localhost:9876/my-webhook \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -d '{"ref":"refs/heads/main","repo":"hookbridge/demo"}'

返回响应：

{"ok":true,"msg":"HookBridge received"}

刷新 Web UI，即可看到这条请求已出现在列表中，并自动识别为 GitHub 模板。

💡 接收路径是"任意路径"——你 POST 到 /webhook、/stripe、/api/v1/notify 都可以，HookBridge 全部接收。接入方完全无需改造既有 WebHook 配置。

🐳 Docker 部署

# 构建镜像
docker build -t hookbridge:v1.0.0-final .

# 运行容器
docker run -d \
  --name hookbridge \
  -p 9876:9876 \
  -v $(pwd)/data:/data \
  -v $(pwd)/hookbridge.yaml:/etc/hookbridge/hookbridge.yaml:ro \
  hookbridge:v1.0.0-final \
  -data /data -config /etc/hookbridge/hookbridge.yaml

或使用 docker-compose：

docker-compose up -d

镜像特点：32.7 MB · 非 root 用户 · 内置 HEALTHCHECK · 多阶段构建

🐧 systemd 部署（Linux 服务器推荐）

sudo cp deploy/hookbridge.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hookbridge
sudo journalctl -u hookbridge -f       # 查看日志

服务文件含 13 项安全沙箱指令（NoNewPrivileges / ProtectSystem=strict / PrivateTmp / ProtectKernel* / RestrictNamespaces 等）+ 资源限制（LimitNOFILE=65536）。

完整部署指南见 deploy/README.md。

⚙️ 配置说明

HookBridge 支持命令行参数与 YAML 配置文件两种方式，命令行参数优先级更高。

命令行参数

参数 说明 默认值
-port HTTP 服务端口 9876
-data 数据目录 ./data
-public-url 公网回调地址 自动推断
-auto-tls 自动生成自签名 TLS 证书 false
-forward 转发 WebHook 到指定 URL 空
-config YAML 配置文件路径 ./hookbridge.yaml
-log-level 日志级别：debug/info/warn/error info
-demo 演示模式：每 10 秒生成一条 mock webhook false
-test 零资源自检并退出 false
-version 打印版本号并退出 false

YAML 配置文件

完整示例见 hookbridge.yaml.example：

server:
  port: 9876
  public_url: ""              # 公网地址，例如 https://hook.example.com
  auto_tls: false             # 自动生成自签名证书

storage:
  path: ./data                # SQLite 数据目录
  retention_days: 7           # 自动清理保留天数，0 表示永不清理
  max_body_bytes: 10485760    # 请求体最大字节数，默认 10MB

forward:
  targets:                    # 多目标列表（企业版）
    - url: http://internal-svc:8080/hook
      timeout_ms: 5000
  mode: load_balance          # load_balance (轮询) / backup (主备)
  retry: 3                    # 转发失败重试次数（指数退避）

templates:
  enabled: true               # 启用预置协议模板匹配
  custom_template: ""         # 自定义模板文件路径

security:
  secret: ""                  # 管理 API 共享密钥（Bearer Token）
  ip_whitelist: []            # 管理 API IP 白名单（CIDR）

signatures:                   # 签名验证器（企业版）
  - template: Stripe
    secret: whsec_xxx
  - template: GitHub
    secret: your-github-webhook-secret

🎯 内置协议模板

模板名 平台 识别依据
Stripe Stripe 支付 Stripe-Signature 头或路径含 /stripe
GitHub GitHub X-GitHub-Event 或 X-Hub-Signature-256
GitLab GitLab X-Gitlab-Event 头
Gitee Gitee 码云 X-Gitee-Token 或 X-Gitee-Event
Alipay 支付宝 路径含 /alipay 或 form 体含 notify_id
WeChatPay 微信支付 路径含 /wechat 或 XML 体含 <appid>/<mch_id>
DingTalk 钉钉 体含 EventType + 路径/签名头
Feishu 飞书 X-Lark-Request-Timestamp 或 X-Lark-Signature
WeCom 企业微信 XML 体含 <ToUserName>/<Encrypt>
GB28181 GB28181 平台 路径含 gb28181 或体含 device_id/channel_id
HikvisionISAPI 海康 ISAPI XML 体含 EventNotificationAlert
DahuaDSS 大华 DSS 路径含 /dahua 或体含 deviceid/alarm

📊 性能指标

4 核 4G 容器、本地回环网络、SQLite WAL 模式实测：

指标 实测值 阈值 结论
/health QPS 11,796 > 5,000 ✅ 2.36 倍达标
平均延迟 7.10 ms < 50 ms ✅
错误率 0.00% 0% ✅
1 分钟稳定压测 QPS 4,706 — ✅ 持续稳定
Panic/fatal 计数 0 0 ✅
压测后内存 35.8 MB < 30 MB ⚠️ 超 5.8MB，无泄漏
二进制体积 11~12 MB < 25 MB ✅
Docker 镜像 32.7 MB < 50 MB ✅
冷启动 < 1s < 1s ✅

完整验收报告：ACCEPTANCE-REPORT.md

🏗️ 架构图

flowchart LR
    WH[WebHook 上游<br/>Stripe/GitHub/支付宝/...]
    subgraph HB[HookBridge 单二进制]
        SRV[HTTP Server]
        PARSER[Parser<br/>模板匹配+字段提取]
        STORE[(SQLite<br/>WAL 模式)]
        HUB[WebSocket Hub]
        FWD[Forwarder<br/>多目标+重试]
        MOCK[Mock Engine]
        SIG[Signature Manager]
        REPLAY[Replay Engine]
        UI[Web UI<br/>embed.FS]
    end
    CLIENT[浏览器/调试者]

    WH -->|POST 任意路径| SRV
    SRV --> PARSER
    PARSER --> STORE
    STORE --> HUB
    HUB -->|实时推送| CLIENT
    CLIENT -->|管理 API| SRV
    SRV --> FWD
    SRV --> MOCK
    SRV --> SIG
    SRV --> REPLAY
    REPLAY -->|重放| STORE
    FWD -->|转发| UPSTREAM[内部服务]
    SRV --> UI
Loading

完整架构说明：docs/ARCHITECTURE.md

📡 REST API 列表

完整文档：docs/API.md。核心端点：

路径 方法 说明 鉴权
/health GET 健康检查 否
/metrics GET Prometheus 指标 否
/api/requests GET 请求列表（分页） 是
/api/requests/{id} GET 请求详情 是
/api/requests/{id}/replay POST 一键重放 是
/api/replay/batch POST 批量重放 是
/api/requests/compare POST 请求对比 是
/api/mock/rules GET/POST Mock 规则 CRUD 是
/api/signature/logs GET 签名验证日志 是
/api/forward/records GET 转发记录 是
/api/stats GET 统计数据 是
/ws WS WebSocket 实时推送 否

👥 适合人群

  • 后端工程师 — 调试 WebHook 接收逻辑，本地一键重放，无需上游平台重新推送
  • 运维工程师 — 内网 WebHook 网关，多目标转发 + 主备模式 + 失败重试，保障回调可靠送达
  • 安全工程师 — 签名验证日志审查、IP 白名单、敏感头脱敏、数据不出内网
  • WebHook 集成开发者 — 12 个内置模板自动识别，Mock 引擎模拟第三方平台各种状态，加速集成联调

📄 开源协议

MIT — 欢迎企业内网部署、二次开发与商用。

📞 Links

⭐ 如果项目对你有帮助，给个 Star ⭐

Made with ❤️ by HookBridge Contributors · Copyright © 2026

About

🌉 自托管 WebHook 网关 · 单二进制零依赖 · 数据不出内网 · 12 协议模板 · 11796 QPS

Topics

alipaydebuggb28181githubgogolanghikvisionmockreplayself-hostedsqlitestripewebhookwebhook-gateway

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages