记录共享 PostgreSQL 背景与计划中的 DBaaS 租户中间层

README.md

@@ -6,6 +6,7 @@
 
 - [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。
 - [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。
+- [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
 - [待核实与文档缺口](verification.md)：互相矛盾的记录、缺少使用说明的服务、下一步核实方法。
 - [架构约束](architecture/constraints.md)：修改环境前必须遵守的设计及原始依据。
 - [workload-sts 设计历史](architecture/workload-sts-history.md)：已归档的早期身份方案及 SPIRE 替代决策。
@@ -17,7 +18,8 @@
 
 首轮盘点日期为 **2026-09-16**，依据 `/home/panxiao81/services` 工作区，基线 commit 为
 `ebe0ec154dab557598075b5cf6d3629c3c23fe2a`。该工作区包含未提交修改和未跟踪文件。
-SPIFFE/SPIRE 随后按维护者授权补读了 #34 及其已合并 runbook；其他条目仍以初轮工作区证据为限。
+后续按维护者提供的线索补读了 SPIFFE/SPIRE #34 与 runbook、workload-sts 归档决策、
+PostgreSQL Tenant Operator 的 README 与架构文档。具体来源和查阅范围见各页；其余条目仍以初轮工作区证据为限。
 后续状态查询先向维护者确认动态工作与资料来源，授权范围内不重复询问。
 本轮没有查询运行环境；“文档记录已部署”不等于今天已验证健康。
 本库中的入口地址来自原有记录，也尚未逐一验证可达性。

services/index.md

@@ -67,6 +67,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；其他条目仍为初轮工作区
 
 ## 计划、归档与范围外
 
+- [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；README 记录为 API 骨架阶段，不代表服务已上线。
 - [workload-sts](../architecture/workload-sts-history.md)：已归档的早期机器身份方案；停止开发、不部署 PoC，由 SPIFFE/SPIRE 替代。
 - Backstage：规划中的服务目录与文档入口；本轮未发现独立部署目录。
 - Keycloak、Casdoor：`archive/` 下有明确退役记录，替代入口为 Authelia。

services/postgresql-tenant-operator.md

@@ -0,0 +1,66 @@
+---
+title: PostgreSQL Tenant Operator（计划中的 DBaaS）
+lifecycle: planned
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+sources:
+  - https://git.ddupan.top/panxiao81/postgresql-tenant-operator
+  - https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/architecture.md
+---
+
+# PostgreSQL Tenant Operator
+
+计划中的 homelab DBaaS 中间层：在已有 PostgreSQL 实例上，为下游服务声明式创建和管理
+database、login role、权限、扩展及连接凭据。
+
+## 为什么需要它
+
+homelab 资源有限，为每个应用维护一套数据库会浪费资源。绝大多数服务使用 PostgreSQL，
+因此集群内目前已经共用一套 PostgreSQL 实例，但数据库、账号、权限和凭据仍不容易维护。
+计划自行实现这个中间层，让下游通过统一接口申请可消费的数据库，降低共享实例的管理成本。
+
+这段现状和设计动机由维护者于 2026-09-16 提供；本轮没有查询数据库或集群。
+现有实例的源码入口为 homelab-infra 的 `apps/shared-postgresql/`。
+
+## 当前进度
+
+2026-09-16 查阅[项目 README](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/README.md)
+与架构文档时，项目记录为 **API 骨架阶段，尚未对 PostgreSQL 或 OpenBao 执行写操作**。
+已批准的设计合同不等于已经实现的功能，本文不表示 DBaaS 已上线。
+项目首页还注明 `config/samples` 保留旧 API 骨架，不能将其直接当作最终使用接口。
+
+## 计划中的使用方式
+
+1. 平台管理员通过 `PostgreSQLInstance` 注册已有 PostgreSQL 实例及管理连接。
+2. 下游以 namespaced `PostgreSQLTenant` 声明所需 database、login owner 和扩展。
+3. controller 校验所有权与冲突，幂等创建凭据、role、database 和授权等资源。
+4. 应用凭据以 OpenBao KV 为事实来源，由 ESO 投射为 Kubernetes Secret。
+   非 Kubernetes 消费者使用提供的 OpenBao API URL，并通过自身授权获取凭据。
+5. ESO 投射成功且应用凭据实际登录成功后，Tenant 才能进入 Ready。
+
+GitOps、Terraform、kubectl 和未来 Backstage 计划共用这套 Kubernetes API。
+当前没有可供日常申请数据库的已验证服务入口；接口和具体行为以项目规范为准。
+
+## 职责边界
+
+- operator 管理实例内的租户资源，不运行 PostgreSQL/OpenBao，也不管理 VM、存储、备份或 OpenBao PKI。
+- 应用密码写入 OpenBao，不进入 CR、Event 或日志；ESO 负责向 Kubernetes 消费者投射。
+- 默认删除策略为 `Retain`，删除声明不会默认删除业务数据；显式 `Delete` 需重新校验所有权。
+- 遇到未知 database/role 等资源报告 Conflict，不能自动接管、覆盖或删除；现有数据库迁移需遵循迁移合同。
+- namespace 是 Kubernetes 身份与 RBAC 边界；database/role 名称在一个 PostgreSQL Instance 内仍全局唯一。
+
+这些是项目已记录的设计合同，不是本轮验证过的运行行为。
+
+## 设计与操作文档入口
+
+已查阅[系统架构](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/architecture.md)，
+其中说明组件、所有权、协调流程及凭据边界。其他文档按 README 收录，未在本轮逐篇复核：
+
+- [规范与验收标准](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/specification.md)：规范性行为；与架构视图冲突时以规范为准。
+- [API 合同](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/api-reference.md)：资源字段和 Condition。
+- [部署](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/deployment.md)与[安全](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/security.md)：依赖和权限。
+- [迁移](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/migration.md)与[运维](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/docs/operations.md)：现有数据库、删除和恢复合同。
+
+具体实现进度回到[项目仓库](https://git.ddupan.top/panxiao81/postgresql-tenant-operator)查询，
+后续查询前先向维护者对齐当前工作与 ticket。本页保留设计定位和带日期的阶段摘要。

verification.md

@@ -35,8 +35,11 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom
 
 - `docs/cicd.md` 提及 `e5renew`、`rustfs`，但无独立组件目录；需要确认现状与归属。
 - `infrastructure/docker/README.md` 提及仓库外 `research-auto`，不能在本轮算作已盘点服务。
-- 本轮发现远端仓库 `gitea-microvm-runner`、`postgresql-tenant-operator`，
+- 本轮发现远端仓库 `gitea-microvm-runner`，
   尚未审阅内容或运行状态。后续将跨仓库服务纳入总览。
+- PostgreSQL Tenant Operator 已按维护者说明及项目 README/架构文档收录为
+  [计划中的 DBaaS 中间层](services/postgresql-tenant-operator.md)。共享 PostgreSQL 已在使用，
+  operator 仍按项目记录标为 API 骨架阶段；本轮未查询运行环境。
 - workload-sts 已按维护者提供的信息查阅：仓库已归档，停止开发、不部署 PoC，
   作为[早期设计与替代决策的历史来源](architecture/workload-sts-history.md)保留，不列为待接入服务。
 - 新增 NATS、zot、microVM 等来源含未提交文件；合并后补可访问的 commit/PR 链接。