OpenEverest 架构深度解析：everest server 与 everest-controller 双组件如何协同工作-平芜编程栈

【免费下载链接】openeverest

OpenEverest is an open-source platform for automated database, storage and LLMs provisioning and management. It supports multiple technologies and can be hosted on any Kubernetes infrastructure, in the cloud or on-premises.

项目地址：https://gitcode.com/gh_mirrors/op/openeverest

点击查看免费下载

OpenEverest 是一个开源的 Kubernetes 云原生数据库平台，用于自动化数据库、存储与 LLM 的供给和管理。它的后端由两个独立组件构成：everest server（API 服务，负责用户交互）和everest-controller（控制器，负责与 Kubernetes 集群持续调谐）。两者不直接通信，而是通过 Kubernetes CRD 资源"隔空握手"。本文将带你快速看懂这套双组件架构的分工、数据流与协同机制。

一、全局视角：前台与后台的分工 💡

OpenEverest 的部署形态遵循 Kubernetes 生态的经典"API Server + Operator"模式：

维度	everest server（`everest`）	everest-controller（`manager`）
入口	cmd/main.go	cmd/controller/main.go
角色	HTTP API 网关 + Web UI	Controller Manager（控制器管理器）
核心职责	认证、鉴权、参数校验、CR 写入	Watch CRD、执行调谐（Reconcile）
技术栈	Go + Echo 路由框架 + Casbin RBAC	Go + controller-runtime
高可用	无状态 HTTP 服务	`--leader-elect`领导者选举
对外暴露	`svc/everest:8080`（UI + REST API）	仅`/healthz`、`/readyz`探针端口

两个二进制的构建目标分别定义在 Makefile 中：build生成 server 二进制everest，build-controller生成 controller 二进制manager。

二、组件一：everest server —— 面向用户的"前台" 🚪

一个内嵌 Web UI 的 HTTP API 服务

everest server 的实现在 internal/server/everest.go。它做了三件关键的事：

内嵌 UI：构建时会把 Web 前端（ui/目录的产物，位于public/dist）直接嵌入二进制，单容器即可同时提供 REST API 与界面访问。
认证与会话：支持 JWT Session 与 OIDC 登录，配合内存级登录限流器（登录爆破防护）与全局 API 速率限制。
实时事件中心：内置事件 Hub（pkg/events/hub.go），持续 Watch Kubernetes 中的 K8s Event，通过订阅-广播机制把实例创建、备份进度等变化实时推送到前端，UI 无需轮询。

它的 REST 路由由 OpenAPI 规范生成，完整定义在 api/openapi/http-api.yaml，例如：

POST /clusters/{cluster}/namespaces/{namespace}/instances—— 创建数据库实例
GET /clusters/{cluster}/namespaces/{namespace}/backup-storages—— 列出备份存储

三层 Handler 责任链：RBAC → 校验 → 写 Kubernetes

server 的业务逻辑采用责任链模式组织，定义见 internal/server/handlers/handler.go：

用户请求 ──▶ rbacHandler ──▶ validateHandler ──▶ k8sHandler ──▶ 写入 CR （权限拦截） （参数合法性） （真正操作集群）

RBAC 层（internal/server/handlers/rbac/handler.go）：基于 Casbin 引擎按"用户 + 组 + 资源 + 动作"做细粒度鉴权，不通过则直接返回insufficient permissions；
校验层（internal/server/handlers/validation/）：校验请求体结构、引用对象是否存在；
K8s 层（internal/server/handlers/k8s/）：链路的终点，把请求转化为 Kubernetes API 调用，真正创建/更新 CR。

链路组装代码在 internal/server/everest.go 的setupHandlers中，注释特别说明：RBAC 必须最先执行，因为校验层会携带用户凭据去访问用户指定的端点。

备份存储等配置同样走 API

在设置页管理备份存储位置时，前端调用的同样是这条 handler 链，最终落盘为BackupStorageCR：

三、组件二：everest-controller —— 幕后"管家" 🏗️

一个 Manager，七组 Reconciler

everest-controller 基于 controller-runtime 构建，入口在 cmd/controller/main.go。启动时它向 Manager 注册了7 个 Reconciler，每个对应一类 CRD 的调谐逻辑：

Reconciler	调谐的资源	源码位置
BackupReconciler	`Backup`（备份任务）	internal/controller/backup/backup_controller.go
RestoreReconciler	`Restore`（恢复任务）	internal/controller/backup/restore_controller.go
BackupStorageReconciler	`BackupStorage`（备份存储）	internal/controller/backup/backupstorage_controller.go
BackupImportReconciler	`BackupImport`（备份导入）	internal/controller/backup/backupimport_controller.go
MonitoringConfigReconciler	`MonitoringConfig`（监控配置）	internal/controller/monitoring/monitoringconfig_controller.go
PluginReconciler / InstalledExtensionReconciler	`Plugin`/`InstalledExtension`（插件扩展）	internal/controller/extension/

以 Backup 为例，其 Reconciler 会Owns一批下游对象（Job、Secret、ServiceAccount、Role、RoleBinding），并Watches集群级资源的变化（backup_controller.go）——也就是说，备份执行的全过程都由它驱动：创建 Job → 跟踪 Pod 状态 → 回写status条件。

领导者选举与准入 Webhook

领导者选举：部署清单 config/manager/manager.yaml 中显式传入--leader-elect，保证多副本时只有一个活跃实例执行调谐；
健康探针：/healthz与/readyz挂在 8081 端口，供 Deployment 探活；
准入 Webhook：对MonitoringConfig注册了变更校验 Webhook（internal/webhook/monitoring/v1alpha1/），在非法配置写入之前就拦截下来。

四、协同机制：CRD 就是两者的"合同" 🤝

写路径：UI/CLI/API → server → CR

无论是 Web 向导、everestctlCLI，还是裸 REST 调用，最终都汇聚到同一条路径：

用户操作 ──▶ everest server（认证 + RBAC + 校验）──▶ 写入 Kubernetes CR │ everest-controller（Watch 到新 CR）◀───┘ │ 创建/更新 Deployment、Job 等实际工作负载 │ 回写 CR 的 status（条件、阶段） │ server 的事件 Hub（Watch K8s Events）◀─┘ │ UI 实时刷新 / CLI --wait 轮询

以"创建一个 MongoDB 实例"为例：

用户在向导中填写参数并提交（见下方截图），server 将其翻译为 Instance CR——其中providerRef指定由哪个 Provider 管理，version、topology、components、backup等字段描述期望状态；
server 侧只负责把 CR 写进 etcd 即返回，不做任何调谐；
真正拉起数据库 Pod、Proxy、Secret 等的是数据库 Provider Operator（其开发契约定义在 provider-runtime/controller/interface.go 的ProviderInterface：Validate / Sync / Status / Cleanup四步）；
状态回写后，server 的事件 Hub 捕获 K8s Event 推送给 UI，列表页与详情页随之刷新。

读路径：状态如何回到用户眼前

REST 查询：UI 打开详情页时，server 通过 k8sHandler 直接读取 CR 的status字段并转换为 API 模型；
SSE 式事件流：事件 Hub（pkg/events/）采用带序号（Seq）的订阅模型，慢消费者会被主动丢弃保护广播链路，断线后可凭 Seq 游标重放缓冲事件。

备份执行过程中，UI 详情页的备份状态更新正是这条链路的体现：

为什么拆成两个组件？✅

安全边界：server 处理不可信的用户输入（认证、限流、校验都发生在写 CR 之前），controller 只信任集群内的 CR，职责清晰；
独立扩缩容：API 流量高峰时只需扩 server，controller 保持稳定单活；
故障隔离：controller 调谐卡顿不会拖垮 API 响应；server 重启也不会中断进行中的备份 Job；
标准 Operator 生态：CRD + Reconciler 是 Kubernetes 社区的通用范式，其他工具（kubectl、Argo CD 等）也能直接操作这些资源。

五、源码地图：从哪里开始读？🗺️

想了解	建议入口
server 启动与中间件	cmd/main.go → internal/server/everest.go
API 路由全貌	api/openapi/http-api.yaml
Handler 责任链	internal/server/handlers/
权限模型	pkg/rbac/（Casbin 策略模型见 data/rbac/model.conf）
备份调谐全流程	internal/controller/backup/
Provider 接入契约	provider-runtime/
四类 CRD 类型定义	api/（core / backup / monitoring / extensions 四个组）
部署清单	config/（CRD、RBAC、Manager、Webhook）

六、小结

OpenEverest 的双组件架构一句话概括：everest server 负责"收单"——认证用户、校验请求、把意图写成 CR；everest-controller 负责"履约"——监听 CR 并持续调谐集群使其收敛到期望状态。Kubernetes 对象存储充当两者之间唯一的通信总线，这种"声明式 + 调谐循环"的设计让系统天然可观测、可恢复，也让你既能通过 UI 点点鼠标，也能用 kubectl 对同一套资源进行手术级干预。

想要动手验证？克隆仓库后从 docs/process/tech_stack.md 了解技术栈全貌，再用make build与make build-controller分别编译两个组件即可。