Olares 中间件(Middleware)全面解析:从 Control Hub 数据管理到 OlaresManifest.yaml 声明式应用集成
Olares 中间件(Middleware)全面解析:从 Control Hub 数据管理到 OlaresManifest.yaml 声明式应用集成
Olares 以"中间件即服务"的思路,为运行在其上的应用提供数据存储、消息队列、对象存储与可观测性等基础设施能力。本文基于 Olares 中间件文档体系,梳理中间件的定位、两大类使用场景(访问管理与应用集成)、全部受支持服务的清单与对应文档入口,并结合仓库源码说明声明式集成从 OlaresManifest.yaml 到真实数据库资源的完整链路。读完本文,你将掌握在 Control Hub 中获取中间件连接信息、通过 CLI/Bytebase/Dashboard 管理数据,以及在应用清单中声明并消费中间件服务的完整实战方法。
什么是 Olares 中间件
中间件(Middleware)指位于你的应用与系统之间的基础设施服务,为应用提供数据存储、消息传递等通用能力。在 Olares 中,开发者无需自行搭建和维护这些服务:系统以集群化、高可用的方式内置了常见中间件,并通过声明式配置把连接信息注入到应用中。
Olares 的中间件文档被组织为两类指南:
- 访问和管理数据(Access and manage data):连接到一个正在运行的服务,检查数据并排查问题;
- 应用集成(App integrate):通过
OlaresManifest.yaml配置你的应用使用 Olares 中的某个中间件服务。
这两类指南分别对应中间件生命周期的两端:运维视角的"怎么连、怎么看",与开发视角的"怎么用、怎么接"。
访问和管理数据类指南
访问和管理数据类指南讲解如何连接运行中的中间件服务进行管理操作。当你需要以下场景时使用:
- 检查已存储的数据或索引;
- 运行查询或命令;
- 调试应用行为;
- 验证服务状态。
具体访问方式(CLI、Dashboard 或 Bytebase)取决于服务类型:数据库类服务通常支持命令行与 Bytebase 双通道,MinIO 与 RabbitMQ 则提供了各自的 Web Dashboard,Grafana 与 OpenTelemetry 则面向可观测性场景。
应用集成类指南
应用集成类指南讲解如何把你的应用连接到某个中间件服务。当你的应用需要以下能力时使用:
- 在
OlaresManifest.yaml中声明依赖; - 请求服务资源(数据库、用户、桶、vhost 等);
- 在应用中读取系统注入的连接值。
集成是声明式的:你只需在清单中描述"需要什么",由 Olares 在部署时完成资源的创建与连接信息的注入,应用本身无需关心底层集群拓扑。
支持的中间件服务全景
Olares 当前支持的中间件服务可分为三类:数据库与缓存、消息与流、存储与可观测性。下表(与官方文档一致)列出了每类服务对应的访问指南与应用集成指南入口,点击链接即可跳转到对应文档深入学习。
数据库与缓存
| 服务 | 访问和管理数据 | 应用集成 |
|---|---|---|
| Elasticsearch | Access | Integrate |
| MariaDB | Access | Integrate |
| MongoDB | Access | Integrate |
| MySQL | Access | Integrate |
| PostgreSQL | Access | Integrate |
| Redis | Access | Integrate |
消息与流
| 服务 | 访问和管理数据 | 应用集成 |
|---|---|---|
| RabbitMQ | Access | Integrate |
| NATS | Access | — |
存储与可观测性
| 服务 | 访问和管理数据 | 应用集成 |
|---|---|---|
| MinIO | Access | Integrate |
| Grafana | Access | — |
| OpenTelemetry | Access | — |
从上表可以看出:绝大多数服务同时具备"访问管理"与"应用集成"两类指南;而 NATS、Grafana、OpenTelemetry 目前仅提供访问管理类指南(其中 NATS 集成能力可参见环境变量与系统注入运行时值文档中的 deps/svcs 依赖注入机制,以及声明式环境变量文档中的系统变量引用)。
访问和管理数据:连接正在运行的中间件
访问类指南的核心工作流一致:先从 Control Hub 获取连接信息,再选择 CLI、Bytebase 或专用 Dashboard 进入。下面以 PostgreSQL 为例展示完整流程(Redis、MongoDB、MySQL 等数据库服务流程同构)。
第一步:从 Control Hub 获取连接信息
- 从 Launchpad 打开 Control Hub;
- 在左侧导航栏进入 Middleware,选择目标服务(如 Postgres);
- 在 Details 面板中记录以下信息:
- Host:用于 Bytebase 连接;
- User:用于 Bytebase 连接;
- Password:CLI 与 Bytebase 均会用到。
各服务的连接信息字段略有差异,例如 MongoDB 面板提供的是 Mongos(mongos 路由器地址),Redis 面板仅提供 Host 与 Password,NATS 面板则需要按 Subject 选择并记录对应的 User / Password。详细字段请参见各服务的 Access 指南。
第二步:通过 CLI 访问(Olares 终端 + kubectl)
数据库容器在集群中以固定名称部署,可直接从 Olares 终端进入。以几个典型服务为例:
PostgreSQL(默认已安装,容器名为 citus-0):
kubectl exec -it -n os-platform citus-0 -- sh
psql -h citus-0 -U olares
按提示输入从 Control Hub 获取的密码即可。
Redis(默认已安装,容器名为 kvrocks-0,注意 Olares 使用 Redis Cluster 版本):
kubectl exec -it -n os-platform kvrocks-0 -- sh
redis-cli -p 6666 -a <your password from control-hub>
MySQL(需先从 Market 安装):
kubectl exec -it -n mysql-middleware mysql-mysql-0 -- sh
mysql -u root -p
MongoDB(需先从 Market 安装,容器名不固定):
kubectl get pods -n os-platform | grep tapr-middleware
kubectl exec -it -n os-platform <tapr-middleware-pod> -- sh
mongosh "mongodb://root:<your password from controlhub>@mongodb-mongodb-headless.mongodb-middleware:27017"
NATS(使用 nats-box 工具测试消息订阅与发布):
kubectl apply -f nats-box.yaml
kubectl get pods -n os-platform | grep nats-box
kubectl exec -it -n os-platform <nats-box-pod> -- sh
# 订阅消息
nats sub <subject-from-controlhub> --user=<user-from-controlhub> --password=<password-from-controlhub> --all
# 发布消息
nats pub <subject-from-controlhub> '{"hello":"world"}' --user=<user-from-controlhub> --password=<password-from-controlhub>
NATS 的 Subject 采用三级结构 <prefix>.<event>.<olaresId>:第一级为来源标识(系统服务固定为 os,第三方应用使用对应 appId),第二级为事件类型或域(如 users、groups、files、notification),第三级为用户空间的 Olares ID。权限模型上,用户空间应用只能订阅包含自身 <olaresId> 的三级 Subject(只读);系统/集群应用可订阅系统级 Subject、写入自身空间内的二级 Subject,订阅全局二级 Subject 需单独审批。完整说明见 NATS 访问指南。
第三步:通过 Bytebase 图形化管理
Bytebase 为数据库管理、结构变更提供图形界面,支持 PostgreSQL、MySQL、MongoDB、Redis、Elasticsearch、MariaDB 等。安装与配置要点:
- 前置依赖:Bytebase 使用 MongoDB 存储元数据,必须先安装 MongoDB(Market 搜索 "MongoDB" → Get → Install);
- 安装 Bytebase 后,首次启动需配置管理员账号(只有管理员能创建新的数据库实例,请务必记住该凭证);
- 登录后在左侧导航选择 Instances → + Add Instance,选择对应数据库类型,用 Control Hub 的 Host / User / Password 填写连接字段(Host 不含端口;端口通常使用默认值,如 PostgreSQL
5432、MySQL3306、MongoDB27017、Redis6379); - 点击 Test Connection 验证连通性后 Create。
在 Bytebase 中创建实例并不会新建数据库;实例创建完成后,即可使用相应客户端工具检查与管理数据。
通过专用 Dashboard 管理
部分服务提供了专属 Web 管理界面,无需 Bytebase:
- MinIO:从 Market 安装 MinIO 服务与 MinIO Dashboard,用 Control Hub 中的凭据登录即可管理桶与对象,详见 MinIO 访问指南;
- RabbitMQ:先安装 RabbitMQ 服务,再安装 RabbitMQ Dashboard(依赖 RabbitMQ),登录后可查看和管理队列、交换机、vhost 等资源,详见 RabbitMQ 访问指南;
- Grafana:面向监控与可观测性,安装 Prometheus 后安装 Grafana,添加 Prometheus 数据源并创建/导入 Dashboard,详见 Grafana 访问指南;
- OpenTelemetry:通过 Jaeger 查看链路追踪数据,详见 OpenTelemetry 访问指南。
应用集成:在 OlaresManifest.yaml 中声明中间件
应用集成是声明式的:在应用 Chart 根目录的 OlaresManifest.yaml 的 middleware 字段中声明所需服务,Olares 在部署时完成资源创建(数据库、用户、桶、vhost 等)并把连接值注入应用的 values.yaml,应用再在 Helm 模板中将这些值映射为容器环境变量。OlaresManifest.yaml 的完整字段规范见 OlaresManifest Specification。
注入链路与前提条件
Olares 通过两条通道向应用的 values.yaml 注入变量(详见 Environment variables overview):
- 声明式环境变量:开发者在
envs字段中声明,部署时由 app-service 解析后注入.Values.olaresEnv; - 系统注入的运行时值:部署时由 Olares 自动注入,无需声明;其中中间件相关的
.Values.*值只有在你于middleware字段中声明对应依赖后才可用。
安装前提方面:
- PostgreSQL 与 Redis 默认已安装,可直接声明使用;
- MongoDB、MySQL、MariaDB、MinIO、RabbitMQ 必须先由管理员从 Market 安装,之后其他应用才能引用(见 manifest 规范 中的 middleware 章节与 系统注入运行时值 中的说明)。
此外,你还可以在 options.dependencies 中声明中间件依赖并设置 mandatory: true,使安装流程自动先安装所依赖的中间件:
options:
dependencies:
- name: olares
version: ">=1.0.0-0"
type: system
- name: mongodb
version: ">=6.0.0-0"
type: middleware
mandatory: true # 若依赖需先安装,设为 true
PostgreSQL 声明与注入示例
在 OlaresManifest.yaml 中添加:
middleware:
postgres:
username: immich
databases:
- name: immich
extensions:
- vectors
- earthdistance
scripts:
- BEGIN;
- ALTER DATABASE $databasename SET search_path TO "$user", public, vectors;
- ALTER SCHEMA vectors OWNER TO $dbusername;
- COMMIT;
要点:
scripts字段用于指定数据库创建后需要执行的脚本;extensions字段用于在数据库中创建对应的扩展;- 执行脚本时 Olares Application Runtime 会替换两个内置变量:
$databasename(数据库名)与$dbusername(数据库用户名)。
然后在部署模板(如 deployment.yaml)中把注入的 .Values.postgres.* 映射为容器环境变量:
containers:
- name: my-app
env:
# 数据库名:与 OlaresManifest 中 middleware.postgres.databases[i].name 对应
# NOTE: 将 <dbname> 替换为清单中定义的实际名称(如 immich)
- name: DB_POSTGRESDB_DATABASE
value: {{ .Values.postgres.databases.<dbname> }}
# 主机
- name: DB_POSTGRESDB_HOST
value: {{ .Values.postgres.host }}
# 端口
- name: DB_POSTGRESDB_PORT
value: "{{ .Values.postgres.port }}"
# 用户名
- name: DB_POSTGRESDB_USER
value: {{ .Values.postgres.username }}
# 密码
- name: DB_POSTGRESDB_PASSWORD
value: {{ .Values.postgres.password }}
各类中间件的声明与 values 引用
下表汇总各服务在 OlaresManifest.yaml 中的声明要点、注入值以及映射方式(完整示例见各 Integrate 指南与 manifest 规范 的 middleware 章节)。
| 服务 | 声明字段 | 注入的 Helm 值 | 映射示例 |
|---|---|---|---|
| PostgreSQL | username、databases[].{name,extensions,scripts} |
.Values.postgres.{host,port,username,password,databases} |
DB_POSTGRESDB_*,databases 为 Map,databases.<dbname> 取库名 |
| Redis | password、namespace |
.Values.redis.{host,port,password,namespaces} |
REDIS_HOST/PORT/PASSWORD/NAMESPACE,namespaces.<namespace> 取命名空间 |
| MongoDB | username、databases[].{name,script} |
.Values.mongodb.{host,port,username,password,databases} |
MONGODB_*,脚本需保证每行是一条完整查询 |
| MySQL | username、databases[].name |
.Values.mysql.{host,port,username,password,databases} |
MDB_HOST/PORT/USER/PASSWORD/DB |
| MariaDB | username、databases[].name |
.Values.mariadb.{host,port,username,password,databases} |
MDB_*(与 MySQL 命名一致) |
| MinIO | username、buckets[].name |
.Values.minio.{host,port,username,password,buckets} |
MINIO_ENDPOINT=host:port、MINIO_ACCESS_KEY、MINIO_SECRET_KEY、MINIO_BUCKET |
| RabbitMQ | username、vhosts[].name |
.Values.rabbitmq.{host,port,username,password,vhosts} |
RABBITMQ_HOST/PORT/USER/PASSWORD/VHOST |
| Elasticsearch | username、indexes[].name |
.Values.elasticsearch.{host,port,username,password,indexes} |
ES_HOST/PORT/USER/PASSWORD/INDEX |
这些 .Values.* 是部署时注入到 values.yaml 的系统托管运行时值,只读、不可由用户编辑。以 PostgreSQL 为例:
| Value | Type | Description |
|---|---|---|
.Values.postgres.host |
String | PostgreSQL 主机地址。 |
.Values.postgres.port |
Number | PostgreSQL 端口。 |
.Values.postgres.username |
String | PostgreSQL 用户名。 |
.Values.postgres.password |
String | PostgreSQL 密码。 |
.Values.postgres.databases |
Map<String,String> | 请求的数据库,以数据库名为键。例如请求 app_db 后可通过 .Values.postgres.databases.app_db 获取。 |
MongoDB、Redis、MinIO、RabbitMQ、MySQL、MariaDB、Elasticsearch 的 values 结构与此一致(Redis 为 namespaces Map,MinIO 为 buckets Map,RabbitMQ 为 vhosts Map,Elasticsearch 为 indexes Map),完整字段表见各服务的 Integrate 指南与 系统注入运行时值。
RabbitMQ 连接串构造示例(Go):
// 读取环境变量
user := os.Getenv("RABBITMQ_USER")
password := os.Getenv("RABBITMQ_PASSWORD")
vhost := os.Getenv("RABBITMQ_VHOST")
host := os.Getenv("RABBITMQ_HOST")
portMQ := os.Getenv("RABBITMQ_PORT")
// 构造 AMQP 连接串
// 格式: amqp://user:password@host:port/vhost
url := fmt.Sprintf("amqp://%s:%s@%s:%s/%s", user, password, host, portMQ, vhost)
NATS 等无独立集成指南的服务
NATS 未提供独立的 mw-integrate-with-nats 指南,但其能力已覆盖在系统注入机制中:应用可通过声明 options.dependencies 依赖 NATS 应用后,在模板中使用 .Values.deps(每个入口的 host/port)与 .Values.svcs(每个服务的 host/port 列表)获取连接信息。在 OAC 全量清单测试数据 中也可以看到 nats 声明支持 subjects[].{name,permission,export} 与 refs 等字段,可用于配置 Subject 权限与跨应用引用。
底层原理:从清单声明到真实资源的实现链路
声明式集成并非魔法,而是由仓库中多个组件协作完成。从源码结构可以梳理出以下链路:
1. 清单解析:OAC 组件
OlaresManifest.yaml 由 framework/oac 的 appconfig.go 负责加载与校验:LoadAppConfiguration 读取清单文件并通过版本感知的解析管线转换为 AppConfiguration(类型别名自 github.com/beclab/api/manifest),ValidateAppConfiguration 则执行结构与跨字段校验(如 dependency.type 必须为 system、application 或 middleware 之一,见 validate.go)。应用 metadata.name 会被规范化为 md5(name)[:8] 形式的 appid,供下游模块使用。
2. 运行时值注入:app-service 组件
部署时由 framework/app-service 解析清单中的中间件声明,并把连接值注入 values.yaml。从 handler_middleware.go 可以看到中间件安装/卸载/取消等 API 的实现,安装会构造 v1alpha1.Middleware 类型的资源并通过 middlewareinstaller 执行安装。环境变量的应用侧注入逻辑见 helm_ops_applyenv.go:AddEnvironmentVariables 构造 values 覆盖项,随后调用 helm.UpgradeCharts(..., helm.ReuseValues) 以增量方式应用。
3. 资源编排:TAPR 的 middleware-request 控制器
真正"把声明变成数据库资源"的是 TAPR 组件中的 middleware-request 控制器(platform/tapr/cmd/middleware/operator/middleware-request)。它监听 apr.bytetrade.io_middlewarerequests.yaml(CRD 定义)中定义的 MiddlewareRequest 自定义资源,通过 informer 与工作队列处理 ADD/UPDATE/DELETE 事件(见 controller.go),并针对不同中间件派发到独立的 handler(handler_pg.go、handler_redis.go、handler_mongodb.go、handler_mysql.go、handler_minio.go、handler_nats.go 等)。
以 PostgreSQL 为例,handler_pg.go 中的 createOrUpdatePGRequest 展示了完整的资源创建流程:
- 通过
findClusterWorkloadAndAdminuserAndPassword定位 Citus 集群 StatefulSet 与管理员凭据; - 遍历集群每个副本节点,用管理员账号连接
nodeHost(格式为<sts-name>-<index>.citus-headless.<namespace>); - 调用
CreateOrUpdateUser创建(或更新)应用声明的用户与密码; - 对每个声明的数据库:
CreateDatabaseIfNotExists创建数据库;若声明为分布式(IsDistributed()),则CreateCitus启用 Citus 扩展并在主节点SetMasterNode建立分布节点; - 依次执行
CreateExtensions(扩展)与ExecuteScript(初始化脚本,含$databasename/$dbusername变量替换)。
4. 底层集群形态
从 数据架构文档 可以确认系统内置中间件的集群化形态:
- PostgreSQL:随系统部署,搭载 Citus 分布式插件,集群由 TAPR 中的 PG Operator 管理;若应用声明数据库为 Distributed,Olares 会将其构建在 Citus 之上,充分利用分布式 PG 能力;
- MongoDB:通过 Percona Operator for MongoDB 提供云原生 MongoDB 集群;
- Redis:使用自定义的 Redis Cluster Operator 提供云原生 Redis Cluster,并额外开发代理层实现
namespace数据隔离机制——该隔离对开发者完全透明,无需在代码中处理 key 前缀,只需在应用 Chart 中简单配置即可实现多应用、多用户间数据隔离(注意系统是 Redis Cluster 版本,与单机版 Redis 有差异,建议参考官方 Redis 文档); - 备份恢复:上述数据库的备份与恢复由系统统一接管,无需用户具备 DBA 技能即可实现定时备份、增量备份与定点恢复,备份对象覆盖 Kubernetes 配置数据、数据库数据(Redis、MongoDB、PostgreSQL 等)与文件系统数据。
下一步:按角色进入对应文档
本文是 Olares 中间件文档的入口总览。按你的实际角色选择下一步:
- 需要检查数据、排查问题:进入各服务的 Access 指南,按 "Control Hub 获取连接信息 → CLI/Bytebase/Dashboard 管理" 的流程操作;
- 需要让自己的应用接入中间件:进入 OlaresManifest Specification 学习清单字段,再对照目标服务的 Integrate 指南完成声明与变量映射;环境变量注入机制的整体说明见 Environment variables overview,系统注入值的完整字段表见 System-injected runtime values;
- 需要理解底层数据架构与备份机制:阅读 数据架构文档,了解 JuiceFS 文件系统、三类应用存储路径(
UserData/AppData/AppCache)以及各数据库集群的部署与备份策略。