HTTP(SM) 插件配置说明

一、概述

HTTP(SM) 是一款支持国密 GM-SSL（SM2/SM3/SM4） 与标准 TLS 双协议的 HTTP / HTTPS 网络探测插件。适用于需要验证国密 TLS 兼容性、证书有效性及常规 HTTPS 性能的场景。

二、输入配置参数详解

2.1 核心连接参数

参数名	类型	是否必填	默认值	说明与影响
`url`	string	是	—	目标 URL。若不以协议头开头，则自动补全为 `https://`。决定请求的目标地址和协议类型。若填写域名，将触发 DNS 解析，解析时间作为独立指标输出。
`ipVersion`	string	否	IPv4	IP 协议版本。填写 `ipv6` 则强制使用 IPv6（内部标记为 `1`）；否则默认使用 IPv4。影响域名解析地址族、套接字创建及连接路径。名字必须是 `ipVersion`
`method`	string	否	`GET`	HTTP 请求方法（如 `GET`、`POST`、`PUT`）。若配置了 `data` 参数，则自动强制为 `POST`，无需手动指定。

2.2 TLS / 国密控制参数

参数名	类型	是否必填	默认值	说明与影响
`mode`	integer	否	`0`	握手模式选择，直接影响加密协议栈行为： • `0`：仅使用 GM-SSL（国密）。若目标不支持国密，握手直接失败。 • `1`：自动切换。先尝试 GM-SSL，若失败则回退到标准 TLS。兼容性最好，但首次握手可能因尝试两种协议而增加耗时。该参数是此插件的核心特性，决定了能否与仅支持国密的服务端通信。
`insecure`	boolean	否	`true`	是否跳过 TLS 证书验证。`true` 时不验证服务器证书链（类似 `curl -k`），可连接自签名证书服务；`false` 时严格验证证书链和主机名，验证失败将触发握手错误。
`cert`	string	否	—	客户端证书，PEM 格式。用于双向 TLS（mTLS）认证。支持多行重复传入以拼接完整证书链。配置了此参数后，服务端可验证客户端身份。
`key`	string	否	—	客户端私钥，PEM 格式。与 `cert` 配对使用，必须同时配置。支持多行重复传入。若 `cert` 存在而 `key` 缺失，握手阶段将报错。
`ccert`	boolean	否	`false`	证书有效期检查开关。`true` 时，插件会检查服务端证书的 `NotBefore` 和 `NotAfter` 字段，若当前时间不在有效期内，则上报证书过期错误（`699000`）。

2.3 请求内容参数

参数名	类型	是否必填	默认值	说明与影响
`data`	string	否	—	POST 请求体内容。
`header`	string	否	—	自定义 HTTP 请求头。支持多行重复传入（每行一个 `header=Key: Value`）。可用于设置 `Content-Type`、`Authorization` 等。注意与 `username`/`password` 的基础认证头可能存在覆盖关系。
`username`	string	否	—	基础认证用户名。配置了此参数后，插件会自动生成 `Authorization: Basic <base64>` 请求头。
`password`	string	否	—	基础认证密码。与 `username` 配对使用。

2.4 响应验证参数

参数名	类型	是否必填	默认值	说明与影响
`ctype`	integer	否	`0`	响应验证类型，决定如何校验 HTTP 响应体 / 头： • `0`：不检查，任何响应均通过。 • `1`：响应 Body 等于 `cvalue`（大小写敏感）。 • `2`：响应 Body 包含 `cvalue`（大小写敏感）。 • `3`：响应 Body 匹配 `cvalue` 正则表达式。 • `4`：响应 Body 的 MD5 等于 `cvalue`（大小写不敏感）。 • `5`：响应头包含 `cvalue` 中指定的 key:value 对（`cvalue` 中用 CRLF 分隔多个头字段）。验证失败将触发对应的错误码。
`cvalue`	string	条件必填	—	验证期望值。当 `ctype ≠ 0` 时必须配置。其格式和语义取决于 `ctype` 的取值。支持多行拼接（每行一个 `cvalue=...`，内部用 `\r\n` 连接），可用于构造多行正则或多头字段验证。

三、参数关联与行为组合

组合场景	实际行为
`mode=0`（默认）+ 目标仅支持标准 TLS	GM-SSL 握手失败，任务报错（`612157` 握手失败）。
`mode=1` + 目标仅支持标准 TLS	先尝试 GM-SSL 失败，自动回退到标准 TLS 并成功。总耗时包含两次尝试时间。
`mode=0`（默认）+ 目标支持国密	使用 GM-SSL 成功，握手速度与标准 TLS 可能不同，密码套件 ID 通常为 `0xe011` 或 `0xe013`。
`data` 已配置 + `method=GET`	`method` 被强制覆盖为 `POST`，`data` 作为请求体发送。
`cert` 已配置 + `key` 未配置	双向认证缺少私钥，TLS 握手阶段报错。
`insecure=true` + 证书过期	即使证书过期也能握手成功（因为跳过了验证），但 `ccert=true` 仍会单独检查有效期并可能报错。
`insecure=false` + 自签名证书	证书链验证失败，握手报错 `612157`。
`ctype=4` + `cvalue=abcdef`	计算响应 Body 的 MD5，与 `abcdef`（大小写不敏感）比较，不匹配则报 `612275`。
`ctype=5` + `cvalue=Content-Type: application/json`	检查响应头中是否包含 `Content-Type: application/json`，不匹配则报 `612290`。
`header` 多行传入	每行解析为一个请求头，格式应为 `HeaderName: HeaderValue`。

四、输出指标详解

stage	指标名	单位	说明
`0`	总下载时间	ms	从发起请求到完整接收响应的整体耗时。是衡量端到端性能的核心指标。
`1`	DNS 解析时间	ms	将 `host` 中的域名解析为 IP 的耗时。若使用 IP 直连，接近 0。
`2`	TCP 连接时间	ms	TCP 三次握手完成的耗时。反映到目标服务器的网络层直连质量。
`3`	TLS / GM 握手时间	ms	加密握手耗时。标准 TLS 下为证书交换+密钥协商；GM-SSL 下为国密 SM2/SM3/SM4 握手流程。此指标是区分国密和标准 TLS 性能的关键数据。
`4`	请求发送时间	ms	发送 HTTP 请求头及 Body 的耗时。上行带宽不足或 Body 较大时可能增大。
`5`	首字节时间（TTFB）	ms	发送完请求到收到第一个响应字节的时间。反映服务端处理请求的首包响应速度。
`6`	剩余接收时间	ms	首字节之后到完整接收响应 Body 的时间。反映响应体大小和下行带宽。
`7`	下载速度	B / s	响应 Body 的平均下载速度，计算方式为 `Body 字节数 / (首字节后耗时)`。
`8`	下载字节数	bytes	接收到的响应 Body 总字节数（不含 HTTP 头）。
`9`	密码套件 ID	integer	协商后的 TLS / GM 密码套件标识。
`10`	TLS / GM 版本	integer	协商后的协议版本标识。用于确认是标准 TLS 1.2/1.3 还是国密 GM-SSL 版本。

4.3 错误码

info 值	含义	触发条件
`612007`	DNS 解析失败	域名无法解析为 IP。
`612029`	TCP 连接失败	目标拒绝连接或网络不可达。
`612157`	TLS / SSL 握手失败	证书验证失败、协议不匹配（如 `mode=0` 国密但目标不支持）、密码套件协商失败等。
`612002`	请求超时	整体请求超过 `timeout` 设定值。
`612272`	Body 内容检查失败	`ctype=1` 或 `ctype=2` 时，Body 与 `cvalue` 不匹配。
`612275`	MD5 检查失败	`ctype=4` 时，Body 的 MD5 与 `cvalue` 不匹配。
`612290`	头部检查失败	`ctype=5` 时，响应头中未包含 `cvalue` 指定的键值对。
`699000`	证书过期	`ccert=true` 时，服务端证书的有效期（`NotBefore`/`NotAfter`）不包含当前时间。

六、国密 GM-SSL 详解

6.1 支持的国密套件

套件 ID	说明
`0xe011`	ECC-SM4-SM3（SM2 密钥交换 + SM4 加密 + SM3 摘要）
`0xe013`	ECDHE-SM4-SM3（SM2 临时密钥交换 + SM4 加密 + SM3 摘要）

6.2 握手模式对比

模式	行为	适用场景
`mode=0`（仅 GM-SSL）	只发送国密 Client Hello，不支持则立即失败	专门测试国密兼容性
`mode=1`（自动切换）	先尝试 GM-SSL，失败后自动重试标准 TLS	通用探测，兼容国密和非国密目标

UDP 插件配置说明

HTTP3 插件配置说明