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 |
报文过滤试算,不写入配置 |
自测步骤:
-
请求 GET http://localhost:8080/api/state,确认返回 config、status、logs。
-
请求 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 为普通数据,直接透传。
-
请求 POST http://localhost:8080/api/config,将第 1 步返回的 state.config 修改后完整提交,应返回 {"ok":true,"errors":[]}。
-
请求 GET /api/state,确认对应规则的 running=true。若为 false,查看 errors 和日志,端口被占用是常见原因。
-
用 TCP 调试助手连接 本机IP:10010:发送帧外杂散数据,应原样收到应答;发送 AA BB … CC DD 完整报文,应没有应答;随后发送不含帧头帧尾的数据,仍应能够通信。
-
请求 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 项全部通过。