feat: add UDP support for load balancing

gjmzj · gjmzj · commit e6861f052690 · 2026-02-12T08:21:11.000+08:00
diff --git a/README.md b/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README_CN.md)
 
-A lightweight Layer-4 TCP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.
+A lightweight Layer-4 TCP/UDP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.
 
 ## Features
 
-- **IPVS Kernel-Level Load Balancing**: High-performance Layer-4 forwarding powered by Linux IPVS
+- **IPVS Kernel-Level Load Balancing**: High-performance Layer-4 TCP/UDP forwarding powered by Linux IPVS
 - **Declarative Reconcile**: Automatically compares desired state with actual IPVS rules and applies incremental changes
 - **Multiple Scheduling Algorithms**: Round Robin (rr), Weighted Round Robin (wrr), Least Connection (lc), Weighted Least Connection (wlc), Destination Hashing (dh), Source Hashing (sh)
 - **TCP & HTTP Health Checks**: Independent health check configuration per service, supporting TCP connection probes and HTTP GET probes with configurable path and expected status code
@@ -70,6 +70,18 @@ services:
         weight: 1
       - address: 192.168.2.11:8443
         weight: 1
+
+  - name: dns-service
+    listen: 10.0.0.2:53
+    protocol: udp            # UDP load balancing
+    scheduler: rr
+    health_check:
+      enabled: false
+    backends:
+      - address: 192.168.3.10:53
+        weight: 1
+      - address: 192.168.3.11:53
+        weight: 1
 ```
 
 ### Usage
diff --git a/README_CN.md b/README_CN.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-基于 Linux IPVS 的四层 TCP 负载均衡工具，采用声明式 Reconcile 模式动态管理 IPVS 服务。
+基于 Linux IPVS 的四层 TCP/UDP 负载均衡工具，采用声明式 Reconcile 模式动态管理 IPVS 服务。
 
 ## 特性
 
-- **IPVS 内核级负载均衡**：基于 Linux IPVS 实现高性能四层转发
+- **IPVS 内核级负载均衡**：基于 Linux IPVS 实现高性能四层 TCP/UDP 转发
 - **声明式 Reconcile**：自动对比期望状态与实际 IPVS 规则，增量同步变更
 - **多种调度算法**：支持轮询 (rr)、加权轮询 (wrr)、最少连接 (lc)、加权最少连接 (wlc)、目标地址哈希 (dh)、源地址哈希 (sh)
 - **TCP & HTTP 健康检查**：每个服务独立配置检查参数，支持 TCP 连接探测和 HTTP GET 探测（可配置路径和期望状态码）
@@ -70,6 +70,18 @@ services:
         weight: 1
       - address: 192.168.2.11:8443
         weight: 1
+
+  - name: dns-service
+    listen: 10.0.0.2:53
+    protocol: udp            # UDP 负载均衡
+    scheduler: rr
+    health_check:
+      enabled: false
+    backends:
+      - address: 192.168.3.10:53
+        weight: 1
+      - address: 192.168.3.11:53
+        weight: 1
 ```
 
 ### 运行
diff --git a/cmd/ezlb/main.go b/cmd/ezlb/main.go
@@ -16,7 +16,7 @@ import (
 var (
 	BuildTime   string
 	BuildCommit string
-	Version     = "0.1.6"
+	Version     = "0.2.0"
 	configPath  string
 	showVersion bool
 )
diff --git a/docs/plans/09.扩展支持UDP流量负载均衡.plan.md b/docs/plans/09.扩展支持UDP流量负载均衡.plan.md
@@ -0,0 +1,82 @@
+### 扩展支持UDP流量负载均衡 ###
+在现有 TCP 负载均衡基础上扩展支持 UDP 协议。由于 IPVS 底层和类型转换层已完全支持 UDP，核心改动集中在配置校验层，同时需要处理同 IP:Port 不同协议的服务共存场景，并补充测试和文档。
+
+
+## 现状分析
+
+项目的 IPVS 操作层（`pkg/lvs/`）已经完全支持 UDP 协议：
+- `pkg/lvs/types.go` 的 `protocolFromString`/`protocolToString` 已处理 `"udp"` <-> `syscall.IPPROTO_UDP`
+- `pkg/lvs/ipvs_models.go` 的 `Service.Protocol` 是 `uint16`，天然支持 TCP/UDP
+- `pkg/lvs/ipvs_handle_linux.go` 和 `ipvs_handle_fake.go` 通过 protocol 字段区分服务，无需修改
+- `pkg/lvs/types_test.go` 已有 UDP 协议转换测试
+
+**唯一的阻塞点**在配置校验层 `pkg/config/config.go`，以及相关的测试和文档。
+
+## 实施步骤
+
+### 步骤 1：修改配置校验 — 允许 UDP 协议
+
+**文件**: `pkg/config/config.go`
+
+1. 将 `validProtocols` 从 `{"tcp": true}` 扩展为 `{"tcp": true, "udp": true}`
+2. 修改 `Validate` 函数中协议校验的错误信息，将 `(supported: tcp)` 改为 `(supported: tcp, udp)`
+3. 修改 `listenSet` 的去重 key，从单纯的 `svc.Listen`（即 `IP:Port`）改为 `svc.Listen + "/" + protocol`，因为 IPVS 允许同一 IP:Port 同时存在 TCP 和 UDP 服务
+
+### 步骤 2：补充配置校验单元测试
+
+**文件**: `pkg/config/config_test.go`
+
+新增测试用例：
+- `TestValidate_ProtocolUDP` — protocol 为 `udp` 时校验通过
+- `TestValidate_ProtocolEmptyDefaultsTCP` — 已有，确认 UDP 不影响默认行为
+- `TestValidate_SameListenDifferentProtocol` — 同一 IP:Port 分别配置 TCP 和 UDP 服务，校验通过（不报重复）
+- `TestValidate_SameListenSameProtocolDuplicate` — 同一 IP:Port 同一协议，校验报重复
+
+### 步骤 3：补充 Reconciler 单元测试
+
+**文件**: `pkg/lvs/reconciler_test.go`
+
+新增测试用例：
+- `TestReconcile_UDPService` — 验证 UDP 协议的 service 能正确创建和 reconcile
+- `TestReconcile_TCPAndUDPSameAddress` — 验证同一 IP:Port 的 TCP 和 UDP 服务能共存且独立管理
+
+### 步骤 4：更新示例配置
+
+**文件**: `examples/ezlb.yaml`
+
+新增一个 UDP 服务的示例配置，如 DNS 负载均衡场景：
+```yaml
+- name: dns-service
+  listen: 10.0.0.3:53
+  protocol: udp
+  scheduler: rr
+  health_check:
+    enabled: false
+  backends:
+    - address: 192.168.4.10:53
+      weight: 1
+    - address: 192.168.4.11:53
+      weight: 1
+```
+
+### 步骤 5：更新文档
+
+**文件**: `README.md`、`README_CN.md`
+
+1. 特性描述从 "Layer-4 TCP load balancer" 改为 "Layer-4 TCP/UDP load balancer"
+2. 配置示例中增加 UDP 服务示例
+3. 说明 `protocol` 字段支持 `tcp`（默认）和 `udp`
+
+## 不需要修改的模块
+
+- **`pkg/lvs/types.go`** — 已支持 UDP 协议转换
+- **`pkg/lvs/manager.go`** — 协议无关，无需修改
+- **`pkg/lvs/reconciler.go`** — 通过 `ServiceKey`（含 Protocol）区分服务，已支持
+- **`pkg/lvs/ipvs_handle*.go`** — 底层 IPVS 操作已支持 UDP
+- **`pkg/healthcheck/`** — 健康检查类型（TCP/HTTP）与服务协议独立，UDP 服务可选择禁用健康检查或使用 TCP/HTTP 探测
+- **`pkg/server/`** — 无协议相关逻辑
+
+
+updateAtTime: 2026/2/12 08:09:18
+
+planId: 845ead06-d442-4206-aae1-5044843630b5
diff --git a/examples/ezlb.yaml b/examples/ezlb.yaml
@@ -50,3 +50,15 @@ services:
         weight: 1
       - address: 192.168.3.11:9090
         weight: 1
+
+  - name: dns-service
+    listen: 10.0.0.3:53
+    protocol: udp
+    scheduler: rr
+    health_check:
+      enabled: false
+    backends:
+      - address: 192.168.4.10:53
+        weight: 1
+      - address: 192.168.4.11:53
+        weight: 1
diff --git a/pkg/config/config.go b/pkg/config/config.go
@@ -143,6 +143,7 @@ var validSchedulers = map[string]bool{
 // validProtocols is the set of supported protocols.
 var validProtocols = map[string]bool{
 	"tcp": true,
+	"udp": true,
 }
 
 // Manager handles configuration loading, validation, and hot-reload.
@@ -227,22 +228,23 @@ func Validate(cfg *Config) error {
 			return fmt.Errorf("service %q: listen port must be a positive number", svc.Name)
 		}
 
-		listenKey := svc.Listen
-		if listenSet[listenKey] {
-			return fmt.Errorf("service %q: duplicate listen address %q", svc.Name, svc.Listen)
-		}
-		listenSet[listenKey] = true
-
 		// Validate protocol (default to tcp)
 		protocol := svc.Protocol
 		if protocol == "" {
 			cfg.Services[i].Protocol = "tcp"
 			protocol = "tcp"
 		}
 		if !validProtocols[protocol] {
-			return fmt.Errorf("service %q: unsupported protocol %q (supported: tcp)", svc.Name, protocol)
+			return fmt.Errorf("service %q: unsupported protocol %q (supported: tcp, udp)", svc.Name, protocol)
 		}
 
+		// Deduplicate by listen address + protocol (IPVS allows same IP:Port for different protocols)
+		listenKey := svc.Listen + "/" + protocol
+		if listenSet[listenKey] {
+			return fmt.Errorf("service %q: duplicate listen address %q for protocol %q", svc.Name, svc.Listen, protocol)
+		}
+		listenSet[listenKey] = true
+
 		// Validate scheduler
 		if !validSchedulers[svc.Scheduler] {
 			return fmt.Errorf("service %q: unsupported scheduler %q (supported: rr, wrr, lc, wlc, dh, sh)", svc.Name, svc.Scheduler)
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
@@ -107,7 +107,7 @@ func TestValidate_ListenAddressDuplicate(t *testing.T) {
 	svc1 := validServiceConfig()
 	svc2 := validServiceConfig()
 	svc2.Name = "test-svc-2"
-	// same listen address as svc1
+	// same listen address and protocol as svc1
 	cfg := &Config{Services: []ServiceConfig{svc1, svc2}}
 	err := Validate(cfg)
 	if err == nil {
@@ -127,15 +127,52 @@ func TestValidate_ProtocolEmptyDefaultsTCP(t *testing.T) {
 	}
 }
 
-func TestValidate_ProtocolUnsupported(t *testing.T) {
+func TestValidate_ProtocolUDP(t *testing.T) {
 	cfg := validConfig()
 	cfg.Services[0].Protocol = "udp"
 	err := Validate(cfg)
+	if err != nil {
+		t.Fatalf("expected valid config with udp protocol, got: %v", err)
+	}
+}
+
+func TestValidate_ProtocolUnsupported(t *testing.T) {
+	cfg := validConfig()
+	cfg.Services[0].Protocol = "sctp"
+	err := Validate(cfg)
 	if err == nil {
 		t.Fatal("expected error for unsupported protocol, got nil")
 	}
 }
 
+func TestValidate_SameListenDifferentProtocol(t *testing.T) {
+	svc1 := validServiceConfig()
+	svc1.Protocol = "tcp"
+	svc2 := validServiceConfig()
+	svc2.Name = "test-svc-udp"
+	svc2.Protocol = "udp"
+	// Same listen address, different protocol — should be allowed
+	cfg := &Config{Services: []ServiceConfig{svc1, svc2}}
+	err := Validate(cfg)
+	if err != nil {
+		t.Fatalf("expected same listen address with different protocols to be valid, got: %v", err)
+	}
+}
+
+func TestValidate_SameListenSameProtocolDuplicate(t *testing.T) {
+	svc1 := validServiceConfig()
+	svc1.Protocol = "udp"
+	svc2 := validServiceConfig()
+	svc2.Name = "test-svc-2"
+	svc2.Protocol = "udp"
+	// Same listen address, same protocol — should be rejected
+	cfg := &Config{Services: []ServiceConfig{svc1, svc2}}
+	err := Validate(cfg)
+	if err == nil {
+		t.Fatal("expected error for duplicate listen address with same protocol, got nil")
+	}
+}
+
 func TestValidate_SchedulerUnsupported(t *testing.T) {
 	cfg := validConfig()
 	cfg.Services[0].Scheduler = "random"
diff --git a/pkg/lvs/reconciler_test.go b/pkg/lvs/reconciler_test.go
@@ -1,6 +1,7 @@
 package lvs
 
 import (
+	"syscall"
 	"testing"
 
 	"github.com/easzlab/ezlb/pkg/config"
@@ -488,6 +489,107 @@ func TestReconcile_BackendRecovery(t *testing.T) {
 	}
 }
 
+// --- UDP protocol tests ---
+
+func TestReconcile_UDPService(t *testing.T) {
+	mgr, _, reconciler := newReconcilerTestEnv(t)
+	defer mgr.Close()
+
+	configs := []config.ServiceConfig{
+		{
+			Name:      "dns-svc",
+			Listen:    "10.0.0.1:53",
+			Protocol:  "udp",
+			Scheduler: "rr",
+			HealthCheck: config.HealthCheckConfig{
+				Enabled: boolPtr(false),
+			},
+			Backends: []config.BackendConfig{
+				makeBackend("192.168.1.1:53", 1),
+				makeBackend("192.168.1.2:53", 1),
+			},
+		},
+	}
+
+	if err := reconciler.Reconcile(configs); err != nil {
+		t.Fatalf("Reconcile failed: %v", err)
+	}
+
+	services, err := mgr.GetServices()
+	if err != nil {
+		t.Fatalf("GetServices failed: %v", err)
+	}
+	if len(services) != 1 {
+		t.Fatalf("expected 1 service, got %d", len(services))
+	}
+	if services[0].Protocol != syscall.IPPROTO_UDP {
+		t.Errorf("expected protocol IPPROTO_UDP (%d), got %d", syscall.IPPROTO_UDP, services[0].Protocol)
+	}
+
+	dests, err := mgr.GetDestinations(services[0])
+	if err != nil {
+		t.Fatalf("GetDestinations failed: %v", err)
+	}
+	if len(dests) != 2 {
+		t.Fatalf("expected 2 destinations, got %d", len(dests))
+	}
+}
+
+func TestReconcile_TCPAndUDPSameAddress(t *testing.T) {
+	mgr, _, reconciler := newReconcilerTestEnv(t)
+	defer mgr.Close()
+
+	configs := []config.ServiceConfig{
+		{
+			Name:      "dns-tcp",
+			Listen:    "10.0.0.1:53",
+			Protocol:  "tcp",
+			Scheduler: "rr",
+			HealthCheck: config.HealthCheckConfig{
+				Enabled: boolPtr(false),
+			},
+			Backends: []config.BackendConfig{
+				makeBackend("192.168.1.1:53", 1),
+			},
+		},
+		{
+			Name:      "dns-udp",
+			Listen:    "10.0.0.1:53",
+			Protocol:  "udp",
+			Scheduler: "rr",
+			HealthCheck: config.HealthCheckConfig{
+				Enabled: boolPtr(false),
+			},
+			Backends: []config.BackendConfig{
+				makeBackend("192.168.1.2:53", 2),
+			},
+		},
+	}
+
+	if err := reconciler.Reconcile(configs); err != nil {
+		t.Fatalf("Reconcile failed: %v", err)
+	}
+
+	services, err := mgr.GetServices()
+	if err != nil {
+		t.Fatalf("GetServices failed: %v", err)
+	}
+	if len(services) != 2 {
+		t.Fatalf("expected 2 services (TCP + UDP), got %d", len(services))
+	}
+
+	// Verify each service has its own destinations
+	for _, svc := range services {
+		dests, err := mgr.GetDestinations(svc)
+		if err != nil {
+			t.Fatalf("GetDestinations failed: %v", err)
+		}
+		if len(dests) != 1 {
+			t.Errorf("expected 1 destination per service, got %d for protocol %d", len(dests), svc.Protocol)
+		}
+	}
+}
+
 // --- Error handling ---
 
 func TestReconcile_InvalidListenAddress(t *testing.T) {

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ import (`
`16`	`16`	`var (`
`17`	`17`	`BuildTime string`
`18`	`18`	`BuildCommit string`
`19`		`- Version = "0.1.6"`
	`19`	`+ Version = "0.2.0"`
`20`	`20`	`configPath string`
`21`	`21`	`showVersion bool`
`22`	`22`	`)`