KubeBYON 数据库设计（当前实现）

最后更新：2026-05-11

适用范围：当前主仓库 Go 后端 + PostgreSQL 实现。

本文档描述当前代码已经落地的数据库设计，而不是早期 MVP 草案。 当前 schema 由应用启动时自动迁移维护。

1. 设计原则

当前数据库设计遵循以下原则：

  1. 平台状态优先落库
    • 用户、订单、系统设置、活动流、集群操作和 cluster job 都以 PostgreSQL 为主状态源。
  2. 快照表与过程表分离
    • 快照表保存“当前状态”，过程表保存“发生过什么”。
  3. 敏感凭据只存 hash，不存明文
    • Session Token、API Key、Join Token、邮箱验证码都不以明文持久化。
  4. 集群生命周期支持同步与异步两种执行拓扑
    • 单机模式可以由 API 直接执行。
    • 多机模式通过 cluster_jobs + RabbitMQ + worker 执行。

2. 表结构总览

当前 PostgreSQL 库共有 19 张业务表。

2.1 身份认证与用户侧

表名作用
users本地用户账号
external_identitiesOAuth 外部身份绑定
sessions登录会话
login_events登录历史
email_verification_codes注册 / 重置密码验证码（hash）
notification_settings用户级通知偏好
api_keysAPI Key

2.2 集群与基础设施侧

表名作用
clusters集群当前快照
cluster_operations集群操作记录
cluster_jobs集群异步 job 记录
tokensJoin Token 生命周期快照
nodes节点当前快照
node_events节点历史事件
control_plane_metrics_snapshots控制面指标历史快照
workload_ingress_hostname_bindings托管业务流量入口 hostname binding
audit_events平台活动流 / 审计事件

2.3 套餐、订单与全局配置

表名作用
plans套餐定义
orders订单记录
system_settings全局系统设置

3. 核心表说明

3.1 users

用户主表，保存平台账号基础信息。

关键字段：

  • id
  • email
  • display_name
  • password_hash
  • role
  • status
  • created_at / updated_at

说明：

  • 本地密码登录依赖 password_hash
  • OAuth 登录额外依赖 external_identities
  • 管理后台的用户禁用 / 解封基于 status

3.2 sessions

保存登录会话。

关键字段：

  • id
  • user_id
  • token_hash
  • expires_at
  • created_at
  • last_used_at

说明：

  • Cookie / Session 认证基于本表
  • 删除用户、重置密码、封禁用户时会联动清理会话

3.3 api_keys

保存 API Key 元数据。

关键字段：

  • id
  • user_id
  • name
  • prefix
  • token_hash
  • created_at
  • last_used_at

说明：

  • 明文 Token 只在创建时返回一次
  • 后续认证走 token_hash

3.4 clusters

集群当前快照表，一行表示一个集群的当前状态。

关键字段：

  • id
  • owner_user_id
  • name
  • vcluster_name
  • namespace
  • 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_dns_record_name
  • managed_workload_ingress_dns_record_target
  • managed_workload_ingress_dns_record_zone_id
  • managed_workload_ingress_dns_record_provider
  • managed_workload_ingress_dns_last_synced_at
  • managed_workload_ingress_dns_last_error
  • managed_workload_ingress_dns_last_error_at
  • tailscale_enabled
  • api_endpoint
  • status
  • connection_status
  • kubeconfig_available
  • kubeconfig_available_at
  • last_observed_at
  • last_error_message
  • deleted_at
  • created_at / updated_at

说明：

  • public_access_mode 当前支持 nodeport | loadbalancer
  • managed_workload_ingress_status 当前支持 disabled | provisioning | ready | error
  • managed_workload_ingress_class 当前默认值为 kubebyon
  • managed_workload_ingress_last_error 用于保存最近一次托管入口收敛失败原因
  • deleted_at 用于软删除
  • api_endpoint 与 kubeconfig_available 由观测与回写流程维护
  • 活跃集群通过部分唯一索引约束 (namespace, vcluster_name)

3.5 cluster_operations

记录一次集群生命周期操作的业务视角结果。

关键字段：

  • id
  • cluster_id
  • type
  • status
  • stage
  • requested_by_user_id
  • error_message
  • started_at
  • finished_at
  • created_at / updated_at

说明：

  • 适合表达“创建中 / 成功 / 失败”这类面向控制台的状态
  • 与 cluster_jobs 配合使用时，可分别表达“业务操作记录”与“执行 job 记录”
  • 控制台 cluster detail 现在可以基于 cluster_operations 与 cluster_jobs 查看 operation / job 历史

3.6 cluster_jobs

记录异步 worker 执行的集群任务。

关键字段：

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

状态语义：

  • pending
  • running
  • succeeded
  • failed

说明：

  • payload 保存 worker 执行所需的集群目标快照
  • API 负责创建 job；RabbitMQ 负责投递 job ID；worker 负责真正执行
  • 单个集群同一时间只允许一个活跃 job（通过唯一索引保证）

3.7 tokens

Join Token 生命周期快照表。

关键字段：

  • id
  • cluster_id
  • token_hash
  • display_prefix
  • status
  • created_by_user_id
  • used_by_node_id
  • bootstrap_secret_name
  • expires_at
  • created_at
  • used_at
  • revoked_at
  • revoked_by_user_id

说明：

  • 数据库只保存 hash
  • 明文 token / join command 只在创建响应中返回一次
  • 当前状态主要有 active / used / expired / revoked

3.8 nodes

节点当前快照表。

关键字段：

  • 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
  • deleted_at
  • created_at / updated_at

说明：

  • 节点删除使用软删除
  • 节点离线不是删除，而是 offline_at / 状态变化
  • (cluster_id, name) 保持唯一，便于幂等 upsert

3.9 node_events

节点历史事件表，保存节点接入、离线、删除以及健康状态变化的时间线。

关键字段：

  • id
  • cluster_id
  • node_id
  • node_name
  • type
  • old_status
  • new_status
  • message
  • observed_at

常见事件：

  • joined
  • ready
  • not_ready
  • pending
  • offline
  • deleted

说明：

  • nodes 是当前节点快照；node_events 是历史事件流
  • 健康状态变化事件使用 old_status / new_status 保留变化前后的状态
  • 控制台通过 GET /api/console/node-events 按 cluster_id、node_id、type 过滤，并按 observed_at DESC, id DESC 展示最近历史
  • 查询默认返回最近 100 条，最大 500 条

适合支撑节点时间线、健康历史观测与审计辅助信息。

3.10 control_plane_metrics_snapshots

保存控制面指标历史快照，用于控制台折线图与历史查询。

关键字段：

  • id
  • cluster_id
  • available
  • namespace
  • pod_name
  • collected_at
  • load_average_1
  • load_average_5
  • load_average_15
  • total_cpu_percent
  • total_memory_rss_bytes
  • total_memory_virtual_bytes
  • components
  • error_message

3.11 workload_ingress_hostname_bindings

保存 cluster 级托管业务流量入口 hostname binding 当前状态。

关键字段：

  • id
  • cluster_id
  • hostname
  • status
  • last_error
  • managed_dns_record_name
  • managed_dns_record_target
  • managed_dns_record_zone_id
  • managed_dns_record_provider
  • 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
  • created_at / updated_at

说明：

  • hostname 当前全局唯一，避免不同 cluster 争抢同一域名
  • status / last_error 表示公网 DNS 最终解析结果
  • managed_dns_* 与 dns_management_* 字段表示平台托管 DNS 自动化自身的记录和最近同步状态
  • tls_* 字段记录 Gateway API workload edge TLS / cert-manager 最小版的观测状态

3.12 audit_events

统一活动流 / 审计事件表。

覆盖范围包括：

  • 登录与账号动作
  • 集群创建 / 更新 / 删除
  • 节点事件
  • 套餐与订单操作
  • 管理员操作

3.13 plans 与 orders

计费基础能力当前采用轻量模型：

  • plans：定义套餐配额和价格
  • orders：记录用户选择套餐后的订单状态，并保存 Stripe Checkout Session / PaymentIntent 标识用于 webhook 幂等回填

当前语义：

  • 更偏“平台套餐 + 订单”模型
  • 尚未拆出完整 subscriptions / payment_transactions 域；Stripe 当前作为订单支付入口接入
  • 权益判断主要依据用户当前有效订单

3.14 system_settings

全局系统设置表，当前使用单行配置。

当前承载内容包括：

  • public_base_url
  • join_base_url
  • managed_workload_ingress_base_domain
  • managed_workload_ingress_dns_*
  • default_cluster_public_access_mode
  • GitHub / Google OAuth 凭据
  • Captcha 配置
  • 通知投递配置（SMTP、通用出站 Webhook 等）
  • updated_at

说明：

  • 这是管理员后台“系统设置”页面的持久化来源
  • 目前密钥（SMTP password、Webhook secret 等）仍存放在数据库字段中；生产环境建议后续增加加密或外部 Secret 管理

4. 生命周期与删除策略

4.1 软删除

当前采用软删除的资源：

  • clusters
  • nodes

实现方式：

  • 写入 deleted_at
  • 主读路径默认过滤已删除资源

4.2 状态流转优先

以下对象主要依赖状态流转，而不是删除：

  • tokens
    • active -> used / expired / revoked
  • orders
    • pending -> paid / cancelled
  • cluster_operations
    • pending / running / succeeded / failed
  • cluster_jobs
    • pending / running / succeeded / failed

4.3 物理删除

当前更偏物理删除的对象：

  • sessions
  • api_keys
  • external_identities
  • email_verification_codes
  • workload_ingress_hostname_bindings

5. 主要关系与索引

5.1 主要关系

  • external_identities.user_id -> users.id
  • sessions.user_id -> users.id
  • notification_settings.user_id -> users.id
  • api_keys.user_id -> users.id
  • orders.user_id -> users.id
  • orders.plan_id -> plans.id
  • tokens.cluster_id -> clusters.id
  • nodes.cluster_id -> clusters.id
  • cluster_operations.cluster_id -> clusters.id
  • cluster_jobs.cluster_id -> clusters.id
  • cluster_jobs.operation_id -> cluster_operations.id
  • control_plane_metrics_snapshots.cluster_id -> clusters.id
  • workload_ingress_hostname_bindings.cluster_id -> clusters.id

5.2 当前重点索引

  • idx_clusters_owner_user_id_created_at
  • idx_clusters_status
  • idx_clusters_namespace_vcluster_name_active
  • idx_cluster_operations_cluster_created_at
  • idx_cluster_jobs_status_created_at
  • idx_cluster_jobs_cluster_created_at
  • idx_cluster_jobs_pending_publish
  • idx_cluster_jobs_active_cluster
  • idx_tokens_cluster_created_at
  • idx_tokens_cluster_status
  • idx_nodes_cluster_created_at
  • idx_nodes_cluster_deleted_at
  • idx_node_events_cluster_observed_at
  • idx_control_plane_metrics_cluster_collected_at
  • idx_workload_ingress_hostname_bindings_hostname
  • idx_workload_ingress_hostname_bindings_cluster_created_at
  • idx_api_keys_user_id_created_at
  • idx_orders_user_created_at
  • idx_orders_user_status_paid_at

6. 当前设计取舍

6.1 优点

  • 平台状态、集群状态与异步执行状态已经分层
  • 凭据类数据默认避免明文持久化
  • 单机与多机两种部署形态共享同一套数据库语义
  • 集群、节点和活动流都具备较清晰的历史保留能力

6.2 当前仍保留的 trade-off

  1. system_settings 仍是单表承载多类全局配置
  2. 订单模型仍是轻量版本，不是完整支付域模型
  3. 部分状态约束主要依赖应用层而非数据库 CHECK
  4. Schema migration 由应用内置完成，尚未引入独立迁移工具链

7. 总结

当前数据库设计已经能够稳定支撑：

  • 账号与 OAuth 登录
  • Session / API Key 认证
  • 系统设置与通知配置
  • 套餐与订单基础能力
  • 集群创建 / 更新 / 删除
  • 异步 cluster job 执行
  • Join Token 发放与撤销
  • 节点状态与节点事件
  • 托管业务流量入口 hostname binding、平台 DNS 自动化与 TLS 观测状态
  • 活动流与审计