feat: add HTTP health check support

gjmzj · gjmzj · commit e08527fa096f · 2026-02-11T07:38:22.000+08:00
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ A lightweight Layer-4 TCP load balancer based on Linux IPVS, using declarative r
 - **IPVS Kernel-Level Load Balancing**: High-performance Layer-4 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 Health Checks**: Independent health check configuration per service, with option to disable
+- **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
 - **Hot Config Reload**: File changes automatically trigger reconciliation without restart
 
 ## Quick Start
@@ -41,6 +41,7 @@ services:
     scheduler: wrr
     health_check:
       enabled: true
+      type: tcp              # optional: tcp (default), http
       interval: 5s
       timeout: 3s
       fail_count: 3
@@ -50,6 +51,25 @@ services:
         weight: 5
       - address: 192.168.1.11:8080
         weight: 3
+
+  - name: api-service
+    listen: 10.0.0.1:443
+    protocol: tcp
+    scheduler: wlc
+    health_check:
+      enabled: true
+      type: http             # HTTP health check
+      interval: 10s
+      timeout: 5s
+      fail_count: 5
+      rise_count: 3
+      http_path: /healthz            # default: /
+      http_expected_status: 200      # default: 200
+    backends:
+      - address: 192.168.2.10:8443
+        weight: 1
+      - address: 192.168.2.11:8443
+        weight: 1
 ```
 
 ### Usage
@@ -86,7 +106,7 @@ ezlb/
 ├── pkg/
 │   ├── config/           # Config management (loading, validation, hot reload)
 │   ├── lvs/              # IPVS management (operations, reconcile)
-│   ├── healthcheck/      # Health checking (TCP probes)
+│   ├── healthcheck/      # Health checking (TCP & HTTP probes)
 │   └── server/           # Server orchestration (lifecycle management)
 ├── tests/e2e/            # End-to-end tests
 ├── examples/             # Example configurations
diff --git a/README_CN.md b/README_CN.md
@@ -9,7 +9,7 @@
 - **IPVS 内核级负载均衡**：基于 Linux IPVS 实现高性能四层转发
 - **声明式 Reconcile**：自动对比期望状态与实际 IPVS 规则，增量同步变更
 - **多种调度算法**：支持轮询 (rr)、加权轮询 (wrr)、最少连接 (lc)、加权最少连接 (wlc)、目标地址哈希 (dh)、源地址哈希 (sh)
-- **TCP 健康检查**：每个服务独立配置检查参数，支持禁用
+- **TCP & HTTP 健康检查**：每个服务独立配置检查参数，支持 TCP 连接探测和 HTTP GET 探测（可配置路径和期望状态码）
 - **配置热加载**：修改配置文件自动触发 Reconcile，无需重启
 
 ## 快速开始
@@ -41,6 +41,7 @@ services:
     scheduler: wrr
     health_check:
       enabled: true
+      type: tcp              # 可选: tcp（默认）、http
       interval: 5s
       timeout: 3s
       fail_count: 3
@@ -50,6 +51,25 @@ services:
         weight: 5
       - address: 192.168.1.11:8080
         weight: 3
+
+  - name: api-service
+    listen: 10.0.0.1:443
+    protocol: tcp
+    scheduler: wlc
+    health_check:
+      enabled: true
+      type: http             # HTTP 健康检查
+      interval: 10s
+      timeout: 5s
+      fail_count: 5
+      rise_count: 3
+      http_path: /healthz            # 默认: /
+      http_expected_status: 200      # 默认: 200
+    backends:
+      - address: 192.168.2.10:8443
+        weight: 1
+      - address: 192.168.2.11:8443
+        weight: 1
 ```
 
 ### 运行
@@ -86,7 +106,7 @@ ezlb/
 ├── pkg/
 │   ├── config/           # 配置管理（加载、校验、热加载）
 │   ├── lvs/              # IPVS 管理（操作封装、Reconcile）
-│   ├── healthcheck/      # 健康检查（TCP 探测）
+│   ├── healthcheck/      # 健康检查（TCP & HTTP 探测）
 │   └── server/           # 服务编排（生命周期管理）
 ├── tests/e2e/            # 端到端测试
 ├── examples/             # 示例配置
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.5"
+	Version     = "0.1.6"
 	configPath  string
 	showVersion bool
 )
diff --git a/docs/plans/08.增加HTTP方式健康检查.plan.md b/docs/plans/08.增加HTTP方式健康检查.plan.md
@@ -0,0 +1,97 @@
+### 增加HTTP方式健康检查 ###
+在现有 TCP 健康检查基础上，增加可选的 HTTP 健康检查方式。用户可以在配置文件中通过 type 字段选择 tcp 或 http，HTTP 模式支持配置路径、期望状态码等参数。
+
+
+## 现状分析
+
+当前项目仅支持 TCP 健康检查：
+- `pkg/healthcheck/checker.go` 定义了 `Checker` 接口和 `TCPChecker` 实现
+- `pkg/healthcheck/manager.go` 的 `UpdateTargets` 中硬编码 `NewTCPChecker`
+- `pkg/config/config.go` 的 `HealthCheckConfig` 无检查类型字段
+
+## 实施步骤
+
+### 步骤 1：扩展配置结构体 `HealthCheckConfig`
+
+**文件**: `pkg/config/config.go`
+
+在 `HealthCheckConfig` 中新增以下字段：
+- `Type string` - 健康检查类型，可选值 `tcp`（默认）、`http`
+- `HTTPPath string` - HTTP 健康检查请求路径，默认 `/`
+- `HTTPExpectedStatus int` - 期望的 HTTP 状态码，默认 `200`
+
+新增辅助方法：
+- `GetType() string` - 返回检查类型，默认 `tcp`
+- `GetHTTPPath() string` - 返回 HTTP 路径，默认 `/`
+- `GetHTTPExpectedStatus() int` - 返回期望状态码，默认 `200`
+
+在 `Validate` 函数中增加校验：
+- `type` 字段仅允许 `tcp` 或 `http`（或为空，默认 `tcp`）
+- 当 `type` 为 `http` 时，`http_path` 必须以 `/` 开头（如果设置了的话）
+- `http_expected_status` 必须在 100-599 范围内（如果设置了的话）
+
+### 步骤 2：实现 `HTTPChecker`
+
+**文件**: `pkg/healthcheck/checker.go`
+
+新增 `HTTPChecker` 结构体，实现 `Checker` 接口：
+- 字段：`timeout`、`path`、`expectedStatus`
+- `Check(address string)` 方法：向 `http://{address}{path}` 发送 GET 请求，检查响应状态码是否匹配期望值
+- 使用 `http.Client` 并设置超时
+
+新增构造函数 `NewHTTPChecker(timeout, path, expectedStatus)`
+
+### 步骤 3：修改 Manager 根据配置选择 Checker 类型
+
+**文件**: `pkg/healthcheck/manager.go`
+
+修改 `UpdateTargets` 方法中创建 checker 的逻辑（约第 99 行）：
+- 当前硬编码：`checker := NewTCPChecker(svcCfg.HealthCheck.GetTimeout())`
+- 改为根据 `svcCfg.HealthCheck.GetType()` 选择创建 `TCPChecker` 或 `HTTPChecker`
+
+### 步骤 4：补充单元测试
+
+**文件**: `pkg/healthcheck/checker_test.go`
+
+新增 HTTP 健康检查测试用例：
+- `TestHTTPChecker_Success` - 启动本地 HTTP server，验证正常返回 200
+- `TestHTTPChecker_UnexpectedStatus` - 后端返回非期望状态码，验证报错
+- `TestHTTPChecker_ConnectionRefused` - 连接不可达，验证报错
+- `TestHTTPChecker_CustomPath` - 验证自定义路径生效
+- `TestHTTPChecker_Timeout` - 验证超时场景
+
+**文件**: `pkg/config/config_test.go`
+
+新增配置校验测试用例：
+- `TestValidate_HealthCheckTypeHTTP` - type 为 http 时校验通过
+- `TestValidate_HealthCheckTypeInvalid` - type 为非法值时校验失败
+- `TestGetType_Default` - 未设置 type 时默认返回 tcp
+
+### 步骤 5：更新示例配置和文档
+
+**文件**: `examples/ezlb.yaml`
+
+在某个 service 中增加 HTTP 健康检查的示例配置，展示 `type`、`http_path`、`http_expected_status` 的用法。
+
+**文件**: `README.md`、`README_CN.md`
+
+更新健康检查相关描述，说明支持 TCP 和 HTTP 两种模式。
+
+## 配置示例
+
+```yaml
+health_check:
+  enabled: true
+  type: http              # 可选: tcp (默认), http
+  interval: 5s
+  timeout: 3s
+  fail_count: 3
+  rise_count: 2
+  http_path: /healthz     # HTTP 模式专用，默认 /
+  http_expected_status: 200  # HTTP 模式专用，默认 200
+```
+
+
+updateAtTime: 2026/2/11 07:18:24
+
+planId: 5b2638e7-5c0b-4463-b112-60fa0266afba
diff --git a/examples/ezlb.yaml b/examples/ezlb.yaml
@@ -26,10 +26,13 @@ services:
     scheduler: wlc
     health_check:
       enabled: true
+      type: http
       interval: 10s
-      timeout: 5s
-      fail_count: 5
-      rise_count: 3
+      timeout: 2s
+      fail_count: 3
+      rise_count: 2
+      http_path: /healthz
+      http_expected_status: 200
     backends:
       - address: 192.168.2.10:8443
         weight: 1
diff --git a/pkg/config/config.go b/pkg/config/config.go
@@ -34,11 +34,14 @@ type ServiceConfig struct {
 
 // HealthCheckConfig defines per-service health check parameters.
 type HealthCheckConfig struct {
-	Enabled   *bool  `yaml:"enabled"    mapstructure:"enabled"`
-	Interval  string `yaml:"interval"   mapstructure:"interval"`
-	Timeout   string `yaml:"timeout"    mapstructure:"timeout"`
-	FailCount int    `yaml:"fail_count" mapstructure:"fail_count"`
-	RiseCount int    `yaml:"rise_count" mapstructure:"rise_count"`
+	Enabled            *bool  `yaml:"enabled"              mapstructure:"enabled"`
+	Type               string `yaml:"type"                 mapstructure:"type"`
+	Interval           string `yaml:"interval"             mapstructure:"interval"`
+	Timeout            string `yaml:"timeout"              mapstructure:"timeout"`
+	FailCount          int    `yaml:"fail_count"           mapstructure:"fail_count"`
+	RiseCount          int    `yaml:"rise_count"           mapstructure:"rise_count"`
+	HTTPPath           string `yaml:"http_path"            mapstructure:"http_path"`
+	HTTPExpectedStatus int    `yaml:"http_expected_status" mapstructure:"http_expected_status"`
 }
 
 // IsEnabled returns whether health check is enabled for this service.
@@ -76,6 +79,33 @@ func (h HealthCheckConfig) GetTimeout() time.Duration {
 	return duration
 }
 
+// GetType returns the health check type.
+// Defaults to "tcp" if not set.
+func (h HealthCheckConfig) GetType() string {
+	if h.Type == "" {
+		return "tcp"
+	}
+	return h.Type
+}
+
+// GetHTTPPath returns the HTTP health check request path.
+// Defaults to "/" if not set.
+func (h HealthCheckConfig) GetHTTPPath() string {
+	if h.HTTPPath == "" {
+		return "/"
+	}
+	return h.HTTPPath
+}
+
+// GetHTTPExpectedStatus returns the expected HTTP response status code.
+// Defaults to 200 if not set.
+func (h HealthCheckConfig) GetHTTPExpectedStatus() int {
+	if h.HTTPExpectedStatus <= 0 {
+		return 200
+	}
+	return h.HTTPExpectedStatus
+}
+
 // GetFailCount returns the consecutive failure threshold.
 // Defaults to 3 if not set.
 func (h HealthCheckConfig) GetFailCount() int {
@@ -230,6 +260,23 @@ func Validate(cfg *Config) error {
 					return fmt.Errorf("service %q: invalid health_check.timeout %q: %w", svc.Name, svc.HealthCheck.Timeout, err)
 				}
 			}
+
+			// Validate health check type
+			checkType := svc.HealthCheck.GetType()
+			if checkType != "tcp" && checkType != "http" {
+				return fmt.Errorf("service %q: unsupported health_check.type %q (supported: tcp, http)", svc.Name, checkType)
+			}
+
+			// Validate HTTP-specific parameters
+			if checkType == "http" {
+				if svc.HealthCheck.HTTPPath != "" && svc.HealthCheck.HTTPPath[0] != '/' {
+					return fmt.Errorf("service %q: health_check.http_path must start with '/'", svc.Name)
+				}
+				if svc.HealthCheck.HTTPExpectedStatus != 0 &&
+					(svc.HealthCheck.HTTPExpectedStatus < 100 || svc.HealthCheck.HTTPExpectedStatus > 599) {
+					return fmt.Errorf("service %q: health_check.http_expected_status must be between 100 and 599", svc.Name)
+				}
+			}
 		}
 
 		// Validate backends
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
@@ -175,6 +175,88 @@ func TestValidate_HealthCheckTimeoutInvalid(t *testing.T) {
 	}
 }
 
+func TestValidate_HealthCheckTypeHTTP(t *testing.T) {
+	cfg := validConfig()
+	cfg.Services[0].HealthCheck.Type = "http"
+	cfg.Services[0].HealthCheck.HTTPPath = "/healthz"
+	cfg.Services[0].HealthCheck.HTTPExpectedStatus = 200
+	err := Validate(cfg)
+	if err != nil {
+		t.Fatalf("expected valid config with http health check, got: %v", err)
+	}
+}
+
+func TestValidate_HealthCheckTypeInvalid(t *testing.T) {
+	cfg := validConfig()
+	cfg.Services[0].HealthCheck.Type = "grpc"
+	err := Validate(cfg)
+	if err == nil {
+		t.Fatal("expected error for unsupported health_check.type, got nil")
+	}
+}
+
+func TestValidate_HealthCheckHTTPPathInvalid(t *testing.T) {
+	cfg := validConfig()
+	cfg.Services[0].HealthCheck.Type = "http"
+	cfg.Services[0].HealthCheck.HTTPPath = "no-leading-slash"
+	err := Validate(cfg)
+	if err == nil {
+		t.Fatal("expected error for http_path without leading slash, got nil")
+	}
+}
+
+func TestValidate_HealthCheckHTTPExpectedStatusInvalid(t *testing.T) {
+	cfg := validConfig()
+	cfg.Services[0].HealthCheck.Type = "http"
+	cfg.Services[0].HealthCheck.HTTPExpectedStatus = 999
+	err := Validate(cfg)
+	if err == nil {
+		t.Fatal("expected error for http_expected_status out of range, got nil")
+	}
+}
+
+func TestGetType_Default(t *testing.T) {
+	hc := HealthCheckConfig{}
+	if hc.GetType() != "tcp" {
+		t.Errorf("expected default type 'tcp', got %q", hc.GetType())
+	}
+}
+
+func TestGetType_HTTP(t *testing.T) {
+	hc := HealthCheckConfig{Type: "http"}
+	if hc.GetType() != "http" {
+		t.Errorf("expected type 'http', got %q", hc.GetType())
+	}
+}
+
+func TestGetHTTPPath_Default(t *testing.T) {
+	hc := HealthCheckConfig{}
+	if hc.GetHTTPPath() != "/" {
+		t.Errorf("expected default http_path '/', got %q", hc.GetHTTPPath())
+	}
+}
+
+func TestGetHTTPPath_Custom(t *testing.T) {
+	hc := HealthCheckConfig{HTTPPath: "/healthz"}
+	if hc.GetHTTPPath() != "/healthz" {
+		t.Errorf("expected http_path '/healthz', got %q", hc.GetHTTPPath())
+	}
+}
+
+func TestGetHTTPExpectedStatus_Default(t *testing.T) {
+	hc := HealthCheckConfig{}
+	if hc.GetHTTPExpectedStatus() != 200 {
+		t.Errorf("expected default http_expected_status 200, got %d", hc.GetHTTPExpectedStatus())
+	}
+}
+
+func TestGetHTTPExpectedStatus_Custom(t *testing.T) {
+	hc := HealthCheckConfig{HTTPExpectedStatus: 204}
+	if hc.GetHTTPExpectedStatus() != 204 {
+		t.Errorf("expected http_expected_status 204, got %d", hc.GetHTTPExpectedStatus())
+	}
+}
+
 func TestValidate_HealthCheckDisabledSkipsIntervalValidation(t *testing.T) {
 	cfg := validConfig()
 	cfg.Services[0].HealthCheck.Enabled = boolPtr(false)
diff --git a/pkg/healthcheck/checker.go b/pkg/healthcheck/checker.go
diff --git a/pkg/healthcheck/checker_test.go b/pkg/healthcheck/checker_test.go
diff --git a/pkg/healthcheck/manager.go b/pkg/healthcheck/manager.go

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.5"`
	`19`	`+ Version = "0.1.6"`
`20`	`20`	`configPath string`
`21`	`21`	`showVersion bool`
`22`	`22`	`)`