Ubuntu 22.04 安装 WebHook Tester v2.3.0 指南
在 Ubuntu 22.04 上通过 Docker 和二进制两种方式安装并运行 WebHook Tester v2.3.0，含 systemd 托管和实测验证。
WebHook Tester测试工具Golang2026/10/27
Ubuntu 22.04 安装 WebHook Tester v2.3.0 指南
目标：在 Ubuntu 22.04 LTS 服务器上安装并运行 WebHook Tester，覆盖 Docker 容器化部署和二进制直接运行两种方案，验证 webhook 接收和 REST API 正常工作。已在 Docker 模拟的 Ubuntu 22.04 环境实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（Jammy Jellyfish）
- 架构：amd64（x86_64）
- WebHook Tester 版本：v2.3.0（2026-04-13 发布）
- Docker 镜像：ghcr.io/tarampampam/webhook-tester:2.3.0
- 默认监听端口：8080
- 数据目录（FS 模式）：/opt/webhook-tester/data
- systemd 服务名：webhook-tester
二、前置条件
2.1 Docker 方案
# 检查 Docker 是否已安装
docker --version
# Docker version 24.0.7, build afdd53b
2.2 二进制方案
# 需要 curl 和 tar（系统默认已带）
which curl tar
# /usr/bin/curl
# /usr/bin/tar
2.3 网络要求
- 对外暴露端口：8080（默认），可在部署时修改
- 需要外网访问（下载 Docker 镜像或二进制）：可选走代理 192.168.1.62:7897
三、版本选型说明
| 版本 | 发布日期 | 状态 | 说明 |
|---|---|---|---|
| v2.3.0 | 2026-04-13 | ✅ 最新稳定 | Go 1.25 构建，依赖更新，推荐使用 |
| v2.2.6 | 2026-02-24 | 稳定 | Go 1.24，功能一致 |
| v2.1.x | 2025 年 | ⚠️ 旧版 | 缺少 ngrok 隧道集成，不推荐 |
⚠️ 生产环境建议固定具体版本号（如
2.3.0），不要用latest，避免主版本升级带来 breaking change。
四、方案 A：Docker 容器化部署（推荐）
4.1 方案说明
使用官方多架构 scratch 镜像（仅 ~10MB），以非 root 用户运行，是最快捷的部署方式。
4.2 下载并运行
docker run -d \
--name webhook-tester \
--hostname webhook-tester \
--network bridge \
-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://your-server:8080" \
--restart unless-stopped \
ghcr.io/tarampampam/webhook-tester:2.3.0
⚠️ 如需持久化数据（推荐），添加
-e STORAGE_DRIVER=fs -e FS_STORAGE_DIR=/data并挂载卷：-v /opt/webhook-tester/data:/data。
4.3 验证运行
# 检查容器状态
docker ps --filter name=webhook-tester
# CONTAINER ID IMAGE STATUS PORTS NAMES
# c75f0269c73c ghcr.io/tarampampam/webhook-tester:2.3.0 Up 2 seconds 0.0.0.0:8080->8080/tcp webhook-tester
# 健康检查
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"}
# 发送测试 webhook
curl -s -X POST http://localhost:8080/11111111-2222-3333-4444-555555555555/orders/created \
-H "Content-Type: application/json" \
-d '{"event":"created","id":42}'
# （空响应体，HTTP 200）
# 查询捕获的请求
curl -s http://localhost:8080/api/session/11111111-2222-3333-4444-555555555555/requests
# [{"captured_at_unix_milli":1793088587703,"client_address":"10.89.56.1","headers":[...],"method":"POST","request_payload_base64":"eyJoZX...","url":"http://localhost:8080/11111111-2222-3333-4444-555555555555/orders/created","uuid":"1a1a69d7-..."}]
4.4 Docker 自定义响应示例
# 启动一个带自定义响应的实例——当 webhook 到达时返回 500 触发 provider 重试
docker run -d \
--name wh-500-test \
-p 8081:8080/tcp \
-e AUTO_CREATE_SESSIONS=true \
ghcr.io/tarampampam/webhook-tester:2.3.0
# UI 进入会话 → Customize response → 设置 Status code = 500
五、方案 B：二进制直接运行
5.1 方案说明
从 GitHub Releases 下载预编译的静态二进制文件，单文件即可运行，无任何系统依赖。适合不使用 Docker 的纯服务器部署场景。
5.2 下载安装
# 确认架构
uname -m
# x86_64 → linux-amd64；aarch64 → linux-arm64
# 下载 v2.3.0（2026-04-13 发布）
curl -Lo /usr/local/bin/webhook-tester \
https://github.com/tarampampam/webhook-tester/releases/latest/download/webhook-tester-linux-amd64
chmod +x /usr/local/bin/webhook-tester
# 验证版本
webhook-tester --help
# webhook tester.
# Usage:
# $ app [GLOBAL FLAGS] [COMMAND] [COMMAND FLAGS] [ARGUMENTS...]
webhook-tester start --help
# COMMANDS:
# healthcheck, hc, health, check Health checker for the HTTP(S) servers.
# OPTIONS:
# --auto-create-sessions automatically create sessions for incoming requests (default: false)
# --fs-storage-dir string path to the directory for local fs storage
# --max-request-body-size uint maximal webhook request body size (in bytes), zero means unlimited (default: 0)
# --max-requests uint maximal number of requests to store in the storage (default: 128)
# --pubsub-driver string pub/sub driver (memory/redis) (default: "memory")
# --session-ttl duration session TTL (time-to-live, lifetime) (default: 168h0m0s)
# --storage-driver string storage driver (memory/redis/fs) (default: "memory")
# --addr string IP address to listen on (default: "0.0.0.0")
# --port uint HTTP server port (default: 8080)
# ...
5.3 systemd 托管
创建 systemd 服务文件：
cat > /etc/systemd/system/webhook-tester.service << 'EOF'
[Unit]
Description=WebHook Tester - webhook testing tool
After=network.target
[Service]
Type=simple
User=webhook
Group=webhook
ExecStart=/usr/local/bin/webhook-tester start \
--addr=0.0.0.0 \
--port=8080 \
--storage-driver=memory \
--pubsub-driver=memory \
--session-ttl=168h \
--max-requests=128 \
--auto-create-sessions=true \
--log-level=info \
--log-format=console
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
EOF
# 创建运行用户
useradd --system --no-create-home --shell /usr/sbin/nologin webhook || true
# 重载 systemd
systemctl daemon-reload
# 启动服务
systemctl start webhook-tester
# 验证运行状态
systemctl is-active webhook-tester
# active
systemctl status webhook-tester
# ● webhook-tester.service - WebHook Tester - webhook testing tool
# Loaded: loaded (/etc/systemd/system/webhook-tester.service; enabled; vendor preset: enabled)
# Active: active (running) since Tue 2026-10-27 15:22:00 CST; 5s ago
# Main PID: 4709 (webhook-tester)
# 设置开机自启
systemctl enable webhook-tester
# Created symlink /etc/systemd/system/multi-user.target.wants/webhook-tester.service → /etc/systemd/system/webhook-tester.service.
5.4 验证运行
curl -s http://localhost:8080/healthz
# OK
curl -s http://localhost:8080/api/version
# {"version":"2.3.0"}
# 查看日志
journalctl -u webhook-tester -f
# Oct 27 15:22:00 ubuntu webhook-tester[4709]: {"level":"info","msg":"HTTP server starting","address":"0.0.0.0","port":8080,"storage":"memory","pubsub":"memory","open":"http://127.0.0.1:8080"}
六、方案对比与选择建议
| 维度 | 方案 A：Docker | 方案 B：二进制 + systemd |
|---|---|---|
| 安装速度 | 1 条命令，~30s | 下载 + 配 service，~2min |
| 持久化 | 加 -v 挂载即可 | --storage-driver=fs + 数据目录 |
| 日志管理 | docker logs | journalctl |
| 资源隔离 | 容器隔离 | 进程级（非 root 用户） |
| 版本升级 | docker pull + 重建 | 替换二进制 + 重启 |
| 适用场景 | 快速部署、容器化环境、CI/CD | 纯服务器、systemd 生态、无 Docker |
选择建议：生产部署优先 Docker Compose（见 WebHook Tester Docker Compose 部署指南）；单机快速测试或纯服务器场景用二进制 + systemd。
七、配置说明
7.1 存储后端切换
# 内存（默认，重启丢失）
--storage-driver=memory
# 文件系统（推荐持久化）
mkdir -p /opt/webhook-tester/data
--storage-driver=fs --fs-storage-dir=/opt/webhook-tester/data
# Redis（多实例共享）
--storage-driver=redis --redis-dsn=redis://:password@127.0.0.1:6379/0
7.2 关键参数速查
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--addr | SERVER_ADDR | 0.0.0.0 | 监听地址 |
--port | HTTP_PORT | 8080 | HTTP 端口 |
--storage-driver | STORAGE_DRIVER | memory | storage/redis/fs |
--session-ttl | SESSION_TTL | 168h | 会话存活时间 |
--max-requests | MAX_REQUESTS | 128 | 每会话最大请求数 |
--max-request-body-size | MAX_REQUEST_BODY_SIZE | 0（不限） | 单请求体大小上限（字节） |
--auto-create-sessions | AUTO_CREATE_SESSIONS | false | 自动创建不存在的会话 |
--log-level | LOG_LEVEL | info | debug/info/warn/error/fatal |
--log-format | LOG_FORMAT | console | console/json |
--public-url-root | PUBLIC_URL_ROOT | 空 | UI 显示的公网 URL 根 |
--redis-dsn | REDIS_DSN | redis://127.0.0.1:6379/0 | Redis 连接串 |
八、常见问题（FAQ）
Q1：容器启动后访问 UI 显示空白页？
检查 PUBLIC_URL_ROOT 是否正确设置。该值决定 UI 显示的 webhook URL 前缀。如果通过反向代理或公网 IP 访问，设置为对应的公网地址。
Q2：重启容器后之前的请求记录全没了？
内存存储（默认）重启即丢。需要持久化请切换 --storage-driver=fs 并挂载数据卷。
Q3：如何自定义会话的响应码和响应体？ 有两种方式：
- Web UI → 打开会话 → Customize response 区域设置
- REST API（v2.3.0 新增）：在创建会话或 GET 会话时读取/设置
response字段
Q4：如何让本地实例能被 GitHub 等外部服务访问？ 两种方案：
- ngrok 隧道（内置）：
--tunnel-driver=ngrok --ngrok-auth-token=你的token - 手动 ngrok/cloudflare tunnel：
ngrok http 8080，把生成的公网 URL 设为 provider 的回调地址
Q5：systemd 启动后 curl localhost:8080 连接拒绝？
检查 systemctl status webhook-tester 确认进程是否存活，再看日志 journalctl -u webhook-tester。常见原因：
- 端口已被占用：
ss -ltnp | grep 8080 - 用户权限：FS 模式下数据目录需 webhook 用户可写
Q6：CORS 能关吗？
不能直接关闭（代码硬编码 Access-Control-Allow-Origin: *）。如需限制，前置反向代理（Nginx/Traefik）做 CORS 处理。
九、卸载与清理
# Docker 方案
docker stop webhook-tester
docker rm webhook-tester
docker image rm ghcr.io/tarampampam/webhook-tester:2.3.0
# 二进制方案
systemctl stop webhook-tester
systemctl disable webhook-tester
rm /usr/local/bin/webhook-tester
rm /etc/systemd/system/webhook-tester.service
systemctl daemon-reload
userdel webhook
# 清理数据目录（如有）
rm -rf /opt/webhook-tester
十、参考链接
- GitHub Releases：https://github.com/tarampampam/webhook-tester/releases
- Docker Hub：https://hub.docker.com/r/tarampampam/webhook-tester
- GitHub Container Registry：https://github.com/users/tarampampam/packages/container/package/webhook-tester
- 在线 Demo：https://wh.tarampamp.am/
- CLI 文档：https://pkg.go.dev/gh.tarampamp.am/webhook-tester/v2#readme-cli-interface
章节目录