wu-lazy-cloud-network/项目说明文档.md

# Wu-Lazy-Cloud-Network 项目说明文档

## 📋 项目概述

**Wu-Lazy-Cloud-Network (WLCN)** 是一款基于 Spring Boot 3.5.0 和 JDK 24 开发的网络穿透、渗透工具，支持 TCP、HTTP、SOCKS 协议。该项目是 [wu-framework-parent](https://gitee.com/wujiawei1207537021/wu-framework-parent) 框架孵化的网络解决方案。

### 🎯 主要功能

- **内网穿透**：将局域网服务映射到公网，实现远程访问
- **网络代理**：支持 HTTP 和 SOCKS 代理，实现异地组网
- **流量监控**：实时监控网络流量使用情况
- **多协议支持**：支持 TCP、HTTP、SOCKS 等多种协议
- **集群部署**：支持单机版和集群模式部署

## 🏗️ 系统架构

### 核心模块

| 模块 | 版本 | 描述 | 端口 |
|------|------|------|------|
| `wu-lazy-cloud-heartbeat-common` | 1.3.1-JDK24 | 公共模块（接口、枚举、常量、适配器） | - |
| `wu-lazy-cloud-heartbeat-server` | 1.3.1-JDK24 | 服务端核心组件 | 6001(Web), 7001(TCP) |
| `wu-lazy-cloud-heartbeat-client` | 1.3.1-JDK24 | 客户端核心组件 | 6004(Web) |
| `wu-lazy-cloud-heartbeat-dns` | 1.3.1-JDK24 | DNS 解析模块 | - |
| `wu-lazy-cloud-heartbeat-protocol-proxy` | 1.3.1-JDK24 | 代理协议模块 | 8001(HTTP), 9001(SOCKS) |

### 启动模块

| 模块 | 版本 | 描述 | 用途 |
|------|------|------|------|
| `wu-lazy-cloud-heartbeat-server-start` | 1.3.1-JDK24 | 服务端启动模块 | 生产部署 |
| `wu-lazy-cloud-heartbeat-client-start` | 1.3.1-JDK24 | 客户端启动模块 | 生产部署 |
| `wu-lazy-cloud-heartbeat-server-cluster-start` | 1.3.1-JDK24 | 集群服务端启动模块 | 集群部署 |

## 🔧 技术栈

### 核心框架
- **Spring Boot**: 3.5.3
- **JDK**: 24
- **Netty**: 网络通信框架
- **Lazy ORM**: 数据库操作框架

### 数据库
- **MySQL**: 8.0.33
- **H2**: 开发环境数据库

### 其他依赖
- **Lombok**: 代码生成
- **MapStruct**: 对象映射
- **wu-framework-web**: Web 容器
- **wu-authorization-server-platform-starter**: 用户授权体系

## 🚀 快速开始

### 环境要求

- **操作系统**: Windows、Mac、Linux
- **Java**: JDK 13+ (推荐 JDK 24)
- **内存**: 最小 512MB，推荐 1GB+
- **网络**: 需要公网 IP（服务端）

### Docker 部署

#### 1. 启动服务端

```bash
docker run -d -it -p 6001:6001 -p 7001:7001 -p 8001:8001 -p 9001:9001 \
  --name wlcn-server \
  registry.cn-hangzhou.aliyuncs.com/wu-lazy/wu-lazy-cloud-heartbeat-server:1.3.1-JDK24
```

**端口说明**:
- `6001`: Web 管理界面
- `7001`: TCP 连接端口
- `8001`: HTTP 代理端口
- `9001`: SOCKS 代理端口

#### 2. 启动客户端

```bash
docker run -d -it --privileged -p 6004:6004 \
  --name wlcn-client \
  --restart=always \
  -e spring.lazy.netty.client.inet-host=YOUR_SERVER_IP \
  -e spring.lazy.netty.client.inet-port=7001 \
  -e spring.lazy.netty.client.client-id="your-client-id" \
  registry.cn-hangzhou.aliyuncs.com/wu-lazy/wu-lazy-cloud-heartbeat-client-start:1.3.1-JDK24
```

**环境变量说明**:
- `spring.lazy.netty.client.inet-host`: 服务端 IP 地址
- `spring.lazy.netty.client.inet-port`: 服务端 TCP 端口
- `spring.lazy.netty.client.client-id`: 客户端唯一标识

### 源码部署

#### 1. 克隆项目

```bash
git clone https://gitee.com/wujiawei1207537021/wu-lazy-cloud-network.git
cd wu-lazy-cloud-network
```

#### 2. 编译项目

```bash
mvn clean package -DskipTests
```

#### 3. 启动服务端

```bash
cd wu-lazy-cloud-heartbeat-start/wu-lazy-cloud-heartbeat-server-start
java -jar target/wu-lazy-cloud-heartbeat-server-start-1.3.1-JDK24.jar
```

#### 4. 启动客户端

```bash
cd wu-lazy-cloud-heartbeat-start/wu-lazy-cloud-heartbeat-client-start
java -jar target/wu-lazy-cloud-heartbeat-client-start-1.3.1-JDK24.jar
```

## 📖 使用指南

### Web 管理界面

#### 1. 访问管理界面

- **服务端**: http://127.0.0.1:6001/netty-server-ui/index.html
- **客户端**: http://127.0.0.1:6004/netty-client-local-ui/index.html

#### 2. 初始配置

1. **登录系统**
   - 默认账号: `admin`
   - 默认密码: `admin`

2. **初始化项目**
   - 添加角色
   - 为用户授权
   - 配置客户端映射

### 内网穿透配置

#### 服务端渗透客户端（内网穿透）

1. **配置端口池**
   - 在服务端管理界面配置需要开放的端口

2. **配置客户端映射**
   - 设置访客端口与客户端真实端口的映射关系
   - 例如：访客端口 19080 → 客户端本地端口 18080

#### 客户端渗透服务端

1. **配置客户端端口池**
   - 在客户端管理界面配置本地端口池

2. **配置渗透映射**
   - 设置本地端口到远程端口的映射关系

### 代理功能使用

#### HTTP 代理

1. **获取代理信息**
   - 服务端: `127.0.0.1:8001`
   - 客户端: `127.0.0.1:8002`

2. **配置代理**
   - 在系统设置中配置 HTTP 代理
   - 或使用第三方代理软件

#### SOCKS 代理

1. **获取代理信息**
   - 服务端: `127.0.0.1:9001`
   - 客户端: `127.0.0.1:9002`

2. **使用代理软件**
   - 推荐使用 Proxifier 等专业代理软件
   - 支持全局代理和应用程序代理

### 路由管理

#### 虚拟路由

1. **创建虚拟 IP**
   - 在路由管理界面创建虚拟 IP 地址
   - 配置代理目标 IP 和端口

2. **应用路由规则**
   - 系统会自动将虚拟 IP 的流量代理到目标地址

## 🔍 功能详解

### 网络穿透模式

#### 1. 服务端渗透客户端
- **用途**: 将内网服务暴露到公网
- **场景**: 远程访问内网 Web 服务、数据库等
- **配置**: 在服务端配置访客端口与客户端端口的映射

#### 2. 服务端渗透服务端
- **用途**: 同局域网内端口映射
- **场景**: 在同一网络环境下的服务间通信
- **配置**: 配置服务端端口池和映射关系

#### 3. 客户端渗透服务端
- **用途**: 本地端口映射到远程服务端端口
- **场景**: 访问远程服务器上的服务
- **配置**: 在客户端配置本地端口到远程端口的映射

#### 4. 客户端渗透客户端
- **用途**: 不同网络间的端口映射
- **场景**: 异地组网，跨网络访问
- **配置**: 配置两个客户端之间的端口映射

### 代理功能

#### HTTP 代理
- 支持 HTTP/HTTPS 协议代理
- 可配置代理认证
- 支持流量监控

#### SOCKS 代理
- 支持 SOCKS4/SOCKS5 协议
- 支持 TCP/UDP 代理
- 可配置认证机制

### 流量监控

#### 实时监控
- 监控每个客户端的流量使用情况
- 支持按端口统计流量
- 提供流量趋势图表

#### 报表功能
- 日流量统计报表
- 客户端流量排行
- 端口使用情况分析

## ⚙️ 配置说明

### 服务端配置

```yaml
spring:
  lazy:
    netty:
      server:
        mode: standalone  # 模式：standalone/cluster
        node-id: default  # 节点ID
        node-host: 127.0.0.1  # 节点主机
        node-port: 7001  # 节点端口
        enable-flow-control: true  # 启用流量控制
        enable-token-verification: false  # 启用Token验证
        tcp:
          port: 7001  # TCP端口
        udp:
          port: 7001  # UDP端口
```

### 客户端配置

```yaml
spring:
  lazy:
    netty:
      client:
        client-id: your-client-id  # 客户端ID
        inet-host: 127.0.0.1  # 服务端地址
        inet-port: 7001  # 服务端端口
        enable: true  # 启用客户端连接
```

### 代理配置

```yaml
spring:
  lazy:
    netty:
      protocol:
        proxy:
          authentication: true  # 启用代理认证
          enable-proxy-log: false  # 启用代理日志
          socket-protocol-proxy:
            port: 9001  # SOCKS代理端口
          http-protocol-proxy:
            port: 8001  # HTTP代理端口
```

## 🔧 开发指南

### 项目结构

```
wu-lazy-cloud-network/
├── wu-lazy-cloud-heartbeat-common/          # 公共模块
├── wu-lazy-cloud-heartbeat-server/          # 服务端核心
├── wu-lazy-cloud-heartbeat-client/          # 客户端核心
├── wu-lazy-cloud-heartbeat-dns/             # DNS模块
├── wu-lazy-cloud-heartbeat-protocol-proxy/  # 代理协议模块
└── wu-lazy-cloud-heartbeat-start/           # 启动模块
    ├── wu-lazy-cloud-heartbeat-server-start/    # 服务端启动
    ├── wu-lazy-cloud-heartbeat-client-start/    # 客户端启动
    └── wu-lazy-cloud-heartbeat-server-cluster-start/  # 集群启动
```

### 核心概念

#### 1. 通道（Channel）
- **心跳通道**: 客户端与服务端建立的持久连接
- **访客通道**: 外部访问者建立的连接
- **真实通道**: 客户端本地服务的连接

#### 2. 渗透（Permeate）
- **服务端渗透**: 由服务端发起的网络穿透
- **客户端渗透**: 由客户端发起的网络穿透

#### 3. 代理（Proxy）
- **HTTP代理**: 基于HTTP协议的代理服务
- **SOCKS代理**: 基于SOCKS协议的代理服务

### 扩展开发

#### 自定义协议
1. 实现 `NettyMsg` 接口
2. 注册到协议处理器
3. 配置协议路由

#### 自定义过滤器
1. 继承 `NettyFilter` 接口
2. 实现过滤逻辑
3. 注册到过滤器链

## 🐛 故障排除

### 常见问题

#### 1. 客户端连接失败
- **检查网络**: 确保客户端能访问服务端
- **检查端口**: 确认服务端端口已开放
- **检查配置**: 验证客户端配置参数

#### 2. 内网穿透不工作
- **检查映射**: 确认端口映射配置正确
- **检查服务**: 确认目标服务正在运行
- **检查防火墙**: 确认防火墙规则允许

#### 3. 代理连接失败
- **检查代理配置**: 确认代理地址和端口正确
- **检查认证**: 确认代理认证信息正确
- **检查网络**: 确认网络连接正常

### 日志分析

#### 服务端日志
```bash
# 查看服务端日志
docker logs wlcn-server

# 查看详细日志
docker logs wlcn-server --tail 100 -f
```

#### 客户端日志
```bash
# 查看客户端日志
docker logs wlcn-client

# 查看详细日志
docker logs wlcn-client --tail 100 -f
```

## 📈 性能优化

### 系统调优

#### 1. 网络缓冲区优化
```bash
# Linux系统
sudo sysctl -w net.core.rmem_default=4194304
sudo sysctl -w net.core.rmem_max=4194304
sudo sysctl -w net.core.wmem_default=4194304
sudo sysctl -w net.core.wmem_max=4194304
```

#### 2. JVM 参数优化
```bash
# 生产环境推荐配置
-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200
```

#### 3. 连接池优化
- 调整 Netty 连接池大小
- 优化线程池配置
- 调整缓冲区大小

### 监控指标

#### 1. 系统监控
- CPU 使用率
- 内存使用率
- 网络 I/O

#### 2. 应用监控
- 连接数
- 流量统计
- 响应时间

## 🔒 安全说明

### 认证机制
- 支持 Token 认证
- 支持 AppKey/AppSecret 认证
- 支持代理认证

### 网络安全
- 支持 SSL/TLS 加密
- 支持流量加密传输
- 支持访问控制

### 数据安全
- 敏感信息加密存储
- 支持数据备份
- 支持审计日志

## 📞 技术支持

### 联系方式
- **作者**: 吴佳伟 (Jia Wei Wu)
- **邮箱**: 1207537021@qq.com
- **项目地址**: 
  - [Gitee](https://gitee.com/wujiawei1207537021/wu-lazy-cloud-network)
  - [GitHub](https://github.com/wujiawei1207537021/wu-lazy-cloud-network)

### 社区支持
- **Issues**: 通过 Git 平台提交问题
- **讨论**: 参与项目讨论
- **贡献**: 欢迎提交 Pull Request

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 许可证。

---

**版本**: 1.3.1-JDK24  
**更新时间**: 2024年  
**维护者**: 吴佳伟