Terminus(Olares)应用接入 MySQL:OlaresManifest 中间件声明与环境变量映射实战
Terminus(Olares)应用接入 MySQL:OlaresManifest 中间件声明与环境变量映射实战
本篇指南围绕 Terminus(Olares)个人云系统中应用的中间件集成能力,完整讲解如何通过 OlaresManifest.yaml 声明 MySQL 中间件、由系统自动注入运行时连接配置,并在应用部署 YAML 中把 .Values.mysql.* 字段映射为容器环境变量的全流程。读完本文,你将掌握 MySQL 服务的安装方式、middleware.mysql 配置块的字段语义、五类注入变量的取值方法,以及底层中间件请求的生成与值注入机制。
集成原理概述
在 Terminus(Olares)中,应用与中间件(MySQL、PostgreSQL、Redis、MongoDB 等)的解耦通过两层声明完成:
- 应用侧声明:在应用的
OlaresManifest.yaml中声明middleware.mysql配置块,指定数据库用户与需要申请的数据库列表; - 系统侧注入:应用安装时,系统根据声明向中间件服务发起请求,获取真实连接信息(主机、端口、用户名、密码、数据库映射),并注入到 Helm 渲染使用的
values.yaml中,形成.Values.mysql.*变量; - 容器侧映射:应用自己的部署 YAML 通过
{{ .Values.mysql.* }}模板取值,把连接配置映射为容器环境变量,应用即可直接使用。
这套机制让应用开发者无需关心 MySQL 实例的部署位置、网络拓扑与凭据管理,由平台统一负责中间件的生命周期与安全隔离。
安装 MySQL 服务
在编写应用配置之前,需要先确保目标环境中已有可用的 MySQL 中间件实例:
- 从启动台打开应用市场,搜索 “MySQL”;
- 点击获取,然后点击安装,并等待安装完成。
安装完成后,MySQL 服务及其连接信息会显示在控制面板的中间件列表中。该中间件实例由平台统一管理,应用侧只消费由系统注入的连接参数,不直接操作底层实例。
配置 OlaresManifest.yaml 中的 MySQL 中间件
在应用根目录的 OlaresManifest.yaml 中添加 middleware 配置块,并声明 mysql 子项:
- 使用
username字段指定 MySQL 数据库用户; - 使用
databases字段申请一个或多个数据库。每个数据库名称将作为键注入到.Values.mysql.databases中。
middleware:
mysql:
username: mysqlclient
databases:
- name: aaa
完整的 manifest 示例还可以同时声明密码与多个数据库,参考仓库中的完整示例 framework/oac/testdata/full_manifest/OlaresManifest.yaml:
middleware:
mysql:
username: mysqluser
password: mysqlpass
databases:
- name: mysqlapp
说明:password 字段为可选项。若不填写密码,系统会生成并保存密码凭据(详见下文“凭据与安全”小节)。
字段语义
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
middleware.mysql.username |
String | 是 | 申请使用的 MySQL 数据库用户名 |
middleware.mysql.password |
String | 否 | 数据库密码;留空时由系统创建并注入 Secret |
middleware.mysql.databases[].name |
String | 是 | 申请创建的数据库名称,将作为键注入 .Values.mysql.databases |
middleware 中的 mysql 结构体在源码中统一映射为 MySQLConfig,定义位于共享的 manifest 包 github.com/beclab/api,并由 framework/app-service/pkg/tapr/middleware_types.go 别名复用,保证配置格式在各组件间一致。
映射环境变量
在应用的部署 YAML(Chart 模板)中,通过 {{ .Values.mysql.* }} 引用系统注入的运行时值,并将其映射为容器环境变量:
containers:
- name: my-app
# MySQL 对应的注入值如下
env:
- name: MDB_HOST
value: "{{ .Values.mysql.host }}"
- name: MDB_PORT
value: "{{ .Values.mysql.port }}"
- name: MDB_USER
value: "{{ .Values.mysql.username }}"
- name: MDB_PASSWORD
value: "{{ .Values.mysql.password }}"
# 数据库名称
# 在 OlaresManifest 中配置的数据库名(例如:aaa)
- name: MDB_DB
value: "{{ .Values.mysql.databases.aaa }}"
映射完成后,应用代码即可通过 MDB_HOST、MDB_PORT、MDB_USER、MDB_PASSWORD、MDB_DB 等环境变量组装连接串。数据库名称的取值方式与声明一一对应:声明了 aaa,就用 .Values.mysql.databases.aaa 取实际库名(实际库名可能带有平台前缀,因此必须通过该映射而非硬编码)。
MySQL 变量参考
MySQL 运行时变量会在部署过程中注入到 values.yaml 中。这些变量由系统统一管理,用户无法自行修改:
| 变量 | 类型 | 说明 |
|---|---|---|
.Values.mysql.host |
String | MySQL 主机地址。 |
.Values.mysql.port |
Number | MySQL 端口。 |
.Values.mysql.username |
String | MySQL 用户名。 |
.Values.mysql.password |
String | MySQL 密码。 |
.Values.mysql.databases |
Map<String,String> | 请求的数据库集合,按数据库名为键。 例如申请 app_db,可通过 .Values.mysql.databases.app_db 获取对应的值。 |
这一变量形状在源码中有直接对应:Helm 静态渲染(lint)阶段,framework/oac/internal/helmrender/values.go 会为 mysql 预置一个空的 databases 映射,使模板在无集群环境下也能安全渲染;实际安装阶段,framework/app-service/pkg/tapr/middleware.go 将中间件服务返回的连接信息组装为同构的 vals["mysql"] 结构并写入 Helm values。两处结构保持一致,保证开发期渲染与生产期渲染结果一致。
底层注入流程与源码实现
理解底层调用链有助于排查集成问题。整个 MySQL 中间件集成的核心逻辑集中在 framework/app-service/pkg/tapr/middleware.go 的 Apply 函数中:
- 构造用户名:当
middleware.MySQL != nil时,系统按username-ownerName-appName的规则生成实际数据库用户名(见 middleware.go#L303-L305),保证多应用之间凭据隔离; - 生成中间件请求:调用
process,通过 GenMiddleRequest 将 manifest 声明渲染为MiddlewareRequest资源。MySQL 请求模板见 middleware_request_tpl.go#L129-L153,其中:- 请求类型为
apr.bytetrade.io/v1alpha1下的MiddlewareRequest,spec.middleware: mysql; - 遍历
.Middleware.Databases生成数据库申请列表; - 若 manifest 中未提供密码,则从名为
<appName>-<namespace>-mysql-password的 Secret 的password键取值(valueFrom.secretKeyRef);
- 请求类型为
- 创建或更新资源:通过
CreateOrUpdateMiddlewareRequest将请求提交到集群,中间件服务据此实际创建数据库与账号; - 获取注入值:向中间件服务(
middleware-service.os-platform的/middleware/v1/request/info接口,见 middleware.go#L111-L118)查询请求结果,得到host、port、username、password与databases映射; - 写入 Helm values:将上述结果组装为
vals<a href="https://link.gitcode.com/i/5e603169ac12665ac900c877fa5e482a" target="_blank">"mysql"](见 [middleware.go#L315-L321),供应用 Chart 模板在渲染时通过{{ .Values.mysql.* }}取值。
支持的中间件类型
从 middleware.go#L21-L48 可以看出,MySQL 只是平台中间件体系中的一员,同一套机制同样覆盖 PostgreSQL、Redis、MongoDB、MinIO、RabbitMQ、Elasticsearch、MariaDB、NATS、ClickHouse 等。掌握 MySQL 的接入方式后,可举一反三接入其他中间件。
凭据与安全
当应用在 OlaresManifest.yaml 中不显式提供密码时,系统会调用 CreateOrUpdateSecret 为应用创建独立的密码 Secret(见 middleware.go#L368-L374),随后通过 MiddlewareRequest 的 secretKeyRef 引用该 Secret。密码不会明文出现在应用 Chart 中,而是由系统解密后注入 .Values.mysql.password,保证凭据的最小暴露面。
校验规则
middleware 配置块在 manifest 校验阶段会被检查,dependency.type 必须为 system、application 或 middleware 三者之一(见 framework/oac/internal/manifest/validate.go 与 validate.go#L1110)。声明中间件依赖时务必使用合法的类型值,否则安装校验会失败。
快速排障指引
- 应用无法连接 MySQL:检查部署 YAML 中是否完整映射了
host、port、username、password五个变量;确认数据库名取值使用的是.Values.mysql.databases.<name>映射而非硬编码。 - 提示凭据错误:若 manifest 中未声明
password,确认密码来源为系统 Secret,不要在自己的配置中重复覆盖同名环境变量。 - 中间件未出现在控制面板:回到应用市场确认 MySQL 服务已安装完成,安装完成前中间件列表不会显示连接信息。
- 模板渲染报错:
databases键名必须与.Values.mysql.databases.xxx的xxx严格一致,注意大小写与中划线等字符的完全匹配。
小结
在 Terminus(Olares)中接入 MySQL 只需三步:安装 MySQL 服务 → 在 OlaresManifest.yaml 中声明 middleware.mysql(用户名 + 数据库列表)→ 在部署 YAML 中把 .Values.mysql.* 映射为环境变量。底层由 app-service 的中间件请求引擎自动完成建库、建账号与凭据注入,应用侧零感知。通过源码中的请求模板与变量注入实现,可以进一步理解平台中间件体系的通用工作方式,并迁移到其他受支持的中间件类型上。