KubeBYON 后端部署与运行总览

最后更新：2026-04-27

本文档描述当前版本 KubeBYON 后端 API 的正式部署方式，以及每个核心 API 请求在后端内部的执行步骤与最终效果。

适用范围：

需要部署当前 KubeBYON 后端

需要理解后端如何驱动 vCluster Private Nodes

需要明确每个请求到底会改数据库、改 Kubernetes，还是只读查询

1. 当前版本的真实工作方式

当前版本的 KubeBYON 后端已经固定使用真实 vcluster 后端，且它的真实实现已经不是早期的：

exec.Command("vcluster", "create", ...)
exec.Command("vcluster", "connect", ...)
pods/exec 进入 control-plane Pod 执行命令

而是：

创建 vCluster：使用 Helm Go SDK
读取节点：使用 client-go 直连 vCluster API
签发 join token：使用 client-go 在 vCluster 中创建 bootstrap.kubernetes.io/token Secret
状态持久化：使用 PostgreSQL

因此当前后端的实际形态应理解为：

Go API + PostgreSQL + Helm SDK + Kubernetes API(client-go)

2. 部署目标

完成本文档中的步骤后，你将得到：

一个可运行的 kubebyon-api 后端进程
一个已连接 PostgreSQL 的 KubeBYON API
一个可通过 API 创建 vCluster 的控制面入口
一个可通过 API 签发 BYON join token 的统一接口
一个可通过 API 实时读取 vCluster 节点状态的查询入口
一个可按 cluster 维度收敛托管业务流量入口 controller 的后端运行时

3. 前置条件

在部署 KubeBYON 后端前，需要先具备这些条件。

3.1 基础宿主环境

你至少需要一台作为 Host 的 Linux 机器，建议：

角色	最低建议
Host	2C / 4G / Debian 12

该机器需要承担：

宿主 Kubernetes（本文档使用 k3s）
self-hosted vCluster Platform
用户 vCluster
KubeBYON API 本身

3.2 数据库

当前版本仅支持 PostgreSQL。

你需要准备一个可写数据库，例如：

postgresql://user:password@host:5432/kubebyon?sslmode=require

服务启动时会自动初始化表结构，无需额外执行迁移脚本。

3.3 Private Nodes 所需平台能力

如果你要让 KubeBYON 创建启用 privateNodes.enabled: true 的 vCluster，则必须提前准备：

self-hosted vCluster Platform
一个可用的 AccessKey
一个 Kubernetes Secret：vcluster-platform-api-key

注意：当前代码会在创建集群前，将这个 Secret 从源 namespace 复制到目标 namespace。

4. KubeBYON 后端部署步骤

第 1 步：在 Host 上安装基础组件

先在 Host 上准备基础工具：

apt-get update
apt-get install -y curl ca-certificates jq openssl postgresql-client

安装 k3s：

curl -sfL https://get.k3s.io | \
  INSTALL_K3S_EXEC='server --write-kubeconfig-mode 644 --tls-san <HOST_IP>' sh -

安装 Helm：

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

安装 vCluster CLI：

curl -L https://github.com/loft-sh/vcluster/releases/download/v0.33.0/vcluster-linux-amd64 \
  -o /usr/local/bin/vcluster
chmod +x /usr/local/bin/vcluster

验证：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes -o wide
kubectl get pods -A -o wide
helm version
vcluster version

这一步的效果

你会得到一个可用的宿主集群，后续所有组件都将部署在这里：

vCluster Platform
业务 vCluster
KubeBYON API

第 2 步：安装 self-hosted vCluster Platform

准备平台 values（低配机器建议压低资源请求）：

resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 2Gi

执行安装：

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

vcluster platform start \
  --namespace vcluster-platform \
  --host "loft.<HOST_IP>.sslip.io" \
  --email admin@kubebyon.local \
  --password '<LOFT_ADMIN_PASSWORD>' \
  --values /root/vcluster-platform-values.yaml \
  --no-login \
  --no-port-forwarding \
  --no-tunnel

如果宿主入口是 k3s 默认的 Traefik，需要修正 Ingress Class：

kubectl patch ingress loft-ingress -n vcluster-platform \
  --type merge \
  -p '{"spec":{"ingressClassName":"traefik"}}'

验证：

kubectl get pods,svc,ingress -n vcluster-platform -o wide
curl -kI "https://loft.<HOST_IP>.sslip.io"

这一步的效果

你会得到一个可访问的 self-hosted vCluster Platform，它是后续启用 Private Nodes 的前提能力之一。

第 3 步：创建 Platform AccessKey 与 Secret

先创建一个专门保存平台 Secret 的 namespace：

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

准备一个 AccessKey：

apiVersion: storage.loft.sh/v1
kind: AccessKey
metadata:
  name: admin-vcluster
spec:
  user: admin
  type: Other
  key: <PLATFORM_ACCESS_KEY>
  scope:
    allowLoftCli: true
    projects:
      - project: "*"
    roles:
      - role: vcluster

应用：

kubectl apply -f /tmp/admin-vcluster-key.yaml

可选：用该 key 验证登录：

vcluster platform login "https://loft.<HOST_IP>.sslip.io" \
  --access-key "<PLATFORM_ACCESS_KEY>" \
  --insecure

创建供 KubeBYON 复制的 Secret：

kubectl create secret generic vcluster-platform-api-key -n kubebyon-system \
  --from-literal=host="https://loft.<HOST_IP>.sslip.io" \
  --from-literal=accessKey="<PLATFORM_ACCESS_KEY>" \
  --from-literal=insecure='true' \
  --dry-run=client -o yaml | kubectl apply -f -

这一步的效果

后续通过控制台 API POST /api/console/clusters 创建集群时，KubeBYON 可以把这个 Secret 自动复制到目标 namespace，用于创建支持 Private Nodes 的 vCluster。

第 4 步：准备 vCluster values 文件

当前推荐的最小 values 示例：

privateNodes:
  enabled: true
controlPlane:
  distro:
    k8s:
      enabled: true
      image:
        tag: v1.31.2
  coredns:
    embedded: false
  service:
    spec:
      type: NodePort
  proxy:
    extraSANs:
      - "<HOST_IP>"
  statefulSet:
    resources:
      requests:
        cpu: 100m
        memory: 256Mi
        ephemeral-storage: 1Gi
networking:
  podCIDR: 10.64.0.0/16
  serviceCIDR: 10.128.0.0/16

设计说明

privateNodes.enabled: true：启用 BYON / Private Nodes 能力
service.type: NodePort：让 vCluster API 可以通过宿主机公网地址访问
extraSANs：允许通过宿主机 IP 访问 TLS 端点
不固定 httpsNodePort：减少端口冲突概率

这一步的效果

该文件将被 KubeBYON 后端在创建集群时直接传入 vCluster Helm Chart。

第 5 步：准备 PostgreSQL DSN

当前版本使用 PostgreSQL 作为唯一正式存储。

示例：

KUBEBYON_DATABASE_DSN=postgresql://user:password@host:5432/kubebyon?sslmode=require

这一步的效果

后端启动时会：

连接 PostgreSQL
自动初始化表：
- clusters
- tokens
- nodes

第 6 步：编译 Linux 目标二进制

如果你的本地开发机不是 Linux，必须交叉编译。

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags='-s -w' \
  -o .tmp/bin/kubebyon-api ./cmd/kubebyon-api

这一步的效果

你会得到一个可直接上传到 Debian / Linux x86_64 机器上运行的后端二进制。

第 7 步：上传后端与配置文件到 Host

需要上传：

kubebyon-api
kubebyon-api.env
kubebyon-vcluster-values.yaml

推荐环境变量如下：

KUBEBYON_HTTP_ADDR=:8080
KUBEBYON_DATABASE_DSN=<POSTGRES_DSN>
KUBEBYON_CORS_ALLOWED_ORIGINS=https://console.example.com
KUBEBYON_SESSION_COOKIE_SECURE=true
KUBEBYON_JOIN_RATE_LIMIT_WINDOW_SECONDS=3
KUBEBYON_JOIN_RATE_LIMIT_BURST=5
KUBEBYON_JOIN_RATE_LIMIT_MAX_ENTRIES=10000
KUBEBYON_AUTH_RATE_LIMIT_WINDOW_SECONDS=30
KUBEBYON_AUTH_RATE_LIMIT_BURST=5
KUBEBYON_AUTH_RATE_LIMIT_MAX_ENTRIES=5000
# Comma-separated reverse proxy CIDRs allowed to supply X-Forwarded-For / X-Real-IP.
KUBEBYON_TRUSTED_PROXY_CIDRS=127.0.0.1/32,10.0.0.0/8
KUBEBYON_KUBECONFIG_PATH=/etc/rancher/k3s/k3s.yaml
KUBEBYON_VCLUSTER_VALUES_FILE=/root/kubebyon-vcluster-values.yaml
KUBEBYON_VCLUSTER_CHART_VERSION=0.33.0
KUBEBYON_MANAGED_INGRESS_CHART_VERSION=
KUBEBYON_PLATFORM_API_KEY_SECRET_NAME=vcluster-platform-api-key
KUBEBYON_PLATFORM_API_KEY_SOURCE_NAMESPACE=kubebyon-system

各变量作用

变量	作用
`KUBEBYON_HTTP_ADDR`	API 监听地址
`KUBEBYON_DATABASE_DSN`	PostgreSQL 连接串
`KUBEBYON_CORS_ALLOWED_ORIGINS`	逗号分隔的浏览器 Console origin 白名单。cookie session 同站跨 origin 调用必须显式配置；任意 cross-site 前端仍会被 `Sec-Fetch-Site: cross-site` 与 `SameSite=Lax` cookie 策略阻止，需改用 Bearer/API token 或重新设计 `SameSite=None`。`*` 不会返回 credentials，也不会被 CSRF 防护信任。
`KUBEBYON_SESSION_COOKIE_SECURE`	HTTPS 站点应设为 `true`，让 session cookie 只通过 HTTPS 发送。
`KUBEBYON_JOIN_RATE_LIMIT_*`	join script 下载限流；默认 burst=5、每 3 秒恢复 1 次，超过后返回 `429` + `Retry-After`。
`KUBEBYON_AUTH_RATE_LIMIT_*`	登录、注册、验证码、重置密码限流；默认 burst=5、每 30 秒恢复 1 次，超过后返回 `429` + `Retry-After`。
`KUBEBYON_TRUSTED_PROXY_CIDRS`	逗号分隔的可信反向代理 CIDR；只有来自这些地址的请求才会采信 `X-Forwarded-For` / `X-Real-IP` 作为审计客户端 IP。未部署反向代理时可留空。
`KUBEBYON_KUBECONFIG_PATH`	宿主集群 kubeconfig
`KUBEBYON_VCLUSTER_VALUES_FILE`	vCluster Helm values 文件
`KUBEBYON_VCLUSTER_CHART_VERSION`	vCluster Chart 版本
`KUBEBYON_MANAGED_INGRESS_CHART_VERSION`	可选，锁定托管业务流量入口内置 chart 版本
`KUBEBYON_PLATFORM_API_KEY_SECRET_NAME`	要复制的 Secret 名称
`KUBEBYON_PLATFORM_API_KEY_SOURCE_NAMESPACE`	Secret 源 namespace

注意：join_base_url / public_base_url 现在统一改为在管理员控制台“系统设置”里维护，不再通过环境变量注入。

当前托管业务流量入口内置 controller 明确收敛为 ingress-nginx，因此通常只建议覆盖 version，不建议修改 chart name / repo。

第 8 步：启动 KubeBYON 后端

可以使用后台方式启动：

nohup /root/kubebyon-api >/var/log/kubebyon-api.log 2>&1 &
echo $! >/var/run/kubebyon-api.pid

验证健康检查：

curl -sf http://127.0.0.1:8080/healthz

{"status":"ok"}

查看日志时，建议确认以下关键项：

storage initialized, driver=postgres
using vcluster backend
control_plane_provisioner=helm-sdk
node_observer=client-go
token_issuer=client-go-bootstrap-token

这一步的效果

说明后端已经：

成功启动 HTTP 服务
成功连接 PostgreSQL
成功装配 vCluster 后端能力

5. 核心 API 请求说明

本节讲的是每个请求在当前版本中的真实执行路径。

5.1 `GET /healthz`

请求

GET /healthz

后端步骤

进入健康检查 handler
直接返回：

{"status":"ok"}

效果

只说明 API 进程可访问
不说明集群已创建
不说明数据库里有业务数据
不说明 Worker 已可加入

5.2 `POST /api/console/clusters`

请求示例

curl -X POST http://<HOST_IP>:8080/api/console/clusters \
  -H 'Content-Type: application/json' \
  -H 'Cookie: kubebyon_session=<SESSION>' \
  -d '{
    "name":"demo",
    "vcluster_name":"demo",
    "namespace":"demo",
    "control_plane_host":"<HOST_IP>"
  }'

后端步骤

校验请求体，name 不能为空
生成 cluster id，例如：cl_xxx
规范化 vcluster_name 与 namespace
先将 cluster 记录写入 PostgreSQL，状态为 provisioning
确保目标 namespace 存在
从 KUBEBYON_PLATFORM_API_KEY_SOURCE_NAMESPACE 读取 vcluster-platform-api-key
将该 Secret 复制到目标 namespace
使用 Helm Go SDK 安装或升级 vCluster Chart
Helm release 成功后，将 cluster 状态更新为 ready
若 Helm 阶段失败，则将 cluster 状态更新为 error

对 Kubernetes 的影响

会新增或更新：

目标 namespace
vcluster-platform-api-key Secret
vCluster release
vCluster control-plane Pod / StatefulSet
vCluster Service
导出的 kubeconfig Secret（通常是 vc-<vclusterName>）

对数据库的影响

clusters 表新增 1 条记录，并在成功后更新状态为 ready。

请求效果

该请求是当前系统的控制面创建入口。成功后意味着：

一个可供后续签发 join token、接入 Worker、读取节点状态的 vCluster 已经创建完成。

5.3 `GET /api/console/clusters`

请求

GET /api/console/clusters

后端步骤

校验当前登录用户
从 PostgreSQL 读取当前用户可访问的 clusters
返回集群元数据列表

效果

只读查询
不会创建或修改 Kubernetes 资源
不会创建 token 或节点

适用于：

查看当前用户可访问的集群
确认某个创建请求是否已经落库

5.4 `GET /api/console/clusters/{clusterID}`

请求

GET /api/console/clusters/cl_xxx

后端步骤

校验当前登录用户
根据 clusterID 查询 PostgreSQL clusters 表
校验当前用户是否可访问该集群
返回该集群的元数据

效果

只读查询
适合查看单个集群的 namespace、vcluster 名称、control plane host 和状态

5.5 `POST /api/console/clusters/{clusterID}/join-token`

请求示例

curl -X POST http://<HOST_IP>:8080/api/console/clusters/cl_xxx/join-token \
  -H 'Content-Type: application/json' \
  -H 'Cookie: kubebyon_session=<SESSION>' \
  -d '{
    "ttl_seconds":7200
  }'

后端步骤

校验当前登录用户
校验当前用户是否可访问该 cluster
从 PostgreSQL 中读取 cluster 元数据
读取宿主集群中导出的 vCluster kubeconfig Secret：
- 通常为 vc-<vclusterName>
解析 kubeconfig
如果 kubeconfig 中 server 仍是 https://localhost:8443，则根据实际 vCluster Service 自动解析成真实可访问地址：
- 例如 https://<HOST_IP>:<NodePort>
使用 client-go 直连 vCluster API
在 vCluster 的 kube-system namespace 中创建类型为：
- bootstrap.kubernetes.io/token 的 Secret
生成 join command：

curl -fsSLk "https://<HOST_IP>:<NODE_PORT>/node/join?token=<id.secret>" | sh -

将 token 信息写入 PostgreSQL tokens 表

对 Kubernetes 的影响

在 vCluster 内部新增 1 个真实的 bootstrap token Secret。

对数据库的影响

tokens 表新增 1 条记录。

请求效果

这是当前系统的节点接入凭据签发入口。它返回的不是演示字符串，而是：

真实可执行、可用于 Worker 加入 vCluster 的 join command。

5.6 Worker 执行 join command（非 API 请求，但属于主链路关键步骤）

典型命令

curl -fsSLk "https://<HOST_IP>:<NODE_PORT>/node/join?token=<TOKEN>" | sh -

Worker 侧发生的事情

join 脚本会自动执行：

检测发行版
准备 Kubernetes 所需二进制
加载内核模块
启用 ip_forward
启动 containerd
启动 kubelet
使用 bootstrap token 执行 join 流程
向 vCluster 注册 node

请求效果

该步骤完成后，新的 Worker 节点会出现在 vCluster 中，通常会先经历：

NotReady

随后在 flannel / kube-proxy / coredns 等系统组件拉起后进入：

Ready

5.7 `GET /api/console/nodes?cluster_id=<clusterID>`

请求

GET /api/console/nodes?cluster_id=cl_xxx

后端步骤

校验当前登录用户
根据 cluster_id 读取 cluster 元数据并校验权限
再次读取导出的 vCluster kubeconfig Secret
自动修正 vCluster API endpoint
使用 client-go 调用：
- CoreV1().Nodes().List(...)
将 Kubernetes Node 转换为 KubeBYON 自己的节点响应结构

对 Kubernetes / 数据库的影响

不修改 Kubernetes 资源
不写入 PostgreSQL nodes 表

请求效果

这是当前系统的真实节点状态查询入口。

返回的是：

实时节点状态
实时 Internal IP
实时 Ready / NotReady 状态

而不是缓存结果。

6. 推荐的正式调用顺序

如果你要按照当前最小主链路完成一次验证，建议按以下顺序执行：

第 1 步：检查 API 存活

GET /healthz

效果：

确认 API 进程可访问

第 2 步：创建集群

POST /api/console/clusters

效果：

创建 vCluster 控制面
写入 clusters 表

第 3 步：查询集群

GET /api/console/clusters
GET /api/console/clusters/{id}

效果：

确认 cluster 已存在且状态正确

第 4 步：创建 token

POST /api/console/clusters/{id}/join-token

效果：

在 vCluster 中创建真实 bootstrap token
返回可执行 join command
写入 tokens 表

第 5 步：在 Worker 执行 join command

效果：

Worker 加入 vCluster

第 6 步：轮询节点状态

GET /api/console/nodes?cluster_id={id}

效果：

初期可能 not_ready
稍后应转为 ready

7. Console kubectl 代理安全边界

POST /api/console/clusters/{clusterID}/kubectl 是控制台使用的后端 kubectl 代理，默认只读。

为降低越权和误操作风险，代理会拒绝以下类型：

写操作与节点运维：apply、delete、patch、drain、cordon、wait。
交互、隧道和文件传输：exec、port-forward、cp。
原始 API、身份冒充、连接覆盖和文件输入：--raw、--as、--as-group、--server、--token、--kubeconfig、-f/-k。
持续输出：watch / follow。

这是安全收紧，可能影响旧自动化或运维习惯。需要变更集群时，请改用专用 API、受控运维流程，或在授权环境中使用 kubeconfig。

8. 各请求的落地结果总表

请求	写数据库	改 Kubernetes	主要作用
`GET /healthz`	否	否	进程存活检查
`POST /api/console/clusters`	是	是	创建 vCluster
`GET /api/console/clusters`	否	否	查询集群列表
`GET /api/console/clusters/{id}`	否	否	查询单个集群
`POST /api/console/clusters/{id}/join-token`	是	是	签发真实 join token
`GET /api/console/nodes?cluster_id={id}`	否	否	实时查询指定集群节点

9. 部署完成后的最小验证清单

完成部署后，建议至少验证以下项目：

curl http://127.0.0.1:8080/healthz 返回 {"status":"ok"}
POST /api/console/clusters 成功返回 cluster.id
宿主集群中出现目标 namespace 与 vCluster Pod
POST /api/console/clusters/{id}/join-token 返回可执行 join command
Worker 执行 join command 后出现 This node has joined the cluster
GET /api/console/nodes?cluster_id={id} 最终返回 ready
在 vCluster 内调度一个 smoke pod 并验证 DNS

10. 当前实现的边界说明

10.1 `nodes` 表当前不是实时同步来源

虽然 API 可以返回真实节点，但当前读取路径是：

读取 vCluster kubeconfig Secret
用 client-go 直连 vCluster API
实时返回节点状态

因此：

API 里能看到节点
PostgreSQL nodes 表仍可能是 0

这属于当前设计范围，不代表测试失败。

10.2 当前最适合的使用方式

当前后端最适合的工作模式是：

KubeBYON API 负责统一入口与状态持久化
Helm SDK 负责创建 vCluster
client-go 负责发 token 和查节点

这是当前版本已经被真实机器验证通过的主链路。

11. 相关文档

API 简介：../api/http-api.md
托管业务流量入口：../architecture/managed-workload-ingress-plan.md

KubeBYON 后端部署与运行总览

1. 当前版本的真实工作方式

2. 部署目标

3. 前置条件

3.1 基础宿主环境

3.2 数据库

3.3 Private Nodes 所需平台能力

4. KubeBYON 后端部署步骤

第 1 步：在 Host 上安装基础组件

这一步的效果

第 2 步：安装 self-hosted vCluster Platform

这一步的效果

第 3 步：创建 Platform AccessKey 与 Secret

这一步的效果

第 4 步：准备 vCluster values 文件

设计说明

这一步的效果

第 5 步：准备 PostgreSQL DSN

这一步的效果

第 6 步：编译 Linux 目标二进制

这一步的效果

第 7 步：上传后端与配置文件到 Host

各变量作用

第 8 步：启动 KubeBYON 后端

这一步的效果

5. 核心 API 请求说明

5.1 GET /healthz

请求

后端步骤

效果

5.2 POST /api/console/clusters

请求示例

后端步骤

对 Kubernetes 的影响

对数据库的影响

请求效果

5.3 GET /api/console/clusters

请求

后端步骤

效果

5.4 GET /api/console/clusters/{clusterID}

请求

后端步骤

效果

5.5 POST /api/console/clusters/{clusterID}/join-token

请求示例

后端步骤

对 Kubernetes 的影响

对数据库的影响

请求效果

5.6 Worker 执行 join command（非 API 请求，但属于主链路关键步骤）

典型命令

Worker 侧发生的事情

请求效果

5.7 GET /api/console/nodes?cluster_id=<clusterID>

请求

后端步骤

对 Kubernetes / 数据库的影响

请求效果

6. 推荐的正式调用顺序

第 1 步：检查 API 存活

第 2 步：创建集群

第 3 步：查询集群

第 4 步：创建 token

第 5 步：在 Worker 执行 join command

第 6 步：轮询节点状态

7. Console kubectl 代理安全边界

8. 各请求的落地结果总表

9. 部署完成后的最小验证清单

10. 当前实现的边界说明

10.1 nodes 表当前不是实时同步来源

10.2 当前最适合的使用方式

11. 相关文档

5.1 `GET /healthz`

5.2 `POST /api/console/clusters`

5.3 `GET /api/console/clusters`

5.4 `GET /api/console/clusters/{clusterID}`

5.5 `POST /api/console/clusters/{clusterID}/join-token`

5.7 `GET /api/console/nodes?cluster_id=<clusterID>`

10.1 `nodes` 表当前不是实时同步来源