云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载在 Olares 中PostgreSQL 是默认预装的基础数据库中间件。应用开发者无需关心数据库的部署与运维细节只需在OlaresManifest.yaml中声明依赖并在 Helm 模板里把系统注入的连接信息映射为容器环境变量即可在应用中使用一套安全、隔离、由平台统一托管的 PostgreSQL 服务。本文将以 Olares 官方集成指南为主线结合仓库源码逐层拆解完整的集成流程、配置参数与变量注入机制帮助你快速上手。集成原理声明式中间件依赖如何生效Olares 的中间件指位于应用与系统之间的基础设施服务用于提供数据存储、消息通信等通用能力。PostgreSQL 的集成过程是声明式的开发者只在OlaresManifest.yaml中描述我需要什么数据库、哪些扩展、初始化时执行什么脚本具体的资源申请、账号创建、数据库初始化、连接信息生成均由 Olares 在部署阶段自动完成参见中间件指南。整个集成链路可概括为三个步骤声明在OlaresManifest.yaml的middleware.postgres段声明用户名、数据库、扩展与初始化脚本自动处理部署时 Olares 应用运行时解析该声明向中间件服务发起MiddlewareRequest创建数据库与账号并返回连接信息随后将连接信息注入应用的values.yaml映射在应用的部署模板如deployment.yaml中将.Values.postgres.*映射为容器环境变量。系统注入的变量是只读的、由平台统一管理且属于 Helm values——它们不会自动进入容器必须通过env:显式映射才能被应用进程读取详见系统注入的运行时变量。配置OlaresManifest.yaml声明 PostgreSQL 依赖在应用包的OlaresManifest.yaml中添加middleware.postgres配置段即可完成依赖声明使用scripts字段指定数据库创建完成后需要执行的 SQL 脚本按顺序执行使用extensions字段为数据库添加所需的扩展如vectors、earthdistance、pg_trgm等系统在执行脚本时会自动提供并替换两个变量$databasename数据库名和$dbusername数据库用户名由 Olares 应用运行时在脚本执行前注入。官方文档给出的完整示例以 Immich 应用申请向量数据库为例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;上述示例的含义是申请一个名为immich的数据库为其安装vectors向量检索与earthdistance地球距离计算用于地理邻近查询扩展并执行三条 SQL把数据库默认search_path调整为包含vectorsschema再把vectorsschema 的所有者移交给当前用户最终提交事务。更完整的字段形态从仓库中用于测试的完整 Manifestframework/oac/testdata/full_manifest/OlaresManifest.yaml可以看到middleware.postgres支持的全部字段middleware: postgres: username: pguser password: pgpass databases: - name: appdb extensions: - pg_trgm scripts: - init.sql distributed: true各字段说明| 字段 | 类型 | 说明 | | -- | -- | -- | |username| String | 申请的 PostgreSQL 用户名。实际生效的用户名会由平台进一步组合加工见下文源码实现一节。 | |password| String | 可选。若不填写系统会生成随机密码并通过 Secret 注入。 | |databases[]| Array | 申请的数据库列表可申请多个。 | |databases[].name| String | 数据库名称需与后续环境变量映射中的 key 对应。 | |databases[].extensions| Array | 需要安装的 PostgreSQL 扩展名称列表。 | |databases[].scripts| Array | 数据库创建后按顺序执行的 SQL 脚本支持$databasename、$dbusername两个自动替换变量。 | |databases[].distributed| Boolean | 是否为分布式数据库Olares 的 PostgreSQL 基于 Citus 构建可声明分布式表能力。 |这些字段对应的 Go 类型定义可在 framework/oac/internal/manifest/types.go 中确认Middleware、Database、PostgresConfig等类型均以github.com/beclab/api/manifest中的共享定义为准保证了 Manifest 解析、校验与应用运行时各模块操作的是同一套类型结构。映射环境变量把连接信息传入容器在应用部署模板中将系统注入的.Values.postgres.*字段映射为应用所需的环境变量containers: - name: my-app env: # 在 OlaresManifest 中配置的数据库名称 # 对应 middleware.postgres.databases[i].name # 注意将 dbname 替换为 Manifest 中定义的实际名称例如 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.postgres.databases是一个以数据库名为键的 Map。申请了几个数据库就对应几个 key。例如申请了immich就用{{ .Values.postgres.databases.immich }}取值端口字符串化.Values.postgres.port类型是 Number映射到环境变量时必须加引号{{ .Values.postgres.port }}否则 Helm 渲染后环境变量值可能不是字符串与系统注入的运行时变量文档中的示例保持一致{{ .Values.postgres.host }}这类引用同样可以出现在任何 Helm 模板文件中比如把数据库主机地址注入为DB_HOST参见系统注入的运行时变量。PostgreSQL 变量参考PostgreSQL 运行时变量会在部署过程中注入到values.yaml由系统统一管理、用户无法自行修改| 变量 | 类型 | 说明 | | -- | -- | -- | |.Values.postgres.host| String | PostgreSQL 主机地址。 | |.Values.postgres.port| Number | PostgreSQL 端口。 | |.Values.postgres.username| String | PostgreSQL 用户名。 | |.Values.postgres.password| String | PostgreSQL 密码。 | |.Values.postgres.databases| MapString,String | 请求的数据库集合按数据库名为键。例如若申请的数据库名为app_db可通过.Values.postgres.databases.app_db获取对应值。 |源码视角中间件请求如何被构造与注入理解集成原理的最好方式是阅读应用安装器app-service中负责中间件编排的代码。核心逻辑位于 framework/app-service/pkg/tapr/middleware.go其中Apply函数在应用部署时被调用构造用户名PostgreSQL 的最终用户名并非直接使用 Manifest 中的username而是组合为{username}_{ownerName}_{appName}并把连字符替换为下划线middleware.go#L146-L149。这样既避免了不同用户/不同应用之间账号冲突也符合 PostgreSQL 标识符规范生成请求process函数通过 GenMiddleRequest 将 Manifest 中的 PostgreSQL 配置渲染为MiddlewareRequest自定义资源CRD请求体通过 Gotext/template生成postgresRequest 模板包含databases含distributed、extensions、scripts、password显式值或secretKeyRef引用、user等字段密码处理若 Manifest 未显式提供password安装器会调用CreateOrUpdateSecret创建同名密码 Secret{appName}-{namespace}-postgres-password并在MiddlewareRequest中以valueFrom.secretKeyRef方式引用middleware_request_tpl.go#L37-L45获取连接信息并注入安装器向http://middleware-service.os-platform/middleware/v1/request/info发起带重试404/429/5xx 自动重试 3 次的查询拿到返回的host、port、username、password、databases最终写入vals[postgres]middleware.go#L111-L164这就是.Values.postgres.*系列变量的最终来源。此外Olares 的 CLI 脚手架还会在打包阶段进行中间件规范检查如果应用把 PostgreSQL 之类的数据存储直接打进自身镜像并作为 Workload 运行脚手架会给出提示要求替换为 Olares 系统中间件并声明options.dependencies依赖参见 cli/pkg/chart/scaffold.go 与 scaffold.go#L884。这从工具链层面保证了声明式集成中间件是唯一受支持的数据库接入方式。获取连接信息与数据验证集成完成后如需人工查看或管理数据库数据例如验证初始化脚本是否生效、排查写入问题可以按查看 PostgreSQL 数据指南操作从控制面板左侧导航栏的中间件 → Postgres中获取主机、用户、密码连接信息面板如下图所示再选择通过 Olares 终端进入 PostgreSQL 容器kubectl exec -it -n os-platform citus-0 -- sh后用psql -h citus-0 -U olares连接或通过 Bytebase 进行可视化管理。小结在 Olares 中集成 PostgreSQL 是一个声明 自动注入 显式映射的过程在OlaresManifest.yaml里通过middleware.postgres声明数据库、扩展与初始化脚本平台即自动完成账号创建、数据库初始化与连接信息生成并通过.Values.postgres.*变量注入到应用应用侧只需在部署模板中把对应值映射为环境变量即可。借助仓库源码middleware.go、middleware_request_tpl.go可以清晰看到从 Manifest 到MiddlewareRequest、再到values.yaml的完整调用链帮助你在遇到连接异常或权限问题时快速定位原因。赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐TerminusOlaresPostgreSQL 中间件集成指南从 OlaresManifest.yaml 声明到应用连接信息注入TerminusOlaresPostgreSQL 中间件集成指南从 OlaresManifest.yaml 声明到应用连接信息注入 在 Terminus云原生后端运维Olares 应用集成 Redis通过 OlaresManifest 声明中间件依赖并映射连接变量Olares 应用集成 Redis通过 OlaresManifest 声明中间件依赖并映射连接变量 本文介绍如何在 Olares开源个人云操作系统中通过云原生后端运维TerminusOlaresRabbitMQ 中间件集成实战用 OlaresManifest.yaml 声明式接入消息队列TerminusOlaresRabbitMQ 中间件集成实战用 OlaresManifest.yaml 声明式接入消息队列 本篇技术指南基于 Termin云原生后端运维上一篇开源项目推荐Gitbook —— 技术知识管理平台的前端核心下一篇突破创意瓶颈使用Dramatron实现AI辅助剧本创作的技术实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/16 1:39:18 · 阅读 1.2k Olares 应用集成 PostgreSQL：OlaresManifest 声明式中间件依赖与连接信息注入实战
云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载在 Olares 中PostgreSQL 是默认预装的基础数据库中间件。应用开发者无需关心数据库的部署与运维细节只需在OlaresManifest.yaml中声明依赖并在 Helm 模板里把系统注入的连接信息映射为容器环境变量即可在应用中使用一套安全、隔离、由平台统一托管的 PostgreSQL 服务。本文将以 Olares 官方集成指南为主线结合仓库源码逐层拆解完整的集成流程、配置参数与变量注入机制帮助你快速上手。集成原理声明式中间件依赖如何生效Olares 的中间件指位于应用与系统之间的基础设施服务用于提供数据存储、消息通信等通用能力。PostgreSQL 的集成过程是声明式的开发者只在OlaresManifest.yaml中描述我需要什么数据库、哪些扩展、初始化时执行什么脚本具体的资源申请、账号创建、数据库初始化、连接信息生成均由 Olares 在部署阶段自动完成参见中间件指南。整个集成链路可概括为三个步骤声明在OlaresManifest.yaml的middleware.postgres段声明用户名、数据库、扩展与初始化脚本自动处理部署时 Olares 应用运行时解析该声明向中间件服务发起MiddlewareRequest创建数据库与账号并返回连接信息随后将连接信息注入应用的values.yaml映射在应用的部署模板如deployment.yaml中将.Values.postgres.*映射为容器环境变量。系统注入的变量是只读的、由平台统一管理且属于 Helm values——它们不会自动进入容器必须通过env:显式映射才能被应用进程读取详见系统注入的运行时变量。配置OlaresManifest.yaml声明 PostgreSQL 依赖在应用包的OlaresManifest.yaml中添加middleware.postgres配置段即可完成依赖声明使用scripts字段指定数据库创建完成后需要执行的 SQL 脚本按顺序执行使用extensions字段为数据库添加所需的扩展如vectors、earthdistance、pg_trgm等系统在执行脚本时会自动提供并替换两个变量$databasename数据库名和$dbusername数据库用户名由 Olares 应用运行时在脚本执行前注入。官方文档给出的完整示例以 Immich 应用申请向量数据库为例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;上述示例的含义是申请一个名为immich的数据库为其安装vectors向量检索与earthdistance地球距离计算用于地理邻近查询扩展并执行三条 SQL把数据库默认search_path调整为包含vectorsschema再把vectorsschema 的所有者移交给当前用户最终提交事务。更完整的字段形态从仓库中用于测试的完整 Manifestframework/oac/testdata/full_manifest/OlaresManifest.yaml可以看到middleware.postgres支持的全部字段middleware: postgres: username: pguser password: pgpass databases: - name: appdb extensions: - pg_trgm scripts: - init.sql distributed: true各字段说明| 字段 | 类型 | 说明 | | -- | -- | -- | |username| String | 申请的 PostgreSQL 用户名。实际生效的用户名会由平台进一步组合加工见下文源码实现一节。 | |password| String | 可选。若不填写系统会生成随机密码并通过 Secret 注入。 | |databases[]| Array | 申请的数据库列表可申请多个。 | |databases[].name| String | 数据库名称需与后续环境变量映射中的 key 对应。 | |databases[].extensions| Array | 需要安装的 PostgreSQL 扩展名称列表。 | |databases[].scripts| Array | 数据库创建后按顺序执行的 SQL 脚本支持$databasename、$dbusername两个自动替换变量。 | |databases[].distributed| Boolean | 是否为分布式数据库Olares 的 PostgreSQL 基于 Citus 构建可声明分布式表能力。 |这些字段对应的 Go 类型定义可在 framework/oac/internal/manifest/types.go 中确认Middleware、Database、PostgresConfig等类型均以github.com/beclab/api/manifest中的共享定义为准保证了 Manifest 解析、校验与应用运行时各模块操作的是同一套类型结构。映射环境变量把连接信息传入容器在应用部署模板中将系统注入的.Values.postgres.*字段映射为应用所需的环境变量containers: - name: my-app env: # 在 OlaresManifest 中配置的数据库名称 # 对应 middleware.postgres.databases[i].name # 注意将 dbname 替换为 Manifest 中定义的实际名称例如 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.postgres.databases是一个以数据库名为键的 Map。申请了几个数据库就对应几个 key。例如申请了immich就用{{ .Values.postgres.databases.immich }}取值端口字符串化.Values.postgres.port类型是 Number映射到环境变量时必须加引号{{ .Values.postgres.port }}否则 Helm 渲染后环境变量值可能不是字符串与系统注入的运行时变量文档中的示例保持一致{{ .Values.postgres.host }}这类引用同样可以出现在任何 Helm 模板文件中比如把数据库主机地址注入为DB_HOST参见系统注入的运行时变量。PostgreSQL 变量参考PostgreSQL 运行时变量会在部署过程中注入到values.yaml由系统统一管理、用户无法自行修改| 变量 | 类型 | 说明 | | -- | -- | -- | |.Values.postgres.host| String | PostgreSQL 主机地址。 | |.Values.postgres.port| Number | PostgreSQL 端口。 | |.Values.postgres.username| String | PostgreSQL 用户名。 | |.Values.postgres.password| String | PostgreSQL 密码。 | |.Values.postgres.databases| MapString,String | 请求的数据库集合按数据库名为键。例如若申请的数据库名为app_db可通过.Values.postgres.databases.app_db获取对应值。 |源码视角中间件请求如何被构造与注入理解集成原理的最好方式是阅读应用安装器app-service中负责中间件编排的代码。核心逻辑位于 framework/app-service/pkg/tapr/middleware.go其中Apply函数在应用部署时被调用构造用户名PostgreSQL 的最终用户名并非直接使用 Manifest 中的username而是组合为{username}_{ownerName}_{appName}并把连字符替换为下划线middleware.go#L146-L149。这样既避免了不同用户/不同应用之间账号冲突也符合 PostgreSQL 标识符规范生成请求process函数通过 GenMiddleRequest 将 Manifest 中的 PostgreSQL 配置渲染为MiddlewareRequest自定义资源CRD请求体通过 Gotext/template生成postgresRequest 模板包含databases含distributed、extensions、scripts、password显式值或secretKeyRef引用、user等字段密码处理若 Manifest 未显式提供password安装器会调用CreateOrUpdateSecret创建同名密码 Secret{appName}-{namespace}-postgres-password并在MiddlewareRequest中以valueFrom.secretKeyRef方式引用middleware_request_tpl.go#L37-L45获取连接信息并注入安装器向http://middleware-service.os-platform/middleware/v1/request/info发起带重试404/429/5xx 自动重试 3 次的查询拿到返回的host、port、username、password、databases最终写入vals[postgres]middleware.go#L111-L164这就是.Values.postgres.*系列变量的最终来源。此外Olares 的 CLI 脚手架还会在打包阶段进行中间件规范检查如果应用把 PostgreSQL 之类的数据存储直接打进自身镜像并作为 Workload 运行脚手架会给出提示要求替换为 Olares 系统中间件并声明options.dependencies依赖参见 cli/pkg/chart/scaffold.go 与 scaffold.go#L884。这从工具链层面保证了声明式集成中间件是唯一受支持的数据库接入方式。获取连接信息与数据验证集成完成后如需人工查看或管理数据库数据例如验证初始化脚本是否生效、排查写入问题可以按查看 PostgreSQL 数据指南操作从控制面板左侧导航栏的中间件 → Postgres中获取主机、用户、密码连接信息面板如下图所示再选择通过 Olares 终端进入 PostgreSQL 容器kubectl exec -it -n os-platform citus-0 -- sh后用psql -h citus-0 -U olares连接或通过 Bytebase 进行可视化管理。小结在 Olares 中集成 PostgreSQL 是一个声明 自动注入 显式映射的过程在OlaresManifest.yaml里通过middleware.postgres声明数据库、扩展与初始化脚本平台即自动完成账号创建、数据库初始化与连接信息生成并通过.Values.postgres.*变量注入到应用应用侧只需在部署模板中把对应值映射为环境变量即可。借助仓库源码middleware.go、middleware_request_tpl.go可以清晰看到从 Manifest 到MiddlewareRequest、再到values.yaml的完整调用链帮助你在遇到连接异常或权限问题时快速定位原因。赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐TerminusOlaresPostgreSQL 中间件集成指南从 OlaresManifest.yaml 声明到应用连接信息注入TerminusOlaresPostgreSQL 中间件集成指南从 OlaresManifest.yaml 声明到应用连接信息注入 在 Terminus云原生后端运维Olares 应用集成 Redis通过 OlaresManifest 声明中间件依赖并映射连接变量Olares 应用集成 Redis通过 OlaresManifest 声明中间件依赖并映射连接变量 本文介绍如何在 Olares开源个人云操作系统中通过云原生后端运维TerminusOlaresRabbitMQ 中间件集成实战用 OlaresManifest.yaml 声明式接入消息队列TerminusOlaresRabbitMQ 中间件集成实战用 OlaresManifest.yaml 声明式接入消息队列 本篇技术指南基于 Termin云原生后端运维上一篇开源项目推荐Gitbook —— 技术知识管理平台的前端核心下一篇突破创意瓶颈使用Dramatron实现AI辅助剧本创作的技术实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考