KubeBYON 公网访问改造清单（HAProxy 方案）

最后更新：2026-04-12

注：该文档属于设计记录 / 改造说明。当前产品的实际行为请结合 current-architecture.md、http-api.md 与部署 runbook 阅读。

目标：

  • 删除对 k3s ServiceLB 的公网入口依赖
  • 为每个 vCluster API 提供稳定域名
  • 使用 HAProxy + TLS SNI 统一承接 443

1. 方案摘要

推荐形态：

kubectl
  -> api.cluster-a.example.com
  -> HAProxy:443
  -> SNI 路由到 cluster-a 对应 backend
  -> 宿主节点 IP:NodePort
  -> vCluster API

其中：

  • 用户看到的始终是 https://<control_plane_host>:443
  • vCluster 底层 Service 保持 NodePort
  • NodePort 只作为 HAProxy 后端，不再直接暴露给最终用户

2. 为什么放弃 k3s ServiceLB

原方案的问题：

  1. 每个 LoadBalancer Service 都会竞争宿主机 hostPort
  2. 多个 vCluster 同时暴露 443 时很快冲突
  3. 不适合“每个 vCluster 一个稳定域名”的长期形态

因此，保留 public_access_mode=loadbalancer 这个产品语义， 但把底层实现切换为：

  • 外部稳定入口：HAProxy
  • 内部后端承载：NodePort

3. 当前实现语义

3.1 public_access_mode=nodeport

  • 直接返回 control_plane_host:NodePort
  • 适合临时调试

3.2 public_access_mode=loadbalancer

  • 对外返回 control_plane_host:443
  • 要求 control_plane_host 为域名
  • 由 HAProxy 根据 TLS SNI 转发到对应 NodePort

4. 关键约束

  1. 必须使用域名，不建议使用 IP
    • HAProxy 方案依赖 TLS SNI
    • IP 字面量通常不会携带 SNI
  2. HAProxy 宿主机必须能访问宿主集群节点的 NodePort
  3. 宿主机 443 端口必须留给 HAProxy
  4. k3s 应禁用 servicelb

5. 后端改造点

  1. 新增运行时 provider：haproxy | servicelb
  2. loadbalancer + haproxy 时：
    • vCluster Service 实际保持 NodePort
    • kubeconfig 返回 https://<control_plane_host>:443
  3. 后台周期性渲染 HAProxy 配置：
    • control_plane_host -> 节点IP:NodePort
  4. Docker Compose 新增 haproxy 服务

6. 部署建议

最小可用：

  • 单台 HAProxy 节点
  • 多个 vCluster 域名都解析到这一台机器

生产增强：

  • 两台或以上 HAProxy 网关
  • 多个 A 记录 / 外部 DNS 健康检查
  • 节点间通过 VPC / WireGuard / overlay 网络访问 NodePort

7. 推荐阅读