KubeBYON 当前架构（纯文本）

最后更新：2026-06-19

本文描述 当前仓库已经落地的产品架构，重点覆盖：

• Web Console / API / Worker / Route Agent / PostgreSQL 的关系
• 单机与多机两种运行拓扑
• 集群生命周期、节点接入、控制面公网入口、托管业务流量入口、Longhorn 存储层与 Admission Webhook 的位置

1. 总览架构

                                   +----------------------+
                                   |   用户 / 管理员浏览器  |
                                   +----------+-----------+
                                              |
                                              | HTTPS
                                              v
                         +---------------------------------------------+
                         |           Web Console（Next.js）            |
                         |  - 用户控制台                                |
                         |  - 管理后台                                  |
                         |  - 登录 / OAuth 入口                         |
                         +----------------+----------------------------+
                                          |
                                          | HTTP / HTTPS API
                                          v
+----------------------------------------------------------------------------------+
|                             KubeBYON API（Go）                                   |
|----------------------------------------------------------------------------------|
|  认证：注册 / 登录 / OAuth / Session / API Key                                    |
|  控制台：集群 / 节点 / Join Token / kubeconfig / 指标 / 活动流                     |
|  管理：用户 / 套餐 / 订单 / 系统设置 / 通知配置 / cluster job 队列观测              |
|  编排：写库、校验、发起 cluster job、与宿主 Kubernetes / vCluster 交互               |
+----------------------+---------------------------+-------------------------------+
                       |                           |                               |
                       | SQL                       | AMQP（多机模式）               | HTTPS / OAuth / SMTP
                       v                           v                               v
             +------------------+       +------------------+          +-------------------------+
             |   PostgreSQL     |       |    RabbitMQ      |          |  外部依赖 / 第三方服务   |
             |------------------|       |------------------|          |-------------------------|
             | users            |       | cluster job queue|          | GitHub / Google OAuth   |
             | sessions         |       +--------+---------+          | SMTP / 其他通知渠道      |
             | clusters         |                |                    | HAProxy / Gateway API    |
             | cluster_jobs     |                v                    +-------------------------+
             | tokens           |      +------------------------+
             | nodes            |      | kubebyon-worker（可选） |
             | plans / orders   |      |------------------------|
             | system_settings  |      | 领取并执行 cluster job  |
             | audit_events     |      | 创建 / 更新 / 删除集群   |
             +--------+---------+      +-----------+------------+
                      |                                |
                      | Kubernetes API / Helm / client-go
                      +---------------+----------------+
                                      |
                                      v
                    +--------------------------------------------------+
                    |           Host Kubernetes / k3s                  |
                    |--------------------------------------------------|
                    | namespace per cluster                            |
                    | - vCluster control plane                         |
                    | - kubeconfig Secret                              |
                    | - Service（ClusterIP / NodePort）                |
                    | - vCluster control plane PVC（可用 Longhorn）      |
                    | - ResourceQuota / LimitRange                     |
                    | - Longhorn CSI / StorageClass（可选共享存储层）    |
                    | - vCluster 内 webhook config（按需）              |
                    | - vCluster 内 managed ingress controller（按需）  |
                    | - kubebyon-route-agent DaemonSet（按需）          |
                    +-----------------------+--------------------------+
                                            |
                                            | Join Script / Private Nodes / VPN
                                            v
                                +-------------------------------+
                                |   用户自带工作节点（BYON）       |
                                |-------------------------------|
                                | kubelet / containerd / CNI    |
                                | 接入目标 vCluster             |
                                +-------------------------------+

2. 两种运行拓扑

2.1 单机模式

单机模式通常使用：

• deployments/single-node/docker-compose
• deployments/single-node/helm/kubebyon

特点：

• kubebyon-api 与 PostgreSQL 同机或同集群部署
• 未配置 RabbitMQ 时，API 进程直接在本机协程中执行集群生命周期动作
• 更适合自托管、开发与轻量生产环境

2.2 多机模式

多机模式通常使用：

• deployments/multi-node/docker-compose
• deployments/multi-node/helm/kubebyon

特点：

• API 负责接收请求、校验、写库、投递 cluster job
• kubebyon-worker 负责真正执行集群生命周期动作
• RabbitMQ 负责在 API 与 worker 之间传递 job ID
• 管理员 API 可只读查看 cluster_jobs 队列与 worker 执行快照，用于观测积压、租约、重试次数与失败原因；当前不提供重试或取消 job 的写操作
• 更适合把请求面与执行面拆开扩展

2.3 可选 Route Agent

当 Gateway API workload edge 启用 PodCIDR 路由，并且路由模式为 routeagent 时，会额外运行 kubebyon-route-agent：

• 通常以 DaemonSet 形式运行在宿主 Kubernetes 节点上
• 读取 workloadpodcidrnoderouteplans 路由计划资源
• 在当前节点应用目标 vCluster workload PodCIDR 路由
• 与 kubebyon-worker 不同，它不执行集群生命周期 job，只负责节点本地路由收敛

2.4 Longhorn 存储层

Longhorn 是宿主 Kubernetes / k3s 上的可选共享存储层。当前 Helm values 已经把新建 vCluster 控制面 StatefulSet PVC 指向 storageClass: longhorn：

controlPlane:
  statefulSet:
    persistence:
      volumeClaim:
        enabled: true
        size: 5Gi
        storageClass: longhorn
        accessModes:
          - ReadWriteOnce

当前边界：

• Longhorn 只负责 KubeBYON 创建的 vCluster control plane PVC。
• local-path 可以继续作为宿主集群默认 StorageClass，KubeBYON 通过显式 storageClass: longhorn 使用 Longhorn。
• vCluster 内用户 workload 的 StorageClass 不会自动同步到 Longhorn。
• PostgreSQL、RabbitMQ、平台自身 PVC 不会因为 vCluster values 使用 Longhorn 而自动迁移；需要分别通过对应 chart values 或外部托管服务规划。

运维前提：

• 宿主集群必须先安装 Longhorn，并存在可用的 longhorn StorageClass。
• 每台可能运行 Longhorn 组件或承载副本的宿主节点都需要安装 open-iscsi、nfs-common，并启用 iscsid。
• 新增宿主节点时，应先补齐这些依赖，再确认 longhorn-manager、longhorn-csi-plugin、instance-manager 在新节点上正常运行。

如果目标环境没有 Longhorn，需要在部署前把 vCluster values 中的 controlPlane.statefulSet.persistence.volumeClaim.storageClass 改为实际可用的 StorageClass，或关闭该 PVC 配置；否则新建 vCluster 控制面 PVC 可能一直 Pending。

详细安装、验证和回滚步骤见 ../runbooks/migrate-vcluster-control-plane-storage-to-longhorn.md。

3. 关键调用链

3.1 登录与控制台链路

浏览器
  -> Web Console
  -> KubeBYON API
  -> PostgreSQL

用途：

• 注册 / 登录 / OAuth
• 获取当前用户、API Key、通知偏好
• 查看用户集群、节点、节点事件 / 健康历史、订单、活动流
• 管理员维护用户、套餐、订单与系统设置

3.2 集群生命周期链路

浏览器 / API Client
  -> KubeBYON API
  -> 写 clusters / cluster_operations / cluster_jobs
  -> (单机) API 本地执行
     或
     (多机) RabbitMQ -> kubebyon-worker
  -> 宿主 Kubernetes API + Helm SDK
  -> 创建 / 更新 / 删除 vCluster
  -> 回写集群状态、连通性、kubeconfig 可用性

说明：

• 创建、更新、删除都已经有显式的状态与操作记录
• 多机模式下，worker 以数据库快照 + job payload 为准执行
• API 不再只是“命令转发器”，而是整个产品的编排中心
• 管理后台可通过 GET /api/console/admin/cluster-jobs?status=&cluster_id=&limit= 只读查询全局 cluster job 队列，辅助 worker / job 队列可观测，不承担重试、取消等控制面操作

3.3 节点接入链路

用户在控制台生成 Join Token / Join Script
  -> API 返回 join 命令或脚本地址
  -> 用户在自带节点执行脚本
  -> 节点安装并启动接入组件
  -> 通过 Private Nodes / VPN 接入目标 vCluster
  -> KubeBYON 读取节点当前状态并写入 nodes 快照
  -> 状态变化 / 接入 / 离线 / 删除事件写入 node_events
  -> 控制台展示节点当前状态与节点事件 / 健康历史

说明：

• nodes 表达节点当前快照，适合列表与详情页展示
• node_events 表达历史事件流，适合节点时间线和健康状态变化观测
• 控制台使用 GET /api/console/node-events?cluster_id=&node_id=&type=&limit= 查询最近事件，响应按 observed_at DESC, id DESC 排序
• 该事件查询是认证后的 console API，默认返回最近 100 条，最大 500 条

3.4 公网访问链路

kubectl / 用户客户端
  -> control_plane_host
  -> HAProxy:443（Helm chart 默认 provider；裸二进制默认 provider 为 servicelb）
     或
  -> Gateway API shared Gateway:443（control plane 替代 provider）
  -> TLS passthrough / TLS SNI 路由
  -> 宿主节点 IP:NodePort
  -> vCluster API Server / Proxy

当前语义：

• public_access_mode=nodeport
  • 更适合调试或临时入口
• public_access_mode=loadbalancer
  • publicAccess.provider=haproxy 时，对外表现为稳定的 :443 域名入口
  • publicAccess.provider=gatewayapi 时，由共享 Gateway + TLSRoute 承接 vCluster control plane passthrough

注意：

• control-plane 链路：shared Gateway + TLSRoute，只负责 vCluster 控制面 API / kubeconfig
• platform 链路：独立 platform Gateway，负责平台 hostname 下的 /api 前缀、/healthz，以及可选的 / -> web
• workload 链路：独立 workload edge shared Gateway，负责托管业务流量入口；默认 HTTP:80，并可选增加 HTTPS:443 + cert-manager 最小版
• 若同一 platform hostname 同时启用 web / 路由，/api 前缀与 Exact /healthz 仍会因更具体的 Gateway API 路径匹配优先进入 API，/ 只兜底站点流量

如果启用了 Gateway API Phase 3（平台 Gateway + in-cluster web），平台站点链路会额外变成：

浏览器
  -> https://<platform-hostname>
  -> platform Gateway HTTPS listener
  -> /api 前缀, /healthz -> kubebyon-api Service
  -> /               -> kubebyon-web Service

如果启用了 Gateway API workload edge，业务站点链路会额外变成：

终端用户 / 浏览器
  -> http:// / https:// <managed_workload_ingress_cname_target> 或已绑定 hostname
  -> workload edge shared Gateway
     - chart 保留的 HTTP listener
     - 可选 runtime-managed HTTPS listener（TLS Secret / Certificate 由 kubebyon-api runtime syncer 编排）
  -> runtime syncer 按 cluster 级 managed_workload_ingress_cname_target 与 hostname bindings 维护 host-side HTTPRoute / HTTPS listener / Certificate
     - HTTP backend route
     - 可选 HTTPS backend route
     - 可选 HTTP -> HTTPS redirect route
     - self-managed dedicated HTTPS route 会把 Host rewrite 回 cluster 级 managed_workload_ingress_cname_target
  -> 同 namespace 的 Service / EndpointSlice shim
  -> 优先直达托管 ingress controller PodIP:80
  -> 不可达时再回退到宿主节点 IP:NodePort
  -> 目标 vCluster 内托管 ingress controller
  -> 用户 workload Service

说明：这里的 workload edge 目前是独立 Gateway 对象。是否因此需要第二个公网 IP，取决于具体 Gateway controller 的地址分配与共享模型；很多基于 LoadBalancer 的实现默认会按 Gateway 分配独立地址。

3.5 托管业务流量入口链路（当前实现）

用户在控制台开启 managed workload ingress
  -> KubeBYON API / worker 更新 cluster 期望状态
  -> 使用 vCluster internal REST config 连接目标 vCluster
  -> Helm SDK 在 vCluster 内 install / upgrade ingress controller
  -> 生成 NodePort Service + 托管 IngressClass
  -> 状态回写为 provisioning / ready / error

当前语义：

• 这是 cluster 级的可选开关
• 当前内置实现收敛为 ingress-nginx
• 即使开启托管业务流量入口，用户仍可继续在 vCluster 内自行安装其他 ingress controller 或使用其他入口方案
• 当前实现已经补充了部分产品面：
  • 管理员可配置 managed_workload_ingress_base_domain
  • console cluster 视图会返回只读 managed_workload_ingress_cname_target
  • console cluster 视图会返回 cluster 级 managed_workload_ingress_dns_status / managed_workload_ingress_dns_message，以及最近成功同步时间、最近失败原因与失败时间；UI 会基于既有时间字段派生展示“已恢复（Recovered）”历史提示（最近成功同步时间 > 最近失败时间），但这不是新增 API 字段，也不代表公网 DNS 最终解析已恢复
  • cluster 详情页可维护自定义 hostname binding 记录，并通过只读 dns_management_scope、dns_management_status、dns_management_message 及最近成功/失败观测字段区分平台托管范围与平台 DNS 自动化同步状态；其中 status / last_error 仍表示公网 DNS 最终解析结果，UI 基于 dns_management_* 时间字段派生的“已恢复（Recovered）”只表示平台 DNS 自动化历史上的恢复
  • hostname binding 创建表单会在 UI 层基于 cluster managed_workload_ingress_cname_target 反推 base domain，实时预览创建后预计是 platform_managed 还是 self_managed；这只是前端引导，外部 hostname 仍然合法，只是归为 self_managed
• 当前已可自动维护平台自有 base domain 下的 cluster 级 CNAME，以及同样落在该 base domain 下的 hostname binding CNAME
• 当前若启用 Gateway API workload edge，Helm chart 会创建独立 workload edge shared Gateway 基础对象并保留 HTTP:80 listener；kubebyon-api 内的 workload edge syncer 会在每个 cluster 对应的宿主 namespace 中维护 HTTPRoute、Service 与 EndpointSlice，并按需要在同一 Gateway 上动态编排 HTTPS listener / route / Certificate。当前实现优先把 shim EndpointSlice 直接指到目标 vCluster 内托管 ingress controller 的 PodIP:80，若当前宿主拓扑或 reachability 不满足，再自动回退到宿主节点 IP + NodePort
• workload edge 的 PodCIDR 路由收敛支持 local 与 routeagent 两种模式：local 模式由 kubebyon-api 所在进程直接同步宿主路由；routeagent 模式由宿主节点上的 kubebyon-route-agent 读取 route plan 并在本节点执行路由变更
• 若启用 cert-manager，syncer 会在 workload Gateway namespace 为 platform-managed hostname 动态维护共享 Certificate，把 cluster 级 CNAME target 与落在 managed_workload_ingress_base_domain 下的 hostname bindings 聚合进 SAN
• 若启用 self-managed cert-manager，syncer 还可为 self-managed 外部 hostname 维护独立 Certificate；若未显式 override issuerRef，则回退到 workload cert-manager 默认 issuerRef。对应的 dedicated HTTPS HTTPRoute 还会把 Host rewrite 回 cluster 级 managed_workload_ingress_cname_target，避免 vCluster 内托管 ingress 只识别平台 canonical hostname 时出现 404
• 但平台仍不负责外部用户 DNS Zone 托管；self-managed 外部 hostname 的证书编排已补到最小版，但更细粒度的证书可视化/策略仍未完成

3.6 Admission Webhook 链路（可选）

用户在 vCluster 内创建 Pod / Deployment
  -> vCluster 内 webhook configuration
  -> kubebyon-api 暴露的 admission HTTPS handler
  -> 根据集群配额 / 平台策略放行或拒绝

说明：

• Admission handler 与 kubebyon-api 同部署
• webhook configuration 写入目标 vCluster 控制面，而不是宿主 namespace 的普通对象

4. 当前架构边界

1. 平台面与集群面分层
   • 平台业务：internal/api/http、internal/app
   • 集群适配：internal/infra/vcluster
   • 异步任务：internal/domain/clusterjob、internal/infra/mq/rabbitmq
   • 节点路由 Agent：cmd/kubebyon-route-agent、internal/infra/vcluster/podcidr_route_*
2. 数据库是平台状态源
   • 用户、订单、系统设置、审计、集群操作与 job 记录都以 PostgreSQL 为准
3. 宿主 Kubernetes 是统一控制面
   • 每个用户集群对应宿主集群中的一个 vCluster 实例
4. BYON Node 是外部资源
   • 用户工作节点由用户提供，平台负责接入与观测，不负责供应底层机器
   • kubebyon-worker 是平台侧异步任务执行进程，不等同于用户自带 BYON 节点
5. 控制面公网入口与业务流量入口分离
   • public_access_mode 只描述 vCluster API
   • managed_workload_ingress_enabled 只描述工作负载入口 controller 的托管开关
6. Gateway API provider 已进入 workload edge HTTPS + cert-manager 最小版
   • 当前 Helm in-cluster chart 会创建 control-plane shared Gateway，并把相关网关元数据传给后端/worker
   • 可选额外创建平台站点专用 Gateway；默认路由 /api 前缀与 /healthz 到 API，web.enabled=true 时同 host 下再额外路由 / 到 in-cluster web，且更具体的 /api / /healthz 匹配保持优先
   • 可选额外创建 workload edge shared Gateway；chart 只保留 HTTP:80 listener，HTTPS listener / redirect / Certificate 由 runtime syncer 动态维护
   • kubebyon-api runtime syncer 会在 cluster 宿主 namespace 中维护 cluster 级 CNAME target 与 hostname bindings 对应的 HTTPRoute、Service 与 EndpointSlice，优先走 shim Service -> EndpointSlice -> ingress PodIP:80
   • workload PodCIDR 路由支持 API 本地同步与 kubebyon-route-agent 两种收敛路径；routeagent 模式下 route plan 是 API/agent 之间的状态交接对象
   • 若启用 cert-manager，syncer 会在 workload Gateway namespace 动态维护 platform-managed 共享 Certificate；当前最小范围只自动覆盖平台可托管 base domain 内的 hostname
   • 若启用 self-managed cert-manager，syncer 还可为 self-managed 外部 hostname 维护独立 Certificate，并在 dedicated HTTPS route 上做 Host rewrite
   • 三条链路保持分离：control-plane 不与 platform / workload 混在同一个 Gateway；证书自动化已区分 platform-managed 共享模式与 self-managed 独立模式
7. 文档面向当前实现
   • 当前产品说明以本文件、API 文档、数据库设计和部署 runbook 为准
   • 部署文档只保留当前推荐路径、可选能力和运维检查点

5. 建议同时阅读

• 产品路线图：../product-roadmap.md
• 托管业务流量入口：./managed-workload-ingress-plan.md
• HTTP API：../api/http-api.md
• 数据库设计：./database-design.md
• 单机 Docker Compose 部署：../runbooks/deploy-kubebyon-backend-docker-compose.md
• 多机 Docker Compose 部署：../runbooks/deploy-kubebyon-backend-multi-node-docker-compose.md
• Gateway API 控制面入口：../runbooks/deploy-gateway-api-public-access.md