Webhook Relay Server 镜像文档

一、镜像概述和主要用途

Webhook Relay Server 是一个独立部署的轻量级 Webhook 转发服务，旨在解决跨网络环境下的 Webhook 通信问题。其核心功能是接收来自源端的 Webhook 请求，经过简单处理（如验证、过滤）后，转发至目标服务端点。
主要用途：

• 实现内网服务接收公网 Webhook（替代复杂的内网穿透方案）
• 聚合多源 Webhook 请求并统一转发至后端服务
• 对 Webhook 请求进行安全验证（如 token 校验、IP 过滤）
• 简化跨域或跨网络环境的 Webhook 通信链路

二、核心功能和特性

1. 轻量级部署：独立容器化运行，无外部依赖（如数据库、消息队列），资源占用低
2. 灵活转发规则：支持单目标转发、多路径路由（不同请求路径转发至不同目标）
3. 安全验证：内置请求签名验证（支持 HMAC、Bearer Token）、IP 白名单过滤
4. 协议兼容性：支持 HTTP/HTTPS 协议（可配置自签名证书或权威证书）
5. 日志与监控：输出结构化日志（JSON 格式），支持请求耗时、状态码等关键指标记录
6. 高可用性：支持水平扩展（多实例负载均衡），无状态设计确保集群一致性

三、使用场景和适用范围

典型场景

1. 内网服务接收公网 Webhook

   • 场景：本地开发环境或内网服务（如 Jenkins、GitLab Runner）需接收来自 GitHub、GitLab 等公网平台的 Webhook
   • 解决：通过公网部署的 Relay Server 接收请求，转发至内网服务

2. 多源 Webhook 聚合

   • 场景：前端应用需接收来自支付平台（如 Stripe）、消息通知（如 Slack）、代码仓库（如 GitHub）的多类 Webhook
   • 解决：通过 Relay Server 统一入口接收，按路径路由至后端不同处理服务

3. Webhook 安全加固

   • 场景：暴露公网的 Webhook 端点需防止恶意请求或伪造签名
   • 解决：Relay Server 前置验证（如校验 GitHub 签名、过滤非白名单 IP），仅转发合法请求

4. 跨网络环境转发

   • 场景：跨 VPC、跨云厂商的服务间 Webhook 通信（如阿里云服务转发至 AWS 服务）
   • 解决：通过 Relay Server 作为中间节点，简化网络策略配置

四、使用方法和配置说明

4.1 快速启动（Docker Run）

通过 docker run 命令可快速部署单实例服务，示例如下：

docker run -d \
  --name webhook-relay \
  -p 8080:8080 \  # 映射容器端口到主机
  -e LISTEN_PORT=8080 \  # 容器内监听端口
  -e TARGET_DEFAULT=[***] \  # 默认转发目标（必填）
  -e AUTH_TOKEN=your-relay-token-123 \  # 源端请求验证 Token（可选，建议配置）
  -e LOG_LEVEL=info \  # 日志级别（debug/info/warn/error，默认 info）
  webhook-relay-server:latest

4.2 Docker Compose 配置

对于多实例或需持久化配置的场景，推荐使用 docker-compose.yml 管理：

version: "3.8"
services:
  webhook-relay:
    image: webhook-relay-server:latest
    container_name: webhook-relay
    restart: always  # 异常退出自动重启
    ports:
      - "8080:8080"  # HTTP 端口
      - "8443:8443"  # HTTPS 端口（如需启用）
    environment:
      - LISTEN_PORT=8080
      - LISTEN_SSL_PORT=8443  # 启用 HTTPS 时需配置
      - TARGET_DEFAULT=[***]  # 默认转发目标
      - AUTH_TOKEN=your-relay-token-123  # 全局请求验证 Token
      - IP_WHITELIST=192.168.1.0/24,10.0.0.1  # 允许的请求源 IP 白名单（可选）
      - SSL_CERT_PATH=/etc/relay/cert.pem  # SSL 证书路径（挂载外部证书）
      - SSL_KEY_PATH=/etc/relay/key.pem    # SSL 私钥路径
    volumes:
      - ./relay-config:/etc/relay  # 挂载证书或自定义路由配置文件
    networks:
      - backend-network  # 接入后端服务所在网络（如需直接通信）

networks:
  backend-network:
    external: true  # 假设后端服务已在该网络中

4.3 核心配置参数（环境变量）

4.4 自定义路由配置（高级功能）

如需按请求路径转发至不同目标（如 /github 转发至 GitHub 处理服务，/slack 转发至 Slack 通知服务），可通过配置文件实现。

配置文件格式（YAML 示例，route.yaml）：

routes:
  - path: "/github"          # 请求路径匹配（前缀匹配，如 `/github/webhook` 也会命中）
    target: "[***]"  # 目标服务 URL
    auth_token: "github-specific-token"    # 该路由独立的验证 Token（覆盖全局 AUTH_TOKEN）
    timeout: 5000          # 转发超时时间（毫秒），默认 3000
  - path: "/slack"
    target: "[***]"
    ip_whitelist: "35.190.247.0/24"  # 该路由独立的 IP 白名单（覆盖全局 IP_WHITELIST）

挂载配置文件：

在 docker run 或 docker-compose 中添加挂载：

# Docker Run 示例
docker run -d \
  -v ./route.yaml:/etc/relay/route.yaml \  # 挂载路由配置文件
  -e ROUTE_CONFIG_PATH=/etc/relay/route.yaml \  # 指定配置文件路径
  ...（其他参数同上）

4.5 请求验证机制

1. Token 验证

• 源端需在请求 Header 中携带 X-Relay-Token: <token>，服务端验证与配置的 AUTH_TOKEN（或路由独立 auth_token）一致则允许转发。
• 未携带或验证失败时，返回 401 Unauthorized。

2. IP 白名单验证

• 仅允许 IP_WHITELIST（或路由独立 ip_whitelist）中指定的 IP 地址/网段请求，其他来源返回 403 Forbidden。

五、使用示例

示例 1：内网服务接收 GitHub Webhook

场景：本地 Jenkins 服务（内网 IP：192.168.1.100:8080）需接收 GitHub Webhook。
部署步骤：

1. 在公网服务器部署 Relay Server：

   docker run -d \
     --name github-relay \
     -p 80:8080 \  # 公网 80 端口映射到容器 8080
     -e TARGET_DEFAULT=[***] \  # 转发至内网 Jenkins
     -e AUTH_TOKEN=github-webhook-secret-xxx \  # 与 GitHub Webhook 配置的 Secret 一致
     webhook-relay-server:latest
   

2. 在 GitHub 仓库 Webhook 配置中，设置 Payload URL 为 [***]，Secret 为 github-webhook-secret-xxx。

示例 2：多路径路由转发

场景：需将 /github 转发至 A 服务，/slack 转发至 B 服务。
配置文件（route.yaml）：

routes:
  - path: "/github"
    target: "[***]"
    auth_token: "token-for-a"
  - path: "/slack"
    target: "[***]"
    auth_token: "token-for-b"

启动命令：

docker run -d \
  -v ./route.yaml:/etc/relay/route.yaml \
  -e ROUTE_CONFIG_PATH=/etc/relay/route.yaml \
  -e LISTEN_PORT=8080 \
  -p 8080:8080 \
  webhook-relay-server:latest

六、注意事项

1. HTTPS 配置：如需启用 HTTPS，需确保挂载的证书和私钥文件权限正确（容器内用户需可读，建议权限 600）。
2. 性能与扩展：单实例支持 QPS 约 1000+（取决于请求大小和转发目标响应速度），高并发场景可通过负载均衡器部署多实例。
3. 日志排查：通过 docker logs <容器名> 查看实时日志，debug 级别可输出详细请求/响应信息（生产环境建议使用 info）。
4. 安全建议：生产环境务必配置 AUTH_TOKEN 和 IP_WHITELIST，避免服务被恶意滥用。