# TCP端口转发 **Repository Path**: fensnote/tcp-port-forwarding ## Basic Information - **Project Name**: TCP端口转发 - **Description**: 零第三方依赖的 Go 程序:监听本地端口,每个接入连接拨号目标地址做双向透传;在 Web 页面配置转发规则和过滤内容。 - **Primary Language**: Go - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-11 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # tcpfwd — TCP 端口转发透传 + 报文过滤 零第三方依赖的 Go 程序:监听本地端口,每个接入连接拨号目标地址做双向透传;在 Web 页面配置转发规则和过滤内容。 过滤规则支持**两种模式**: | 模式 | 判据 | 报文边界来自 | | --- | --- | --- | | ① 包含指定数据 `contains` | 帧内包含所填 HEX / ASCII 片段 → 丢弃整帧 | 上方「报文分帧」配置 | | ② 根据帧头帧尾过滤 `envelope` | 凡是识别出的完整报文 → **一律整帧丢弃** | **过滤规则自己填写的帧头帧尾** | 两种模式下,帧头之前 / 帧尾之后的其它数据都**立即原样透传、不参与过滤、不等待**。 前端页面已用 `embed` 打包进二进制,部署时只需要一个 exe + 一个 config.json,内网离线环境可直接用。 --- ## 一、快速开始 ```bash cd tcpfwd go build -o tcpfwd.exe . tcpfwd.exe -config config.json -web :8080 ``` 浏览器打开 `http://localhost:8080`。启动参数: | 参数 | 说明 | 默认值 | | --- | --- | --- | | `-config` | 配置文件路径,不存在时自动生成空白示例 `config.json` | `config.json` | | `-web` | 覆盖配置里的管理页面地址 | 配置文件中的 `web.addr` | `config.json` 只带一条**默认禁用**的空示例规则,分帧区帧头帧尾、过滤内容均为空,不预置任何具体报文。按现场协议自行填写:目标地址 → 过滤规则模式与内容 → 启用 →「保存并应用」,不用重启进程。 > **v1.2.0 起**:连上后不发数据也不会被断开(旧版空闲 10 秒会被误踢)。半关闭后的可选兜底见第二节「空闲长连接与半关闭」。 > > **v1.3.0 起**:`envelope` 严格按「帧头+内容+帧尾」切帧,帧尾后数据独立透传;前一报文缺帧尾时不再吞并后续报文,详见第二节「严格报文边界与粘包」。**升级必须替换 `tcpfwd.exe` 并重启进程**,启动时横幅会打印 `v1.3.0`,`/api/state` 的 `version` 字段也可核对。 --- ## 二、关键设计:先分帧,才能「丢弃完整报文」 TCP 是**字节流**,没有天然报文边界。要做到「报文命中就丢掉完整一帧」,必须先定义什么算一帧,否则一次 `Read` 读到的可能只是半帧或两帧半。分帧方式可配置: | 模式 | 成帧判据 | 适用场景 | | --- | --- | --- | | `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.3.0) **丢弃单位永远是「帧头 + 内容 + 帧尾」这一段,帧尾之后再跟的数据一律独立透传、不参与过滤。** `envelope` 状态机在**第一个帧尾**处立即切帧,帧尾后的字节作为 `check=false` 段写出。因此以下常见粘包都不会误伤: | 输入形态 | 结果 | | --- | --- | | `帧外 + 报文 + 帧外` | 只丢中间的报文,两段帧外数据原样透传 | | `报文1 + 报文2` | 切成两帧分别判定,互不影响 | | `报文 + 帧尾后裸数据` | 只丢报文,裸数据立即透传 | **v1.3.0 修复的缺陷**:如果前一个报文**缺帧尾**(线路丢字节、设备截断、报文被 TCP 拆包且包间隔超过 `idle_ms` 被判半帧),旧版帧内状态会一直往后吞,直到找到下一个帧尾才收工,于是把「残缺报文 + 后面的完整报文 + 帧尾后的有效数据」拼成**一个超大帧整段丢掉** —— 表现就是「不该丢的数据偶尔也被丢了」,日志里出现长度异常的大帧(现场曾看到 249 / 245 字节帧)。 现在帧内若在帧尾之前又检测到**新的帧头**,即判定上一个报文不完整:前半按 `on_incomplete` 单独处理(`pass` 原样透传 / `drop` 只丢这半帧),从新帧头重新开始识别,后续报文与帧外数据不再被吞并。检测同样适用于帧头跨多个 `Read` 到达的情况。 配套可观测性: - 丢弃日志的 HEX 预览同时给出**开头 48 字节 + 结尾 12 字节 + 总长度**,可直接看出这一帧是否严格以帧尾结束、有没有夹带多余数据; - 发生拆分或等不到帧尾时写 `WARN` 日志:`检测到报文内嵌帧头…` / `等不到帧尾或帧体超长…`,现场据此判断报文是否被截断; - 若频繁出现 `等不到帧尾`,把 `idle_ms` 调大(大于报文被 TCP 拆包的最大间隔),必要时调大 `max_frame` 以容纳最长报文。 唯一边界:帧外数据**末尾若恰好是一个不完整的帧头前缀**(例如只收到 `3C`、`3C 42`),这几个字节会暂留到下一次数据到达再透传,以免把随后补齐的帧头拆散导致漏识别;它不会被丢弃。 ### 空闲长连接与半关闭(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`(支持 `\r \n \t \0 \\ \xHH` 转义,中文按 UTF-8 匹配),`case_insensitive` 仅 ASCII 有效。 ### 模式② 根据帧头帧尾过滤 在过滤规则里直接填写 `start` / `end` / `mark_type`,**凡是识别出的完整报文一律整帧丢弃**,不需要填过滤内容。 - 适合:某类报文整体不要,其它数据完整透传; - 帧头帧尾可按 `hex`(如 `AA BB CC`)或 `ascii`(如 ``)填写; - 帧头之前、帧尾之后的字节立即原样透传,即使里面恰好也含过滤片段也不会被丢; - 等不到帧尾超过 `idle_ms` 时按分帧区的「不完整帧处理」执行:`pass` 半帧原样透传(不丢字节)、`drop` 丢弃半帧; - 同一条转发规则里若有多条模式②规则,帧头帧尾必须一致(否则无法共用一套分帧依据,保存时会报错); - 模式① 与模式② 可以共存,但模式② 恒命中所有完整报文,此时模式① 不会再有机会生效。 > 旧配置里的 `encoding: "any"`(任意完整报文全丢)继续兼容,等价于模式②,但边界来自分帧区。 > ⚠️ **语义提醒**:模式②是「凡是 `<帧头>…<帧尾>` 一律丢」。如果日志里看到不同命令码的报文(心跳、读响应、批量数据上报)统统被丢,这不是粘包误判,而是该模式的**预期行为**;只想丢其中一类请改用模式①,把 `pattern` 填成那一类报文独有的字段。先确认这个语义,再排查粘包问题。 --- ## 四、过滤规则字段 | 字段 | 说明 | | --- | --- | | `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 秒。 --- ## 六、配置文件示例 模式②(分帧区保持默认、帧头帧尾写在过滤规则里): ```json { "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" } ] } ] } ``` 模式①(分帧区界定边界,过滤规则按内容匹配): ```json { "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=` | 增量日志 | | 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`): ```json { "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`,表示已由过滤规则接管)与 3 段:第 1 段 `01 02` 为**普通数据**、`check=false`;第 2 段 `AA BB 55 66 CC DD` 为完整报文、`dropped=true`;第 3 段 `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 用户:密码`)。 --- ## 八、部署到设备(交叉编译) 纯标准库、无 cgo,直接交叉编译出单个静态二进制: ```bash 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 服务器 ``` 把二进制和 `config.json` 放同一目录,用 systemd 托管: ```ini [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` 重新解压覆盖 `E:\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 端到端测试 | ```bash go test ./... -v -count=1 ``` 已覆盖:HEX/ASCII 解析与转义、大小写、两种过滤模式、有效分帧接管(idle/raw/delimiter/fixed/envelope 全覆盖)、多组帧头帧尾冲突校验、默认配置无示例字节、五种分帧与拆包重组、帧头/帧尾跨 Read 拼合、读超时不刷出半个帧头、半帧两种策略、超长保护、配置校验、真实 TCP 透传、**帧外数据含过滤片段仍原样透传**、完整报文整帧丢弃、过滤后连接存活、纯透传二进制无损、目标不可达、热重载不中断旧连接、**空闲长连接不被断开(零过滤快路径 / 过滤路径 / delimiter)**、半关闭兜底超时、`0` 不限时、`half_close_timeout_ms` 非法值校验、**envelope 严格边界(帧尾后数据独立透传 / 多报文粘连 / 内嵌帧头拆分 / 跨 Read 拆分 / 分帧告警 / 日志首尾 HEX 预览)**、真实 TCP 粘包「残缺帧 + 完整报文 + 帧尾后数据」不误丢。 另有真实链路验证(启动编译好的 exe + Web API + 真实 TCP 连接):v1.2.0 验证空闲 12.5 秒仍可收发、半关闭 300ms 兜底;v1.3.0 验证版本号、帧尾后数据透传、残缺帧不吞并后续数据、长帧日志首尾可见、内嵌帧头告警、丢弃统计、连接存活,15 项全部通过。