KubeBYON 部署 Runbook 入口

最后更新：2026-06-19

本页面向第一次部署或接手运维 KubeBYON 的读者，用来选择正确的部署文档。

1. 推荐阅读顺序

首次部署推荐路径

如果你只是想把当前产品跑起来，建议按下面顺序阅读：

  1. 先读本文：确认部署形态与可选能力边界。
  2. 选择一个主部署 runbook：
  3. 按需阅读可选能力 runbook：

2. 应该选哪种部署方式

场景推荐文档说明
第一次生产化自托管deploy-kubebyon-backend-helm.md推荐主路径；API 运行在宿主 Kubernetes 内
需要 API / Worker 分离deploy-kubebyon-backend-multi-node-helm.md适合多机、异步任务、RabbitMQ、独立 worker
本地开发 / 快速远程验证deploy-kubebyon-backend-docker-compose.md更容易调试，不是首选生产形态
Docker Compose 多机验证deploy-kubebyon-backend-multi-node-docker-compose.md适合验证 API/Worker/RabbitMQ 拆分
旧版裸机流程参考deploy-kubebyon-backend.md更偏早期手工部署参考，不建议作为新部署首选

3. 关键选择建议

3.1 单机还是多机

选择 单机，如果：

  • 你是第一次部署；
  • 你只需要一个 API 进程直接执行集群生命周期动作；
  • 你不想额外维护 RabbitMQ 和 worker。

选择 多机，如果：

  • 你希望 API 请求面和集群执行面分离；
  • 你需要一个或多个 kubebyon-worker 异步执行 cluster job；
  • 你已经准备好 PostgreSQL + RabbitMQ。

3.2 Helm 还是 Docker Compose

优先选 Helm：

  • 更贴近当前产品的 in-cluster 部署形态；
  • 更容易启用 Gateway API、route-agent、in-cluster web 等能力；
  • 更适合长期运维。

选择 Docker Compose：

  • 适合开发、PoC、远程快速验证；
  • 适合你需要直接看容器日志、快速 rebuild 的场景。

3.3 HAProxy 还是 Gateway API

选择 HAProxy，如果：

  • 你希望走当前 Helm chart 默认的控制面公网入口；
  • 你只需要稳定的 vCluster control plane SNI 入口；
  • 你的 Gateway API controller 尚未准备好。

选择 Gateway API，如果：

  • 你已经有可用的 Gateway API controller；
  • 你希望使用 shared Gateway + TLSRoute 承接 vCluster control plane；
  • 你还计划启用 platform Gateway 或 workload edge Gateway。

3.4 是否启用 workload edge

先不要启用，除非你明确需要平台托管业务流量入口。

启用 workload edge 前，请确认：

  • 你理解它和 public_access_mode 的区别：
    • public_access_mode：vCluster API / kubeconfig 控制面入口；
    • managed_workload_ingress_enabled：用户 workload HTTP/HTTPS 入口控制器；
  • 已配置 managed_workload_ingress_base_domain；
  • 已准备 workload Gateway、DNS、必要时的 cert-manager issuer。

3.5 是否启用 route-agent

kubebyon-route-agent 只和 Gateway API workload edge 的 PodCIDR 路由有关，不执行集群生命周期 job。

选择 routeagent 模式，通常适用于：

  • 多宿主节点；
  • workload edge 希望优先直连 vCluster 内托管 ingress controller PodIP:80；
  • 需要由每个宿主节点本地收敛 PodCIDR 路由。

否则可以先保持默认或不启用 PodCIDR route。

3.6 是否使用 Longhorn 存储 vCluster 控制面

当前 Helm values 默认把新建 vCluster control plane PVC 指向 storageClass: longhorn，用于避免控制面数据绑定在单个宿主节点的 local-path 上。

使用默认配置前，请确认：

  • 宿主集群已安装 Longhorn，且存在 longhorn StorageClass；
  • 所有可能承载 Longhorn 组件的宿主节点已安装 open-iscsi、nfs-common，并启用 iscsid；
  • 新增宿主节点后会补齐 Longhorn 节点依赖并确认 longhorn-system Pod 正常；
  • 你理解该配置只影响 vCluster control plane PVC，不自动迁移 PostgreSQL、RabbitMQ 或 vCluster 内用户 workload 的 StorageClass。

如果不准备安装 Longhorn，请在主部署 values 中把 vCluster control plane PVC 改成实际可用的 StorageClass，或关闭该 PVC 配置。

4. 首次部署 Checklist

4.1 基础设施

  • 宿主 Kubernetes / k3s 可用
  • kubectl 能访问宿主集群
  • helm 可用
  • 如使用 Helm，已确认默认 scoped RBAC 满足宿主集群策略；从旧 cluster-admin 默认行为升级时，已规划 ClusterRoleBinding 重建或临时 rbac.clusterAdmin=true 回退
  • PostgreSQL 可用，或确认启用内置 PostgreSQL chart
  • 如使用多机模式，RabbitMQ 可用
  • 如使用默认 vCluster values，Longhorn 已安装且 longhorn StorageClass 可用
  • 如使用 Longhorn，所有宿主节点已安装 open-iscsi、nfs-common 并启用 iscsid
  • 如使用 Gateway API，Gateway API CRD 与 controller 已安装
  • 如使用 cert-manager，Issuer / ClusterIssuer 已准备好

4.2 必要配置

  • 初始管理员账号 / 密码已设置或确认使用默认值后立即修改
  • public_base_url
  • join_base_url
  • 宿主 Kubernetes 连接方式：in-cluster config 或 kubeconfig
  • vCluster chart values 文件或 Helm values 已准备

4.3 可选配置

  • OAuth：GitHub / Google client ID 和 secret
  • SMTP：通知邮件投递
  • Captcha：hCaptcha / Turnstile
  • managed_workload_ingress_base_domain
  • Cloudflare DNS 自动化配置
  • Gateway API workload TLS / cert-manager 配置

4.4 部署后验证

  • /healthz 返回 OK（仅表示 API 进程/HTTP 路由存活，不代表 PostgreSQL、RabbitMQ、worker、宿主 Kubernetes 或 cluster job 全部健康）
  • 已额外验证管理员登录与数据库读写链路
  • 管理员可以登录
  • 可以创建 cluster，状态最终变为 ready
  • connection_status 最终变为 reachable
  • 可以创建 join token
  • BYON 节点执行 join script 后出现在节点列表中
  • 如使用多机模式，RabbitMQ 队列、consumer、worker 消费与测试 job 均正常
  • 如启用公网 kubeconfig，确认 api_endpoint 与 kubeconfig 可用
  • 如启用 workload ingress，确认 hostname binding 与 DNS 状态符合预期

5. 可选能力文档

能力文档何时阅读
Gateway API control-plane / platform / workload edgedeploy-gateway-api-public-access.md准备使用 Gateway API 替代或扩展 HAProxy 入口时
HAProxy control-plane 公网入口deploy-haproxy-public-access.md使用 Helm 默认 HAProxy provider 或需要排查 SNI 入口时
Admission Webhookdeploy-cluster-workload-admission-webhook.md需要对 vCluster 内 Pod 创建做资源默认值/配额校验时
Longhorn vCluster 控制面存储migrate-vcluster-control-plane-storage-to-longhorn.md使用默认 vCluster control plane Longhorn PVC、验证存储或需要回滚时
Console HTTPS on 443enable-console-https-on-443.md非 Gateway API Phase 3 场景下暴露控制台 HTTPS 时

6. 生产运维 Runbook

如果你准备长期运行 KubeBYON，建议至少补读以下文档：

主题文档适用场景
生产就绪检查production-readiness-checklist.md上线前、接手现网前做生产基线确认；也适合作为按角色导航中的 production readiness 起点
备份与恢复backup-restore.md为 PostgreSQL、RabbitMQ、配置与凭据建立恢复能力
升级与回滚upgrade-rollback.md做版本升级、维护窗口与失败回滚前
事故响应incident-response.md平台故障分级、止血、排障与复盘
PostgreSQL / RabbitMQ HAha-postgresql-rabbitmq-notes.md设计依赖组件可用性与恢复策略
vCluster 故障恢复vcluster-failure-recovery.md单租户 cluster 控制面异常排查与恢复
安全配置检查security-configuration-checklist.md上线前和周期性安全巡检
监控与告警检查observability-alert-checklist.md建立最小可观测性与值班告警基线

7. 推荐同时阅读