KubeBYON HTTP API（当前实现）

最后更新：2026-05-16

本文档描述当前仓库已经落地的 HTTP API。

当前推荐运行组合：

集群后端：vcluster

持久化存储：PostgreSQL

多机异步执行：RabbitMQ + kubebyon-worker（可选）

Gateway API workload PodCIDR routeagent 模式：kubebyon-route-agent DaemonSet（可选）

启动

KUBEBYON_HTTP_ADDR=:8080 ./scripts/dev/run-api.sh

首次启动后，请使用管理员账号登录控制台，在“系统设置”里补齐：

public_base_url
join_base_url
managed_workload_ingress_base_domain（可选；用于生成托管业务流量入口的 cluster 级 CNAME target）
OAuth2 提供商凭据（如需）

连接宿主 Kubernetes / vCluster 所需配置

KUBEBYON_KUBECONFIG_PATH=/etc/rancher/k3s/k3s.yaml \
KUBEBYON_VCLUSTER_VALUES_FILE=/root/kubebyon-values.yaml \
./scripts/dev/run-api.sh

说明：

当前运行时固定使用真实 vcluster 后端，不再提供 KUBEBYON_BACKEND 切换项
KUBEBYON_VCLUSTER_VALUES_FILE：传给 vCluster Helm Chart 的 values 文件
KUBEBYON_MANAGED_INGRESS_CHART_VERSION：可选，锁定托管业务流量入口内置 chart 版本
当前推荐使用 PostgreSQL 作为持久化存储，服务启动时自动初始化 schema
如果配置了 RabbitMQ 与 kubebyon-worker，集群生命周期操作会走异步 job 执行路径

浏览器安全、CORS 与限流

所有 HTTP 响应都会设置基础安全头：X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin、X-Frame-Options: DENY。
使用 session cookie 的 POST / PUT / PATCH / DELETE 请求会进行 CSRF 来源校验。后端会信任请求自身 origin、系统 public_base_url 以及显式配置的 KUBEBYON_CORS_ALLOWED_ORIGINS；* 不会被作为可信 cookie origin。
如果 Web Console 与 API 不同 origin，必须把 Console origin 显式加入 KUBEBYON_CORS_ALLOWED_ORIGINS。浏览器 cookie session 通常只支持同站跨 origin（例如 console.example.com -> api.example.com）；任意 cross-site 前端仍会被 Sec-Fetch-Site: cross-site 与 SameSite=Lax cookie 策略阻止，需改用 Bearer/API token 或重新设计 SameSite=None。
wildcard * 不会返回 Access-Control-Allow-Credentials，因此不适合浏览器 cookie session 登录。
带 Authorization: Bearer ... 的 API 请求不依赖 cookie，不走 cookie CSRF 校验。
join script 下载默认按客户端 IP 限流：KUBEBYON_JOIN_RATE_LIMIT_WINDOW_SECONDS=3、KUBEBYON_JOIN_RATE_LIMIT_BURST=5、KUBEBYON_JOIN_RATE_LIMIT_MAX_ENTRIES=10000。
登录、注册、验证码、重置密码默认按客户端 IP + endpoint scope 限流：KUBEBYON_AUTH_RATE_LIMIT_WINDOW_SECONDS=30、KUBEBYON_AUTH_RATE_LIMIT_BURST=5、KUBEBYON_AUTH_RATE_LIMIT_MAX_ENTRIES=5000。
触发限流时返回 429 Too Many Requests，并带 Retry-After header。
如果 API 位于反向代理之后，请配置 KUBEBYON_TRUSTED_PROXY_CIDRS，否则审计 IP 与限流 key 可能都是代理地址。

1. 接口总览

Health

GET /healthz

Join / Script

GET /join?token={token}
GET /api/join/clusters/{clusterID}/script?token={token}

推荐对外展示短命令：

curl -sfL "https://kubebyon.app/join?token=xxx" | sh -

/api/join/clusters/{clusterID}/script 保留用于兼容旧客户端。

Auth / Identity

GET    /api/auth/providers
GET    /api/auth/sso/{provider}/login
GET    /api/auth/sso/{provider}/callback
POST   /api/auth/register/send-code
POST   /api/auth/register
POST   /api/auth/reset-password/send-code
POST   /api/auth/reset-password
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

GET    /api/console/me
PUT    /api/console/me
POST   /api/console/me/avatar
DELETE /api/console/me

GET    /api/console/settings/notifications
PUT    /api/console/settings/notifications
      # body/response settings: email_notifications, slack_notifications,
      # telegram_notifications, telegram_chat_id

GET    /api/console/api-keys
POST   /api/console/api-keys
DELETE /api/console/api-keys/{keyID}

Billing / Plans

GET  /api/console/plans
GET  /api/console/billing/entitlement
GET  /api/console/orders
POST /api/console/orders
POST /api/console/orders/{orderID}/checkout
POST /api/console/orders/{orderID}/pay
POST /api/console/orders/{orderID}/cancel
POST /api/console/orders/test

POST /api/console/orders/{orderID}/checkout 为当前用户的待支付订单创建 Stripe Checkout Session，响应包含 checkout_url，前端应跳转到该 URL。启用前需要在管理员系统设置中配置 Stripe Secret Key、Stripe Webhook Secret，并配置 public_base_url。

Stripe Webhook

POST /api/stripe/webhook

Stripe webhook 需要配置到 https://<public_base_url>/api/stripe/webhook，当前处理 checkout.session.completed 与 checkout.session.async_payment_succeeded 事件，并在验签成功且支付状态确认成功后把对应订单标记为已支付。

Admin Activities

GET /api/console/admin/activities

Admin Cluster Jobs

GET /api/console/admin/cluster-jobs?status=&cluster_id=&limit=

Admin Plans

GET    /api/console/admin/plans
POST   /api/console/admin/plans
GET    /api/console/admin/plans/{planID}
PUT    /api/console/admin/plans/{planID}
DELETE /api/console/admin/plans/{planID}

Admin Users

GET  /api/console/admin/users
GET  /api/console/admin/users/{userID}
PUT  /api/console/admin/users/{userID}/status
POST /api/console/admin/users/{userID}/reset-password
GET  /api/console/admin/users/{userID}/login-history

Console Notification Settings

GET /api/console/settings/notifications
PUT /api/console/settings/notifications

settings 响应/请求包含 email_notifications、slack_notifications、slack_target 与 updated_at。当用户启用 slack_notifications=true 时，必须同时提供个人 slack_target（Slack user ID、DM channel ID 或 channel ID）；否则后端返回 validation error。个人订单通知只会在用户启用 Slack 且绑定了 slack_target 时派发 Slack，不会回退发送到管理员配置的全局 webhook/channel。

Admin Orders

GET  /api/console/admin/orders
POST /api/console/admin/orders/{orderID}/pay
POST /api/console/admin/orders/{orderID}/cancel

Admin System Settings / Notifications

GET  /api/console/admin/system-settings
PUT  /api/console/admin/system-settings
GET  /api/console/admin/notifications/config
PUT  /api/console/admin/notifications/config
POST /api/console/admin/notifications/test

统一测试通知接口 POST /api/console/admin/notifications/test 支持通过 Email、Slack 或 Telegram 发送示例模板，用于验证已保存的投递配置。请求体：

{
  "channel": "email|slack|telegram",
  "target": "recipient email / Slack user or channel ID / Telegram chat ID",
  "template": "welcome|cluster-alert|order-paid"
}

说明：

system-settings 当前额外支持：
- managed_workload_ingress_base_domain
- managed_workload_ingress_dns（enabled / active_provider / record_target_hostname / cloudflare.zone_id）
managed_workload_ingress_dns.cloudflare.api_token 仅支持写入；更新时需配合 api_token_changed
读取响应使用 managed_workload_ingress_dns.cloudflare.api_token_configured 表示是否已配置 token
notification_delivery.enabled_channels 现支持 email、slack、webhook、telegram。
notification_delivery 支持 Slack 投递字段：slack_enabled、slack_channel，以及写入专用的 slack_webhook_url/slack_webhook_url_changed、slack_bot_token/slack_bot_token_changed；读取响应使用 slack_webhook_configured 和 slack_bot_token_configured 表示密钥是否已配置。启用 Slack 时需提供 HTTPS incoming webhook URL，或 bot token（系统通知回退到全局 webhook/channel；用户个人通知会优先使用用户绑定的 Slack target + bot token）。
Telegram Bot 投递需启用 telegram_enabled 并配置 telegram_bot_token（写入时配合 telegram_bot_token_changed）。全局 telegram_chat_id 仅作为系统/管理员通知目标，个人订单通知不会默认投递到该目标。
管理员/系统集成出站 webhook 支持字段：webhook_enabled、webhook_url、webhook_headers、webhook_headers_changed、webhook_secret（仅写入）、webhook_secret_changed；读取时使用 webhook_secret_configured 表示是否已配置 secret，webhook_headers 只返回请求头名称和掩码值，具体值按 write-only 处理。
webhook_url 只允许 http/https 的公网 DNS 主机或公网 IP，拒绝 localhost/loopback、RFC1918/private、link-local、metadata、unspecified/multicast 等 SSRF 风险目标；发送器在拨号前重新解析并拒绝受限地址，以降低 DNS rebinding 风险。
用户级通知设置支持 slack_notifications/slack_target 与 telegram_notifications/telegram_chat_id；开启 Slack/Telegram 用户通知时必须绑定对应个人目标，订单通知只会投递到该用户绑定的目标。全局 webhook 仅作为系统/管理员集成目标，不会默认用于个人订单通知。
读取通知配置时不会返回 Slack webhook URL、Slack bot token、Telegram bot token 或 webhook secret 明文，使用对应 *_configured 字段表示是否已配置。配置 webhook secret 时会添加 X-KubeBYON-Signature: sha256=<hmac> 和 X-Hub-Signature-256 签名头。
当 managed_workload_ingress_base_domain 为合法域名时，console cluster 响应会返回只读字段 managed_workload_ingress_cname_target
若同时启用了 managed_workload_ingress_dns，后端会为该 cluster 级 managed_workload_ingress_cname_target 自动维护平台自有 Zone 下的 CNAME 记录
用户自定义 hostname binding 仍然允许使用外部域名；响应会额外返回只读 dns_management_scope（platform_managed / self_managed）来区分当前是否由平台自动托管 DNS。若启用 workload edge TLS / cert-manager，平台还会在 runtime syncer 中为 platform-managed hostname 动态维护共享 Certificate，并可选为 self-managed 外部 hostname 维护独立 Certificate

Clusters

GET    /api/console/clusters
POST   /api/console/clusters
GET    /api/console/clusters/{clusterID}
PUT    /api/console/clusters/{clusterID}
DELETE /api/console/clusters/{clusterID}
GET    /api/console/clusters/{clusterID}/workload-ingress-hostnames
POST   /api/console/clusters/{clusterID}/workload-ingress-hostnames
DELETE /api/console/clusters/{clusterID}/workload-ingress-hostnames/{bindingID}
POST   /api/console/clusters/{clusterID}/kubeconfig
GET    /api/console/clusters/{clusterID}/control-plane-metrics/history
POST   /api/console/clusters/{clusterID}/join-token
POST   /api/console/clusters/{clusterID}/kubectl

Tokens

DELETE /api/console/tokens/{tokenID}

Nodes

GET    /api/console/nodes
GET    /api/console/nodes/{nodeID}
GET    /api/console/node-events?cluster_id=&node_id=&type=&limit=
POST   /api/console/nodes/{nodeID}/cordon
POST   /api/console/nodes/{nodeID}/uncordon
POST   /api/console/nodes/{nodeID}/drain
DELETE /api/console/nodes/{nodeID}

Console Overview

GET /api/console/overview
GET /api/console/activities
GET /api/console/clusters/{clusterID}/operations

Admission / Internal

POST /api/internal/admission/clusters/{clusterID}/{signature}/mutate-pod
POST /api/internal/admission/clusters/{clusterID}/{signature}/validate-pod

2. 核心资源说明

2.1 Cluster

当前版本的 cluster 对象除了基础元数据外，还包含连接可达性信息。

典型字段：

id
name
namespace
vcluster_name
control_plane_host
kubernetes_version
workload_cpu_limit_milli_cores
workload_memory_limit_mib
control_plane_cpu_request_milli_cores
control_plane_memory_request_mib
public_access_enabled
public_access_mode
public_access_port
managed_workload_ingress_enabled
managed_workload_ingress_status
managed_workload_ingress_class
managed_workload_ingress_last_error
managed_workload_ingress_cname_target
managed_workload_ingress_dns_status
managed_workload_ingress_dns_message
managed_workload_ingress_dns_last_synced_at
managed_workload_ingress_dns_last_error
managed_workload_ingress_dns_last_error_at
api_endpoint
status
connection_status
kubeconfig_available
kubeconfig_available_at
last_observed_at
last_error_message
created_at
updated_at

`status` 与 `connection_status`

status：生命周期状态
- provisioning
- ready
- error
- deleting
- deleted
connection_status：连接状态
- pending
- kubeconfig_pending
- reachable
- unreachable
- error

`managed_workload_ingress_status`

disabled
provisioning
ready
error

`managed_workload_ingress_dns_status`

not_managed
pending
synced
error

说明：

该字段表示 KubeBYON 平台托管 DNS 自动化自身 的同步状态
它与 managed_workload_ingress_status 不同：后者表示托管 ingress controller 的收敛状态
managed_workload_ingress_dns_message 会补充当前 DNS 自动化状态说明
managed_workload_ingress_dns_last_synced_at 表示最近一次平台托管 DNS reconcile 成功完成的时间
managed_workload_ingress_dns_last_error / managed_workload_ingress_dns_last_error_at 表示最近一次平台托管 DNS reconcile 失败原因与时间
这些字段是观测字段，不改变原有 DNS reconcile 的 best-effort 语义
console / UI 当前会基于既有时间字段派生展示一个“已恢复（Recovered）”历史提示：当 managed_workload_ingress_dns_last_synced_at > managed_workload_ingress_dns_last_error_at 时，表示平台 DNS 自动化曾失败、随后又成功同步
该“已恢复（Recovered）”仅是前端派生展示，不是新增 API 字段；它也不表示公网 DNS 最终解析已经恢复

2.2 Token

当前版本的 token 采用只返回一次明文的语义。

2.3 Workload Ingress Hostname Binding

当前版本新增 cluster 级工作负载入口域名绑定资源。

典型字段：

id
cluster_id
hostname
status
dns_management_scope
dns_management_status
dns_management_message
dns_management_last_synced_at
dns_management_last_error
dns_management_last_error_at
tls_mode
tls_secret_name
tls_status
tls_last_synced_at
tls_last_error
tls_last_error_at
last_error
created_at
updated_at

`status`

pending
ready
error

`dns_management_status`

not_managed
pending
synced
error

说明：

status / last_error 仍表示公网 DNS 最终解析结果
dns_management_scope 表示当前是平台托管还是用户自管
dns_management_status / dns_management_message 表示 KubeBYON 平台 DNS 自动化自身 的同步状态
dns_management_last_synced_at 表示最近一次平台托管 DNS reconcile 成功完成的时间
dns_management_last_error / dns_management_last_error_at 表示最近一次平台托管 DNS reconcile 失败原因与时间
console / UI 当前也会基于既有时间字段派生展示 hostname binding 平台 DNS 自动化的“已恢复（Recovered）”历史提示：当 dns_management_last_synced_at > dns_management_last_error_at 时，表示平台 DNS 自动化曾失败、随后又成功同步
该“已恢复（Recovered）”仅是前端派生展示，不是新增 API 字段；它描述的是平台 DNS 自动化历史，不替代 status 对公网 DNS 最终解析结果的表达
因此：
- dns_management_scope=self_managed 且 status=ready 是合理的，表示该域名由用户自行维护 DNS，但最终解析已正确生效
- dns_management_scope=platform_managed 且 dns_management_status=synced 只表示平台自动化已经完成记录收敛，公网侧最终解析是否可见仍看 status
- base domain 外 hostname binding 仍然合法；此时 dns_management_* 的时间/错误字段可以为空

创建响应中的 token

POST /api/console/clusters/{clusterID}/join-token 的响应中，token 可能包含：

id
cluster_id
value ← 只在创建响应中返回
join_command ← 只在创建响应中返回
display_prefix
status
bootstrap_secret_name
expires_at
created_at

查询响应中的 token

撤销 token 接口返回的是生命周期元数据，通常不再包含：

value
join_command

而是包含：

id
cluster_id
display_prefix
status：active/used/expired/revoked
created_by_user_id
used_by_node_id
bootstrap_secret_name
expires_at
created_at
used_at
revoked_at
revoked_by_user_id

设计约束

token 明文不会在数据库中持久化
调用方需要自行保存创建响应中的 value / join_command

2.4 Node

节点列表接口返回当前节点快照，典型字段：

id
cluster_id
name
status
internal_ip
os_image
kubelet_version
container_runtime_version
cpu_allocatable_milli_cores
memory_allocatable_bytes
ephemeral_storage_allocatable_bytes
source
last_seen_at
ready_at
offline_at
created_at
updated_at

节点状态：

pending
ready
not_ready
unknown

2.5 Node Event / Health History

GET /api/console/node-events 返回节点事件与健康状态变化历史。该接口需要 console 认证。

查询参数：

cluster_id：可选，只返回指定 cluster 的节点事件
node_id：可选，只返回指定节点事件
type：可选，只返回指定事件类型
limit：可选，默认 100，最大 500；超过上限时按 500 返回

响应按 observed_at DESC, id DESC 排序。

响应示例：

{
  "events": [
    {
      "id": "nevt_001",
      "cluster_id": "cl_demo_001",
      "node_id": "node_demo_001",
      "node_name": "worker-1",
      "type": "not_ready",
      "old_status": "ready",
      "new_status": "not_ready",
      "message": "Node condition Ready changed to False",
      "observed_at": "2026-04-23T07:50:00.000Z"
    }
  ]
}

常见 type：

joined
ready
not_ready
pending
offline
deleted

说明：

nodes 表仍表示当前节点快照；node_events 表示历史事件和健康状态变化时间线
old_status / new_status 记录状态变化前后值；非状态变化事件可以为空
observed_at 是平台观测到事件或状态变化的时间

2.6 Console Activity

/api/console/overview 与 /api/console/activities 中的 activities 现已直接来源于审计事件。

典型字段：

id
type
message
cluster_id
cluster_name
node_name
occurred_at
relative_time

示例 type：

cluster_create_requested
cluster_create_succeeded
token_create
token_revoke
node_joined
session_login
api_key_create

2.6 Console Cluster Operations

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

用于查看单个集群最近的生命周期操作记录，以及对应的异步 worker job 历史。

返回结构：

operations: 集群业务操作记录列表
jobs: 异步执行 job 列表

operations 典型字段：

id
cluster_id
type
status
stage
requested_by_user_id
error_message
started_at
finished_at
created_at
updated_at

jobs 典型字段：

id
cluster_id
operation_id
type
status
attempt_count
published_at
leased_until
worker_id
last_error
started_at
finished_at
created_at
updated_at

说明：

主要用于 cluster detail 页面排查“创建/更新/删除集群为什么失败或卡住”
返回按 created_at desc 排序
当前是只读历史接口，不包含重试/取消等写操作

2.7 Admin Cluster Jobs

GET /api/console/admin/cluster-jobs?status=&cluster_id=&limit=

用于管理员查看全局 cluster job 队列与 worker 执行状态，辅助观测多机模式下 RabbitMQ + kubebyon-worker 的投递、领取、执行与失败情况。

查询参数：

status：可选，按 job 状态过滤，例如 pending / running / succeeded / failed
cluster_id：可选，按集群过滤
limit：可选，限制返回条数；未提供或非法时默认 100，最大值封顶为 500

返回结构：

jobs: 异步执行 cluster job 列表

jobs 典型字段：

id
cluster_id
operation_id
type
status
attempt_count
published_at
leased_until
worker_id
last_error
started_at
finished_at
created_at
updated_at

说明：

主要用于管理员侧 worker / job 队列可观测，定位队列积压、worker 租约、重试次数与最近失败原因
返回按 created_at DESC, id DESC 排序，优先展示最新 job
当前接口只读，不包含重试、取消或强制重新投递等写操作

3. 关键接口说明

3.1 创建集群

POST /api/console/clusters

请求示例：

curl -X POST http://localhost: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":"203.0.113.10",
    "kubernetes_version":"v1.31.2",
    "workload_cpu_limit_milli_cores":2000,
    "workload_memory_limit_mib":4096,
    "control_plane_cpu_request_milli_cores":100,
    "control_plane_memory_request_mib":512
  }'

语义：

每个 vCluster 独占一个同名宿主 namespace；namespace 省略时等于最终 vcluster_name，显式传入时也必须与 vcluster_name 完全一致。
先写入 status=provisioning
如果配置了真实 provisioner，则异步创建 vCluster
创建成功后 cluster 会进入 ready
kubeconfig 可能晚于集群创建完成，因此 connection_status 可能先是 kubeconfig_pending

3.2 更新集群资源 / 公网访问 / 托管业务流量入口

PUT /api/console/clusters/{clusterID}

请求支持的典型字段：

workload_cpu_limit_milli_cores
workload_memory_limit_mib
control_plane_cpu_request_milli_cores
control_plane_memory_request_mib
public_access_enabled
public_access_mode
control_plane_host
managed_workload_ingress_enabled

请求示例：

curl -X PUT http://localhost:8080/api/console/clusters/<clusterID> \
  -H 'Content-Type: application/json' \
  -H 'Cookie: kubebyon_session=<SESSION>' \
  -d '{
    "public_access_enabled": true,
    "public_access_mode": "loadbalancer",
    "control_plane_host": "api.demo.example.com",
    "managed_workload_ingress_enabled": true
  }'

语义：

这些变更会先立即写入 cluster 当前快照
公网访问与托管业务流量入口的底层收敛通常走异步更新链路
因此前端可能先看到：
- managed_workload_ingress_status=provisioning
- 或新的 public_access_mode 已保存，但底层入口尚在收敛

当前限制：

托管业务流量入口当前会：
- 在目标 vCluster 内准备内置 ingress controller
- 根据 managed_workload_ingress_base_domain 生成 cluster 级 managed_workload_ingress_cname_target
- 提供 hostname binding 的 API / 控制台产品面
当前仍不包含外部用户 DNS Zone 托管、域名归属校验或完整平台边缘网关；若部署侧启用 Gateway API workload edge TLS / cert-manager，则已有最小版 TLS / Certificate 自动化接线

3.3 管理工作负载入口域名绑定

GET    /api/console/clusters/{clusterID}/workload-ingress-hostnames
POST   /api/console/clusters/{clusterID}/workload-ingress-hostnames
DELETE /api/console/clusters/{clusterID}/workload-ingress-hostnames/{bindingID}

创建请求示例：

curl -X POST http://localhost:8080/api/console/clusters/<clusterID>/workload-ingress-hostnames \
  -H 'Content-Type: application/json' \
  -H 'Cookie: kubebyon_session=<SESSION>' \
  -d '{
    "hostname": "app.demo.example.com"
  }'

说明：

当前仅支持在 已开启 managed_workload_ingress_enabled=true 的集群上创建
hostname 会统一做小写化与尾随 . 归一化
当前按全局唯一约束处理，避免不同 cluster 争抢同一域名
hostname binding 创建表单当前会做一个 console / UI 层 的“DNS 托管范围实时预览”：前端基于 cluster managed_workload_ingress_cname_target 反推 base domain，并据此提示创建后预计会是 platform_managed 还是 self_managed
这个实时预览只是前端的预期提示，不是新增 API 字段，也不是新增请求参数
list/create 响应中的每个 hostname binding 都会返回只读 dns_management_scope
- platform_managed：当前 hostname 落在 managed_workload_ingress_base_domain 下，且 managed_workload_ingress_dns 已启用，因此平台会 best-effort 自动维护其 CNAME
- self_managed：其他情况；binding 仍然合法，但 DNS 记录需要用户自行维护
因此，外部 hostname 一直都是合法输入；在创建表单实时预览中看到 self_managed，只表示预计由用户自行维护 DNS，不表示该 hostname 非法，也不表示公网 DNS 最终解析失败
若管理员已配置 managed_workload_ingress_base_domain，则 GET /api/console/clusters / GET /api/console/clusters/{clusterID} 会返回 managed_workload_ingress_cname_target
用户可将自己的域名 CNAME 到该 target，再在控制台维护 hostname binding 记录
若管理员已启用 managed_workload_ingress_dns，平台会自动维护 cluster 级 CNAME target 在平台自有 Zone 下的 DNS 记录
若某个 hostname binding 本身也落在 managed_workload_ingress_base_domain 下，平台还会 best-effort 自动维护该 binding 的 CNAME，使其指向该 cluster 的 CNAME target
不在 managed_workload_ingress_base_domain 下的 hostname binding 仍需用户自行完成 DNS Zone 侧变更
若部署侧启用了 Gateway API workload edge TLS / cert-manager，runtime syncer 可为 platform-managed hostname 维护共享 Certificate，并可选为 self-managed 外部 hostname 维护独立 Certificate；证书可视化与更细粒度策略仍未产品化

3.4 删除集群

DELETE /api/console/clusters/{clusterID}

语义：

当前实现为软删除
删除成功后会把 cluster 标记为：
- status = deleted
- deleted_at = 删除时间
常规集群查询与列表接口默认不会再返回该集群
这样可以保留历史上下文（如 audit / operation / metrics），同时不再把它当作活跃集群展示

3.5 获取 kubeconfig

POST /api/console/clusters/{clusterID}/kubeconfig

安全要求：

该接口需要已认证用户；旧路径 /api/clusters/{clusterID}/kubeconfig 已移除，console 路径 /api/console/clusters/{clusterID}/kubeconfig 不支持直接 GET。
请求体必须提交当前登录账号的密码，用于二次校验：

{
  "password": "<CURRENT_PASSWORD>"
}

支持的响应形式：

普通 JSON 返回
?download=1：若后端支持，会返回 kubeconfig YAML attachment；否则仍按实现返回 JSON / 错误响应

请求示例：

read -rsp 'Current password: ' KUBEBYON_CURRENT_PASSWORD
printf '\n'
tmp_payload="$(mktemp)"
trap 'rm -f "$tmp_payload"' EXIT
export KUBEBYON_CURRENT_PASSWORD
python3 - <<'PY' > "$tmp_payload"
import json
import os

print(json.dumps({"password": os.environ["KUBEBYON_CURRENT_PASSWORD"]}))
PY
unset KUBEBYON_CURRENT_PASSWORD

curl -X POST http://localhost:8080/api/console/clusters/<clusterID>/kubeconfig \
  -H 'Content-Type: application/json' \
  -H 'Cookie: kubebyon_session=<SESSION>' \
  -d @"$tmp_payload"

不要把当前密码直接写进命令行参数或 shell history；download=1 也必须使用带密码 JSON 请求体的 POST，不能作为无密码浏览器直链下载。

JSON 返回示例：

{
  "api_endpoint": "https://203.0.113.10:30443",
  "kubeconfig": "kind: Config\n...",
  "version": "v1.31.2"
}

常见错误：

400 Bad Request：请求体缺失、JSON 非法或未提供 password
401 Unauthorized：未认证、session 无效或当前密码校验失败
404 Not Found：继续使用已移除的 legacy /api/clusters/... 路径
405 Method Not Allowed：对现有 console 路径使用了错误方法，例如直接 GET

3.6 创建 Join Token

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

请求示例：

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

说明：

返回真实 token 与 join command
数据库存储的是 hash 与生命周期信息
前端/调用方如需二次展示，必须自行保存创建响应中的明文

3.7 Console kubectl 代理

POST /api/console/clusters/{clusterID}/kubectl

说明：

该接口是后端代执行 kubectl 的受控入口，默认仅允许只读查询。
会拒绝写操作、交互、隧道、文件输入、原始 API 代理、身份冒充和连接覆盖参数。
典型拒绝项包括：apply、delete、patch、exec、port-forward、cp、drain、cordon、wait、--raw、--as、--as-group、--server、--token、--kubeconfig、-f/-k，以及 watch / follow 类持续输出。
这是安全收紧：旧自动化脚本或习惯通过控制台 kubectl 做变更、进入容器、端口转发、读取本地文件清单的流程可能需要改为使用专用 API 或线下 kubeconfig。

3.8 撤销 Token

DELETE /api/console/tokens/{tokenID}

返回示例：

{
  "token": {
    "id": "tok_xxx",
    "cluster_id": "cl_xxx",
    "display_prefix": "kbt_xxxxxx",
    "status": "revoked",
    "revoked_at": "2026-03-26T15:00:00Z",
    "revoked_by_user_id": "usr_xxx"
  }
}

说明：

重复撤销幂等返回当前 token 状态
撤销动作会写入审计事件

3.9 节点列表

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

说明：

返回真实同步后的节点快照
当使用 vcluster 后端时，节点数据会同步写入数据库快照，并生成 node event / audit event

3.10 Console Activities / Audit Stream

GET /api/console/activities?limit=20&category=security&resource_type=session&action=login
GET /api/console/admin/activities?limit=100&category=security&resource_type=token
GET /api/console/overview

说明：

当前不再通过 cluster/node/token 临时拼装活动流，而是统一读取 audit_events。
/api/console/activities 只返回当前登录用户本人触发的事件；响应字段包括 id、聚合后的 type、message、集群/节点展示字段、occurred_at 与 relative_time，适合用户侧时间线。
/api/console/admin/activities 要求管理员权限，返回跨用户事件，并额外包含 actor_user_id、actor_type、actor_method、resource_type、resource_id、action、result，足以表达安全审计事件。
两个列表接口兼容原有 limit，并支持轻量过滤：category=security、resource_type=<type>、action=<action>；过滤在限量前生效，便于只查看安全相关活动。

本轮纳入 activity/audit stream 的敏感/安全事件类型包括：

认证与账号：session/login、session/logout、user/register、user/update_profile、user/update_avatar、user/reset_password、user/delete_current_user、user/ban、user/activate。
凭据与访问入口：token/create、token/revoke、token/used、api_key/create、api_key/delete。
集群/节点运维：cluster/create_requested、cluster/create_failed、cluster/create_succeeded、cluster/delete_requested、cluster/delete_failed、cluster/delete_succeeded、cluster/kubeconfig_read、cluster/kubectl_exec、cluster/settings_update_requested、cluster/settings_update_failed、cluster/settings_updated、node/cordoned、node/uncordoned、node/drained、node/deleted、node/joined、node/offline。
管理配置：system_settings/update、notification_settings/update。

敏感信息脱敏原则：

token、API Key、session token、kubeconfig、密码/密码哈希、验证码、OAuth subject、邮箱验证码等秘密值不得写入 message、resource_id 或扩展字段；创建类接口只在业务响应中按既有规则返回一次明文。
审计消息保留可定位对象的低敏标识（如资源 ID、名称、actor user ID、cluster/node 展示名），但不记录命令输出、kubeconfig 内容、环境变量或请求中的原始密钥。
category=security 是后端维护的安全相关事件集合；未知 category 返回空列表，不影响旧客户端不带过滤参数的行为。

4. 认证说明

GET /api/auth/providers 会返回：
- 当前可用的 OAuth 提供方列表
- 当前前台可见的 hCaptcha 配置（仅返回 enabled 与 site_key）
OAuth 登录流程为：
1. 前端读取 /api/auth/providers
2. 跳转 GET /api/auth/sso/{provider}/login
3. 第三方回调 GET /api/auth/sso/{provider}/callback
密码注册流程分为两步：
1. POST /api/auth/register/send-code
2. POST /api/auth/register 并提交 email_verification_code
当管理员在系统设置里启用 hCaptcha 后：
- POST /api/auth/login
- POST /api/auth/register/send-code
- POST /api/auth/register 都需要额外提交 captcha_token
/api/auth/login 成功后通过 cookie 建立 session
/api/console/* 主要接口要求认证
认证成功后，后端会把当前 actor 注入上下文，用于写入审计事件

5. 与数据库语义相关的变更

本轮 API 语义变化重点如下：

Token 明文只在创建时返回一次
Token 查询接口返回生命周期元数据，不再是历史明文列表
Cluster 响应新增 connection_status、kubeconfig_available 等字段
Console Activities 改为真实审计流
新增 token revoke 接口

数据库设计详见：

docs/architecture/database-design.md

KubeBYON HTTP API（当前实现）

启动

连接宿主 Kubernetes / vCluster 所需配置

浏览器安全、CORS 与限流

1. 接口总览

Health

Join / Script

Auth / Identity

Billing / Plans

Stripe Webhook

Admin Activities

Admin Cluster Jobs

Admin Plans

Admin Users

Console Notification Settings

Admin Orders

Admin System Settings / Notifications

Clusters

Tokens

Nodes

Console Overview

Admission / Internal

2. 核心资源说明

2.1 Cluster

status 与 connection_status

managed_workload_ingress_status

managed_workload_ingress_dns_status

2.2 Token

2.3 Workload Ingress Hostname Binding

status

dns_management_status

创建响应中的 token

查询响应中的 token

设计约束

2.4 Node

2.5 Node Event / Health History

2.6 Console Activity

2.6 Console Cluster Operations

2.7 Admin Cluster Jobs

3. 关键接口说明

3.1 创建集群

3.2 更新集群资源 / 公网访问 / 托管业务流量入口

3.3 管理工作负载入口域名绑定

3.4 删除集群

3.5 获取 kubeconfig

3.6 创建 Join Token

3.7 Console kubectl 代理

3.8 撤销 Token

3.9 节点列表

3.10 Console Activities / Audit Stream

4. 认证说明

5. 与数据库语义相关的变更

`status` 与 `connection_status`

`managed_workload_ingress_status`

`managed_workload_ingress_dns_status`

`status`

`dns_management_status`