🔧 配置详解

MockHub 的全部配置通过 config.yaml 完成，顶层结构如下：

yaml

server:     # 管理端
proxy:      # HTTP 代理端
nacos:      # Nacos 注册
log:        # 日志
tcp:        # TCP 代理
udp:        # UDP 代理
tcpRules:   # TCP / UDP 规则表（共用）
services:   # HTTP 服务与规则

🌐 server — 管理端

参数	类型	默认值	说明
`port`	int	`9861`	管理后台监听端口（内嵌 Web UI + `/api` 接口）
`name`	string	`mock`	服务名称
`gzip`	bool	`true`	是否启用 gzip 压缩（SSE 流接口除外）

🔄 proxy — HTTP 代理端

参数	类型	默认值	说明
`port`	int	`9862`	代理端监听端口，接收外部 HTTP 请求
`timeout`	int	`30`	转发下游请求超时（秒）
`fallback`	string	`404`	未命中任何规则时的兜底策略：`404` 返回 404 / `passthrough` 透传到第一个启用服务
`maxRecordSize`	ByteSize	`64M`	单条录制请求/响应体上限，超出截断（支持 `64M` / `1G` 等单位）
`maxRecords`	int	`10000`	全局录制条数上限，超出自动淘汰最旧记录
`maxCaptures`	int	`200`	抓包记录保留上限，超出自动淘汰最旧已完成记录
`breakpointTimeout`	int	`30`	断点请求超时自动放行时间（秒），避免请求永久挂起
`maxIdleConns`	int	`100`	下游连接池全局空闲连接上限
`maxIdleConnsPerHost`	int	`10`	每下游主机空闲连接上限
`idleConnTimeout`	int	`90`	连接池空闲连接回收时间（秒）
`tlsHandshakeTimeout`	int	`10`	下游 TLS 握手超时（秒）
`dialTimeout`	int	`10`	下游 TCP 连接建立超时（秒）
`responseHeaderTimeout`	int	`0`	等待下游响应头超时（秒），`0` 表示不限制

ByteSize 单位

支持 B / K / KB / KiB / M / MB / MiB / G / GB / GiB / T / TB / TiB（大小写不敏感，1024 进制），也可直接写纯数字字节数。

masking — 抓包敏感数据脱敏

proxy.masking 控制抓包 / 断点记录入库前的敏感数据脱敏（默认关闭）。完整说明见抓包与断点 · 敏感数据脱敏。

参数	类型	默认值	说明
`enabled`	bool	`false`	总开关：是否对抓包 / 断点中的敏感数据打码后入库
`builtinFields`	string[]	`[]`	内置敏感字段名启用清单；为空启用全部，配置后仅启用列出的（authorization / token / phone 等）
`builtinPatterns`	string[]	`[]`	内置敏感值正则启用清单；为空启用全部，配置后仅启用列出的（phone / idcard / bankcard / email）
`headerFields`	string[]	`[]`	追加的敏感 Header / Query 字段名，始终生效
`valuePatterns`	string[]	`[]`	追加的敏感值正则，命中内容替换为 `******`，始终生效

yaml

proxy:
  masking:
    enabled: true
    headerFields:
      - X-Api-Key
    valuePatterns:
      - \bCUST-\d{6}\b
    builtinFields: []
    builtinPatterns: []

🔌 tcp — TCP 代理

顶层参数

参数	类型	默认值	说明
`enabled`	bool	`false`	是否启用 TCP 代理
`maxMessageSize`	ByteSize	`4M`	单条消息上限，超限断开连接
`maxRecords`	int	`10000`	TCP 录制条数上限，超出自动淘汰最旧记录
`idleTimeout`	int	`300`	空闲连接超时（秒），`0` 表示不限制
`listeners`	array	`[]`	TCP 监听器列表
`codecs`	array	`[]`	自定义协议编解码器列表（后台可管理）

listeners — 监听器

yaml

listeners:
    - name: redis-demo            # 监听器名称（唯一，规则引用依据）
      port: 16379                 # 监听端口
      upstreamHost: 127.0.0.1     # 上游主机
      upstreamPort: 6379          # 上游端口
      tls:                        # 上游 TLS 配置
        enabled: false
        skipVerify: false
      protocol:                   # 协议分帧与解析配置
        type: redis               # 见下表
        delimiter: ""
        maxDelimiterScan: 0
        lengthBytes: 4
        lengthEndian: big
        lengthIncludesSelf: false
        lengthOffset: 0
        bodyOffset: 4
        fixedLength: 0
        codecName: ""
        parseFields: []

protocol.type 分帧类型

类型	说明
`raw`	透传，不做分帧
`delimiter`	按分隔符分帧（如 `\n`、`\r\n`、`\x00`）
`lengthPrefix`	长度前缀分帧（如 4 字节大端长度 + body）
`fixedLength`	固定长度分帧
`redis`	Redis RESP 协议，自动解析命令与响应
`mysql`	MySQL 协议，自动解析 COM 命令 / OK / ERR / 结果集
`mqtt`	MQTT 协议，自动解析 CONNECT / PUBLISH / SUBSCRIBE / PINGREQ 等
`websocket`	WebSocket，自动处理 HTTP Upgrade 握手与数据帧（去掩码）
`grpc`	gRPC over HTTP/2，解析前奏 + HTTP/2 帧 + HPACK 头 + gRPC 消息
`custom`	引用 `codecs` 表中的命名 Codec（通过 `codecName`）

protocol 参数

参数	默认值	说明
`delimiter`	`""`	分隔符分帧的分隔符，支持 `\r` `\n` `\x00` 等转义
`maxDelimiterScan`	`0`	分隔符最长扫描字节，`0` 表示不限制
`lengthBytes`	`4`	长度前缀字节数（1 / 2 / 4 / 8）
`lengthEndian`	`big`	长度字段字节序：`big` / `little`
`lengthIncludesSelf`	`false`	长度值是否包含长度字段自身
`lengthOffset`	`0`	长度字段起始偏移
`bodyOffset`	`lengthBytes`	body 起始偏移（默认等于长度字段字节数）
`fixedLength`	`0`	固定长度分帧的每条消息字节数
`codecName`	`""`	`custom` 类型时引用的 Codec 名称
`parseFields`	`[]`	声明式字段提取配置（见下）

parseFields — 声明式字段提取

yaml

parseFields:
    - name: cmd          # 字段名（规则匹配 / 模板渲染使用）
      offset: 0          # 定长截取：起始偏移
      length: 0          # 定长截取：字节数（<=0 表示截取到消息末尾）
      encoding: utf8     # utf8 / hex，默认 utf8
      json: false        # 整体 JSON 平铺（点号分隔键，如 user.name）
      jsonPath: ""       # JSON 提取单个字段路径（如 a.b.0）
      regex: ""          # 正则提取
      group: 0           # 正则捕获组下标（0 表示整条匹配）
      split: ""          # 按分隔符拆分后取指定段
      index: 0           # 拆分后取第几段

codecs — 自定义协议编解码器

命名 Codec 由 name + protocol 组成，监听器 type=custom 且 codecName 引用表中名称。可在管理后台「协议 Codec」页增删改查，保存后立即生效。

yaml

codecs:
    - name: line-cmd                 # 命名 Codec 名称
      protocol:                      # 结构同监听器的 protocol
        type: delimiter
        delimiter: "\n"
        maxDelimiterScan: 1024
        lengthBytes: 4
        lengthEndian: big
        lengthIncludesSelf: false
        lengthOffset: 0
        bodyOffset: 4
        fixedLength: 0
        codecName: ""
        parseFields:
            - name: cmd
              split: ' '
              index: 0
            - name: body
              json: true

📡 udp — UDP 代理

yaml

udp:
    enabled: true          # 是否启用 UDP 代理
    maxMessageSize: 4M     # 单条报文上限，超限丢弃
    maxRecords: 10000      # UDP 录制条数上限，超出自动淘汰最旧记录
    idleTimeout: 300       # 会话空闲超时（秒），0 表示不限制
    listeners:             # UDP 监听器（结构同 TCP，protocol.type 支持 coap）
        - name: coap-demo
          port: 5683
          upstreamHost: 127.0.0.1
          upstreamPort: 5684
          tls:
            enabled: false
            skipVerify: false
          protocol:
            type: coap               # RFC 7252 CoAP 协议
            delimiter: ""
            maxDelimiterScan: 0
            lengthBytes: 4
            lengthEndian: big
            lengthIncludesSelf: false
            lengthOffset: 0
            bodyOffset: 4
            fixedLength: 0
            codecName: ""
            parseFields: []

UDP 代理为每个客户端地址建立一个虚拟会话（UDP 无连接语义），规则 / 录制 / 抓包与 TCP 共用表结构，按监听器归属自动隔离（见 UDP 规则）。

☁️ nacos — Nacos 注册（可选）

HTTP 代理端启动后可自动把本实例注册到 Nacos，供下游按服务名发现与直连。注册端口默认取代理端端口 proxy.port（也可用 nacos.port 覆盖）；默认按服务管理中所有启用服务的注册名逐个注册（nacosServiceName 留空时用服务名），也可用 serviceName 固定注册单个服务。

注册开关、注册信息、注销本实例，以及同服务实例的查看 / 下线 / 上线等操作在管理后台「Nacos 注册」页完成，详见 Nacos 注册与实例管理。

参数	类型	默认值	说明
`enabled`	bool	`false`	是否启用注册（开关）
`serverAddr`	string	`127.0.0.1:8848`	Nacos 服务端地址，支持逗号分隔多地址，如 `127.0.0.1:8848,127.0.0.2:8848`
`namespaceId`	string	`""`	命名空间 ID，`public` 留空
`group`	string	`DEFAULT_GROUP`	分组
`serviceName`	string	`""`	可选，固定注册单个服务名；留空按服务管理中启用的服务注册
`username`	string	`""`	Nacos 账号（服务端开启鉴权时必填），留空表示不启用鉴权
`password`	string	`""`	Nacos 密码
`ip`	string	`""`	注册 IP，默认自动探测本机局域网 IP
`port`	int	`0`	注册端口，默认取代理端端口（`proxy.port`）
`weight`	float	`100`	注册权重
`clusterName`	string	`DEFAULT`	集群名
`ephemeral`	bool	`true`	临时实例（心跳保活）
`autoOfflineOthers`	bool	`true`	自动下线同服务其他实例（独占服务），注册后持续监视并下线新上线的其他实例
`metadata`	map	`{}`	附加元数据
`beatIntervalMs`	int	`5000`	心跳间隔（毫秒）

📝 log — 日志

日志写入 logs/ 目录文件（参考 wueasy 系列服务，按大小与天数自动滚动）。

参数	类型	默认值	说明
`level`	string	`info`	日志级别：`debug` / `info` / `warn` / `error`
`maxSize`	int	`100`	单个日志文件大小上限（MB）
`maxBackups`	int	`7`	保留的旧日志文件数量
`maxAge`	int	`30`	日志保留天数
`async`	bool	`false`	是否异步写日志

📋 tcpRules — TCP / UDP 规则表

TCP 与 UDP 共用此规则表，规则通过 listeners 字段限定作用范围。

yaml

tcpRules:
    - id: 1
      name: redis-set-mock       # 规则名称
      enabled: true              # 是否启用
      priority: 1                # 优先级，数值越小越优先
      direction: request         # request / response；空表示双向
      listeners:                 # 应用到的监听器；空 = 应用到所有监听器
        - redis-demo
      match: []                  # 匹配条件（解析字段）
      action:                    # 命中后动作
        type: proxy              # proxy / mock / drop
        delayMs: 0               # 模拟延迟（毫秒）
        mock:
            data: "+OK\r\n"      # mock 响应内容（支持模板）
        record: false            # 是否录制
        close: false             # drop 时是否直接关闭连接

match — 匹配条件

match 为 TcpMatchItem 列表，多个条件同时满足才命中：

yaml

match:
    - field: cmd            # 解析字段名（来自 parseFields）
      op: eq                # 见下表
      value: "SET"

op	说明
`eq`	等于
`ne`	不等于
`contains`	包含
`prefix`	前缀匹配
`suffix`	后缀匹配
`regex`	正则匹配
`exists`	字段是否存在

action.type — 动作

类型	说明
`proxy`	透传到上游（可同时录制）
`mock`	返回 mock 数据（支持模板，如 `{{ .fields.xxx }}`、`{{ .session.id }}`）
`drop`	丢弃该消息（`close: true` 时直接关闭连接）

🛠️ services — HTTP 服务与规则

服务是下游系统分组，规则挂在服务下。

yaml

services:
    - id: 1
      name: 示例服务              # 服务名称
      description: 演示用下游服务
      upstreamUrl: http://127.0.0.1:9001   # 上游地址（proxy 透传 / passthrough 兜底使用）
      enabled: true
      rules:
        - id: 1
          name: 获取用户           # 规则名称
          methods:                # 请求方法；空/ANY 表示匹配所有
            - GET
          paths:                  # 可配置多个接口地址（支持 :id 路径参数）
            - /api/user/:id
            - /api/user/list
          matchHeaders: []        # 请求头匹配条件
          matchQuery: []          # query 匹配条件
          matchBody: []           # 请求体匹配条件（JSON/form 字段，点号路径）
          mode: mock              # mock / proxy / replay
          record: false           # proxy 模式下是否录制请求/响应
          responseStatus: 200     # mock 响应状态码
          responseHeaders:        # mock 响应头（支持模板）
            - name: Content-Type
              value: application/json
          responseBody: '{"id":1,"name":"demo"}'   # mock 响应体（支持模板）
          delayMs: 0              # 模拟延迟（毫秒）
          priority: 1             # 越小越优先
          enabled: true

匹配条件格式

matchHeaders / matchQuery / matchBody 均为 {name, value} 列表，同一条件内多组同时满足：

yaml

matchHeaders:
    - name: X-Token
      value: "abc123"
matchQuery:
    - name: type
      value: "user"
matchBody:
    - name: user.name      # JSON 点号路径
      value: tom
    - name: list.0.id      # 数组下标
      value: "10"

mode — 响应模式

模式	说明
`mock`	直接返回 `responseStatus` / `responseHeaders` / `responseBody`
`proxy`	透传到 `upstreamUrl`（`record: true` 时录制请求与响应）
`replay`	重放历史上录制的真实响应

♻️ 配置热加载

管理后台提供「重新加载配置」功能（POST /api/config/reload），重新读取 config.yaml 并热生效，无需重启进程。TCP / UDP 监听器、Codec 的新增 / 修改 / 删除保存后立即生效。

🔧 配置详解 ​

🌐 server — 管理端 ​

🔄 proxy — HTTP 代理端 ​

masking — 抓包敏感数据脱敏 ​

🔌 tcp — TCP 代理 ​

顶层参数 ​

listeners — 监听器 ​

protocol.type 分帧类型 ​

protocol 参数 ​

parseFields — 声明式字段提取 ​

codecs — 自定义协议编解码器 ​

📡 udp — UDP 代理 ​

☁️ nacos — Nacos 注册（可选） ​

📝 log — 日志 ​

📋 tcpRules — TCP / UDP 规则表 ​

match — 匹配条件 ​

action.type — 动作 ​

🛠️ services — HTTP 服务与规则 ​

匹配条件格式 ​

mode — 响应模式 ​

♻️ 配置热加载 ​

🔧 配置详解

🌐 server — 管理端

🔄 proxy — HTTP 代理端

masking — 抓包敏感数据脱敏

🔌 tcp — TCP 代理

顶层参数

listeners — 监听器

protocol.type 分帧类型

protocol 参数

parseFields — 声明式字段提取

codecs — 自定义协议编解码器

📡 udp — UDP 代理

☁️ nacos — Nacos 注册（可选）

📝 log — 日志

📋 tcpRules — TCP / UDP 规则表

match — 匹配条件

action.type — 动作

🛠️ services — HTTP 服务与规则

匹配条件格式

mode — 响应模式

♻️ 配置热加载