TcpMapping

TCP port forwarding server with WebUI management and real-time connection monitoring.

TCP端口转发服务器，支持WebUI管理界面和实时连接监控。

Features | 功能特性

• TCP Port Forwarding - Forward TCP traffic to backend servers | TCP端口转发
• Multiple Mappings - Manage multiple forwarding rules simultaneously | 多端口映射
• WebUI Management - Modern web interface for real-time monitoring | WebUI管理界面
• Connection Monitoring - Real-time connection count and traffic statistics | 实时连接监控
• Secure Authentication - bcrypt password hashing, login protection | 安全认证

Installation | 安装

NPM Global Install (Recommended) | NPM全局安装（推荐）

npm install -g @chenpu17/tcpmapping

tcpmapping setup-password   # Set admin password | 设置管理员密码
tcpmapping init             # Create config file | 创建配置文件
tcpmapping start            # Start server | 启动服务

Local Install | 本地安装

git clone https://github.com/chenpu17/TcpMapping.git
cd TcpMapping
npm install
npm run setup-password
npm start

CLI Commands | CLI命令

| Command | Description | |---------|-------------| | tcpmapping start | Start server in background | 后台启动服务 | | tcpmapping stop | Stop server | 停止服务 | | tcpmapping restart | Restart server | 重启服务 | | tcpmapping status | Show status and config paths | 查看状态和配置路径 | | tcpmapping logs | Show recent logs | 查看最近日志 | | tcpmapping logs -f | Follow logs in real-time | 实时跟踪日志 | | tcpmapping setup-password | Set admin password | 设置管理员密码 | | tcpmapping init | Create config file | 创建配置文件 |

WebUI

After starting, visit http://localhost:9999

启动后访问 http://localhost:9999

Default username | 默认用户名: admin

Configuration | 配置

Config file location (priority order) | 配置文件位置（优先级）:

1. ./config.json - Current directory | 当前目录
2. ~/.tcpmapping/config.json - User data directory | 用户数据目录

Example | 示例

{
  "mappings": [
    {
      "name": "web-server",
      "listen": { "host": "0.0.0.0", "port": 8080 },
      "target": { "host": "192.168.1.100", "port": 3000 }
    },
    {
      "name": "database",
      "listen": { "host": "127.0.0.1", "port": 3307 },
      "target": { "host": "db.example.com", "port": 3306 }
    }
  ],
  "webui": { "port": 9999 },
  "logging": { "level": "info" }
}

Config Options | 配置项

| Option | Description | |--------|-------------| | mappings[].name | Mapping name | 映射名称 | | mappings[].listen.host | Listen address (0.0.0.0 for all) | 监听地址 | | mappings[].listen.port | Listen port | 监听端口 | | mappings[].target.host | Target host IP or domain | 目标主机 | | mappings[].target.port | Target port | 目标端口 | | webui.port | WebUI port (default: 9999) | WebUI端口 | | logging.level | Log level: debug/info/warn/error | 日志级别 |

Data Persistence | 数据持久化

User configuration is stored in ~/.tcpmapping/:

用户配置存储在 ~/.tcpmapping/ 目录：

• config.json - Port mapping configuration | 端口映射配置
• auth-config.json - Authentication configuration | 认证配置
• tcpmapping.log - Log file | 日志文件
• tcpmapping.pid - PID file | PID文件

Upgrading will NOT overwrite your configuration.

升级不会覆盖你的配置文件。

Security | 安全特性

• Strong Password Policy - 8+ chars, uppercase, lowercase, numbers | 强密码策略
• Login Protection - Lock after 5 failed attempts for 30 minutes | 登录保护
• Session Timeout - 24 hours auto expiration | 会话超时
• Password Encryption - bcrypt with 12 rounds | bcrypt加密

API

See docs/API.md for API documentation.

详细API文档请参阅 docs/API.md

Quick Reference | 快速参考

# Health check (no auth) | 健康检查
curl http://localhost:9999/api/health

# Login | 登录
curl -X POST http://localhost:9999/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword"}' \
  -c cookies.txt

# Get mappings | 获取映射列表
curl http://localhost:9999/api/mappings -b cookies.txt

FAQ | 常见问题

Forgot password? | 忘记密码？

tcpmapping setup-password
# or | 或
npm run reset-password

Check if running? | 检查运行状态？

tcpmapping status

Port already in use? | 端口被占用？

Edit webui.port or mappings[].listen.port in config.json.

修改 config.json 中的 webui.port 或 mappings[].listen.port。

License | 许可证

MIT License