RelayPulse探测模板深度解析:占位符机制与请求体字节级伪装技巧
RelayPulse探测模板深度解析:占位符机制与请求体字节级伪装技巧
RelayPulse 是一个企业级 LLM 中转服务可用性监控系统,它的核心武器是位于 templates/ 目录下的探测模板:一份 JSON 文件描述一次完整的 HTTP 探测请求,通过 {{BASE_URL}}、{{API_KEY}}、{{PROMPT}} 等占位符在发送前动态填充,再以字节级伪装还原真实客户端(如 claude-cli、Codex-CLI)的请求形态,从而穿透中转站的回显、mock 作弊与身份识别。本文带你完整理解这套机制的设计原理。
探测模板是什么:一份 JSON 描述一次真实请求
每个探测模板都是 templates/ 目录下的一份 JSON 文件,例如 cc-haiku-arith.json,结构如下(节选):
{
"url": "{{BASE_URL}}/v1/messages",
"method": "POST",
"headers": {
"Authorization": "Bearer {{API_KEY}}",
"User-Agent": "claude-cli/2.1.76 (external, cli)"
},
"body": {
"model": "{{MODEL}}",
"messages": [{ "role": "user", "content": [{ "text": "{{PROMPT}}", "type": "text" }] }],
"stream": true
},
"response": { "success_contains": "{{EXPECTED_ANSWER}}" },
"probe": { "slow_latency": "5s", "timeout": "10s", "retry": 0 }
}
模板的解析结构定义在 internal/config/template.go,关键字段一览:
| 字段 | 作用 |
|---|---|
url / method / headers / body |
请求四要素,均支持占位符 |
request_model |
真正写入 body 的模型 ID,可与展示名 model 分离 |
success_contains |
响应内容校验关键字,支持 {{EXPECTED_ANSWER}} |
slow_latency / timeout / retry |
黄色慢速阈值、整体超时、重试策略 |
模板随 Docker 镜像打包,配置里只需一行 template: "cc-haiku-arith" 即可引用(见 docs/user/config.md)。
占位符机制:10 个 {{变量}} 的完整清单
所有占位符在一次探测前由 InjectVariables 统一替换,它返回一个临时副本,绝不污染共享配置。占位符按语义分三类:
1️⃣ 环境注入类
| 占位符 | 替换为 |
|---|---|
{{BASE_URL}} |
中转站接入地址(每行监测配置不同) |
{{API_KEY}} |
该通道的真实密钥 |
{{MODEL}} / {{REQUEST_MODEL}} |
实际请求的模型 ID(回退链:request_model > model) |
{{USER_ID}} / {{USER_ID_HASH}} |
按通道维度派生、定期刷新的 user_id(user_<sha256>_account__session_<uuid> 格式,见 internal/identity/userid.go) |
2️⃣ 动态随机类
| 占位符 | 替换为 |
|---|---|
{{RAND_UUID}} / {{RAND_UUID2}} |
每次探测随机生成的 UUIDv4 |
{{RAND_UUID_V7}} / {{RAND_UUID_V7_2}} |
内嵌真实毫秒时间戳的 UUIDv7——真实客户端的 session/turn 标识普遍是 v7,拿 v4 冒充会在 version 位露馅 |
{{UNIX_MS}} |
当前 Unix 毫秒,避免模板里冻结的时间戳永久漂移 |
3️⃣ 会话一致性类(伪装的精髓)
| 占位符 | 替换为 |
|---|---|
{{SESSION_UUID_V7}} |
同一监测行在 1 小时滚动窗口内恒定的会话 ID |
{{STABLE_UUID}} / {{STABLE_UUID2}} |
按通道派生的稳定 UUIDv4,模拟安装 ID / 账号 ID |
{{PROMPT}} / {{EXPECTED_ANSWER}} / {{ARITH_A}} / {{ARITH_B}} |
每次探测随机生成的算术题与答案 |
会话级标识的窗口派生逻辑在 internal/identity/session.go,注释写明了为什么窗口恰好是一小时:
- 窗口过短 → 每天产生 288 个会话,与真实客户端行为不符;
- 窗口过长 → UUIDv7 内嵌的"会话创建时刻"与请求时刻越差越远,任何解析 v7 的网关都能识破"一条创建了三个月的会话"。
同时,各监测行的窗口相位按哈希错开,避免同一家中转商下多条监测行"在同一毫秒创建会话"的明显破绽。
请求体字节级伪装:从抓包到复现的四个层次
以 cc-opus-ping.json 为例,伪装做到了四个层次:
🔹 第一层:请求头全量还原。 User-Agent: claude-cli/2.1.195 (external, sdk-cli)、X-Stainless-Lang/OS/Runtime、十余项 anthropic-beta 特性开关——全部来自真实 CLI 抓包。对比 cc-opus-arith.json 里精简的头集合,不同模板还原的是不同形态的客户端。
🔹 第二层:身份字段格式位合规。 {{STABLE_UUID}} 产出的 UUID 会正确设置 version=4、variant=RFC4122 位(internal/identity/userid.go 注释:线上实测见过 variant=3 的破绽串,合法值只能是 8/9/a/b)。格式校验严格的网关对"伪 UUID"一目了然。
🔹 第三层:整包 attestation 按原始字节搬运。 ping 模板的 cch(billing header 校验和)对请求体是字节敏感的——"改一个字节两个值全作废",所以模板中整段按抓包原样复制、不做任何调整,连其中冻结的 currentDate 都保留(注释里诚实标注了"已知永久漂移")。
🔹 第四层:语义级校验。 见 templates/cx-native-arith.json,instructions 里写着 You are Codex, based on GPT-5...,请求形态与 Codex CLI 逐字一致——伪装的不只是外壳,还有"这个客户端会说什么话"。
算术题池:让回显作弊无处遁形
{{PROMPT}} 不是随便一句"ping",而是 internal/monitor/prompt.go 里 5 种随机轮换的两位数加法题:
- 裸算式:
Compute 42 + 37. Reply only with RP_ANSWER=... - 应用题:
A shelf holds 42 books on one row and 37 on another... - 纯英文数词:
Find the sum of forty-two and thirty-seven...(题面没有阿拉伯数字,\d+正则空手而归) - 数词换序 +
Add:干扰固定位置/运算符字面的脆弱正则 - 混合表示(一数词一数字):让"抓所有数字求和"的取巧算法算错
答案 RP_ANSWER=<和> 只用于校验、绝不写进题面(用反引号包裹 RP_ANSWER= 保证答案不是题面子串,纯回显骗不过检测)。success_contains 填 {{EXPECTED_ANSWER}} 后,HTTP 200 但内容是回显/mock 的端点会被判红(content_mismatch)——哪怕 httpbin.org/anything 这样的回显服务也测不通。
安全边界:curl 复现与密钥脱敏
管理员测试失败时,系统会生成一条可复制的 curl 命令给通道方排障(internal/probe/curl.go)。它的输出契约很讲究:
- 密钥绝不出现明文,命中处替换为
$RP_API_KEYshell 变量(长度 < 8 的短串放弃脱敏,避免误伤正常文本); - 覆盖密钥的三种形态:原文、QueryEscape、PathEscape(key 落在 URL 里会被重编码成
%xx); - 用
--data-binary发送,保证 body 字节级一致。
公开自测路径则永不输出 curl,代理也仅管理员路径可用,防止本服务被当作 SSRF 跳板(internal/probe/inline.go)。
动手实践:读懂一份模板只需 5 步
- 打开 templates/ 目录,按
cc-(Claude Code 形态)、cx-(Codex 形态)、gm-(Gemini)前缀挑一份目标模板; - 对照上表识别
url/headers/body中的占位符,弄清哪些是"每通道不同"、哪些是"每次随机"、哪些是"窗口内恒定"; - 看
response.success_contains:填{{EXPECTED_ANSWER}}表示启用内容级校验,填固定词(如pong)表示语义校验; - 在 docs/user/config.md 中按
provider/service/channel/template挂一行监测配置,模板即生效; - 失败时用管理后台的"点探测"查看 HTTP 码、延迟与脱敏 curl 排障。
💡 命名约定也有讲究:
<service>-native-*命名的"厂商无关模板"刻意不声明 model/vendor,三项身份必须由监测行填写(判定逻辑见 IsNativeProbeTemplate)——这正是占位符机制与配置继承链协同的体现。
理解占位符的三类语义、窗口化会话派生和算术题池之后,你会发现 RelayPulse 的探测模板本质上是一份"可执行的请求指纹":它不关心中转站说自己有多快,只关心这一字节一字节发出去的请求,换不换个真客户端来做都一样的绿。

