仅使用目录——零平台编写的 MariaDB + Adminer
本示例部署一个小型的真实栈——一个 MariaDB 数据库,前面配一个 Adminer Web UI——仅引用标准库目录 实体。这里不编写任何 Component、Feature 或 Recipe:三个 简短的 YAML 文件将一切路由到目录已提供的实体。
这是 Aggrega 提供的最小编写面,也是初次接触该语言的自然起点。编写层级的姊妹示例 部署同一个栈,同时构建自己的目录层——先阅读本 示例,了解一个完成的目录能为你带来什么,再阅读那个示例,学习 其下的层是如何构建的。
三个文件
aggregate.yaml——Developer 的意图:栈是什么。通过type:从目录中选取的两个组件,一个作为槽位填充附件的必需凭据,以及一条uses边,将数据库接入 Adminer 的databases插座。release.yaml——Operator 按环境进行的实现:多大、在哪里。infra:块(引擎版本、存储大小、发布端口)属于 Operator;Aggregate 从不携带它们。manifest.yaml——Operator 的路由:在此目标上由哪个 Recipe 实现每种类型。关于这些引用为何以 provider 限定,请见下文。
演示内容
- Components 作为目录引用。
type: core/datastore/mariadb和type: core/devtool/adminer就是全部的计算声明。 Developer 只编写 Component 模式公开的值——每个 省略的字段都取其模式默认值(对比渲染输出中的 charset 和 collation 环境变量,以及生成它们的单行values:块)。 - String Pipe。 Adminer 的目录 Component 声明了一个
databasesuses 插座,接受任何标记为component.aggrega.ai/type=stateful-server的组件。Aggregate 的边将 数据库 Recipe 的provides.host注入ADMINER_DEFAULT_SERVER。 编译器路由该字符串而不解释它——在此目标上它是 一个 compose 服务名;同一条边在 Kubernetes 目标上则会携带 一个 Service DNS 名称。 - 附件支柱。 数据库 Component 的
featuresSchema要求 一个root_password槽位,由目录的core/secret-valueFeature 填充。该槽位是黑盒:由 Manifest 选定的 FeatureRecipe 控制交付方式,Developer 无法指定。 - 按 Provider 限定的 Recipe 路由。 Manifest 将
core/datastore/mariadb:1.0.0映射到compose/mariadb:1.0.0——按 提供者限定——因为标准库在多个提供者下都提供了 mariadb Recipe(其中包括 compose 和 helm)。 正是 Operator 的映射消除了目标的歧义:一个未加限定的裸引用如果匹配多个提供者的 Recipe,构建会明确报错并中止, 而不会静默地选择其中一个。要将该技术栈切换到其他目标,只需重新指向 这些映射;Aggregate 无需改动。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example catalog-only然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd catalog-only构建
在此目录中运行,目录实体从 .aggrega-config.yaml 指定的默认注册表 hub.aggrega.ai 解析:
aggrega pull --release release.yamlaggrega build --release release.yaml拉取会解析每个被引用的实体,并将其锁定在 release.lock 中(标识 + 内容摘要;再次运行拉取即可重新生成过时的锁文件)。若有标准库目录的检出(获取途径),在两条命令上都用 --catalog 指定其 aggrega-catalog 目录,即可从那里读取实体。构建读取该锁文件——没有它,构建会中止并指出两条前进路径:拉取或 --auto-pull——然后渲染 dist/compose/docker-compose.yaml。该 Release 直接编写其组件(没有 boundaries: 块),因此编译器将它们并入合成的默认作用域,并平铺输出到 dist/ 下——一个边界,路径中没有边界名称段。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `catalog-only` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `catalog-only`,且不提供 `dir`:它会把示例写入一个新的 `catalog-only` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `catalog-only`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `catalog-only/dist/` 下。阅读输出
在渲染出的 compose 文件中,连接关系变得可见:
web服务携带ADMINER_DEFAULT_SERVER: db——即数据库 Recipe 的provides.host(compose 服务名),通过 uses 边传递;- 同一条边生成了
depends_on: [db]——是拓扑,而不仅是字符串; db服务的MARIADB_CHARACTER_SET_SERVER和MARIADB_COLLATION_SERVER来自 Aggregate 从未 提及的模式默认值;image: mariadb:11.4和8080:8080端口绑定来自 Release 的infra:块——Operator 的支柱,与 Developer 的支柱一同渲染。
运行
cd dist/composedocker compose up -d打开 http://localhost:8080:服务器字段已预填为 db。
以 root 身份登录,使用 Aggregate 附件中的开发密码
(dev-root-pw-change-me——这是一个占位符,在本地开发
之外的任何场景中都应替换),数据库为 appdb。
下一步
编写层级让你自己构建同样的平台层 ——即本示例直接使用的现成 Components、Recipes 和凭据 FeatureRecipes ——并将一个 Aggregate 编译到四个目标。