# Netty Load Balancer

**Repository Path**: leefine/netty-load-balancer

## Basic Information

- **Project Name**: Netty Load Balancer
- **Description**: 基于 Netty 的高性能多协议负载均衡器，提供 Web 管理界面，支持 HTTP / TCP 代理，内置 5 种负载均衡算法，具备后端健康检查、实时统计、配置持久化与自动拉起能力。支持RDP,SSH，数据库等端口的转发。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Netty Load Balancer

基于 Netty 的高性能多协议负载均衡器，提供 Web 管理界面，支持 HTTP / TCP 代理，内置 5 种负载均衡算法，具备后端健康检查、实时统计、配置持久化与自动拉起能力。

---

## 功能特性

### 代理引擎

- **HTTP 代理** — 基于 `HttpServerCodec` / `HttpClientCodec` 流式转发，不使用 `HttpObjectAggregator`，避免大响应体阻塞导致 `ERR_EMPTY_RESPONSE`
- **TCP 代理** — 原始字节流双向透传，支持 RDP、SSH 等任意 TCP 协议
- **消息缓冲队列** — 后端连接建立前暂存客户端数据（HTTP 使用 `Queue<Object>`，TCP 使用 `Queue<ByteBuf>`），连接就绪后自动刷新，解决异步连接竞态条件
- **空闲超时检测** — HTTP 代理 60s/30s 读写超时，TCP 代理 300s/300s 读写超时，通过 `IdleStateHandler` 自动关闭僵死连接
- **X-Forwarded-For 注入** — HTTP 代理自动追加客户端真实 IP 到请求头，支持多级代理链
- **连接生命周期绑定** — 前端/后端通道双向绑定，任一端关闭自动关闭另一端；`channelInactive` 统一处理连接计数递减，防止计数泄漏

### 负载均衡

- **5 种算法** — 轮询、加权轮询、随机、最少连接、一致性哈希
- **策略模式** — `LoadBalanceStrategy` 接口 + `StrategyFactory` 工厂，算法可插拔
- **一致性哈希** — 160 虚拟节点/物理节点，基于客户端 IP 哈希，MD5 哈希函数，懒重建哈希环
- **健康感知路由** — 请求优先分发到健康节点，全部不健康时降级为全量分发

### 运维能力

- **后端健康检查** — 每 15 秒 TCP 连接探测（5s 超时），故障自动摘除，恢复自动加入
- **实时统计** — 活跃连接数、请求数、传输字节数，支持全局概览与单实例详情，前端 6 秒自动刷新
- **配置持久化** — 所有配置保存至 `config.json`，多路径解析兼容 IDE 运行与 fat-jar 部署
- **自动拉起** — 实现 `ApplicationRunner`，应用启动后自动启动所有已保存的负载均衡实例
- **优雅关闭** — `@PreDestroy` 统一停止所有代理与健康检查任务

### Web 管理界面

- 基于 Bootstrap 5 + Bootstrap Icons，前端资源本地离线部署（`vendor/` 目录）
- 概览仪表盘：总配置数、运行中数量、总连接数、总流量
- 实例管理：创建 / 编辑 / 启停 / 删除，后端服务器动态添加与权重配置
- Bearer Token 认证，`AuthInterceptor` 拦截 `/api/**`，排除 `/api/auth/**`

---

## 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 网络框架 | Netty | 4.1.137.Final |
| 应用框架 | Spring Boot | 2.7.18 |
| JDK | Java | 1.8+ |
| 构建工具 | Maven | 3.x |
| 序列化 | Jackson | Spring Boot 内置 |
| 前端 UI | Bootstrap 5 + Bootstrap Icons | 离线本地部署 |

---

## 快速开始

### 环境要求

- JDK 1.8+
- Maven 3.x

### 编译与启动

```bash
git clone <repo-url>
cd Netty-LoadBalancer
mvn clean package -DskipTests
java -jar target/netty-loadbalancer-1.0.0.jar
```

启动后访问 `http://localhost:8080` 进入 Web 管理界面。

### 自定义端口

```bash
java -jar target/netty-loadbalancer-1.0.0.jar --server.port=9090
```

---

## 架构设计

```
                          ┌─────────────────────────────────┐
                          │      Web 管理界面 (:8080)        │
                          │  Bootstrap 5 + REST API + Token  │
                          └────────────┬────────────────────┘
                                       │
                          ┌────────────▼────────────────────┐
                          │     LoadBalancerManager          │
                          │  ApplicationRunner + @PreDestroy  │
                          └──┬──────────┬──────────┬────────┘
                             │          │          │
              ┌──────────────▼──┐  ┌────▼─────┐  ┌▼──────────────┐
              │ HttpProxyServer │  │TcpProxy  │  │HealthCheck    │
              │ (流式HTTP转发)   │  │Server    │  │Service        │
              │                 │  │(原始字节) │  │(15s TCP探测)  │
              └───────┬─────────┘  └────┬─────┘  └───────────────┘
                      │                 │
              ┌───────▼─────────────────▼──────┐
              │     LoadBalanceStrategy         │
              │  RR / WRR / Rand / LC / CHash   │
              └───────┬─────────────────────────┘
                      │
              ┌───────▼─────────────────────────┐
              │        Backend Servers           │
              │  (健康节点优先，全挂降级全量)       │
              └──────────────────────────────────┘
```

### 代理层

| 特性 | HTTP 代理 | TCP 代理 |
|------|----------|---------|
| Pipeline | `HttpServerCodec` + `IdleStateHandler` | `IdleStateHandler`（原始字节） |
| 超时 | 读 60s / 写 30s | 读 300s / 写 300s |
| 缓冲队列 | `Queue<Object>`（HttpObject） | `Queue<ByteBuf>`（原始字节） |
| 流式转发 | 无聚合器，逐 chunk 转发 | 双向透传 |
| X-Forwarded-For | 自动注入 | 不适用 |
| SO_BACKLOG | 128 | 1024 |
| 连接超时 | 5s | 10s |

### 负载均衡层

| 算法 | 实现类 | 说明 |
|------|--------|------|
| 轮询 | `RoundRobinStrategy` | `AtomicInteger` 计数器取模 |
| 加权轮询 | `WeightedRoundRobinStrategy` | 按权重展开列表后取模 |
| 随机 | `RandomStrategy` | `ThreadLocalRandom` 随机选取 |
| 最少连接 | `LeastConnectionStrategy` | 遍历比较 `activeConnections` |
| 一致性哈希 | `ConsistentHashStrategy` | 160 虚拟节点，`TreeMap` 哈希环，客户端 IP 作为哈希 key |

### 服务层

| 服务 | 职责 |
|------|------|
| `LoadBalancerManager` | 核心管理器：启停代理、自动拉起、优雅关闭、统计聚合 |
| `HealthCheckService` | 定时调度 TCP 探测任务，每实例独立 `ScheduledFuture` |
| `ConfigPersistenceService` | JSON 文件持久化，`CopyOnWriteArrayList` 线程安全存储，多路径解析 |
| `UserService` | 用户凭据管理（`user.json`），MD5 密码存储，内存 Token 会话 |

---

## REST API

### 认证接口（无需 Token）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/auth/status` | 获取认证状态（`setupComplete`、`authenticated`） |
| POST | `/api/auth/setup` | 初始化管理员账号（仅首次） |
| POST | `/api/auth/login` | 登录，返回 `token` 和 `username` |
| POST | `/api/auth/logout` | 登出，销毁 Token |

### 负载均衡管理接口（需 `Authorization: Bearer <token>`）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/configs` | 获取所有负载均衡配置 |
| POST | `/api/configs` | 创建配置（自动检测端口冲突） |
| PUT | `/api/configs/{id}` | 更新配置 |
| DELETE | `/api/configs/{id}` | 删除配置（自动停止运行中的实例） |
| POST | `/api/configs/{id}/start` | 启动实例（自动端口检测 + 健康检查） |
| POST | `/api/configs/{id}/stop` | 停止实例 |
| GET | `/api/configs/{id}/stats` | 获取单实例实时统计（含各后端节点详情） |
| GET | `/api/stats/overview` | 获取全局概览（总配置数、运行数、总连接/请求/流量） |

---

## 配置说明

### application.yml

```yaml
server:
  port: 8080

spring:
  application:
    name: netty-loadbalancer
  jackson:
    serialization:
      indent-output: true

logging:
  file:
    path: ${LOG_PATH:.}       # 日志目录，可通过环境变量 LOG_PATH 覆盖
  level:
    com.loadbalancer: INFO
    io.netty: WARN
```

### config.json

所有负载均衡实例配置自动保存至运行目录下的 `config.json`，结构：

```json
[{
  "id": "e9214766",
  "name": "Web",
  "listenPort": 80,
  "protocol": "HTTP",
  "algorithm": "ROUND_ROBIN",
  "status": "RUNNING",
  "backendServers": [
    { "ip": "10.0.0.1", "port": 8080, "weight": 1 },
    { "ip": "10.0.0.2", "port": 8080, "weight": 2 }
  ],
  "createTime": 1788400807071
}]
```

配置文件路径解析优先级：当前工作目录 → JAR 包所在目录 → 自动创建。

---

## 项目结构

```
src/main/java/com/loadbalancer/
├── balance/                          # 负载均衡算法策略
│   ├── LoadBalanceStrategy.java      # 策略接口
│   ├── RoundRobinStrategy.java       # 轮询
│   ├── WeightedRoundRobinStrategy.java  # 加权轮询
│   ├── RandomStrategy.java           # 随机
│   ├── LeastConnectionStrategy.java  # 最少连接
│   ├── ConsistentHashStrategy.java   # 一致性哈希（160 虚拟节点）
│   └── StrategyFactory.java          # 策略工厂
├── config/
│   ├── WebConfig.java                # CORS 配置 + 拦截器注册
│   └── AuthInterceptor.java          # Bearer Token 认证拦截
├── controller/
│   ├── LoadBalancerController.java   # 负载均衡 CRUD / 启停 / 统计
│   └── AuthController.java           # 认证：登录 / 登出 / 初始化
├── model/
│   ├── Algorithm.java                # 算法枚举
│   ├── BackendServer.java            # 后端节点（AtomicLong 运行时统计）
│   ├── LoadBalancerConfig.java       # 实例配置
│   └── LoadBalancerStats.java        # 运行统计快照
├── proxy/
│   ├── HttpProxyServer.java          # HTTP 代理服务（流式转发）
│   ├── HttpProxyFrontendHandler.java # HTTP 前端（缓冲队列 + X-Forwarded-For）
│   ├── HttpProxyBackendHandler.java  # HTTP 后端（响应回传 + 字节统计）
│   ├── TcpProxyServer.java           # TCP 代理服务（原始字节流）
│   ├── TcpProxyFrontendHandler.java  # TCP 前端（缓冲队列 + 超时检测）
│   └── TcpProxyBackendHandler.java   # TCP 后端（双向透传 + 字节统计）
└── service/
    ├── LoadBalancerManager.java      # 核心管理器（自动拉起 + 优雅关闭）
    ├── HealthCheckService.java       # 健康检查（15s TCP 探测）
    ├── ConfigPersistenceService.java # 配置持久化（多路径解析）
    ├── UserService.java              # 用户认证（MD5 + Token 会话）
    └── ProxyServer.java              # 代理服务器接口

src/main/resources/
├── static/
│   ├── index.html                    # 管理主界面
│   ├── login.html                    # 登录 / 初始配置页
│   ├── css/app.css                   # 自定义样式
│   ├── js/app.js                     # 前端逻辑（6s 自动刷新）
│   └── vendor/                       # Bootstrap 5 离线资源
├── application.yml                   # 应用配置
└── logback-spring.xml                # 日志配置
```

---

## 许可证

Apache License 2.0