找回密码
立即注册
搜索
发回帖 发新帖

6988

积分

0

好友

847

主题
发表于 8 小时前 | 查看: 3| 回复: 0

tcpfwd 是一个零第三方依赖的 Go 程序:它监听本地端口,为每个接入连接拨号目标地址并进行双向透传。与常规端口转发工具不同,tcpfwd 可以通过 Web 页面配置转发规则和过滤内容,按规则过滤指定报文。

过滤规则支持两种模式:

模式 判据 报文边界来源
① 包含指定数据 contains 帧内包含指定的 HEX / ASCII 片段时,丢弃整帧 「报文分帧」配置
② 根据帧头帧尾过滤 envelope 识别出的完整报文一律整帧丢弃 过滤规则中填写的帧头帧尾

使用帧头帧尾界定报文时,帧头之前、帧尾之后的其他数据会立即原样透传,不参与过滤,也不等待。

前端页面已通过 embed 打包进二进制。部署时只需要一个可执行文件和一个 config.json,可用于内网离线环境。

码云项目地址:https://gitee.com/fensnote/tcp-port-forwarding

快速开始

cd tcpfwd
go build -o tcpfwd.exe .
tcpfwd.exe -config config.json -web :8080

浏览器打开 http://localhost:8080。启动参数如下:

参数 说明 默认值
-config 配置文件路径;文件不存在时自动生成空白示例配置 config.json
-web 覆盖配置中的管理页面地址 配置文件中的 web.addr

生成的 config.json 只有一条默认禁用的空示例规则。分帧区的帧头、帧尾和过滤内容均为空,不预置具体报文。使用时按现场协议填写目标地址、过滤模式和内容,再启用规则并点击「保存并应用」,无需重启进程。

从 v1.2.0 起,连接建立后即使不发送数据,也不会因空闲被断开。旧版存在空闲 10 秒被误踢的问题;半关闭后的可选兜底设置见下文。

关键设计:先分帧,再丢弃完整报文

TCP 是字节流,没有天然的报文边界。要在报文命中时丢弃完整的一帧,必须先定义帧边界:一次 Read 可能只读到半帧,也可能读到两帧半。

tcpfwd 支持以下分帧方式:

模式 成帧判据 适用场景
idle 静默间隔(默认) 连续 idle_ms 无新数据,即认为一帧结束 Modbus RTU、无显式帧界的私有协议
delimiter 分隔符 出现指定分隔符即成帧 以 0D 0A、16 5A 等结尾的协议
fixed 固定长度 每 fixed_len 字节为一帧 定长帧协议
envelope 帧头加帧尾 从 start 开始到 end 结束,才算完整报文 有明确帧头帧尾,且需要按内容过滤的协议
raw 纯透传 不分帧 不启用过滤规则时,使用 io.Copy 快路径

有效分帧优先级:只要某条转发规则中存在启用的模式②「根据帧头帧尾过滤」,程序就会使用该过滤规则的帧头帧尾切分报文,覆盖分帧区的配置。

因此,使用模式②时,分帧区可以保持默认 idle,帧头帧尾留空,无需重复填写。即使分帧区显式选择了 envelope,仍以过滤规则中的帧头帧尾为准,页面会给出提示。

实现细节:

  • 读超时只用于触发「静默成一帧」或「等不到帧尾」,不意味着断开连接。
  • 帧头、帧尾被 TCP 拆到多个 Read 时,可以正确拼合。搜索态遇到读超时不会刷出半个帧头,避免漏识别下一帧。
  • 一端关闭时,先刷出残余数据,再通过 CloseWrite 优雅半关闭,避免丢尾包。
  • 某个方向没有启用过滤规则时,自动使用 io.Copy 快路径。

空闲长连接与半关闭(v1.2.0)

只要两个方向都还连着,无论多久不发数据,程序都不会因空闲断开连接。TCP 长连接空闲是正常状态;idle_ms 只用于分帧,与连接生命周期无关。

早期版本在会话建立后就启动 10 秒「半关闭等待」计时,到点便关闭两条连接。因此,调试助手连接后若一直不发数据,可能恰好在 10 秒时被踢掉,日志出现 半关闭等待超时,强制断开。v1.2.0 改为两阶段等待:

阶段 条件 行为
双向都活着 两个方向的转发都还在运行 无限期等待,不启动计时器
一侧已结束 收到对端 FIN 或读出错,进入半关闭 此时才启动 half_close_timeout_ms 兜底计时

half_close_timeout_ms 是每条转发规则独立配置的字段,位于页面「规则编辑」的基本信息中,与拨号超时并列。

值 行为
0(默认,推荐) 不限时,由两端决定何时关闭,适合设备长连接或心跳保活
> 0 半关闭后对端一直不关闭时,等待指定毫秒数后强制断开,以回收连接资源;建议填 30000 以上

旧配置文件没有该字段时按 0 处理,无需修改配置。只有真正发生半关闭且超时,日志才会出现 半关闭后对端 Nms 内未关闭,强制断开。

过滤规则的两种模式

模式①:包含指定数据

在「报文分帧」中界定报文边界,再在过滤规则中填写内容。帧内通过 bytes.Contains 命中时,整帧丢弃。

  • 适用于只丢弃包含某个字段或指令的报文,其余报文正常转发。
  • 有帧头帧尾时,建议选择 envelope 并填写 start / end;只有帧尾时可用 delimiter;依靠时间间隔区分帧时可用 idle。
  • 内容编码支持 hex 或 ascii。ASCII 支持 \r \n \t \0 \\ \xHH 转义,中文按 UTF-8 匹配;case_insensitive 仅对 ASCII 有效。

模式②:根据帧头帧尾过滤

在过滤规则中直接填写 start、end 和 mark_type。凡是识别出的完整报文,一律整帧丢弃,无需填写过滤内容。

  • 适用于整类报文都不需要、其他数据需要完整透传的场景。
  • 帧头帧尾可按 hex(如 AA BB CC)或 ascii(如 <HDR>)填写。
  • 帧头之前、帧尾之后的字节立即原样透传,即使其中恰好包含过滤片段也不会被丢弃。
  • 等待帧尾超过 idle_ms 时,按分帧区的「不完整帧处理」执行:pass 将半帧原样透传,不丢字节;drop 丢弃半帧。
  • 同一条转发规则中若有多条模式②规则,帧头帧尾必须一致,否则无法共用分帧依据,保存时会报错。
  • 模式①和模式②可以共存,但模式②会命中所有完整报文,此时模式①不会再有机会生效。

旧配置中的 encoding: "any" 继续兼容,其含义是丢弃任意完整报文,效果等价于模式②,但报文边界来自分帧区。

过滤规则字段

字段 说明
mode contains 表示包含指定数据;envelope 表示根据帧头帧尾过滤。旧配置缺少该字段时按 contains 处理
name / enable 规则名称、是否启用;关闭后规则不生效,但可保留备用
direction both 双向;up 上行,即客户端到设备;down 下行,即设备到客户端
encoding / pattern / case_insensitive 模式①专用:内容编码、报文的一部分、ASCII 忽略大小写
start / end / mark_type 模式②专用:帧起始标记、帧结束标记,以及两者的编码类型 hex / ascii

HEX 支持 AA BB、AABB、0xAA,0xBB、AA-BB 等写法。

页面下方的报文过滤测试器可以使用当前编辑中的配置试算,无需保存。粘贴帧外数据和多个完整报文后,可以查看每段被标记为「完整报文」还是「普通数据·直接透传」、是否丢弃,以及命中了哪条规则。顶部还会显示有效分帧模式及其是否由过滤规则接管,适合在上线前验证配置。

配置热重载语义

点击「保存并应用」后,程序会写入 config.json,通过临时文件加 rename 原子写入,然后重新计算所有规则:

  • 配置没变的规则保持监听,不断开连接。
  • 配置有变化的规则关闭旧监听并重新监听,新连接使用新配置。
  • 已建立的连接继续持有旧配置快照直到结束,不会被强行断开。
  • 某条规则的监听端口被占用时,只记录错误和日志,不影响其他规则生效。
  • 修改 web.addr 管理地址后,需要重启进程才会生效。

左侧「全局设置」可配置管理页面账号密码:留空则不认证;填写后启用 Basic Auth,连续 5 次失败会锁定该 IP 60 秒。

配置文件示例

模式②:分帧区保持默认,帧头帧尾写在过滤规则里。

{
  "web": {
    "addr": ":8080",
    "user": "",
    "pass": ""
  },
  "log_lines": 200,
  "rules": [
    {
      "id": "r10010",
      "name": "端口转发 + 帧头帧尾过滤",
      "enable": true,
      "listen": ":10010",
      "target": "192.168.1.123:10010",
      "dial_timeout_ms": 5000,
      "half_close_timeout_ms": 0,
      "framing": {
        "mode": "idle",
        "idle_ms": 200,
        "start": "",
        "end": "",
        "mark_type": "hex",
        "on_incomplete": "pass",
        "max_frame": 65536
      },
      "filters": [
        {
          "id": "f1",
          "name": "丢弃这类完整报文",
          "enable": true,
          "mode": "envelope",
          "start": "AA BB CC",
          "end": "CC DD EE",
          "mark_type": "hex",
          "direction": "both"
        }
      ]
    }
  ]
}

模式①:分帧区界定边界,过滤规则按内容匹配。以下为规则中的配置片段:

{
  "framing": {
    "mode": "envelope",
    "idle_ms": 200,
    "start": "AA BB CC",
    "end": "CC DD EE",
    "mark_type": "hex",
    "on_incomplete": "pass",
    "max_frame": 65536
  },
  "filters": [
    {
      "id": "f1",
      "name": "丢弃含指定字段的报文",
      "enable": true,
      "mode": "contains",
      "encoding": "hex",
      "pattern": "70 D8",
      "direction": "both",
      "case_insensitive": false
    }
  ]
}

HTTP API 与 Postman 分步自测

方法 路径 说明
GET / 配置页面
GET /api/state 当前配置、各规则状态和统计、最近日志
GET /api/logs?since=<id> 增量日志
POST /api/config 保存并应用配置,body 为完整 Config JSON
POST /api/test 报文过滤试算,不写入配置

自测步骤:

  1. 请求 GET http://localhost:8080/api/state,确认返回 config、status、logs。

  2. 请求 POST http://localhost:8080/api/test,Body 选择 raw / JSON。以下是模式②示例,帧头为 AA BB,帧尾为 CC DD:

    {
     "rule": {
       "id": "r1",
       "name": "t",
       "enable": true,
       "listen": ":10010",
       "target": "192.168.1.123:10010",
       "dial_timeout_ms": 5000,
       "framing": {
         "mode": "idle",
         "idle_ms": 200,
         "start": "",
         "end": "",
         "mark_type": "hex",
         "on_incomplete": "pass",
         "max_frame": 65536
       },
       "filters": [
         {
           "id": "f1",
           "name": "帧头帧尾全丢",
           "enable": true,
           "mode": "envelope",
           "start": "AA BB",
           "end": "CC DD",
           "mark_type": "hex",
           "direction": "both"
         }
       ]
     },
     "direction": "up",
     "encoding": "hex",
     "data": "01 02 AA BB 55 66 CC DD 09 08"
    }

    应返回 framing=envelope 和 configured_framing=idle,表示分帧已由过滤规则接管。数据分为三段:01 02 为普通数据,check=false;AA BB 55 66 CC DD 为完整报文,dropped=true;09 08 为普通数据,直接透传。

  3. 请求 POST http://localhost:8080/api/config,将第 1 步返回的 state.config 修改后完整提交,应返回 {"ok":true,"errors":[]}。

  4. 请求 GET /api/state,确认对应规则的 running=true。若为 false,查看 errors 和日志,端口被占用是常见原因。

  5. 用 TCP 调试助手连接 本机IP:10010:发送帧外杂散数据,应原样收到应答;发送 AA BB … CC DD 完整报文,应没有应答;随后发送不含帧头帧尾的数据,仍应能够通信。

  6. 请求 GET /api/logs?since=0,可查看类似 FILTER ... 丢弃整帧 N 字节 ... 命中[xxx(帧头帧尾)] HEX=... 的日志。

若页面启用了 Basic 认证,以上请求需要携带 Authorization: Basic ...,也可以在 curl 中使用 -u 用户:密码。

部署到设备:交叉编译

项目使用 Go 标准库,不依赖 cgo,可交叉编译为单个静态二进制:

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -o tcpfwd_arm7 .    # hi3536c / Cortex-A7
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=5 go build -o tcpfwd_arm9 .    # nuc980 / ARM926
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o tcpfwd_arm64 .         # ma35d1 等 64 位设备
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o tcpfwd_amd64 .         # x86 服务器

代码目录中也提供了 build.sh,用于编译不同平台的可执行文件。

将二进制文件和 config.json 放在同一目录后,可以使用 systemd 托管:

[Unit]
Description=TCP Forward with Frame Filter
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/tcpfwd
ExecStart=/opt/tcpfwd/tcpfwd_arm7 -config /opt/tcpfwd/config.json -web :8080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Windows 可使用计划任务或 nssm 注册服务。管理端口建议只对内网开放。

本机 Go 环境问题

一次编译中,E:\Go 是 Go 1.22.0,但 GOROOT 中混入了 Go 1.24+ 的 src/bytes/iter.go、src/strings/iter.go。这两个文件没有 build tag,却使用了 import "iter";同时,src/iter/iter.go 仍是 1.22 的实验版,导致引用 bytes 或 strings 的程序报错:

imports bytes
imports iter: build constraints exclude all Go files in E:\Go\src\iter

项目代码兼容 Go 1.22,使用的 embed、any 等分别是 1.16、1.18 起提供的特性。该环境随后使用干净的 E:\go-v1.26\go\bin\go.exe 编译通过。

可选择以下方式处理:

  • 直接使用 E:\go-v1.26\go\bin\go.exe 编译。
  • 或从 E:\go1.22.0.windows-amd64.zip 恢复干净的 Go 1.22 GOROOT。恢复前应移除或隔离旧的混杂目录,避免直接覆盖后残留多余文件。

文件清单与验证

文件 作用
main.go 入口、启动、优雅退出
config.go 配置结构、两种过滤模式校验、有效分帧计算、原子持久化
filter.go HEX / ASCII 解析、转义、包含匹配、两种模式编译
framer.go 五种分帧、envelope 状态机、拆包拼合、超长保护
forward.go 监听管理、双向转发、两阶段半关闭等待、热重载、统计和日志
web.go HTTP API、认证、报文试算
web/index.html 内嵌配置页面,过滤规则按模式动态展示
config.json 空白示例配置,不预置具体报文
*_test.go 单元测试和真实 TCP 端到端测试

运行测试:

go test ./... -v -count=1

测试覆盖了 HEX / ASCII 解析与转义、大小写、两种过滤模式、有效分帧接管(idle、raw、delimiter、fixed、envelope)、多组帧头帧尾冲突校验、默认配置无示例字节,以及五种分帧和拆包重组。

连接与转发方面,覆盖了帧头帧尾跨 Read 拼合、读超时不刷出半个帧头、两种半帧策略、超长保护、配置校验、真实 TCP 透传、帧外数据包含过滤片段时仍原样透传、完整报文整帧丢弃、过滤后连接存活、纯透传二进制无损、目标不可达和热重载不中断旧连接。

空闲与半关闭测试覆盖了零过滤快路径、过滤路径和 delimiter 下的空闲长连接,以及半关闭兜底超时、0 不限时和 half_close_timeout_ms 非法值校验。

另有启动编译后的 exe、调用 Web API 并使用真实 TCP 连接的链路验证:连接建立后空闲 12.5 秒仍可正常收发,期间无强制断开日志;还验证了半关闭 300ms 兜底和 0 不限时。该次验证全程无 ERROR,15 项全部通过。




上一篇:ESP32-C3 能跑 AI 吗?4MB 开发板算力实测
下一篇:HEX协议报文怎么解析?用AI辅助Modbus协议分析
您需要登录后才可以回帖 登录 | 立即注册

关闭

站长推荐上一条 /1 下一条

手机版|小黑屋|网站地图|云栈社区 ( 苏ICP备2022046150号-2 )

GMT+8, 2026-11-21 15:43 , Processed in 0.078296 second(s), 41 queries , Gzip On.

Powered by Discuz! X3.5

© 2025-2026 云栈社区.

快速回复 返回顶部 返回列表