# portmap

**Repository Path**: helssdo/portmap

## Basic Information

- **Project Name**: portmap
- **Description**: RDP-Map 是一个基于 Windows C++ 开发的 **RDP (远程桌面协议) 端口映射与数据透传系统**。它采用 **MS-TC-TS 三层架构**，通过一个中心调度服务器（MS）协调两端（TC 和 TS）之间的数据连接，实现类似内网穿透/端口映射的功能。

### 核心功能

- **内网穿透**：将内网服务（如 RDP 远程桌面）暴露到外网
- **端口映射**：将本地端口映射到远
- **Primary Language**: Unknown
- **License**: LGPL-2.1
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RDP-Map 端口映射与数据透传系统

## 项目简介

RDP-Map 是一个基于 Windows C++ 开发的 **RDP (远程桌面协议) 端口映射与数据透传系统**。它采用 **MS-TC-TS 三层架构**，通过一个中心调度服务器（MS）协调两端（TC 和 TS）之间的数据连接，实现类似内网穿透/端口映射的功能。

### 核心功能

- **内网穿透**：将内网服务（如 RDP 远程桌面）暴露到外网
- **端口映射**：将本地端口映射到远程目标端口
- **数据透传**：支持 UDP 透传、TCP 中转、TCP 透传三种传输模式
- **双通道分离**：控制通道（加密）和数据通道（映射）分离，安全可靠

---

## 系统架构

### 三层模型

```
┌─────────────────────────────────────────────────────────────┐
│                        系统架构图                            │
│                                                             │
│   ┌──────────────┐          ┌──────────────┐               │
│   │  TC 客户端    │          │  TS 客户端    │               │
│   │  (被控端)     │          │  (服务端)     │               │
│   │  TcClient/   │          │  TsClient/   │               │
│   │  TcAgent     │          │  TsAgent     │               │
│   │  主动发起连接  │          │  被动接受连接  │               │
│   └──────┬───────┘          └──────┬───────┘               │
│          │                         │                        │
│          │   控制连接(YRC4加密)     │                        │
│          ├─────────────────────────┤                        │
│          │                         │                        │
│          │   数据连接(MAP协议)      │                        │
│          ├─────────────────────────┤                        │
│          │                         │                        │
│          │         ┌───────────────┴────────┐               │
│          │         │    MS 中心调度服务器     │               │
│          └─────────►    lssRdpServer        │               │
│                    │    rdpAdminThread      │               │
│                    │    连接管理与调度       │               │
│                    └───────────────────────┘               │
└─────────────────────────────────────────────────────────────┘
```

### 角色说明

| 角色 | 名称 | 说明 |
|------|------|------|
| **MS** | Middle Server (中心服务器) | 调度中心，负责协调 TC 和 TS 之间的连接，管理注册、配对、数据传输 |
| **TC** | Target Client (目标客户端) | 被控端，主动向 MS 发起连接，本地监听端口接收外部请求，将请求转发到 TS |
| **TS** | Target Server (目标服务端) | 服务端，连接到 MS 等待 TC 的连接请求，最终将数据转发到目标内网服务 |
其中MS的工程如下：
在windows环境中，可以使用svrPortmap，这是一个服务
在linux环境中，可以使用portmapServer，通过CMakelists.txt编译，windows上也可以使用
---

## 项目结构

```
portMap/
│
├── portmapServer/                          # MS 中心调度服务器
│   ├── CMakeLists.txt                      # CMake构建配置
│   ├── portmapServer.cpp                   # 主入口
│   ├── portmapServer.h                     # 主头文件
│   ├── rdpAdminThread.cpp                  # 核心管理线程（业务逻辑核心）
│   └── rdpAdminThread.h                    # 管理线程头文件
│
├── client/                                 # 客户端程序
│   ├── TcClient/                           # TC 客户端（新版，Web管理界面）
│   │   ├── TcAgent/                        # TC 代理程序（lssClient 架构）
│   │   │   ├── CMakeLists.txt              # CMake构建配置
│   │   │   ├── main.cpp                    # 入口
│   │   │   ├── TcWebLeader.cpp/h           # Web领导线程
│   │   │   ├── ServiceController.cpp/h     # 服务控制器
│   │   │   ├── DeviceAdapt.cpp/h            # 设备适配层
│   │   │   └── MyHttpData.cpp/h             # HTTP数据处理
│   │   └── web/                            # Web前端（Vue 3 + Vite）
│   │       ├── src/
│   │       │   ├── App.vue
│   │       │   ├── components/             # Vue组件
│   │       │   ├── api/                    # API接口
│   │       │   └── utils/                  # 工具函数
│   │       └── package.json
│   │
│   ├── TsClient/                           # TS 客户端（新版，Web管理界面）
│   │   ├── TsAgent/                        # TS 代理程序（lssClient 架构）
│   │   │   ├── CMakeLists.txt              # CMake构建配置
│   │   │   ├── main.cpp                    # 入口
│   │   │   ├── TsWebLeader.cpp/h           # Web领导线程
│   │   │   ├── ServiceController.cpp/h     # 服务控制器
│   │   │   ├── DeviceAdapt.cpp/h            # 设备适配层
│   │   │   └── MyHttpData.cpp/h             # HTTP数据处理
│   │   └── web/                            # Web前端（Vue 3 + Vite）
│   │       ├── src/
│   │       │   ├── App.vue
│   │       │   ├── components/             # Vue组件
│   │       │   └── api/                    # API接口
│   │       └── package.json
│   │
│   ├── TcRdpCtl/                           # TC 客户端（旧版，命令行参数模式）
│   ├── TsRdpCtl/                           # TS 客户端（旧版，命令行参数模式）
│   │
│   ├── rdpAgent/                           # rdpAgent Windows 服务
│   │   ├── rdpAgent.cpp                    # Windows 服务实现
│   │   └── rdpAgent.idl                    # COM 接口定义
│   │
│   └── common/                             # 客户端公共库
│       ├── adl/                            # ADL通信库
│       ├── compress/                       # 压缩工具
│       ├── crash/                          # 崩溃处理
│       ├── ctrl/                           # 控制模块
│       ├── dbnt/                           # 数据库定义
│       ├── download/                       # 下载工具
│       ├── rdp/                            # RDP协议核心实现
│       ├── ServerLog/                      # 服务器日志
│       ├── tcp_api/                        # TCP通信API
│       ├── tcp_iocp/                       # TCP IOCP实现
│       ├── UrlCode/                        # URL编解码
│       └── yrc4/                           # RC4加密算法
│
├── common/                                 # 服务器端公共库
│   └── rdp/                                # RDP 核心协议实现
│       ├── RdpClient.h/cpp                 # 基础 RDP 客户端
│       ├── CtlRdpClient.h/cpp              # 控制通道客户端
│       ├── DataRdpClient.h/cpp             # 数据通道客户端
│       ├── TransRdpAdmin.h/cpp             # 传输管理
│       ├── TransRdpGroupAdmin.h/cpp        # 组管理
│       ├── PairRdpMsAdmin.h/cpp            # 配对管理（MS 端）
│       ├── PairRdpTsAdmin.h/cpp            # 配对管理基础类
│       ├── PairClientBase.h/cpp            # 配对客户端基类
│       ├── ListenSocket.h/cpp              # 监听套接字
│       ├── tsRdpCmd.h                      # 命令字定义
│       ├── RdpTcpThread.h/cpp              # TCP 传输线程
│       ├── RdpListenThread.h/cpp           # 本地监听线程
│       ├── RdpLeaderBase.h/cpp             # 领导线程基类
│       ├── RdpSrcThread.h/cpp              # 源数据线程
│       ├── PairRdpAdminClient.h/cpp        # 客户端配对管理
│       └── ControlRdpConnectThread.h/cpp   # 控制连接线程基类
│
└── third_party/                            # 第三方库
    └── common/
        ├── ctrl/                           # 控制模块（日志、线程）
        ├── json/                           # JSON库
        ├── lssHttpProxy/                   # HTTP代理
        ├── mongoose/                       # Mongoose web服务器
        ├── serialWork/                     # 串口工作库
        ├── SQLite/                         # SQLite数据库
        └── superSocket/                    # SuperSocket通信框架
            ├── include/CommonBridge.h      # 通信桥接基类
            └── lib/64_dll/superSocket_R.dll
```

---

## 核心业务流程

### 1. 连接建立流程

```
TS 启动 ──► 连接 MS 控制端口 ──► 注册身份标识
                                            │
TC 启动 ──► 连接 MS 控制端口 ──► 注册身份标识
                                            │
TC 本地有连接进来 ──► 向 MS 请求新建数据通道
                                            │
MS 协调 TC 和 TS ──► 建立数据连接
                                            │
         ┌────────────────┬────────────────┐
         │                │                │
     UDP 透传          TCP 中转        TCP 透传
   (直连模式)        (服务器中转)      (直连模式)
```

### 2. 注册与配对

- **TS 先注册**到 MS，等待 TC 连接
- **TC 后注册**，MS 验证 TC 要连接的 TS 是否在线
- 配对成功后，`CPairRdpMsAdmin` 管理 TC 和 TS 之间的配对关系
- 配对完成后，双方互知对方的 IP 和端口，建立直连

### 3. 数据传输模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **UDP 透传** | TC 和 TS 之间直接建立 UDP 连接 | 低延迟、实时性要求高的场景 |
| **TCP 中转** | 通过 MS 中转 TCP 数据 | 无法直连的网络环境 |
| **TCP 透传** | TC 和 TS 之间直接建立 TCP 连接 | 可直连的网络环境 |

---

## 通信协议

### 命令字定义

系统定义了一套完整的命令枚举体系，定义在 `common/rdp/tsRdpCmd.h` 中：

#### 基础命令 (0-999)
| 命令 | 值 | 说明 |
|------|-----|------|
| `DBNT_CMD_QUERY_ID` | 1 | 请求唯一 ID |
| `DBNT_CMD_REGISTER` | 2 | 客户端注册 |
| `DBNT_CMD_HEART` | 3 | 心跳握手 |

#### 控制命令 (1000-1499)
| 命令 | 值 | 说明 |
|------|-----|------|
| `DBNT_CMD_REQ_ID` | 1000 | TC 请求连接目标 TS |
| `DBNT_CMD_REG_ID` | 1001 | 注册透传 ID |
| `DBNT_CMD_TC_NEW_CONNECT` | 1002 | TC 新建连接请求 |
| `DBNT_CMD_TS_NEW_CONNECT` | 1003 | TS 新建连接响应 |
| `DBNT_CMD_TS_DATA_CLOSE` | 1005 | 数据连接关闭 |
| `DBNT_CMD_TC_CLOSE_CHANNEL` | 1007 | TC 关闭通道 |

#### 数据命令 (1500-1999)
| 命令 | 值 | 说明 |
|------|-----|------|
| `DBNT_CMD_DATA_NEW_CONNECT` | 1500 | 新建数据连接 |
| `DBNT_CMD_TRANS_DATA` | 1501 | 数据传输 |
| `DBNT_CMD_PAIR_OK` | 1502 | 配对成功 |

#### UDP 命令 (2000-2999)
| 命令 | 值 | 说明 |
|------|-----|------|
| `DBNT_CMD_UDP_CONNECT_OK` | 2000 | UDP 连接成功 |
| `DBNT_CMD_UDP_PAIR_OK` | 2004 | UDP 配对成功 |
| `DBNT_CMD_UDP_TEST_END` | 2006 | UDP 测试结束 |

#### TCP 命令 (3000-3999)
| 命令 | 值 | 说明 |
|------|-----|------|
| `DBNT_CMD_TCP_TS_NEW_CONNECT` | 3000 | TCP 新建连接 |
| `DBNT_CMD_TCP_TS_START` | 3001 | TCP 开始传输 |
| `DBNT_CMD_TCP_PAIR_OK` | 3003 | TCP 配对成功 |
| `DBNT_CMD_TCP_TRANS_SUCCESS` | 3005 | TCP 传输成功 |

### 设备类型

```cpp
enum DBNT_DEV_TYPE {
    DBNT_DEV_NULL,    // 未定义
    DBNT_DEV_TC,      // TC 程序（被控端）
    DBNT_DEV_TS,      // TS 程序（服务端）
    DBNT_DEV_MS,      // 中心服务器
};
```

### 内部消息定义

```cpp
// 窗口消息基址
WM_AD_BASE_ID       = WM_USER + 0x100    // 客户端管理消息
WM_TRANS_BASE_ID    = WM_USER + 600      // 传输控制消息

// 传输控制消息
WM_TRANS_REG_ID             // 控制连接注册
WM_TRANS_CTL_CLOSE          // 控制连接断开
WM_TRANS_NEW_CONNECT        // TC 请求新建数据连接
WM_TRANS_NEW_DATA_CONNECT   // 新建数据连接
WM_TRANS_DATA_CLOSE         // 数据连接断开
WM_TRANS_TRANS_CMD          // 透传命令
WM_TRANS_NEW_TCP_CONNECT    // 新建 TCP 透传连接
WM_TRANS_TCP_TS_START       // 开始 TCP 透传
WM_TCP_TC_SEND_OK           // TCP 透传成功
```

---

## 部署指南

### 环境要求

- **操作系统**：Windows 7 / Windows Server 2008 R2 及以上
- **开发环境**：Visual Studio 2010 及以上（推荐 VS2015+）
- **依赖库**：Windows SDK, ATL（用于 rdpAgent 服务）

### 服务器部署 (MS - portmapServer)

#### 1. 配置 `listen.ini`

```ini
[setting]
control_port=29001      ; 控制端口（TC/TS 连接用）
data_port=29000         ; 数据端口（数据传输用）
udp_port=29002          ; UDP 端口（UDP 透传用）
```

#### 2. 启动服务器

直接运行 `portmapServer.exe`，程序会启动并监听配置的端口。

#### 3. 验证启动

查看日志文件 `rdpMsServer.log`，确认监听端口成功：
```
listen port 29001 success
listen port 29000 success
```

### 客户端部署

新版客户端（TcAgent / TsAgent）使用 **Web 管理界面** 进行配置和操作，无需命令行参数。

#### TS 客户端（TsAgent - 服务端）

启动 TsAgent 后，程序会自动：
1. 连接 MS 服务器，注册身份标识
2. 生成被控码（在 Web 界面显示）
3. 自动向 MS 发布服务列表
4. 保持心跳连接
5. 提供 Web 管理界面（默认地址 http://localhost:8080）

启动方式：
```bash
TsAgent.exe
```

#### TC 客户端（TcAgent - 控制端）

启动 TcAgent 后，程序会自动：
1. 打开 Web 管理界面
2. 用户在界面中输入被控码，连接 MS 服务器
3. 查询 TS 发布的服务列表
4. 添加/配置服务映射（TCP/串口/UDP）
5. 启动数据隧道

启动方式：
```bash
TcAgent.exe
```

#### 旧版客户端（TcRdpCtl / TsRdpCtl）

旧版客户端使用命令行参数模式，仍在逐步迁移中：

**TS 客户端（旧版）**
```bash
TsRdpCtl.exe <TransId> <MS_IP> <ControlPort> <DataPort> <LocalPort>
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `TransId` | 传输标识（唯一 ID） | `12345` |
| `MS_IP` | 中心服务器 IP | `192.168.1.100` |
| `ControlPort` | 服务器控制端口 | `29001` |
| `DataPort` | 服务器数据端口 | `29000` |
| `LocalPort` | 本地服务端口 | `3389`（RDP 默认端口） |

**TC 客户端（旧版）**
```bash
TcRdpCtl.exe <TransId> <MS_IP> <ControlPort> <DataPort> <Mode>
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `TransId` | 传输标识（与 TS 对应） | `12345` |
| `MS_IP` | 中心服务器 IP | `192.168.1.100` |
| `ControlPort` | 服务器控制端口 | `29001` |
| `DataPort` | 服务器数据端口 | `29000` |
| `Mode` | 传输模式（0=TCP中转, 1=TCP透传） | `1` |

### 完整部署示例

假设网络环境：
- MS 服务器：`192.168.1.100`，控制端口 `29001`，数据端口 `29000`
- 内网有一台 RDP 服务器 `10.0.0.5:3389` 需要暴露到外网

**步骤 1**：在 MS 服务器上启动 `portmapServer.exe`

**步骤 2**：在内网 RDP 服务器上启动 TsAgent
```bash
TsAgent.exe
```
记录 Web 界面显示的被控码（如 `12345`）。

**步骤 3**：在外网机器上启动 TcAgent
```bash
TcAgent.exe
```
在 Web 界面中输入被控码 `12345`，连接成功后添加 TCP→TCP 映射：
- TC端：本地监听端口 `1922`
- TS端：目标 IP `10.0.0.5`，目标端口 `3389`

**步骤 4**：使用远程桌面客户端连接 TC 机器的 `127.0.0.1:1922`，即可访问内网的 RDP 服务

---

## 核心类说明

### 服务器端核心类

| 类名 | 文件 | 说明 |
|------|------|------|
| `rdpAdminThread` | `rdpAdminThread.h/cpp` | 核心管理线程，处理所有业务逻辑和消息分发 |
| `ControlListen` | `ListenSocket.h/cpp` | 控制端口监听，接收 TC/TS 的控制连接 |
| `DataListen` | `ListenSocket.h/cpp` | 数据端口监听，接收 TC/TS 的数据连接 |
| `CTransRdpAdmin` | `TransRdpAdmin.h/cpp` | 传输管理，每个主机一个实例，管理该主机的所有连接组 |
| `CTransRdpGroupAdmin` | `TransRdpGroupAdmin.h/cpp` | 组管理，每个连接组一个实例，管理通道配对 |
| `CPairRdpMsAdmin` | `PairRdpMsAdmin.h/cpp` | 配对管理，管理 TC 和 TS 之间的数据通道配对 |

### 客户端核心类（新版）

| 类名 | 文件 | 说明 |
|------|------|------|
| `CTcWebLeader` | `TcWebLeader.h/cpp` | TC Web领导线程，管理Web控制界面和服务管理 |
| `CTsWebLeader` | `TsWebLeader.h/cpp` | TS Web领导线程，管理Web控制界面和服务发布 |
| `CServiceController` | `ServiceController.h/cpp` | 服务控制器，管理接入类型注册和启动 |
| `CDeviceAdapt` | `DeviceAdapt.h/cpp` | 设备适配层，处理 TCP/串口/UDP 接入 |

### 客户端核心类（旧版）

| 类名 | 文件 | 说明 |
|------|------|------|
| `CRdpLeader` | `RdpLeader.h/cpp` | TC 领导线程，管理本地监听和远程连接 |
| `CTsRdpLeader` | `TsRdpLeader.h/cpp` | TS 领导线程，管理控制连接和心跳 |
| `CTcCtlRdpConnectThread` | `TcCtlRdpConnectThread.h/cpp` | TC 控制连接线程 |
| `CTsCtlRdpConnectThread` | `TsCtlRdpConnectThread.h/cpp` | TS 控制连接线程（含心跳检测） |

### 公共核心类

| 类名 | 文件 | 说明 |
|------|------|------|
| `CRdpClient` | `RdpClient.h/cpp` | 基础 RDP 客户端，所有客户端的基类 |
| `CCtlRdpClient` | `CtlRdpClient.h/cpp` | 控制通道客户端，处理控制命令 |
| `CDataRdpClient` | `DataRdpClient.h/cpp` | 数据通道客户端，处理数据传输 |
| `CPairClientBase` | `PairClientBase.h/cpp` | 配对客户端基类，提供配对数据收发接口 |

---

## 开发指南

### 编译项目

#### 新版客户端（TcAgent / TsAgent）

使用 CMake 构建：
```bash
cd client/TcClient/TcAgent
cmake -S . -B out/build/x86-Debug
cmake --build out/build/x86-Debug --config Debug
```

#### 旧版客户端

使用 Visual Studio 打开对应的 `.sln` 或 `.vcxproj` 文件。

#### 服务器（portmapServer）

```bash
cd portmapServer
cmake -S . -B build
cmake --build build --config Release
```

### 项目依赖

- **portmapServer** 依赖 `common/` 目录下的公共库
- **TcAgent / TsAgent** 依赖 `common/` 下的公共库和 `third_party/` 下的第三方库
- **TcRdpCtl / TsRdpCtl**（旧版）依赖 `common/` 下的公共库
- **rdpAgent** 依赖 ATL 库和 `common/` 目录

### 调试建议

1. **日志查看**：各程序都会生成日志文件（`rdpMsServer.log`、`tcRdpCtrl.log`、`tsRdpCtrl.log`）
2. **异常转储**：服务器崩溃时会自动生成 `.dmp` 文件到 `logs/` 目录，可用 WinDbg 分析
3. **调试输出**：日志同时会通过 `OutputDebugString` 输出，可用 DebugView 捕获

---

## 架构演进

| 阶段 | 客户端 | 管理方式 | 状态 |
|------|--------|---------|------|
| **旧版** | TcRdpCtl.exe / TsRdpCtl.exe | 命令行参数 | 逐步迁移中 |
| **新版** | TcAgent.exe / TsAgent.exe (TcClient/TsClient) | Web管理界面 (Vue 3) | 当前主力版本 |

新版优势：
- 无需记忆命令行参数
- Web 界面可视化配置
- 支持 TCP/串口/UDP 多种接入方式
- 支持服务发现（自动发布和查询服务列表）

---

## 安全特性

1. **控制通道加密**：使用 YRC4 算法对控制通道数据进行加密
2. **身份注册机制**：TC 和 TS 需要通过 TransId 注册到 MS，防止未授权连接
3. **异常处理**：全局异常捕获机制，生成 MiniDump 便于问题排查
4. **心跳检测**：TS 端有心跳机制，检测连接是否存活

---

## 许可证

本项目为内部使用项目，具体许可证信息请参考项目相关文档。

---

## 附录

### 配置文件参考

`listen.ini` 完整配置项：
```ini
[setting]
control_port=29001      ; 控制端口
data_port=29000         ; 数据端口
udp_port=29002          ; UDP 端口
```

### 启动脚本参考

新版启动（推荐）：
```batch
TcAgent.exe
TsAgent.exe
```

旧版启动：
```batch
TcRdpCtl.exe 12345 192.168.187.1 29001 29000 1
TsRdpCtl.exe 12345 192.168.187.1 29001 29000 3389
```

### 常见问题

**Q: 连接失败，日志显示 "admin not exist"**
A: 请确保 TS 客户端先启动并成功注册到 MS，然后再启动 TC 客户端。

**Q: 数据传输速度慢**
A: 检查网络环境是否支持直连，尝试切换传输模式（TCP 中转 vs TCP 透传）。

**Q: 程序崩溃**
A: 检查 `logs/` 目录下的 `.dmp` 文件，使用 WinDbg 分析崩溃原因。