# udp-http-bridge

**Repository Path**: bubble0410/udp-http-bridge

## Basic Information

- **Project Name**: udp-http-bridge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-01
- **Last Updated**: 2025-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UDP-HTTP桥接服务

## 项目简介

UDP-HTTP桥接服务是一个轻量级的网络代理工具，用于将HTTP请求转发为UDP请求。当客户端无法直接访问UDP服务时，可以通过这个桥接服务作为中转，实现HTTP到UDP的协议转换。

## 应用场景

- **网络隔离环境**: 客户端网络环境无法直接访问UDP服务
- **协议转换**: 需要将HTTP请求转换为UDP协议进行通信
- **网络代理**: 作为UDP通信的中转代理服务器
- **调试测试**: 用于UDP服务的远程调试和测试

## 功能特性

### 🔄 核心功能
- **HTTP到UDP转发**: 接收HTTP请求并转发为UDP请求
- **响应转换**: 将UDP响应转换为HTTP响应返回
- **批量转发**: 支持批量UDP请求处理
- **连通性测试**: 提供UDP ping测试功能

### 🛠️ 技术特性
- **多编码支持**: UTF-8、GBK、ISO-8859-1、ASCII
- **超时控制**: 可配置的请求超时时间
- **错误处理**: 完善的异常处理和错误信息反馈
- **日志记录**: 详细的操作日志和调试信息
- **跨域支持**: 完整的CORS跨域配置

### 📊 监控功能
- **健康检查**: 服务状态监控
- **性能指标**: 响应时间、传输字节数统计
- **请求追踪**: 唯一请求ID用于追踪和调试

## 技术栈

- **框架**: Spring Boot 2.7.14
- **开发语言**: Java 8+
- **构建工具**: Maven 3.6+
- **网络协议**: HTTP/UDP
- **日志**: SLF4J + Logback

## 快速开始

### 环境要求

- **Java**: JDK 8 或更高版本
- **Maven**: 3.6.0 或更高版本 (可选，有预编译jar包)
- **操作系统**: Windows/Linux/macOS

### 1. 下载项目

```bash
git clone <repository-url>
cd udp-http-bridge
```

### 2. 编译项目

#### Windows
```batch
build.bat
```

#### Linux/macOS
```bash
chmod +x build.sh
./build.sh
```

#### 手动编译
```bash
mvn clean package -DskipTests
```

### 3. 启动服务

#### Windows
```batch
start.bat
```

#### Linux/macOS
```bash
chmod +x start.sh
./start.sh
```

#### 手动启动
```bash
java -jar target/udp-http-bridge-1.0.0.jar
```

### 4. 验证服务

访问健康检查接口：
```bash
curl http://localhost:8090/bridge/api/health
```

## API接口

### 基础信息

- **服务地址**: `http://localhost:8090/bridge`
- **接口前缀**: `/api`
- **响应格式**: JSON

### 主要接口

#### 1. UDP转发
```http
POST /api/forward
Content-Type: application/json

{
  "targetIp": "192.168.1.100",
  "targetPort": 8080,
  "message": "Hello UDP Server!",
  "timeout": 5000,
  "encoding": "UTF-8",
  "waitForResponse": true,
  "requestId": "optional-request-id"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "UDP转发成功",
  "data": {
    "success": true,
    "responseMessage": "Response from UDP server",
    "responseTime": 150,
    "sentBytes": 20,
    "receivedBytes": 25,
    "targetAddress": "192.168.1.100:8080",
    "requestId": "uuid-string",
    "bridgeInfo": "Bridge Server: hostname (ip)"
  },
  "timestamp": 1640995200000
}
```

#### 2. 批量转发
```http
POST /api/forward/batch
Content-Type: application/json

[
  {
    "targetIp": "192.168.1.100",
    "targetPort": 8080,
    "message": "Message 1",
    "waitForResponse": false
  },
  {
    "targetIp": "192.168.1.101", 
    "targetPort": 8081,
    "message": "Message 2",
    "waitForResponse": true
  }
]
```

#### 3. 连通性测试
```http
GET /api/ping?targetIp=192.168.1.100&targetPort=8080&timeout=3000
```

#### 4. 服务信息
```http
GET /api/info
```

#### 5. 健康检查
```http
GET /api/health
```

#### 6. Echo测试
```http
POST /api/echo
Content-Type: application/json

{
  "test": "data"
}
```

## 配置说明

### application.yml 配置

```yaml
server:
  port: 8090                    # 服务端口
  servlet:
    context-path: /bridge       # 上下文路径

# UDP转发配置
bridge:
  udp:
    default-timeout: 5000       # 默认超时时间(ms)
    max-timeout: 30000          # 最大超时时间(ms)
    buffer-size: 4096           # 缓冲区大小(bytes)
    default-encoding: UTF-8     # 默认编码

# 日志配置
logging:
  level:
    com.xinjiang.bridge: DEBUG  # 设置日志级别
  file:
    name: logs/bridge.log       # 日志文件路径
```

### 支持的配置参数

| 参数 | 说明 | 默认值 | 范围 |
|------|------|--------|------|
| targetIp | 目标UDP服务器IP | 必填 | 有效IP地址 |
| targetPort | 目标UDP服务器端口 | 必填 | 1-65535 |
| message | 发送的消息内容 | 必填 | 字符串 |
| timeout | 超时时间(毫秒) | 5000 | 100-30000 |
| encoding | 字符编码 | UTF-8 | UTF-8/GBK/ISO-8859-1/ASCII |
| waitForResponse | 是否等待响应 | true | true/false |
| requestId | 请求ID | 自动生成 | 字符串 |

## 测试指南

### 1. 启动测试服务器

使用项目根目录的UDP测试服务器：
```bash
cd ../xinjiang-admin-backend
python test-udp-server.py 9999
```

### 2. 运行自动化测试

```bash
python test-bridge.py
```

### 3. 手动测试

#### 测试UDP转发
```bash
curl -X POST http://localhost:8090/bridge/api/forward \
  -H "Content-Type: application/json" \
  -d '{
    "targetIp": "127.0.0.1",
    "targetPort": 9999,
    "message": "Hello from Bridge!",
    "timeout": 5000
  }'
```

#### 测试Ping
```bash
curl "http://localhost:8090/bridge/api/ping?targetIp=127.0.0.1&targetPort=9999"
```

## 部署指南

### 1. 生产环境部署

#### 创建部署目录
```bash
mkdir -p /opt/udp-bridge
cd /opt/udp-bridge
```

#### 复制文件
```bash
cp target/udp-http-bridge-1.0.0.jar ./
cp src/main/resources/application.yml ./application-prod.yml
```

#### 修改生产配置
```yaml
# application-prod.yml
server:
  port: 8090

logging:
  level:
    root: WARN
    com.xinjiang.bridge: INFO
  file:
    name: /var/log/udp-bridge/bridge.log
```

#### 启动服务
```bash
java -jar udp-http-bridge-1.0.0.jar --spring.config.location=application-prod.yml
```

### 2. 系统服务配置

#### 创建systemd服务 (Linux)
```bash
sudo tee /etc/systemd/system/udp-bridge.service > /dev/null <<EOF
[Unit]
Description=UDP-HTTP Bridge Service
After=network.target

[Service]
Type=simple
User=bridge
ExecStart=/usr/bin/java -jar /opt/udp-bridge/udp-http-bridge-1.0.0.jar --spring.config.location=/opt/udp-bridge/application-prod.yml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable udp-bridge
sudo systemctl start udp-bridge
```

### 3. 反向代理配置 (Nginx)

```nginx
upstream udp_bridge {
    server localhost:8090;
}

server {
    listen 80;
    server_name bridge.example.com;
    
    location /bridge/ {
        proxy_pass http://udp_bridge;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 使用示例

### Java客户端示例

```java
import org.springframework.web.client.RestTemplate;
import java.util.HashMap;
import java.util.Map;

public class BridgeClient {
    private RestTemplate restTemplate = new RestTemplate();
    private String bridgeUrl = "http://bridge-server:8090/bridge";
    
    public String sendUdpMessage(String targetIp, int targetPort, String message) {
        Map<String, Object> request = new HashMap<>();
        request.put("targetIp", targetIp);
        request.put("targetPort", targetPort);
        request.put("message", message);
        request.put("timeout", 5000);
        request.put("waitForResponse", true);
        
        Map response = restTemplate.postForObject(
            bridgeUrl + "/api/forward", request, Map.class);
            
        if (response != null && response.get("code").equals(200)) {
            Map data = (Map) response.get("data");
            return (String) data.get("responseMessage");
        }
        
        throw new RuntimeException("UDP转发失败");
    }
}
```

### Python客户端示例

```python
import requests

class BridgeClient:
    def __init__(self, bridge_url="http://localhost:8090/bridge"):
        self.bridge_url = bridge_url
        
    def send_udp_message(self, target_ip, target_port, message, timeout=5000):
        """发送UDP消息"""
        request_data = {
            "targetIp": target_ip,
            "targetPort": target_port,
            "message": message,
            "timeout": timeout,
            "waitForResponse": True
        }
        
        response = requests.post(
            f"{self.bridge_url}/api/forward",
            json=request_data,
            timeout=timeout/1000 + 5
        )
        
        if response.status_code == 200:
            result = response.json()
            if result['code'] == 200:
                return result['data']['responseMessage']
            else:
                raise Exception(f"转发失败: {result['message']}")
        else:
            raise Exception(f"HTTP错误: {response.status_code}")

# 使用示例
client = BridgeClient()
try:
    response = client.send_udp_message("192.168.1.100", 8080, "Hello!")
    print(f"UDP响应: {response}")
except Exception as e:
    print(f"错误: {e}")
```

### JavaScript客户端示例

```javascript
class BridgeClient {
    constructor(bridgeUrl = 'http://localhost:8090/bridge') {
        this.bridgeUrl = bridgeUrl;
    }
    
    async sendUdpMessage(targetIp, targetPort, message, timeout = 5000) {
        const requestData = {
            targetIp,
            targetPort,
            message,
            timeout,
            waitForResponse: true
        };
        
        try {
            const response = await fetch(`${this.bridgeUrl}/api/forward`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(requestData)
            });
            
            const result = await response.json();
            
            if (result.code === 200) {
                return result.data.responseMessage;
            } else {
                throw new Error(`转发失败: ${result.message}`);
            }
        } catch (error) {
            throw new Error(`请求异常: ${error.message}`);
        }
    }
    
    async ping(targetIp, targetPort, timeout = 3000) {
        const url = `${this.bridgeUrl}/api/ping?targetIp=${targetIp}&targetPort=${targetPort}&timeout=${timeout}`;
        
        try {
            const response = await fetch(url);
            const result = await response.json();
            
            if (result.code === 200) {
                return {
                    success: true,
                    responseTime: result.data.responseTime,
                    message: result.data.responseMessage
                };
            } else {
                return {
                    success: false,
                    error: result.message
                };
            }
        } catch (error) {
            return {
                success: false,
                error: error.message
            };
        }
    }
}

// 使用示例
const client = new BridgeClient();

client.sendUdpMessage('192.168.1.100', 8080, 'Hello from Browser!')
    .then(response => console.log('UDP响应:', response))
    .catch(error => console.error('错误:', error));
```

## 故障排除

### 常见问题

#### 1. 服务启动失败
- **端口被占用**: 修改配置文件中的端口号
- **Java版本不兼容**: 确保使用Java 8或更高版本
- **权限不足**: 确保有读取配置文件和写入日志的权限

#### 2. UDP转发失败
- **网络不通**: 检查网络连通性和防火墙设置
- **目标服务未启动**: 确保目标UDP服务正在运行
- **IP地址错误**: 验证目标IP地址格式是否正确
- **端口不可用**: 检查目标端口是否开放

#### 3. 超时问题
- **网络延迟高**: 增加timeout设置
- **目标服务响应慢**: 调整超时时间或优化目标服务
- **并发请求过多**: 控制并发数量

#### 4. 编码问题
- **中文乱码**: 检查encoding设置，尝试GBK编码
- **特殊字符**: 确保客户端和服务端编码一致

### 日志分析

#### 查看实时日志
```bash
tail -f logs/bridge.log
```

#### 常见日志信息
- `开始转发UDP请求`: 请求开始处理
- `UDP消息已发送`: 消息发送成功
- `UDP响应已接收`: 收到响应
- `UDP请求超时`: 请求超时
- `Socket错误`: 网络连接问题

### 调试技巧

#### 1. 启用调试日志
```yaml
logging:
  level:
    com.xinjiang.bridge: DEBUG
```

#### 2. 使用请求ID追踪
在请求中添加requestId字段，便于日志追踪：
```json
{
  "targetIp": "192.168.1.100",
  "targetPort": 8080,
  "message": "test",
  "requestId": "debug-001"
}
```

#### 3. 网络工具验证
```bash
# 检查端口连通性
telnet 192.168.1.100 8080

# 检查UDP端口
nc -u 192.168.1.100 8080

# 抓包分析
tcpdump -i any -n host 192.168.1.100 and port 8080
```

## 性能优化

### 1. JVM参数调优
```bash
java -Xms512m -Xmx1024m -XX:+UseG1GC -jar udp-http-bridge-1.0.0.jar
```

### 2. 连接池配置
```yaml
spring:
  task:
    execution:
      pool:
        core-size: 8
        max-size: 32
        queue-capacity: 100
```

### 3. 监控指标
- 响应时间监控
- 成功率统计
- 并发请求数量
- 内存使用情况

## 安全说明

### 1. 网络安全
- 部署在内网环境
- 配置防火墙规则
- 使用VPN或专线连接

### 2. 访问控制
- 限制来源IP地址
- 配置访问白名单
- 设置请求频率限制

### 3. 数据安全
- 敏感数据加密传输
- 避免在日志中记录敏感信息
- 定期更新依赖库

## 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 联系方式

- **项目地址**: [GitHub Repository]
- **问题反馈**: [Issues Page]
- **技术交流**: [Contact Information]

---

**最后更新**: 2025年1月
**版本**: 1.0.0