TinyPortMapper：轻量级高性能端口映射工具全指南

一、核心特性解析

1. 跨协议全支持：TCP/UDP双栈转发能力

TinyPortMapper支持TCP与UDP协议的端口映射，可同时处理两种协议的转发请求。应用场景：在物联网网关中，可同时转发设备的TCP控制指令和UDP实时数据流，如智能家居系统中摄像头的UDP视频流与TCP控制信号的并行转发。核心实现位于common.h中的tcp_pair_t和udp_pair_t结构体定义。

2. 双引擎架构：epoll/libev灵活切换

提供Linux原生epoll和libev两种I/O模型支持。epoll（Linux系统下的高效I/O事件通知机制）适用于高并发场景，libev则提供跨平台兼容性。应用场景：服务器环境优先选择epoll获得最佳性能，嵌入式系统可选用libev适配更多操作系统。两种引擎的封装实现在my_ev.h的事件循环模块。

3. 极致轻量设计：低资源占用运行

整个工具核心代码不足5000行，内存占用低于1MB，CPU使用率可低至0.1%。应用场景：在树莓派等嵌入式设备上，可长期运行作为边缘节点的端口转发服务，不影响主业务运行。资源管理通过fd_manager.h中的fd_manager_t结构体实现文件描述符的高效复用。

二、快速上手流程

1. 环境检测三步法

📌 第一步：检查编译环境

gcc --version && make --version

确保GCC版本≥4.8，Make工具正常安装

📌 第二步：验证系统支持

grep -q EPOLL_SUPPORT /proc/version && echo "epoll supported"

确认系统支持epoll（Linux 2.6+）

📌 第三步：克隆项目代码

git clone https://gitcode.com/gh_mirrors/tin/tinyPortMapper
cd tinyPortMapper

2. 编译选项智能选择

📌 基础编译（默认epoll模式）

make

生成可执行文件tinymapper_amd64

📌 libev模式编译

make USE_LIBEV=1

启用libev引擎支持，需先安装libev开发库

📌 交叉编译嵌入式版本

make CROSS_COMPILE=arm-linux-gnueabihf-

生成ARM架构可执行文件

3. 基础命令实战示例

📌 TCP端口转发

./tinymapper_amd64 -l0.0.0.0:8080 -r192.168.1.100:80 -t

将本地8080端口TCP流量转发到192.168.1.100的80端口

📌 UDP端口转发

./tinymapper_amd64 -l0.0.0.0:5353 -r8.8.8.8:53 -u

将本地5353端口UDP流量转发到8.8.8.8的DNS端口

📌 双协议同时转发

./tinymapper_amd64 -l0.0.0.0:10000 -r10.0.0.1:20000 -t -u

同时转发TCP和UDP协议流量

三、高级配置指南

1. epoll vs libev模式对比

特性	epoll模式	libev模式	适用场景
性能	高（原生系统调用）	中（跨平台抽象层）	高性能服务器
兼容性	仅限Linux	Linux/BSD/macOS	跨平台部署
资源占用	极低	低	嵌入式设备
事件类型	支持边缘/水平触发	丰富的事件类型	复杂事件处理

2. 五大性能调优参数

📌 socket缓冲区大小

--sock-buf 4096

设置为4096kbyte（默认1024），提升大文件传输性能，定义在common.h的socket_buffer_size常量

📌 日志级别控制

--log-level 3

级别3（警告）平衡调试需求与性能损耗，日志系统实现位于log.cpp

📌 连接超时设置

--timeout 300

5分钟无活动自动断开，避免僵尸连接，超时逻辑在tcp_pair_t结构体处理

📌 并发连接数限制

--max-conns 1024

根据服务器配置调整，默认512，定义在fd_manager.h的MAX_FD_COUNT

📌 事件循环优先级

--ev-priority 1

调整事件处理优先级，高优先级适用于低延迟场景，实现在my_ev.cpp的事件调度模块

四、常见问题排查

1. 启动失败：地址已被占用

错误现象：bind: Address already in use
解决方案：

• 使用netstat -tulpn | grep 端口号查找占用进程
• 添加--reuse-port参数允许端口复用
• 修改-l参数指定其他空闲端口

2. 转发延迟高

错误现象：客户端连接卡顿
排查步骤：

1. 检查--sock-buf是否设置过小
2. 使用--log-level 5开启详细日志
3. 通过top命令确认CPU占用是否过高
4. 尝试切换epoll/libev模式对比性能

3. UDP转发丢包

错误现象：UDP数据包丢失
优化方案：

• 增大--sock-buf缓冲区至2048以上
• 检查网络MTU值，添加--mtu 1400调整
• 在udp_pair_t实现中增加重传机制（需修改源码）

五、命令行参数速查表

参数	类型	说明	默认值
-l	字符串	本地监听地址:端口	无
-r	字符串	远程目标地址:端口	无
-t	标志	启用TCP转发	禁用
-u	标志	启用UDP转发	禁用
--sock-buf	数字	socket缓冲区大小(kb)	1024
--log-level	0-6	日志级别(0=无,6=跟踪)	3
--log-position	标志	日志显示文件名和行号	禁用
--disable-color	标志	禁用彩色日志	启用
--timeout	数字	连接超时秒数	300
--max-conns	数字	最大并发连接数	512
--reuse-port	标志	允许端口复用	禁用
-h	标志	显示帮助信息	-

通过上述指南，您可以充分利用TinyPortMapper的轻量级特性和高性能优势，快速部署稳定可靠的端口映射服务。无论是家庭网络穿透还是企业级转发需求，这款工具都能提供高效且资源友好的解决方案。