KubeBYON 多机 Helm 部署 Runbook

最后更新：2026-06-19

本文档记录基于 deployments/multi-node/helm/kubebyon 的多机 Helm 部署流程。

目标形态：

• API Deployment
• 可选 web Deployment
• Worker Deployment
• RabbitMQ Deployment
• 可选 PostgreSQL 子 chart
• Longhorn-backed vCluster control plane PVC（默认 vCluster values 使用 storageClass: longhorn）
• 可选 publicAccess.provider=haproxy（默认）或 publicAccess.provider=gatewayapi
• admission webhook / platform bootstrap
• 默认使用 scoped RBAC 访问宿主集群；仅在临时回退时才设置 rbac.clusterAdmin=true

与原有 deployments/single-node/helm/kubebyon 的区别：

• 当前 chart 保持单机后端的 Helm in-cluster 变体
• 多机 chart 额外拆出 kubebyon-worker
• 多机 chart 增加 RabbitMQ 配置与 secret/service 模板
• API 与 Worker 均可选独立 metrics 端口；默认关闭，避免在 hostNetwork=true 时无意暴露宿主机端口

0.1 NodePort kubeconfig 说明

默认 public_access_mode=nodeport 下，如果创建集群时没有显式传 control_plane_host， 后端会自动选取一个宿主节点 IP 作为控制面地址，并把它注入 vCluster extraSANs， 这样能避免集群已经 ready/reachable 但 kubeconfig 仍因 TLS SAN 不匹配而无法下载。

如果你需要稳定域名入口，仍建议在创建集群时显式提供固定域名或 IP。

0.2 Longhorn 存储说明

当前 multi-node Helm values 默认让新建 vCluster control plane StatefulSet 使用 Longhorn PVC：

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

这意味着部署前需要先确认宿主集群已经准备好 Longhorn：

kubectl get storageclass
kubectl -n longhorn-system get pods -o wide

期望：

• 存在 longhorn StorageClass。
• Longhorn 组件为 Running。
• local-path 可以继续作为默认 StorageClass；KubeBYON 通过显式 storageClass: longhorn 使用 Longhorn。

所有可能运行 Longhorn 组件或承载 Longhorn replica 的宿主节点都需要安装节点依赖：

apt-get update
apt-get install -y open-iscsi nfs-common cryptsetup
systemctl enable --now iscsid
modprobe dm_crypt

新增宿主节点后也要补齐上述依赖，再确认新节点上的 Longhorn Pod 正常：

kubectl -n longhorn-system get pods -o wide

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

注意：

• Longhorn 当前只用于 vCluster control plane PVC。
• vCluster 内用户 workload 的 StorageClass 不会自动同步到 Longhorn。
• RabbitMQ persistence 默认 storageClass: ""，会使用宿主默认 StorageClass；如需 RabbitMQ 也使用 Longhorn，请显式设置 rabbitmq.persistence.storageClass: longhorn 并评估副本/恢复策略。
• PostgreSQL 子 chart 的持久化也需要单独配置，不会自动跟随 vCluster control plane 的 Longhorn 设置。

详细迁移、验证、回滚步骤见 ./migrate-vcluster-control-plane-storage-to-longhorn.md。

1. 目录

deployments/multi-node/helm/kubebyon/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml
    ├── deployment-worker.yaml
    ├── deployment-rabbitmq.yaml
    └── ...

2. 典型调度思路

可以把：

• API + RabbitMQ 调度到 backend 节点池
• Worker 调度到独立 worker 节点池

常用字段：

• globalNodeSelector
• api.nodeSelector
• worker.nodeSelector

如果 PostgreSQL 也使用内置子 chart，请按 Bitnami PostgreSQL values 再单独覆盖其 primary 调度参数。

如果你仍使用 publicAccess.provider=haproxy，建议把 API Pod 固定到一个能够稳定承接 443 的节点。 如果改用 gatewayapi，API Pod 本身不再绑定 sidecar 443，但 Gateway controller 数据面的暴露方式仍需单独规划。

3. 准备 values

3.1 HAProxy provider 示例

image:
  repository: kubebyon-multi-node
  tag: helm-test
  pullPolicy: IfNotPresent

api:
  metrics:
    enabled: false
    address: ":9091"
    port: 9091
  nodeSelector:
    node-role.kubernetes.io/backend: "true"

worker:
  enabled: true
  replicas: 2
  metrics:
    enabled: false
    address: ":9090"
    port: 9090
  nodeSelector:
    node-role.kubernetes.io/worker: "true"

rabbitmq:
  enabled: true

postgresql:
  enabled: true
  primary:
    persistence:
      enabled: false

managedIngress:
  chart:
    version: ""

kubernetes:
  configMode: incluster

platform:
  apiKeySourceNamespace: kubebyon-system
  apiKeySecretName: vcluster-platform-api-key
  bootstrap:
    enabled: true
    mockHost: https://vcluster.pp.ua:18443
    insecure: true
    project: default

Prometheus 抓取建议：

• API：当 api.metrics.enabled=true 时，抓取 API Pod 配置的独立 metrics 端口 /metrics；不要通过公网入口裸露
• Worker：当 worker.metrics.enabled=true 时，抓取 worker Pod :9090/metrics

注意：

• 默认 api.hostNetwork=true、worker.hostNetwork=true，metrics 端口启用后会绑定宿主机端口，因此默认关闭
• 如果要开启 worker metrics 且 worker 多副本运行，建议确保 worker 副本不会调度到同一宿主机，或改用非 hostNetwork / 不同端口规划
• api.metrics.address / worker.metrics.address 应与对应 port 保持一致，便于 Prometheus 抓取配置与 Pod 端口声明匹配

当前主要指标：

• kubebyon_http_requests_total
• kubebyon_http_request_duration_seconds
• kubebyon_cluster_job_publish_attempts_total
• kubebyon_cluster_jobs_processed_total
• kubebyon_cluster_jobs_batch_published_total
• kubebyon_cluster_jobs_requeued_total
• kubebyon_cluster_jobs_backlog
• kubebyon_cluster_jobs_pending_unpublished

3.2 Gateway API provider 示例

image:
  repository: kubebyon-multi-node
  tag: helm-test
  pullPolicy: IfNotPresent

api:
  nodeSelector:
    node-role.kubernetes.io/backend: "true"

worker:
  enabled: true
  replicas: 2
  nodeSelector:
    node-role.kubernetes.io/worker: "true"

rabbitmq:
  enabled: true

postgresql:
  enabled: true
  primary:
    persistence:
      enabled: false

kubernetes:
  configMode: incluster

publicAccess:
  provider: gatewayapi

gatewayAPI:
  # 默认 dual；single/dual 只决定各角色默认解析到哪类 GatewayClass。
  addressMode: dual
  # edge/workload profile 留空时，会最终回退到这里。
  gatewayClassName: eg
  gatewayClassProfiles:
    shared: ""
    edge: eg-public
    workload: eg-workload
  namespace: ""
  name: ""
  listenerName: control-plane
  syncIntervalSeconds: 10
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
    # web.enabled=true 时，HTTP redirect 会覆盖 /；否则仅覆盖 /api 与 /healthz。
    httpToHttpsRedirect: false
  workload:
    enabled: true
    gatewayClassName: ""
    namespace: ""
    name: ""
    listenerName: ""
    nodeAddressType: internal

web:
  enabled: true
  image:
    repository: kubebyon-web
    tag: helm-test
    pullPolicy: IfNotPresent
  service:
    create: true
    port: 3000
  env:
    apiBaseURL: ""
    # 同 host Gateway 路由场景下通常保持留空，让浏览器继续访问当前站点 /api。
    nextPublicAPIBaseURL: ""
    hostname: ""

platform:
  apiKeySourceNamespace: kubebyon-system
  apiKeySecretName: vcluster-platform-api-key
  bootstrap:
    enabled: true
    mockHost: https://vcluster.pp.ua:18443
    insecure: true
    project: default

3.2.1 推荐：single address mode（单公网 IP / 共享入口规划）

适用场景：

• 你希望 control-plane / platform / workload 默认都挂到同一类 Gateway data plane
• controller 侧只准备了一个共享 GatewayClass、一个共享公网入口，或一个共享 address pool
• 你想先以最少网络资源把 Gateway API 跑通，后续再拆分 workload

publicAccess:
  provider: gatewayapi

gatewayAPI:
  addressMode: single
  gatewayClassName: eg
  gatewayClassProfiles:
    shared: eg
    edge: ""
    workload: ""
  listenerName: control-plane
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
  workload:
    enabled: true

默认解析规则：

• control-plane：shared
• platform：shared
• workload：shared
• 若 shared 为空：统一回退到 gatewayAPI.gatewayClassName

3.2.2 推荐：dual address mode（双公网 IP / 分层入口规划，默认）

适用场景：

• 你希望 control-plane / platform 与 workload 默认分离
• controller 侧已经为平台入口和 workload 入口准备了不同 GatewayClass、不同 address pool，或不同 data plane
• 你希望 workload 流量与平台/控制面具备更清晰的容量、证书和回滚边界

publicAccess:
  provider: gatewayapi

gatewayAPI:
  addressMode: dual
  gatewayClassName: eg
  gatewayClassProfiles:
    shared: ""
    edge: eg-public
    workload: eg-workload
  listenerName: control-plane
  platform:
    enabled: true
    hostname: kubebyon.example.com
    tlsSecretName: kubebyon-platform-tls
  workload:
    enabled: true

默认解析规则：

• control-plane：edge
• platform：edge
• workload：workload
• 若 edge 或 workload 为空：对应角色回退到 gatewayAPI.gatewayClassName

如果 RabbitMQ 走外部服务，可关闭内置 RabbitMQ：

rabbitmq:
  enabled: false
  external:
    url: amqp://kubebyon:ChangeMe123!@rabbitmq.default.svc:5672/%2f

如果 PostgreSQL 走外部服务，也请改用：

database:
  external:
    dsn: postgresql://kubebyon:ChangeMe123!@postgres.default.svc:5432/kubebyon?sslmode=disable

说明：

• managedIngress.chart.* 用于控制托管业务流量入口内置 controller 的 chart 配置
• 当前运行时明确收敛为 ingress-nginx
• 因此通常只建议覆盖 managedIngress.chart.version
• gatewayAPI.* 用于提供 shared Gateway 的 class/name/listener/sync interval 给 API 与 worker
• gatewayAPI.addressMode 支持 single / dual，默认 dual
• gatewayAPI.gatewayClassProfiles.shared / edge / workload 用于给 control-plane / platform / workload 提供默认 GatewayClass 解析策略
• 显式 override 优先级保持不变：
  • gatewayAPI.platform.gatewayClassName
  • gatewayAPI.workload.gatewayClassName
  • 若未显式 override，则按 gatewayAPI.addressMode 选择 gatewayAPI.gatewayClassProfiles.*
  • 若选中的 profile 为空，则最终回退到 gatewayAPI.gatewayClassName
• 启用 gatewayAPI.workload.enabled=true 时，kubebyon-api 还会额外收到 workload Gateway 的 namespace / name / listener / nodeAddressType 运行时 env
• 启用 gatewayAPI.workload.tls.enabled=true 时，Helm render 仍只保留 workload Gateway 的 HTTP:80 listener；HTTPS listener / Certificate 元数据会下发给 kubebyon-api
• 若启用 gatewayAPI.platform.enabled=true，chart 还会额外创建独立 platform Gateway + HTTPRoute，用于把 /api 前缀与 /healthz 路由到 API Service
• 若再启用 web.enabled=true，则会在同 host 下额外把 / 路由到 web Service
• 若再启用 gatewayAPI.workload.enabled=true，则会额外创建独立 workload shared Gateway；可保持 HTTP:80，也可让 runtime syncer 动态维护最小范围 HTTPS + cert-manager
• web.env.apiBaseURL 推荐用于 server-side / SSR 请求后端；留空时 chart 默认回落到 in-cluster API Service
• web.env.nextPublicAPIBaseURL 只在浏览器必须直连不同 origin API 时再配置；同 host Gateway 路由场景通常保持留空
• Gateway API provider 当前已覆盖 vCluster control plane TLSRoute passthrough，并可选为平台站点创建独立 Gateway + HTTPRoute；同时也可选创建 workload edge shared Gateway，由 kubebyon-api runtime syncer 按 cluster 维护 HTTPRoute、Service 与 EndpointSlice，当前优先直连目标 vCluster 内托管 ingress controller 的 PodIP:80，不满足条件时再回退到宿主节点 IP + NodePort
• 当前三条链路保持分离：control-plane、platform、workload 不混在同一个 Gateway；workload HTTPS 采用“Helm 基础 Gateway + runtime-managed listener/certificate”模式，platform-managed 继续走共享证书，self-managed 外部 hostname 可选独立证书接线
• rbac.clusterAdmin 默认值为 false，chart 会创建并绑定 scoped ClusterRole。该角色覆盖当前已有功能需要的宿主集群权限，包括 Namespace、Secret、Service、ServiceAccount、PVC、Pod、Job、RBAC bind/escalate、CRD、admission webhook、Gateway API、cert-manager Certificate、IngressClass、Endpoint/EndpointSlice、ResourceQuota/LimitRange、workload route plan 与 /status 子资源。
• 这是一次默认 RBAC 行为变更。旧 release 如果已经以 rbac.clusterAdmin=true 安装，直接升级到默认 scoped mode 时会尝试修改既有 ClusterRoleBinding.roleRef；该字段在 Kubernetes 中不可变，升级可能失败。若需要从旧行为切换到 scoped mode，请先删除旧的 KubeBYON ClusterRoleBinding 后再升级，或本次升级继续显式设置 rbac.clusterAdmin=true。
• 如果自定义 vCluster chart、hook 或插件申请了 scoped RBAC 未覆盖的新资源，可临时设置 rbac.clusterAdmin=true 回退到历史 cluster-admin 绑定；生产环境建议优先补充 scoped RBAC，而不是长期启用回退。

运维前提与兼容说明：

• addressMode 只影响默认 GatewayClass 解析，不会把三个角色的 Gateway 合并成一个对象
• “single / dual 公网 IP”是接入规划语义，不保证控制器一定实际分配 1 个或 2 个公网 IP
• 最终是否共享地址、共享 LoadBalancer、共享 data plane，取决于 Gateway controller 的实现，以及你是否把不同 GatewayClass 绑定到同一 address pool / 同一 provider 配置
• 如果计划走 single，请先确认 controller 支持多个 Gateway 通过 shared GatewayClass 或共享地址池复用同一入口
• 如果计划走 dual，请先确认 edge / workload 对应的 GatewayClass、公网地址、DNS 和证书边界都已准备好
• 若你暂时不需要 profiles，也可以继续只设置 gatewayAPI.gatewayClassName，保持向后兼容的单类 GatewayClass 配置方式

如果启用了平台 API Gateway，建议同步检查：

• session.cookieSecure=true
• cors.allowedOrigins 是否符合你的站点域名策略
• 管理后台中的 public_base_url / join_base_url 是否已更新为你的最终站点 URL

更多边界说明见：

• docs/architecture/managed-workload-ingress-plan.md
• docs/runbooks/deploy-gateway-api-public-access.md

3.3 使用本地镜像时的构建与导入

如果你不走镜像仓库，而是在宿主节点本地构建镜像，必须使用多机 Dockerfile（包含 kubebyon-api 和 kubebyon-worker 两个可执行文件）：

cd /opt/kubebyon
docker build \
  -f deployments/multi-node/docker-compose/Dockerfile \
  -t kubebyon-multi-node:helm-test .

如果启用了 web.enabled=true，还需要单独构建 web 镜像：

docker build \
  -f web/Dockerfile \
  -t kubebyon-web:helm-test \
  .

当前 web/Dockerfile 会从仓库根目录读取 docs/，导出 Next.js 静态站点，并通过 Nginx 监听 3000。

并且需要把镜像导入到所有可能调度 API/Worker 的节点（至少 master + worker）：

# 在每台节点执行
docker save kubebyon-multi-node:helm-test | k3s ctr images import -

如启用了 web，也别忘了同步导入：

# 在每台可能调度 web 的节点执行
docker save kubebyon-web:helm-test | k3s ctr images import -

如果误用了 deployments/single-node/docker-compose/Dockerfile，worker 容器会因为缺少 kubebyon-worker/start-kubebyon-worker.sh 而启动失败。

如果 worker 节点没有 docker，可以只在 master 构建镜像，再把 docker save 生成的 tar 包通过宿主内网分发到 worker 并导入到 k3s/containerd。

3.4 云端构建 + Helm 升级已有 release（推荐联调 / 热修路径）

如果已有一个正在运行的多机 Helm release，希望在不依赖外部镜像仓库的前提下做云端热修，推荐以下路径。

以下示例基于：

• 源码目录：/root/kubebyon-build-96d949a
• 新镜像 tag：routefix-96d949a
• Helm release：kubebyon-multi-node
• namespace：kubebyon-multi-node

3.4.1 在 master 构建镜像

cd /root/kubebyon-build-96d949a

docker build \
  -f deployments/multi-node/docker-compose/Dockerfile \
  -t kubebyon-multi-node:routefix-96d949a .

导入到 master 节点自己的 k3s containerd：

docker save kubebyon-multi-node:routefix-96d949a | k3s ctr images import -

3.4.2 分发到 worker（worker 无 docker 时）

先在 master 导出 tar：

docker save -o /root/routefix-96d949a.tar kubebyon-multi-node:routefix-96d949a

临时起一个仅用于宿主内网分发的 HTTP 服务：

cd /root
python3 -m http.server 18080 --bind 10.104.0.4

然后在 worker 通过 master 私网 IP 下载并导入：

curl -fL http://10.104.0.4:18080/routefix-96d949a.tar -o /root/routefix-96d949a.tar
k3s ctr images import /root/routefix-96d949a.tar

完成后别忘了关闭临时文件服务并清理 tar 包。

3.4.3 Helm 升级

先准备 chart 依赖：

helm dependency build /root/kubebyon-build-96d949a/deployments/multi-node/helm/kubebyon

建议先导出当前 release values，作为升级基线：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

helm get values kubebyon-multi-node -n kubebyon-multi-node -o yaml \
  > /root/kubebyon-multi-node-values-current.yaml

然后执行升级：

helm upgrade --install kubebyon-multi-node \
  /root/kubebyon-build-96d949a/deployments/multi-node/helm/kubebyon \
  -n kubebyon-multi-node \
  -f /root/kubebyon-multi-node-values-current.yaml \
  --set image.tag=routefix-96d949a \
  --wait \
  --timeout 10m

升级完成后，建议立刻确认：

kubectl -n kubebyon-multi-node get pods -o wide
kubectl -n kubebyon-multi-node get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.image}{" "}{end}{"\n"}{end}'

重点确认 api、worker 与 route-agent 都已经切到新 tag。

4. 安装

如果本机没有 Helm，可用容器版 Helm；常规环境也可直接使用系统 Helm。

先准备依赖：

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm dependency build /opt/kubebyon/deployments/multi-node/helm/kubebyon

安装：

kubectl create namespace kubebyon-multi-node --dry-run=client -o yaml | kubectl apply -f -

helm upgrade --install kubebyon-multi-node \
  /opt/kubebyon/deployments/multi-node/helm/kubebyon \
  -n kubebyon-multi-node \
  -f /root/kubebyon-multi-node-values.yaml \
  --wait \
  --timeout 20m

如果宿主集群是 k3s 默认 traefik(Service=LoadBalancer)，且 API 仍使用 chart 默认 publicAccess.provider=haproxy + hostNetwork: true + haproxy :443，建议先释放 443，否则 API Pod 可能无法调度：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

kubectl -n kube-system patch svc traefik --type merge -p '{"spec":{"type":"ClusterIP"}}'
kubectl -n kube-system delete ds -l svccontroller.k3s.cattle.io/svcname=traefik

如果改用 publicAccess.provider=gatewayapi，请先完成：

• Gateway API experimental CRD 安装
• Gateway controller 安装（推荐 Envoy Gateway）
• controller 数据面地址可达

参考：

• ./deploy-gateway-api-public-access.md

5. 验证

查看工作负载：

kubectl -n kubebyon-multi-node get deploy,svc,pods,pvc -o wide

如果使用默认 Longhorn vCluster control plane 存储配置，额外确认 StorageClass 和 Longhorn 组件：

kubectl get storageclass
kubectl -n longhorn-system get pods -o wide
kubectl -n longhorn-system get volumes.longhorn.io -o wide
kubectl -n longhorn-system get replicas.longhorn.io -o wide

创建测试集群后，确认对应 vCluster namespace 中的控制面 PVC 使用 longhorn：

kubectl -n <cluster-namespace> get pvc -o wide

期望控制面 PVC 为 Bound，STORAGECLASS=longhorn，对应 Longhorn volume 为 healthy。

查看 worker：

kubectl -n kubebyon-multi-node logs deploy/kubebyon-multi-node-worker -f

查看 RabbitMQ：

kubectl -n kubebyon-multi-node get svc kubebyon-multi-node-rabbitmq

如果使用 publicAccess.provider=gatewayapi，再额外检查：

kubectl -n kubebyon-multi-node get gateway
kubectl -n kubebyon-multi-node describe gateway kubebyon-multi-node-kubebyon-gateway

重点确认：

• Gateway 已创建
• listener 名称与 gatewayAPI.listenerName 一致
• Gateway controller 已接受并编程该 listener
• control-plane Gateway 实际解析到的 GatewayClass 是否符合 gatewayAPI.addressMode / gatewayAPI.gatewayClassProfiles.* 预期

如果同时启用了 gatewayAPI.platform.enabled=true，再额外检查：

kubectl -n kubebyon-multi-node get gateway <platform-gateway-name>
kubectl -n kubebyon-multi-node get httproute
kubectl -n kubebyon-multi-node describe httproute <platform-api-route-name>

重点确认：

• platform Gateway 的 HTTPS listener 已被 controller 接受
• HTTPRoute 的 ResolvedRefs=True
• HTTPRoute 的 Accepted=True
• 若启用 web.enabled=true，/ 会被额外转发到 web Service
• platform Gateway 实际解析到的 GatewayClass 是否符合 profile 或显式 override 预期

如果启用了 web.enabled=true，建议再检查：

kubectl -n kubebyon-multi-node get deploy,svc | rg 'kubebyon-web|web'
kubectl -n kubebyon-multi-node describe httproute <platform-web-route-name>

如果同时启用了 gatewayAPI.workload.enabled=true，再额外检查：

kubectl -n <workload-gateway-namespace> get gateway <workload-gateway-name>
kubectl -n <workload-gateway-namespace> describe gateway <workload-gateway-name>
kubectl get httproute -A
kubectl get httproute,svc,endpointslice -A -l 'app.kubernetes.io/managed-by=kubebyon,kubebyon.app/gateway-api-sync-kind=workload-edge'

重点确认：

• workload Gateway 已创建，且与 control-plane / platform Gateway 分离
• workload Gateway 实际解析到的 GatewayClass 是否符合 profile 或显式 override 预期
• tls.enabled=false 时 listener 为 HTTP:80
• tls.enabled=true 时，Helm render 仍只保留 HTTP:80 listener；runtime syncer 收敛后应能看到动态维护的 HTTPS listener
• cluster 已生成 managed_workload_ingress_cname_target 或配置 hostname bindings 后，能看到 runtime syncer 在对应 cluster 宿主 namespace 中动态维护的 HTTPRoute、Service 与 EndpointSlice
• HTTPRoute 的 hostnames 应覆盖 cluster 级 CNAME target 与已绑定 hostname，backend 指向同 namespace 的 shim Service
• 这些 shim 资源当前优先转发到目标 vCluster 内托管 ingress controller 的 PodIP:80；若当前宿主机对 PodIP 不可达，则自动回退到宿主节点 IP + NodePort
• 若启用 certManager.enabled=true，还能看到 runtime syncer 在 workload Gateway namespace 动态维护的共享 Certificate
• 若启用 certManager.selfManaged.enabled=true，对 self-managed 外部 hostname 还应看到独立 Certificate，并且 dedicated HTTPS route 上会出现 URLRewrite.hostname=<managed_workload_ingress_cname_target>

5.1 route-agent stale-route 回归（推荐多 vnode / 热修后执行）

如果这次升级涉及 gatewayAPI.workload.podCIDRRoute.mode=routeagent，建议在正式发布后追加一次 stale-route 回归。

示例：

• 旧 vnode 路由：10.64.1.0/24 via 10.104.0.2
• 当前期望路由：10.64.2.0/24 via 10.104.0.3

可在 master / worker 宿主节点手工注入旧路由：

ip route replace 10.64.1.0/24 via 10.104.0.2 dev eth1 proto 186
ip route show proto 186

等待一轮 route-agent 同步（默认 10s，建议观察 20s）后再检查：

ip route show proto 186

预期结果应只剩当前声明态对应的 managed route，例如：

10.64.2.0/24 via 10.104.0.3 dev eth1

如果仍残留旧 route，说明正式镜像或 route-agent 行为与预期不一致，需要继续排查：

• 实际运行镜像 tag / imageID
• RoutePlan 当前声明
• route-agent 日志
• 宿主容器内 ip 命令与 netlink 行为差异

同时建议再做一次公网访问验证：

curl -i --max-time 10 http://<workload-hostname>/

确认修复没有破坏对 pod backend 的公网转发链路。

6. 相关目录

• deployments/multi-node/README.md
• deployments/multi-node/helm/kubebyon/values.yaml
• docs/runbooks/deploy-kubebyon-backend-multi-node-docker-compose.md
• docs/runbooks/deploy-gateway-api-public-access.md