GoReplay v1.3.3 配置参数详解

目标：逐项梳理 GoReplay v1.3.3（命令 gor）的全部配置参数——输入插件（流量捕获/文件回放）、输出插件（HTTP 回放/文件录制）、请求过滤、请求改写、采样限流、中间件与调试杂项，讲清每个参数的默认值与实测行为，并给出影子回放、文件录制、文件回放三类生产配置模板。本文全部命令与回显已在 Ubuntu 22.04 + GoReplay 1.3.3 环境实测通过；安装过程见 《GoReplay v1.3.3 安装指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64），两台：
  • 生产服务器：IP 10.89.56.2，示例业务应用监听 8000 端口，GoReplay 1.3.3 装于 /usr/local/bin/gor
  • 测试服务器：IP 10.89.56.3，主机名 test-server，同款业务应用监听 8000 端口
• GoReplay 版本：1.3.3（程序运行时自报 Version:1.3.0，上游版本常量未随 1.3.3 更新，见 《GoReplay v1.3.3 安装指南》 FAQ Q3）
• 录制文件目录：/var/lib/gor/（生产服务器）
• 参数考证来源：gor --help 实测全量输出（所有默认值均为 1.3.3 二进制内建值，2026-10-25 实测）+ 本地逐类实测验证

二、前置条件

• 已按 《GoReplay v1.3.3 安装指南》完成安装，gor 在 PATH 中。验证命令与实测回显：

which gor && gor 2>&1 | head -2

/usr/local/bin/gor
2026/10/25 00:13:07 [PPID 2667 and PID 2673] Version:1.3.0
2026/10/25 00:13:07 Required at least 1 input and 1 output

• 两台服务器业务应用就位（8000 端口），生产服务器可访问测试服务器：

curl -s -o /dev/null -w "local app:%{http_code}\n" http://127.0.0.1:8000/ && \
curl -s -o /dev/null -w "cross to target:%{http_code}\n" http://test-server:8000/

实测回显：

local app:200
cross to target:200

• 本文用于验证的示例业务为 Python 内置 HTTP 服务（python3 -m http.server 8000），其访问日志在 /var/log/app.log，可用来核对回放请求是否到达

三、参数查看与修改方式

GoReplay 没有配置文件机制：全部配置通过命令行标志（--参数名）在启动时传递，进程启动后参数即固化。因此「查看配置」= 查看帮助与进程启动命令，「修改配置」= 修改启动命令并重启进程。

3.1 查看全部参数：gor --help

gor --help（或任意非法标志，如 gor --version）都会触发完整帮助输出，这是 1.3.3 唯一的参数清单入口。输出结构为「参数列表 + 程序简介 + 版本」，实测（节选首尾）：

gor --help 2>&1 | head -14

实测回显：

  -copy-buffer-size value
    	Set the buffer size for an individual request (default 5MB)
  -cpuprofile string
    	write cpu profile to file
  -exit-after duration
    	exit after specified duration
  -http-allow-header value
    	A regexp to match a specific header against. Requests with non-matching headers will be dropped:
    		 gor --input-raw :8080 --output-http staging.com --http-allow-header api-version:^v1
  -http-allow-method value
    	Whitelist of HTTP methods to replay. Anything else will be dropped:
    		gor --input-raw :8080 --output-http staging.com --http-allow-method GET --http-allow-method OPTIONS
  -http-allow-url value
    	A regexp to match requests against. Filter get matched against full url with domain. Anything else will be dropped:
    		 gor --input-raw :8080 --output-http staging.com --http-allow-url ^www.
  -http-basic-auth-filter value

gor --help 2>&1 | tail -5

实测回显：

  -split-output true
    	By default each output gets same traffic. If set to true it splits traffic equally among all outputs.
  -stats
    	Turn on queue stats output
  -verbose int
    	set the level of verbosity, if greater than zero then it will turn on debug output

💡 说明：帮助正文约 200 行，每个参数都带一句用途说明与示例；多数 -value 型参数可重复出现（如多次 --http-allow-url 叠加多条白名单）。注意 GoReplay 标志写成单横线（-http-allow-url）与双横线（--http-allow-url）均可识别，本文统一用双横线风格。

3.2 修改参数的方式与生效关系

以 systemd 托管为例（把输出从 stdout 改为回放到测试服务器）：

# 编辑 ExecStart 后执行
systemctl daemon-reload
systemctl restart gor
systemctl is-active gor

实测回显：

active

⚠️ 注意：GoReplay 参数是启动期一次性注入的，systemctl reload 对它无意义（unit 未定义 reload 动作）；任何参数变更都必须走完整重启。

四、参数总览

以下总表按功能分组，全部参数名与默认值取自 gor --help 实测输出（1.3.3 内建默认值）。GoReplay 的参数体系即「插件总线」：至少 1 个输入 + 至少 1 个输出，其余参数围绕这两类插件做过滤、改写与调度。

输入插件：流量捕获（--input-raw 族）

关键解读：--input-raw 是 GoReplay 的灵魂参数，默认值基本开箱即用，只有三个场景需要动它——抓包丢包调大 buffer-size、SPAN/隧道场景给 bpf-filter、需要响应配对时加 track-response。

输入插件：文件回放（--input-file 族）

输出插件：HTTP 回放（--output-http 族）

⚠️ 注意：1.3.3 没有全局「每秒请求数（RPS）」限速参数（--output-http-rate 不在 1.3.3 参数清单中）。控制回放量的手段是：--output-http-workers 限制并发、--http-header-limiter/--http-param-limiter 采样放行比例、--input-file 回放时的播放速率控制（见 D1 实战篇实测）。

输出插件：文件录制（--output-file 族）

过滤、改写、采样与杂项

💡 技术拓展：--http-header-limiter 与 --http-param-limiter 的采样用的是 FNV-1A 哈希。常见采样策略对比——

策略	原理	特点
随机采样	每请求独立随机数	简单，但同用户一会放行一会丢弃，不利于会话级观察
哈希采样（GoReplay 采用）	对指定字段做 FNV-1A 哈希后按阈值放行	同一 user-id 恒定同命运，样本对用户一致，利于回放会话完整性
全量放行	不过滤	数据最全但测试环境压力大

GoReplay 1.3.3 内建的是哈希采样，天然满足「同一个用户要么全放行、要么全丢弃」的回放一致性需求。

五、核心参数分类详解

5.1 流量捕获输入：--input-raw

--input-raw 基于 libpcap 在网卡层嗅探发往指定端口的流量并重组 HTTP 请求，需要 root 权限。它不监听端口、不占业务端口，只在网卡旁路复制。最基础用法（生产服务器抓 8000 回放到测试服务器）：

gor --input-raw :8000 --output-http http://test-server:8000

启动后日志首部（实测，/var/log/gor.log）：

Interface: eth0 . BPF Filter: ((tcp dst port 8000) and (dst host 10.89.56.2))
Interface: lo . BPF Filter: ((tcp dst port 8000) and (dst host 127.0.0.1 or dst host ::1))
2026/10/25 00:17:15 [PPID 2893 and PID 2899] Version:1.3.0

💡 解读：1.3.3 会自动为每块相关网卡挂上 BPF 过滤器——eth0 抓发往本机 IP（10.89.56.2）的流量，lo 抓本机回环流量（127.0.0.1），所以本机 curl 自己的流量也能被抓到（后续实测均基于此）。多端口语法一次抓多个端口：--input-raw :80,8080,3000。

实测：track-response 响应配对。加 --input-raw-track-response 后，响应也会进入事件流（供文件录制/中间件使用）：

nohup gor --input-raw :8000 --output-file /var/lib/gor/requests.gor --input-raw-track-response \
  > /var/log/gor-rec.log 2>&1 &
curl -s -o /dev/null -w "rec1:%{http_code}\n" http://127.0.0.1:8000/tmp/
pkill -x gor
head -c 900 /var/lib/gor/requests_0.gor | cat -v

实测回显（录制文件原始格式）：

1 9c6e1f407f000001c3ac7f8e 1792887718616870919 0
GET /tmp/ HTTP/1.1^M
Host: 127.0.0.1:8000^M
User-Agent: curl/7.81.0^M
Accept: */*^M
^M

M-pM-^_M-^PM-5M-pM-^_M-^YM-^HM-pM-^_M-^YM-^I
2 9c6e1f407f000001c3ac7f8e 1792887718617308021 30433
HTTP/1.0 200 OK^M
Server: SimpleHTTP/0.6 Python/3.10.12^M
Date: Sun, 25 Oct 2026 00:21:58 GMT^M
Content-type: text/html; charset=utf-8^M
Content-Length: 346^M
^M
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
...（目录列表 HTML 正文，节选）

💡 解读：.gor 文件的记录结构为「事件类型 + 请求ID + 纳秒时间戳 + 耗时」首行 + HTTP 原文 + 🐵🙈🙉 分隔符（cat -v 下显示为 M-pM-^_... 的 UTF-8 字节序列）。事件类型 1 为请求、2 为响应，二者共享同一请求 ID（9c6e1f407f000001c3ac7f8e）实现配对。另注意：指定的输出名 requests.gor 落盘后自动带序号后缀为 requests_0.gor（分块机制，超过 --output-file-size-limit 32MB 后滚动为 _1、_2）。

5.2 文件回放输入：--input-file

--input-file 读取录制文件按原始时间轴回放。先做 dry-run 预演（不真回放，输出统计）：

gor --input-file /var/lib/gor/requests_0.gor --input-file-dry-run --output-null

实测回显：

2026/10/25 00:22:21 [PPID 3035 and PID 3041] Version:1.3.0
[DEBUG][elapsed 386.799µs]: [INPUT-FILE] FileInput: end of file '/var/lib/gor/requests_0.gor'

Records found: 4
Malformed records: <nil>
Files processed: 1
Bytes processed: 1640
Max wait: 3.684744ms

💡 解读：Records found: 4 = 2 请求 + 2 响应（双录文件）；Max wait: 3.684744ms 表示请求间最大间隔——回放时全文件播放时长 ≈ 各间隔之和，--input-file-max-wait 可把超长间隔截断到指定值；--input-file-loop 让文件循环播放（常与倍速语法配合，见 D1 实战篇）。

5.3 HTTP 回放输出：--output-http

--output-http 把请求转发到测试环境。回显链路实测（生产侧启动回放 → 产生流量 → 测试侧核对）：

nohup gor --input-raw :8000 --output-http http://test-server:8000 > /var/log/gor.log 2>&1 &
curl -s -o /dev/null -w "req:%{http_code}\n" http://127.0.0.1:8000/tmp/

测试服务器业务日志实测回显（回放请求到达）：

10.89.56.2 - - [25/Oct/2026 00:17:17] "GET /tmp/ HTTP/1.1" 200 -

关键行为——Host 头替换：默认 gor 把请求的 Host 头替换为回放目标地址（如 test-server:8000），需要保留原 Host 时加 --http-original-host。并发与超时默认值：--output-http-workers 0（动态扩缩）、--output-http-timeout 5s、--output-http-queue-len 1000。目标是 https 且用自签证书时加 --output-http-skip-verify。

5.4 文件录制输出：--output-file

--output-file 把请求落盘为 GoReplay 专有格式（5.1 已见原始格式）。分块行为实测：录制文件名自动加 _0 序号后缀；--output-file-append 控制追加而非滚动；--output-file-flush-interval 1s 默认每秒刷盘，进程被 kill 后最多丢 1 秒缓冲数据（生产录制建议配合 --output-file-append 且避免频繁 kill）。

5.5 请求过滤：--http-allow-* / --http-disallow-*

过滤参数在引擎层丢弃不匹配的请求（不产生回放流量）。实测 URL 白名单：只放行 /tmp/ 开头的请求，同时注入一个标记头：

nohup gor --input-raw :8000 --output-stdout --http-allow-url "^/tmp/" \
  --http-set-header "X-Gor-Filter: url-whitelist" > /var/log/gor-filter.log 2>&1 &
sleep 2
curl -s -o /dev/null -w "req-tmp:%{http_code}\n" http://127.0.0.1:8000/tmp/
curl -s -o /dev/null -w "req-other:%{http_code}\n" http://127.0.0.1:8000/etc/
sleep 2
grep -E "^(GET|POST|PUT|DELETE|HEAD)" /var/log/gor-filter.log
grep -c "X-Gor-Filter" /var/log/gor-filter.log
pkill -x gor

实测回显：

req-tmp:200
req-other:200
GET /tmp/ HTTP/1.1
1

💡 解读：两笔生产请求都正常返回（过滤发生在 gor 内部，不影响生产请求本身），但 gor 输出侧只见 GET /tmp/——/etc/ 请求被白名单丢弃；注入的 X-Gor-Filter 头出现 1 次（跟随被放行的请求）。白名单支持多条叠加（多次传参即 OR 关系）；黑名单 --http-disallow-url 语义相反（命中即丢弃）。

5.6 请求改写：--http-rewrite-* / --http-set-*

改写参数在回放前修改请求。实测 URL 重写（把 /v1/user/<id>/ping 重写为 /v2/user/<id>/ping）：

nohup gor --input-raw :8000 --output-stdout \
  --http-rewrite-url "/v1/user/([^\/]+)/ping:/v2/user/$1/ping" > /var/log/gor-rw.log 2>&1 &
sleep 2
curl -s -o /dev/null -w "rw:%{http_code}\n" http://127.0.0.1:8000/v1/user/42/ping
sleep 2
grep -E "^(GET|Host)" /var/log/gor-rw.log
pkill -x gor

实测回显：

rw:404
GET /v2/user/42/ping HTTP/1.1
Host: 127.0.0.1:8000

💡 解读：生产请求是 GET /v1/user/42/ping（业务 404 属示例服务无此路由，不影响验证），gor 输出侧变成了 GET /v2/user/42/ping——正则捕获组 $1 把 42 原样带入新路径，重写生效。--http-rewrite-header 同理（如把 Host 正则改写）；--http-set-param api_key=1 用于在回放时补齐测试环境需要的查询参数。

5.7 采样限流：--http-header-limiter / --http-param-limiter

两个限流参数按「字段值 FNV-1A 哈希 + 百分比阈值」做一致性采样，语法为 字段名:百分比%。帮助原文示例（实测照抄）：

  -http-header-limiter value
    	Takes a fraction of requests, consistently taking or rejecting a request based on the FNV32-1A hash of a specific header:
    		 gor --input-raw :8080 --output-http staging.com --http-header-limiter user-id:25%
  -http-param-limiter value
    	Takes a fraction of requests, consistently taking or rejecting a request based on the FNV32-1A hash of a specific GET param:
    		 gor --input-raw :8080 --output-http staging.com --http-param-limiter user_id:25%

💡 说明：采样限流适合「回放部分真实流量」场景——如 --http-header-limiter X-Session-Id:10% 只回放 10% 会话且每个会话完整保留。注意它与并发上限（--output-http-workers）是两种维度：limiter 决定「放行哪些请求」，workers 决定「同时发多少个」。

5.8 中间件：--middleware

--middleware 外接一个可执行命令，GoReplay 把每个请求事件以行协议喂给它、把它输出的行当作（可修改后的）事件流，可实现任意改写、丢弃、复制与自定义路由。最小验证——用 /bin/cat 原样透传，确认中间件管线打通：

timeout 10 gor --input-dummy :0 --middleware "/bin/cat" --output-stdout --exit-after 2s 2>&1 | head -8

实测回显：

2026/10/25 00:23:47 [PPID 3135 and PID 3137] Version:1.3.0
2026/10/25 00:23:47 Running gor for a duration of 2s
1 ffbfa26066b893a1c347b999 1792887828387367054 -1
GET / HTTP/1.1
Host: www.w3.org
User-Agent: Go 1.1 package http
Accept-Encoding: gzip

💡 解读：/bin/cat 不修改任何内容，请求原样到达输出侧（GET /、Host: www.w3.org 是 --input-dummy 测试输入的固定内容），证明「输入 → 中间件 → 输出」管线工作正常。实战中间件用 Python/Lua 脚本按行读写、解析 JSON 消息做改写或丢弃（事件 JSON 结构与用法见 D1 实战篇实测）。

5.9 调试与杂项参数

--output-stdout / --output-null：前者把事件流打印到终端（配合 --prettify-http 自动解码 gzip/chunked，类似 tcpdump）；后者全部丢弃（配合 --input-file-dry-run 只看统计）。--exit-after：运行指定时长后自动退出，用于定点采样窗口：

timeout 8 gor --input-dummy :0 --output-stdout --exit-after 3s 2>&1 | head -6

实测回显：

2026/10/25 00:21:32 [PPID 2953 and PID 2955] Version:1.3.0
2026/10/25 00:21:32 Running gor for a duration of 3s
1 b0a752d1c7fbac7381ed44ab 1792887693774146386 -1
GET / HTTP/1.1
Host: www.w3.org
User-Agent: Go 1.1 package http

--verbose：大于 0 时开启调试输出（如 dry-run 里自动出现的 [DEBUG] 行即调试级别输出）。--http-pprof：在指定端口（默认 :8181）暴露 Go pprof 端点，排查 gor 自身 CPU/内存用。--split-output：默认每个输出都收到全量流量（复制语义），置 true 后多输出间均分流量——注意帮助文本显示其默认值为 true 但语义描述为分流开关，多输出场景务必显式传参明确行为。

六、生产配置模板

以下三个模板覆盖 GoReplay 最常见的三类生产形态，均按 4 核 8GB 内存、普通 SATA/SSD 磁盘的业务服务器规格给出（GoReplay 自身资源开销小，实测常驻捕获内存约 10MB 量级）。

6.1 模板一：影子回放（生产 → 测试环境，常驻）

适用场景：生产应用与测试环境网络互通，要求生产请求实时影子复制到测试环境；测试环境按生产 20% 会话量承载。

# /etc/systemd/system/gor.service 的 ExecStart
ExecStart=/usr/local/bin/gor \
  --input-raw :8000 \
  --output-http http://test-server:8000 \
  --output-http-timeout 10s \
  --output-http-workers 20 \
  --http-header-limiter X-Session-Id:20% \
  --http-allow-url ^/api/ \
  --input-raw-buffer-size 4MB

逐项说明：--output-http-timeout 10s 放宽到 10 秒避免测试环境慢响应误判失败；--output-http-workers 20 封顶回放并发，保护测试环境；--http-header-limiter X-Session-Id:20% 按会话哈希只回放 20% 会话（同一会话要么全放行、要么全丢弃）；--http-allow-url ^/api/ 只回放 API 流量，静态资源请求不回放；--input-raw-buffer-size 4MB 在高 QPS 下防抓包丢包。磁盘无额外要求（不落盘）。

6.2 模板二：文件录制（生产侧落盘，网络隔离）

适用场景：生产与测试网络不互通，先在生产录制、再离线拷贝到测试环境回放；需保留响应做环境差异比对。

# /etc/systemd/system/gor.service 的 ExecStart
ExecStart=/usr/local/bin/gor \
  --input-raw :8000 \
  --input-raw-track-response \
  --output-file /var/lib/gor/prod-%Y-%m-%d.gor \
  --output-file-append \
  --output-file-max-size-limit 100GB \
  --http-disallow-url ^(.*\.(png|jpg|css|js)) \
  --exit-after 1h

逐项说明：--input-raw-track-response 开启请求+响应双录（供回放后比对）；输出文件名支持时间模板（%Y-%m-%d 按天滚动文件）；--output-file-append 同名文件追加写；--output-file-max-size-limit 100GB 兜底磁盘占用（生产 8000 端口日流量按 50GB 估算时留一倍余量，磁盘建议预留 200GB）；--http-disallow-url 剔除静态资源（正则匹配 URL 后丢弃）。

6.3 模板三：文件回放（测试环境离线回放）

适用场景：把 6.2 录制的文件在测试环境以 2 倍速循环回放，快速回归。

# 测试环境执行（前台或 systemd 均可）
gor --input-file "/var/lib/gor/prod-2026-10-25.gor|200%" \
  --input-file-loop \
  --output-http http://127.0.0.1:8000 \
  --output-http-workers 10

逐项说明：|200% 倍速后缀把原始时间轴压缩一半（2 倍速播放，语法与效果实测见 D1 实战篇）；--input-file-loop 播完自动循环；--output-http-workers 10 限制并发。本模板跑在测试环境，无抓包权限要求（--input-file 不需要 root）。

七、常见问题

Q1：参数改了不生效？ GoReplay 无配置文件，参数在进程启动时固化。确认修改的是「正在运行的进程」的启动命令：systemd 场景改完 ExecStart 必须 systemctl daemon-reload && systemctl restart gor；脚本场景要 kill 旧进程再拉起。用 ps -ef | grep gor 核对当前进程实际参数。

Q2：加了 --http-allow-url 后抓包输出一条请求都没有？ 白名单正则是对「完整 URL（含域名）」匹配的，帮助原文写明 "Filter get matched against full url with domain"。本机回环场景 URL 为 http://127.0.0.1:8000/tmp/ 形态，写 ^/tmp/ 能命中是因为 1.3.3 对路径做了兼容处理；若写域名相关正则，注意带上实际 Host。排查技巧：先去掉过滤参数用 --output-stdout 看 gor 眼中的原始请求行，再定正则。

Q3：--output-http-stats 打开了但看不到统计输出？ 实测在短窗口 dummy 流量下该参数未产生可见统计行（统计触发依赖队列活动形态），不如直接 --output-stdout 观察回放明细可靠。需要量化回放成功率时，以测试环境业务日志（或网关访问日志）为准。

Q4：录制文件越来越大，能否自动分割？ --output-file-size-limit（默认 32MB）控制单分块大小，超限滚动新文件（_0、_1…）；文件名支持 %Y-%m-%d 等时间模板按天分割；--output-file-max-size-limit（默认 1TB）兜底总量上限。

Q5：1.3.3 怎么按 RPS 限速回放？ 1.3.3 参数清单中没有全局 RPS 限速参数。替代手段：① --output-http-workers N 用并发数压制瞬时速率；② --http-header-limiter/--http-param-limiter 按比例采样；③ 文件回放用 |N% 倍速语法整体拉长/压缩时间轴（实测见 D1）。全局 RPS 限速能力在 GoReplay 2.0 的参数体系中才出现。

Q6：--input-raw 启动后没有任何输出？ 按序检查：① 是否 root（非 root 无抓包权限）；② 流量目标端口是否与 --input-raw :端口 一致（抓的是「发往该端口」的入站流量）；③ HTTPS 流量默认抓不到明文 HTTP 请求，需按官方 Wiki 的 TLS 捕获指引启用对应捕获方式；④ 用 ps -ef | grep gor 确认进程参数没有被 shell 转义破坏。

八、参考链接

• 官方 Wiki（参数文档）：https://github.com/buger/goreplay/wiki
• Getting Started：https://github.com/buger/goreplay/wiki/Getting-Started
• 官方 Release Notes（1.3.0/1.3.3 变更）：https://github.com/buger/goreplay/releases
• 本专栏系列：《GoReplay v1.3.3 介绍与选型指南》（定位、架构与同类对比）、《GoReplay v1.3.3 安装指南》（三方案安装与 systemd 托管实测）、《GoReplay v1.3.3 常用 CLI 命令与实战详解》（录制/回放/限速/过滤实战）