TinyPortMapper：轻量级高性能端口转发工具技术指南

功能特性

轻量级架构设计

TinyPortMapper采用精简代码结构，核心功能模块（common、fd_manager、log、my_ev）总代码量不足5000行，内存占用低于1MB。通过单线程事件驱动模型消除多线程上下文切换开销，在嵌入式设备与云服务器环境中均能保持高效运行。

跨协议与跨网络支持

• 双协议转发：同时支持TCP流传输与UDP数据报转发，满足不同应用场景需求
• 双栈网络兼容：原生支持IPv4/IPv6地址解析与转换，可在混合网络环境中无缝工作
• 无状态设计：UDP转发采用LRU连接管理机制，自动清理闲置连接（默认超时时间300秒）

高性能设计

// main.cpp 中事件循环核心实现
struct ev_loop * loop= ev_default_loop(0);
ev_io_init(&tcp_accept_watcher, tcp_accept_cb, local_listen_fd_tcp, EV_READ);
ev_io_start(loop, &tcp_accept_watcher);
ev_run(loop, 0);

技术原理卡片：基于libev的I/O多路复用 TinyPortMapper使用libev库实现高效事件驱动，通过epoll/kqueue等系统调用实现I/O多路复用。每个网络事件（连接建立/数据接收）通过回调函数处理，避免传统select/poll的性能瓶颈，单机可支持10K+并发连接。

快速上手

环境准备

1. 源码获取

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

2. 编译构建

make
# 生成可执行文件 tinymapper_amd64

基础命令

参数	说明	示例
-l	本地监听地址:端口	-l 0.0.0.0:8080
-r	远程目标地址:端口	-r 192.168.1.100:80
-t	启用TCP转发	-t
-u	启用UDP转发	-u
--sock-buf	设置缓冲区大小(kB)	--sock-buf 2048
--log-level	设置日志级别(0-6)	--log-level 5

基础转发示例：

# TCP转发：本地8080端口 → 远程192.168.1.100:80
./tinymapper_amd64 -l 0.0.0.0:8080 -r 192.168.1.100:80 -t

# UDP转发：本地53端口 → 远程8.8.8.8:53
./tinymapper_amd64 -l 0.0.0.0:53 -r 8.8.8.8:53 -u

验证方法

1. 进程状态检查

# 检查进程是否运行
ps aux | grep tinymapper_amd64

# 查看监听端口
netstat -tulpn | grep tinymapper

2. 功能验证

# TCP验证（需另开终端）
telnet localhost 8080

# UDP验证（需另开终端）
echo "test" | nc -u localhost 53

进阶配置

场景化配置方案

场景一：内外网穿透

需求：将内网Web服务（192.168.1.10:80）通过公网服务器（203.0.113.5）暴露到公网端口8080

实现步骤：

1. 在公网服务器部署转发

./tinymapper_amd64 -l 0.0.0.0:8080 -r 192.168.1.10:80 -t --sock-buf 4096

2. 配置防火墙规则

# 开放8080端口
ufw allow 8080/tcp

3. 客户端访问测试

curl http://203.0.113.5:8080

场景二：游戏服务器加速

需求：降低UDP游戏流量延迟，设置较大缓冲区减少丢包

优化配置：

./tinymapper_amd64 -l 0.0.0.0:27015 -r game-server:27015 -u \
  --sock-buf 8192 \
  --log-level 3

性能调优建议

缓冲区配置

• 理论依据：缓冲区大小应根据网络带宽×延迟乘积设置（带宽延迟积BDP）
• 计算公式：缓冲区大小(kB) = (带宽Mbps × 延迟ms) / 8
• 推荐值：
  • 局域网环境：512-1024 kB
  • 广域网环境：2048-4096 kB
  • 高延迟链路：8192-16384 kB

日志策略

日志级别	适用场景	性能影响
0 (never)	生产环境	无
4 (info)	日常监控	低
5 (debug)	问题诊断	中
6 (trace)	开发调试	高

生产环境配置：

./tinymapper_amd64 -l 0.0.0.0:80 -r backend:80 -t \
  --log-level 1 \
  --disable-color

常见问题诊断

问题一：无法绑定端口

排查流程：

1. 检查端口占用情况

netstat -tulpn | grep 8080

2. 确认权限是否足够（1024以下端口需root权限）

# 非root用户使用高位端口（如8080）或添加CAP_NET_BIND_SERVICE能力
sudo setcap 'cap_net_bind_service=+ep' ./tinymapper_amd64

问题二：转发速度慢

排查流程：

1. 检查缓冲区配置是否合理

# 查看当前设置
grep "sock-buf" /proc/$(pidof tinymapper_amd64)/cmdline

2. 监控系统资源使用

# 检查CPU/内存占用
top -p $(pidof tinymapper_amd64)

# 检查网络吞吐量
iftop -i eth0

问题三：UDP转发丢包

排查流程：

1. 启用调试日志查看丢包情况

./tinymapper_amd64 ... --log-level 5

2. 调整最大连接数和超时设置

# 在代码中调整（需重新编译）
#define max_conn_num 10000       // my_ev_common.h
#define conn_timeout_tcp 300     // 连接超时时间(秒)

总结

TinyPortMapper通过轻量级设计与高效事件驱动模型，提供了跨协议、跨网络的高性能端口转发解决方案。通过合理配置缓冲区大小、日志级别和连接参数，可在不同网络环境中实现最优性能。其简洁的命令行接口与灵活的配置选项，使其成为系统管理员和开发人员的理想工具。