WebHook Tester Docker Compose 部署指南

目标：使用 Docker Compose 快速部署 WebHook Tester，覆盖两种典型配置——内存存储（轻量快速）和 Redis 持久化（生产推荐）。已在 Docker Compose v2 + Ubuntu 22.04 宿主环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（宿主）
Docker 版本：24.0.7
Docker Compose 版本：v2.21.0（插件式 docker compose）
WebHook Tester 版本：v2.3.0
Redis 版本：7-alpine（持久化方案）
默认端口：8080（webhook 接收与 Web UI）
Compose 项目名：wh-test（示例中使用 -p 指定，避免与其他组件冲突）

二、镜像选型说明

镜像源	镜像地址	说明
GitHub Container Registry	`ghcr.io/tarampampam/webhook-tester:2.3.0`	官方首选，多架构（amd64/arm64），scratch 基础镜像，~10MB
Docker Hub（镜像）	`tarampampam/webhook-tester:2.3.0`	镜像同步，内容相同

⚠️ 生产环境务必锁定具体版本号（如 2.3.0），不要用 latest，避免主版本升级带来 breaking change。

三、前置条件

3.1 Docker Compose 已安装

docker compose version
# Docker Compose version v2.21.0

3.2 网络准备

# 检查 8080 端口是否空闲
ss -ltnp | grep 8080 || echo "端口 8080 可用"

如需修改端口，调整 compose 文件中 ports 映射即可（如 "8131:8080/tcp"）。

四、方案一：内存存储（轻量快速，推荐本地调试）

4.1 方案说明

单服务、零依赖、快速启动。内存存储意味着容器重启后请求记录丢失——适合本地快速调试和临时场景。如需持久化，见下节 Redis 方案。

4.2 Compose 文件

创建 compose-webhook-tester.yml：

services:
  webhook-tester:
    image: ghcr.io/tarampampam/webhook-tester:2.3.0
    container_name: webhook-tester-v2.3
    hostname: webhook-tester
    restart: unless-stopped
    ports:
      - "8080:8080/tcp"
    environment:
      LOG_LEVEL: info
      LOG_FORMAT: console
      AUTO_CREATE_SESSIONS: "true"
      SESSION_TTL: "168h"
      MAX_REQUESTS: "128"
      MAX_REQUEST_BODY_SIZE: "0"
      STORAGE_DRIVER: memory
      PUBSUB_DRIVER: memory
      HTTP_PORT: "8080"
      PUBLIC_URL_ROOT: "http://localhost:8080"
    healthcheck:
      test: ["CMD", "/bin/app", "start", "healthcheck", "--port=8080"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

4.3 部署步骤

# 启动（项目名显式指定，避免与其他组件的 compose 目录同名导致 down 互删）
docker compose -p wh-test -f compose-webhook-tester.yml up -d
# [+] Running 2/2
#  ⠿ Network wh-test_default    Created
#  ⠿ Container webhook-tester-v2.3  Started

# 查看状态
docker compose -p wh-test -f compose-webhook-tester.yml ps
# NAME                  IMAGE                                      STATUS                   PORTS
# webhook-tester-v2.3   ghcr.io/tarampampam/webhook-tester:2.3.0   Up 3 seconds (healthy)   0.0.0.0:8080->8080/tcp

# 查看实时日志
docker compose -p wh-test -f compose-webhook-tester.yml logs -f --tail=50
# webhook-tester-v2.3  | {"level":"info","msg":"HTTP server starting","address":"0.0.0.0","port":8080,"storage":"memory","pubsub":"memory","open":"http://127.0.0.1:8080"}

4.4 验证运行

# 健康检查
curl -s http://localhost:8080/healthz
# OK

curl -s http://localhost:8080/ready
# OK

# 版本
curl -s http://localhost:8080/api/version
# {"version":"2.3.0"}

# 系统设置
curl -s http://localhost:8080/api/settings
# {"limits":{"max_request_body_size":0,"max_requests":128,"session_ttl":604800},"tunnel":{"enabled":false}}

# 发送测试 webhook（自动创建会话）
curl -s -D- -X POST http://localhost:8080/11111111-2222-3333-4444-555555555555/test \
  -H "Content-Type: application/json" \
  -d '{"hello":"world","count":42}'
# HTTP/1.1 200 OK
# Access-Control-Allow-Origin: *
# X-Wh-Created-Automatically: 1

# 查询捕获的请求
curl -s http://localhost:8080/api/session/11111111-2222-3333-4444-555555555555/requests | python3 -m json.tool
# [
#     {
#         "captured_at_unix_milli": 1793088587703,
#         "client_address": "172.22.0.1",
#         "headers": [
#             {"name": "Accept", "value": "*/*"},
#             {"name": "Content-Type", "value": "application/json"},
#             {"name": "User-Agent", "value": "curl/8.18.0"}
#         ],
#         "method": "POST",
#         "request_payload_base64": "eyJoZWxsbyI6IndvcmxkIiwiY291bnQiOjQyfQ==",
#         "url": "http://localhost:8080/11111111-2222-3333-4444-555555555555/test",
#         "uuid": "1a1a69d7-63c8-4b70-84d8-59b669933e5b"
#     }
# ]

# Base64 解码验证请求体
echo "eyJoZWxsbyI6IndvcmxkIiwiY291bnQiOjQyfQ==" | base64 -d
# {"hello":"world","count":42}

五、方案二：Redis 持久化存储（生产推荐）

5.1 方案说明

添加 Redis 作为持久化后端——容器重启后请求记录不丢失。Redis 同时承担 Storage 和 Pub/Sub 两个角色（多实例部署时也需要 Redis 做共享状态）。

5.2 Compose 文件

创建 compose-webhook-tester-redis.yml：

services:
  webhook-tester:
    image: ghcr.io/tarampampam/webhook-tester:2.3.0
    container_name: webhook-tester-v2.3-redis
    hostname: webhook-tester
    restart: unless-stopped
    depends_on:
      redis:
        condition: service_healthy
    ports:
      - "8080:8080/tcp"
    environment:
      LOG_LEVEL: info
      LOG_FORMAT: console
      AUTO_CREATE_SESSIONS: "true"
      SESSION_TTL: "168h"
      MAX_REQUESTS: "128"
      MAX_REQUEST_BODY_SIZE: "0"
      STORAGE_DRIVER: redis
      PUBSUB_DRIVER: redis
      REDIS_DSN: "redis://redis:6379/0"
      HTTP_PORT: "8080"
      PUBLIC_URL_ROOT: "http://your-server:8080"
    healthcheck:
      test: ["CMD", "/bin/app", "start", "healthcheck", "--port=8080"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  redis:
    image: redis:7-alpine
    container_name: webhook-tester-redis
    hostname: redis
    restart: unless-stopped
    command: redis-server --maxmemory 64mb --maxmemory-policy volatile-lru --appendonly yes
    volumes:
      - webhook-tester-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 5s

volumes:
  webhook-tester-redis-data:
    name: webhook-tester-redis-data

5.3 部署步骤

# 启动（Redis 会先于 webhook-tester 就绪）
docker compose -p wh-prod -f compose-webhook-tester-redis.yml up -d
# [+] Running 4/4
#  ⠿ Network wh-prod_default                    Created
#  ⠿ Volume "webhook-tester-redis-data"         Created
#  ⠿ Container webhook-tester-redis             Started
#  ⠿ Container webhook-tester-v2.3-redis         Started

# 验证
docker compose -p wh-prod -f compose-webhook-tester-redis.yml ps
# NAME                      IMAGE                              STATUS                   PORTS
# webhook-tester-v2.3-redis ghcr.io/tarampampam/webhook-tester:2.3.0   Up 1 minutes (healthy)  0.0.0.0:8080->8080/tcp
# webhook-tester-redis      redis:7-alpine                              Up 1 minutes (healthy)

curl -s http://localhost:8080/api/settings
# {"limits":{"max_request_body_size":0,"max_requests":128,"session_ttl":604800},"tunnel":{"enabled":false}}

# 测试持久化——重启后数据应保留
docker compose -p wh-prod -f compose-webhook-tester-redis.yml restart webhook-tester
# 等几秒...
curl -s http://localhost:8080/api/session/11111111-2222-3333-4444-555555555555/requests
# （仍能看到之前的请求列表）

六、数据持久化说明

存储驱动	持久化方式	说明
memory（默认）	❌ 无	容器重启即丢
fs（文件系统）	bind mount	添加 `-e STORAGE_DRIVER=fs -e FS_STORAGE_DIR=/data` + `-v /host/path:/data`
Redis	named volume	上方 Redis compose 示例已覆盖

FS 方案快速配置（不依赖 Redis）

environment:
  STORAGE_DRIVER: fs
  FS_STORAGE_DIR: "/data"
volumes:
  - /opt/webhook-tester/data:/data

七、环境变量速查表

变量名	默认值	说明
LOG_LEVEL	info	debug/info/warn/error/fatal
LOG_FORMAT	console	console（人类可读）/json（结构化）
AUTO_CREATE_SESSIONS	false	收到新 UUID 请求时自动创建会话
SESSION_TTL	168h	会话存活时长
MAX_REQUESTS	128	每会话最大请求数（0 = 不限）
MAX_REQUEST_BODY_SIZE	0	单请求体上限，0 = 不限（字节）
STORAGE_DRIVER	memory	memory / redis / fs
PUBSUB_DRIVER	memory	memory / redis
REDIS_DSN	redis://127.0.0.1:6379/0	Redis 连接串
FS_STORAGE_DIR	空	FS 存储路径（目录需存在）
HTTP_PORT	8080	HTTP 端口
HTTP_READ_TIMEOUT	1m	请求读取超时
HTTP_WRITE_TIMEOUT	1m	响应写入超时
HTTP_IDLE_TIMEOUT	1m	Keep-alive 空闲超时
SERVER_ADDR	0.0.0.0	监听地址
PUBLIC_URL_ROOT	空	UI 显示的 webhook URL 前缀
TUNNEL_DRIVER	空	ngrok（可选）
NGROK_AUTHTOKEN	空	ngrok token
SHUTDOWN_TIMEOUT	15s	优雅关闭超时

八、配置参数说明

8.1 会话自动创建（AUTO_CREATE_SESSIONS）

AUTO_CREATE_SESSIONS: "true"   # 推荐，不用预创建会话

开启后，任意首次请求到新 UUID 路径都会自动创建会话，返回头带 X-Wh-Created-Automatically: 1 标记。关闭时需先通过 REST API /api/session 手动创建。

8.2 会话 TTL（SESSION_TTL）

默认 168h（7 天）后会话自动过期。可用值格式：30m、24h、168h。长时间运行的测试环境可延长：

SESSION_TTL: "720h"  # 30 天

8.3 请求上限（MAX_REQUESTS / MAX_REQUEST_BODY_SIZE）

MAX_REQUESTS=128：每会话保留最近 128 条请求，超出后 FIFO 丢弃
MAX_REQUEST_BODY_SIZE=1048576：单请求体最大 1MB，超限会被拒绝（0 = 不限）

⚠️ 生产环境强烈建议设置 MAX_REQUEST_BODY_SIZE，防止大 body 撑爆内存/存储。

8.4 Redis 内存限制（Redis 容器）

示例中 Redis 设置了 --maxmemory 64mb --maxmemory-policy volatile-lru。根据实际请求量调整——每个请求平均 ~2KB，64MB 可存 ~3 万条请求，足够中小规模团队测试使用。

九、常用运维命令

# 启动/停止
docker compose -p wh-test -f compose-webhook-tester.yml up -d
docker compose -p wh-test -f compose-webhook-tester.yml down

# 重建（版本升级）
docker compose -p wh-test -f compose-webhook-tester.yml pull
docker compose -p wh-test -f compose-webhook-tester.yml up -d --force-recreate

# 仅重启 webhook-tester（不动 Redis）
docker compose -p wh-prod -f compose-webhook-tester-redis.yml restart webhook-tester

# 实时日志
docker compose -p wh-test -f compose-webhook-tester.yml logs -f webhook-tester

# 进入容器
docker exec -it webhook-tester-v2.3 /bin/sh

# 查看健康状态
docker inspect -f '{{.State.Health.Status}}' webhook-tester-v2.3
# healthy

# 查看版本
docker exec webhook-tester-v2.3 /bin/app --version 2>/dev/null || curl -s http://localhost:8080/api/version
# {"version":"2.3.0"}

# 清理全部（含 Redis 持久化卷）
docker compose -p wh-prod -f compose-webhook-tester-redis.yml down -v

十、等价 docker run 命令

与内存方案 compose 等价的单容器启动命令：

docker run -d \
  --name webhook-tester-v2.3 \
  --hostname webhook-tester \
  -p 8080:8080/tcp \
  -e LOG_LEVEL=info \
  -e AUTO_CREATE_SESSIONS=true \
  -e SESSION_TTL=168h \
  -e MAX_REQUESTS=128 \
  -e STORAGE_DRIVER=memory \
  -e PUBLIC_URL_ROOT="http://localhost:8080" \
  --restart unless-stopped \
  ghcr.io/tarampampam/webhook-tester:2.3.0

十一、常见问题（FAQ）

Q1：compose up 后 webhook-tester 启动失败，Redis 连不上？ 检查 Redis 容器健康状态：docker compose -p wh-prod exec redis redis-cli ping。若返回 PONG 但 webhook-tester 仍报错，检查 REDIS_DSN 格式——主机名用 compose service 名 redis，不是 IP。

Q2：数据卷挂载到 FS 模式但启动报错 directory must exist？ FS 驱动要求 FS_STORAGE_DIR 指向的目录提前存在。在 volumes 映射的宿主侧先 mkdir -p /opt/webhook-tester/data && chmod 777 /opt/webhook-tester/data（或对应容器用户可写权限）。

Q3：compose down 后数据还在吗？

memory 模式：down 即丢
Redis + named volume：down 保留，down -v 才删
FS + bind mount：down 完全不影响宿主目录

Q4：如何修改公网显示的 URL？ 设置 PUBLIC_URL_ROOT 为用户从浏览器访问的 URL 前缀。例如部署在子路径反向代理后设为 http://your-domain/wh/，容器内部仍监听 8080。

Q5：多实例部署怎么搞？

Storage 和 Pub/Sub 都切 Redis
负载均衡前置（Nginx/Traefik/K8s Service）
多实例共享同一 Redis 后端

十二、参考链接

官方 Docker 镜像：https://github.com/users/tarampampam/packages/container/package/webhook-tester
Redis 官方镜像：https://hub.docker.com/_/redis
Compose 文件版本说明：Docker Compose v2 已废弃 version: "3.9" 字段，可直接移除
完整 API 文档：WebHook Tester v2.3.0 API 使用详解