KubeBYON 多机 Docker Compose 部署 Runbook

最后更新：2026-04-27

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

目标拓扑：

  • backend 节点：kubebyon-api + PostgreSQL + RabbitMQ + HAProxy
  • worker 节点：一个或多个 kubebyon-worker

相比旧的 deployments/single-node/docker-compose/：

  • 原目录保持不变，继续服务单机 / 一体化部署
  • 当前目录额外引入 RabbitMQ 和独立 worker
  • 适合验证 cluster lifecycle 异步任务、消息队列、PG 并发锁

1. 目录

deployments/multi-node/docker-compose/
├── .env.example
├── .env.worker.example
├── Dockerfile
├── README.md
├── docker-compose.yml
├── docker-compose.worker.yml
└── ...

2. backend 节点启动

进入目录：

cd /opt/kubebyon/deployments/multi-node/docker-compose
cp .env.example .env
cp kubebyon-vcluster-values.example.yaml runtime/kubebyon-vcluster-values.yaml

至少修改：

  • POSTGRES_PASSWORD
  • KUBEBYON_ADMIN_PASSWORD
  • KUBEBYON_HOST_KUBECONFIG_PATH
  • KUBEBYON_RABBITMQ_URL

如果这是正式或公网环境，必须显式打开生产模式：

  • KUBEBYON_ENV=production 或 KUBEBYON_PRODUCTION=true

否则仍会按开发模式启动，不会执行生产安全拒启动校验。KUBEBYON_ENV=production 会强制进入生产模式，KUBEBYON_PRODUCTION=false 不能覆盖它。

所有环境都会拒绝缺失 KUBEBYON_DATABASE_DSN。生产模式会额外拒绝默认管理员密码、CORS=*、不安全 session cookie，以及启用 admission webhook 时缺失的 TLS cert/key 或 shared secret。

如果 Web Console 与 API 不同 origin，还必须把 Console 站点写入：

  • KUBEBYON_CORS_ALLOWED_ORIGINS，例如 https://console.example.com

浏览器 cookie session 通常只支持同站跨 origin（例如 console.example.com -> api.example.com）；任意 cross-site 前端仍会被 Sec-Fetch-Site: cross-site 与 SameSite=Lax cookie 策略阻止，需改用 Bearer/API token 或重新设计 SameSite=None。浏览器 cookie session 不建议使用 *：wildcard CORS 不会返回 credentials，也不会被 CSRF 防护信任。认证与 join script 请求默认启用 IP 级限流；如 backend 前面有反向代理，请同步配置 KUBEBYON_TRUSTED_PROXY_CIDRS，否则限流和审计看到的可能是代理 IP。

如果你希望 worker 从私网访问 backend 节点上的 PostgreSQL / RabbitMQ，通常还要改：

  • KUBEBYON_POSTGRES_HOST_BIND
  • KUBEBYON_POSTGRES_CONNECT_HOST
  • KUBEBYON_RABBITMQ_HOST_BIND
  • KUBEBYON_RABBITMQ_URL

若监听地址改成私网 IP，请同步把 backend 自己的连接地址也改掉，不要保留为 127.0.0.1。

如需锁定托管业务流量入口内置 chart 版本，backend 节点 .env 还可以设置：

  • KUBEBYON_MANAGED_INGRESS_CHART_NAME=ingress-nginx
  • KUBEBYON_MANAGED_INGRESS_CHART_REPO=https://kubernetes.github.io/ingress-nginx
  • KUBEBYON_MANAGED_INGRESS_CHART_VERSION=

说明：

  • 当前运行时只支持 ingress-nginx 作为内置托管 controller
  • 通常只建议覆盖 KUBEBYON_MANAGED_INGRESS_CHART_VERSION

启动：

docker compose --env-file .env up -d --build

查看状态：

docker compose --env-file .env ps
docker compose --env-file .env logs -f kubebyon-api
docker compose --env-file .env logs -f rabbitmq

3. worker 节点启动

把以下内容同步到 worker 机器：

  • cmd/
  • internal/
  • go.mod
  • go.sum
  • deployments/multi-node/docker-compose/

进入目录：

cd /opt/kubebyon/deployments/multi-node/docker-compose
cp .env.worker.example .env.worker
cp kubebyon-vcluster-values.example.yaml runtime/kubebyon-vcluster-values.yaml

把以下配置改成 backend 节点的私网地址：

  • KUBEBYON_DATABASE_DSN
  • KUBEBYON_RABBITMQ_URL

如果 worker 也运行在正式或公网环境，必须同样显式设置 KUBEBYON_ENV=production 或 KUBEBYON_PRODUCTION=true， 便于统一部署语义与日志；worker 启动时仍会强制校验 KUBEBYON_DATABASE_DSN。

启动：

docker compose \
  -f docker-compose.worker.yml \
  --env-file .env.worker \
  up -d --build

查看日志：

docker compose \
  -f docker-compose.worker.yml \
  --env-file .env.worker \
  logs -f kubebyon-worker

4. admission webhook 相关

如果启用了 admission webhook：

  • backend 节点仍按 gen-admission-assets.sh 生成证书与 shared secret
  • worker 节点需要同步 runtime/admission/ 中的证书文件
  • worker 节点的 .env.worker 也要同步：
    • KUBEBYON_ADMISSION_BASE_URL
    • KUBEBYON_ADMISSION_SHARED_SECRET
    • KUBEBYON_MANAGED_INGRESS_CHART_*（如 backend 锁定了 managed ingress chart version）

5. 基本验证

backend API：

curl -fsS http://127.0.0.1:${KUBEBYON_HTTP_PORT:-8080}/healthz

RabbitMQ：

docker compose --env-file .env exec rabbitmq rabbitmq-diagnostics -q ping

worker：

docker compose -f docker-compose.worker.yml --env-file .env.worker ps

6. 相关目录

  • deployments/multi-node/README.md
  • deployments/multi-node/docker-compose/README.md
  • docs/runbooks/deploy-kubebyon-backend-multi-node-helm.md
  • docs/architecture/managed-workload-ingress-plan.md