feat: add cleanup on exit functionality for IPVS and iptables rules, bump version to 0.3.2

Author: gjmzj

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.25 as builder
+FROM golang:1.25 AS builder
 ARG TARGETOS
 ARG TARGETARCH
 ENV GOPROXY="https://goproxy.cn,direct"
@@ -21,7 +21,8 @@ RUN make build
 
 ## runtime image
 FROM debian:bookworm-slim
-ENV LANG C.UTF-8
+ENV LANG=C.UTF-8
+ENV TZ=Asia/Shanghai
 
 # runtime dependencies
 RUN set -eux; \
@@ -49,7 +50,6 @@ RUN set -eux; \
 	; \
 	rm -rf /var/lib/apt/lists/*
 
-ENV TZ=Asia/Shanghai
 WORKDIR /app
 
 COPY --from=builder /workspace/build/* /app/

README.md

@@ -34,6 +34,7 @@ Create a config file `config.yaml`:
 ```yaml
 global:
   log_level: info
+  cleanup_on_exit: true    # Remove managed IPVS services and EZLB-SNAT iptables chain on exit (default: true)
 
 services:
   - name: web-service

README_CN.md

@@ -34,6 +34,7 @@ make build-linux
 ```yaml
 global:
   log_level: info
+  cleanup_on_exit: true    # 退出时删除 ezlb 管理的 IPVS 服务和 EZLB-SNAT iptables 链（默认: true）
 
 services:
   - name: web-service

cmd/ezlb/main.go

@@ -16,7 +16,7 @@ import (
 var (
 	BuildTime   string
 	BuildCommit string
-	Version     = "0.3.1"
+	Version     = "0.3.2"
 	configPath  string
 	showVersion bool
 )

docs/deploy/start-container.sh

@@ -18,6 +18,7 @@ docker run -d \
   --cap-add NET_ADMIN \
   --cap-add NET_RAW \
   --restart unless-stopped \
+  -v /lib/modules:/lib/modules:ro \
   -v ./config.yaml:/app/config.yaml \
   easzlab/ezlb:latest \
   /app/ezlb start -c /app/config.yaml

docs/plans/11.支持退出时清理ipvs等规则.plan.md

@@ -0,0 +1,226 @@
+### cleanup-on-exit ###
+在实现 cleanup_on_exit 功能的基础上，补充单元测试（config、reconciler）、e2e 测试（daemon 模式清理/保留行为）以及 README/README_CN 文档更新。
+
+# 进程退出时按需清理 IPVS 和 iptables 规则
+
+添加 `cleanup_on_exit` 全局配置项（默认 `true`），控制 ezlb 退出时是否删除自身管理的 IPVS 虚拟服务/后端及 iptables SNAT 规则。IPVS 精确删除 ezlb 管理的服务，不影响系统中其他 IPVS 规则；iptables 删除整个 `EZLB-SNAT` 链（该链为本项目专用）。同步补充单元测试、e2e 测试和文档。
+
+## Proposed Changes
+
+---
+
+### config — 新增 cleanup_on_exit 配置项
+
+#### [MODIFY] [config.go](file:///Users/jin.gjm/code/go-network/ezlb/pkg/config/config.go)
+
+在 `GlobalConfig` 中新增字段，并添加 `IsCleanupOnExit()` 方法：
+
+```diff
+ type GlobalConfig struct {
+-    LogLevel string `yaml:"log_level" mapstructure:"log_level"`
++    LogLevel      string `yaml:"log_level"       mapstructure:"log_level"`
++    CleanupOnExit *bool  `yaml:"cleanup_on_exit" mapstructure:"cleanup_on_exit"`
+ }
+
++// IsCleanupOnExit returns whether to clean up IPVS and iptables rules on exit.
++// Defaults to true if not explicitly set.
++func (g GlobalConfig) IsCleanupOnExit() bool {
++    if g.CleanupOnExit == nil {
++        return true
++    }
++    return *g.CleanupOnExit
++}
+```
+
+在 `NewManager` 中设置 viper 默认值：
+
+```diff
+ viperInstance.SetDefault("global.log_level", "info")
++viperInstance.SetDefault("global.cleanup_on_exit", true)
+```
+
+---
+
+### lvs — Reconciler 新增精确清理方法
+
+#### [MODIFY] [reconciler.go](file:///Users/jin.gjm/code/go-network/ezlb/pkg/lvs/reconciler.go)
+
+新增 `Cleanup()` 方法，遍历 `r.managed` 精确删除 ezlb 管理的 IPVS 服务，不影响系统中其他 IPVS 规则：
+
+```go
+// Cleanup removes all IPVS services currently managed by this Reconciler.
+// It only deletes services tracked in the managed map, leaving other IPVS
+// rules untouched.
+func (r *Reconciler) Cleanup() error {
+    r.mu.Lock()
+    defer r.mu.Unlock()
+
+    actualServices, err := r.manager.GetServices()
+    if err != nil {
+        return fmt.Errorf("failed to get IPVS services for cleanup: %w", err)
+    }
+
+    actualMap := make(map[ServiceKey]*Service)
+    for _, svc := range actualServices {
+        actualMap[ServiceKeyFromIPVS(svc)] = svc
+    }
+
+    var errs []error
+    for key := range r.managed {
+        svc, exists := actualMap[key]
+        if !exists {
+            delete(r.managed, key)
+            continue
+        }
+        if err := r.manager.DeleteService(svc); err != nil {
+            errs = append(errs, fmt.Errorf("delete service %s: %w", key, err))
+        } else {
+            delete(r.managed, key)
+        }
+    }
+
+    if len(errs) > 0 {
+        return errors.Join(errs...)
+    }
+    r.logger.Info("cleaned up all managed IPVS services")
+    return nil
+}
+```
+
+---
+
+### server — shutdown 逻辑按配置分支
+
+#### [MODIFY] [server.go](file:///Users/jin.gjm/code/go-network/ezlb/pkg/server/server.go)
+
+```diff
+ func (s *Server) shutdown() {
+     s.healthMgr.Stop()
+-    if err := s.snatMgr.Cleanup(); err != nil {
+-        s.logger.Error("failed to cleanup SNAT rules", zap.Error(err))
+-    }
++    cfg := s.configMgr.GetConfig()
++    if cfg.Global.IsCleanupOnExit() {
++        if err := s.reconciler.Cleanup(); err != nil {
++            s.logger.Error("failed to cleanup IPVS rules", zap.Error(err))
++        }
++        if err := s.snatMgr.Cleanup(); err != nil {
++            s.logger.Error("failed to cleanup SNAT rules", zap.Error(err))
++        }
++    } else {
++        s.logger.Info("cleanup_on_exit is false, preserving IPVS and iptables rules")
++    }
+     s.lvsMgr.Close()
+     s.logger.Info("server stopped")
+ }
+```
+
+---
+
+### examples — 更新示例配置
+
+#### [MODIFY] [ezlb.yaml](file:///Users/jin.gjm/code/go-network/ezlb/examples/ezlb.yaml)
+
+```diff
+ global:
+   log_level: info
++  # cleanup_on_exit: true  # Remove managed IPVS services and EZLB-SNAT iptables chain on exit (default: true)
+```
+
+---
+
+### 单元测试
+
+#### [MODIFY] [config_test.go](file:///Users/jin.gjm/code/go-network/ezlb/pkg/config/config_test.go)
+
+在现有测试文件末尾追加 `GlobalConfig.IsCleanupOnExit()` 的测试用例：
+
+- `TestGlobalConfig_IsCleanupOnExit_DefaultTrue` — `CleanupOnExit` 为 nil 时返回 true
+- `TestGlobalConfig_IsCleanupOnExit_ExplicitTrue` — 显式设置 true 时返回 true
+- `TestGlobalConfig_IsCleanupOnExit_ExplicitFalse` — 显式设置 false 时返回 false
+- `TestManager_LoadYAML_CleanupOnExitDefault` — 不配置时加载后默认为 true
+- `TestManager_LoadYAML_CleanupOnExitFalse` — 配置 `cleanup_on_exit: false` 后加载正确
+
+#### [MODIFY] [reconciler_test.go](file:///Users/jin.gjm/code/go-network/ezlb/pkg/lvs/reconciler_test.go)
+
+追加 `Reconciler.Cleanup()` 的测试用例：
+
+- `TestReconciler_Cleanup_RemovesManagedServices` — reconcile 后调用 Cleanup，验证 managed 服务被删除
+- `TestReconciler_Cleanup_PreservesUnmanagedServices` — 手动创建一个 ezlb 未管理的服务，调用 Cleanup 后该服务仍然存在
+- `TestReconciler_Cleanup_EmptyManaged` — managed 为空时调用 Cleanup 不报错
+- `TestReconciler_Cleanup_WithFullNATService` — 包含 FullNAT 服务时，Cleanup 正确删除 IPVS 服务（SNAT 清理由 snatMgr 负责，此处验证 IPVS 部分）
+
+---
+
+### e2e 测试
+
+#### [MODIFY] [e2e_test.go](file:///Users/jin.gjm/code/go-network/ezlb/tests/e2e/e2e_test.go)
+
+追加两个 daemon 模式测试用例：
+
+**Test 9: `cleanup_on_exit: true`（默认）— 退出后 IPVS 规则被清理**
+
+```
+TestE2E_DaemonMode_CleanupOnExit_True
+```
+- 启动 daemon，配置 `cleanup_on_exit: true`
+- 等待初始 reconcile 完成，验证 IPVS 服务存在
+- 发送 SIGTERM，等待进程退出
+- 验证 IPVS 中对应服务已被删除
+
+**Test 10: `cleanup_on_exit: false` — 退出后 IPVS 规则保留**
+
+```
+TestE2E_DaemonMode_CleanupOnExit_False
+```
+- 启动 daemon，配置 `cleanup_on_exit: false`
+- 等待初始 reconcile 完成，验证 IPVS 服务存在
+- 发送 SIGTERM，等待进程退出
+- 验证 IPVS 中对应服务仍然存在
+
+---
+
+### 文档更新
+
+#### [MODIFY] [README.md](file:///Users/jin.gjm/code/go-network/ezlb/README.md)
+
+在配置参考章节的 `global` 部分新增 `cleanup_on_exit` 字段说明。
+
+#### [MODIFY] [README_CN.md](file:///Users/jin.gjm/code/go-network/ezlb/README_CN.md)
+
+同步更新中文文档，在 `global` 配置说明中新增 `cleanup_on_exit` 字段。
+
+## Verification Plan
+
+### Automated Tests
+
+```bash
+# 单元测试（全平台）
+go test ./pkg/config/... ./pkg/lvs/... ./pkg/snat/...
+
+# e2e 测试（需要 Linux + root）
+go test -v -tags integration ./tests/e2e/...
+```
+
+### Manual Verification
+
+- Linux 环境下启动 ezlb，配置 `cleanup_on_exit: true`，发送 SIGTERM，验证 `ipvsadm -L` 中对应服务已删除，`iptables -t nat -L` 中 `EZLB-SNAT` 链已消失
+- 配置 `cleanup_on_exit: false`，发送 SIGTERM，验证 IPVS 规则和 `EZLB-SNAT` 链均保留
+
+
+## Tasks
+
+- [ ] **pkg/config/config.go** — GlobalConfig 新增 `CleanupOnExit *bool` 字段、`IsCleanupOnExit()` 方法，viper 设置默认值 true
+- [ ] **pkg/lvs/reconciler.go** — 新增 `Cleanup()` 方法，精确删除 managed 的 IPVS 服务
+- [ ] **pkg/server/server.go** — `shutdown()` 按 `IsCleanupOnExit()` 分支调用清理或跳过
+- [ ] **examples/ezlb.yaml** — 添加 `cleanup_on_exit` 注释说明
+- [ ] **pkg/config/config_test.go** — 追加 `IsCleanupOnExit()` 和配置加载相关单元测试（5 个用例）
+- [ ] **pkg/lvs/reconciler_test.go** — 追加 `Reconciler.Cleanup()` 单元测试（4 个用例）
+- [ ] **tests/e2e/e2e_test.go** — 追加 daemon 模式 cleanup_on_exit=true 和 false 的 e2e 测试（2 个用例）
+- [ ] **README.md** — 在 global 配置章节新增 `cleanup_on_exit` 字段说明
+- [ ] **README_CN.md** — 同步更新中文文档
+- [ ] 运行 `go test ./pkg/config/... ./pkg/lvs/... ./pkg/snat/...` 验证无编译错误和测试回归
+
+updateAtTime: 2026/3/16 11:13:24
+
+planId: 138ca5d8-5bcf-4e88-a5e3-ce78d9816ba6

examples/ezlb.yaml

@@ -1,5 +1,6 @@
 global:
   log_level: info
+  # cleanup_on_exit: true  # Remove managed IPVS services and EZLB-SNAT iptables chain on exit (default: true)
 
 services:
   - name: web-service

pkg/config/config.go

@@ -19,7 +19,17 @@ type Config struct {
 
 // GlobalConfig holds global settings.
 type GlobalConfig struct {
-	LogLevel string `yaml:"log_level" mapstructure:"log_level"`
+	LogLevel      string `yaml:"log_level"       mapstructure:"log_level"`
+	CleanupOnExit *bool  `yaml:"cleanup_on_exit" mapstructure:"cleanup_on_exit"`
+}
+
+// IsCleanupOnExit returns whether to clean up IPVS and iptables rules on exit.
+// Defaults to true if not explicitly set.
+func (g GlobalConfig) IsCleanupOnExit() bool {
+	if g.CleanupOnExit == nil {
+		return true
+	}
+	return *g.CleanupOnExit
 }
 
 // ServiceConfig defines a virtual service with its backends and health check settings.
@@ -165,6 +175,7 @@ func NewManager(configPath string, logger *zap.Logger) (*Manager, error) {
 
 	// Set defaults
 	viperInstance.SetDefault("global.log_level", "info")
+	viperInstance.SetDefault("global.cleanup_on_exit", true)
 
 	manager := &Manager{
 		viper:      viperInstance,

pkg/config/config_test.go

@@ -654,3 +654,66 @@ func TestManager_OnChangeChannel(t *testing.T) {
 		t.Fatal("expected OnChange to return non-nil channel")
 	}
 }
+
+// --- GlobalConfig.IsCleanupOnExit tests ---
+
+func TestGlobalConfig_IsCleanupOnExit_DefaultTrue(t *testing.T) {
+	g := GlobalConfig{}
+	if !g.IsCleanupOnExit() {
+		t.Error("expected IsCleanupOnExit to return true when CleanupOnExit is nil")
+	}
+}
+
+func TestGlobalConfig_IsCleanupOnExit_ExplicitTrue(t *testing.T) {
+	g := GlobalConfig{CleanupOnExit: boolPtr(true)}
+	if !g.IsCleanupOnExit() {
+		t.Error("expected IsCleanupOnExit to return true when CleanupOnExit is explicitly true")
+	}
+}
+
+func TestGlobalConfig_IsCleanupOnExit_ExplicitFalse(t *testing.T) {
+	g := GlobalConfig{CleanupOnExit: boolPtr(false)}
+	if g.IsCleanupOnExit() {
+		t.Error("expected IsCleanupOnExit to return false when CleanupOnExit is explicitly false")
+	}
+}
+
+func TestManager_LoadYAML_CleanupOnExitDefault(t *testing.T) {
+	// cleanup_on_exit not set in YAML — should default to true
+	path := writeTestYAML(t, validYAML)
+	mgr, err := NewManager(path, zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewManager failed: %v", err)
+	}
+	cfg := mgr.GetConfig()
+	if !cfg.Global.IsCleanupOnExit() {
+		t.Error("expected IsCleanupOnExit to return true when not set in config")
+	}
+}
+
+func TestManager_LoadYAML_CleanupOnExitFalse(t *testing.T) {
+	yaml := `
+global:
+  log_level: info
+  cleanup_on_exit: false
+services:
+  - name: web-service
+    listen: 10.0.0.1:80
+    protocol: tcp
+    scheduler: rr
+    health_check:
+      enabled: false
+    backends:
+      - address: 192.168.1.10:8080
+        weight: 1
+`
+	path := writeTestYAML(t, yaml)
+	mgr, err := NewManager(path, zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewManager failed: %v", err)
+	}
+	cfg := mgr.GetConfig()
+	if cfg.Global.IsCleanupOnExit() {
+		t.Error("expected IsCleanupOnExit to return false when cleanup_on_exit: false in config")
+	}
+}