# HookBridge **Repository Path**: suoten/HookBridge ## Basic Information - **Project Name**: HookBridge - **Description**: 🌉 自托管 WebHook 网关 · 单二进制零依赖 · 数据不出内网 · 12 协议模板 · 11796 QPS - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 1 - **Created**: 2026-07-26 - **Last Updated**: 2026-10-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: webhook, webhook-gateway, self-hosted, Go语言, stripe ## README

# 🌉 HookBridge **自托管 WebHook 网关 · 单二进制 · 零依赖 · 数据不出内网** [![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go&logoColor=white)](https://go.dev/) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/version-v1.0.0--final-success.svg)](CHANGELOG.md) [![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)]() [![QPS](https://img.shields.io/badge/QPS-11796-orange.svg)](#-性能指标) [![Binary Size](https://img.shields.io/badge/binary-12MB-informational.svg)](#-快速开始小白三步走) [![Docker](https://img.shields.io/badge/docker-32.7MB-2496ED?logo=docker&logoColor=white)](Dockerfile) [![Acceptance](https://img.shields.io/badge/acceptance-99%2F100-brightgreen.svg)](docs/ACCEPTANCE-REPORT.md) [English](README.en.md) | **中文**

--- > 接收 → 持久化 → 实时推送 → 调试重放 → 转发 / 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 发布页](../../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+）** ```bash 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 进入该目录执行： ```powershell .\hookbridge-windows-amd64.exe ``` **Linux / macOS**： ```bash 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： ```bash 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"}' ``` 返回响应： ```json {"ok":true,"msg":"HookBridge received"} ``` 刷新 Web UI，即可看到这条请求已出现在列表中，并自动识别为 **GitHub** 模板。 > 💡 接收路径是"任意路径"——你 POST 到 `/webhook`、`/stripe`、`/api/v1/notify` 都可以，HookBridge 全部接收。接入方完全无需改造既有 WebHook 配置。 ## 🐳 Docker 部署 ```bash # 构建镜像 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： ```bash docker-compose up -d ``` 镜像特点：**32.7 MB** · 非 root 用户 · 内置 HEALTHCHECK · 多阶段构建 ## 🐧 systemd 部署（Linux 服务器推荐） ```bash 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](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](hookbridge.yaml.example)： ```yaml 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 体含 `/` | | `DingTalk` | 钉钉 | 体含 `EventType` + 路径/签名头 | | `Feishu` | 飞书 | `X-Lark-Request-Timestamp` 或 `X-Lark-Signature` | | `WeCom` | 企业微信 | XML 体含 `/` | | `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](docs/ACCEPTANCE-REPORT.md) ## 🏗️ 架构图 ```mermaid flowchart LR WH[WebHook 上游
Stripe/GitHub/支付宝/...] subgraph HB[HookBridge 单二进制] SRV[HTTP Server] PARSER[Parser
模板匹配+字段提取] STORE[(SQLite
WAL 模式)] HUB[WebSocket Hub] FWD[Forwarder
多目标+重试] MOCK[Mock Engine] SIG[Signature Manager] REPLAY[Replay Engine] UI[Web UI
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 ``` 完整架构说明：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) ## 📡 REST API 列表完整文档：[docs/API.md](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](LICENSE) — 欢迎企业内网部署、二次开发与商用。 --- ## 📞 Links - **GitHub**: - **Gitee**: - **English**: [README.en.md](README.en.md) - **验收报告**: [docs/ACCEPTANCE-REPORT.md](docs/ACCEPTANCE-REPORT.md) · 99/100 工业级验收 - **API 文档**: [docs/API.md](docs/API.md) - **架构文档**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - **更新日志**: [CHANGELOG.md](CHANGELOG.md)