4.6 KiB
Database 领域模型
状态：资源模型已确认，字段与绑定协议待细化。日期：2026-09-24。 行为以 系统规格 为准；决策依据见 ADR-0009。
统一语言与关系
| 术语 | 含义 |
|---|---|
| Instance | 平台登记的 PostgreSQL 资源来源与管理入口 |
| Database | 独立存在的数据库资源，保存目标、管理范围、绑定与回收策略 |
| Tenant | 用户对数据库的申请与使用合同 |
| Binding | Database 与 Tenant 的排他关联，不是独立 Claim 或 registry |
| LoginRole | 当前单数据库场景中兼任 owner 的登录角色 |
| CredentialLocation | 与资源生命周期一致的凭据定位，不是密码 |
| CredentialProjection | 面向当前使用者的凭据投射要求与观察 |
Instance 一对多 Database；每个 Database 同时零或一个 Tenant，Tenant 最多一个 Database。 Instance 不持有全部资源的内存集合。三者以引用关联，操作一个资源无需加载整个实例集合。
Database 的 instanceRef 表达资源归属，手工登记时也必须提供，不从 Tenant 反推。 Tenant 动态申请才选择 Instance；引用已有 Database 时使用资源声明的 Instance。 释放使用绑定不改变 Database 的实例归属，修改引用不能实现外部数据库迁移。
Database 不再是 Tenant 内的无独立生命周期描述。原 OwnershipClaim 不再作为独立领域能力： 排他绑定是资源自身的不变量，Kubernetes 保存记录，不另建 PostgreSQL 所有权存储。
职责
Instance 只接收观察并判断当前连接、metadata、管理权限和扩展支持，不访问 IO、不初始化 registry。管理凭据来源和连接刷新由应用层协调，连接池由 pgxpool 实现。见 Instance 规格。
Database 保护目标和管理范围、排他绑定、导入验证与 Retain/Delete 规则。资源首次外部操作前 必须已有持久记录；完成记录与外部存在性分别检查。数据库名称不是归属证明。
Tenant 表达申请与交付要求；显式选择已有资源不自动授权使用。绑定后检查数据库满足要求、 应用凭据可登录且 ESO 投射完成，才可 Ready。Tenant 删除意味着释放使用关系。
LoginRole 与 CredentialLocation 的生命周期必须随独立资源保留，不能因为 Tenant 消失就 失去定位或未经授权被删除；具体字段归属及导入时的管理范围需继续评审。不要因此新增 Role、 Credential 或 Claim CRD。当前首版仍是单 database + 单 login owner。
生命周期与恢复
- 动态创建与显式导入最终形成同一种 Database 资源，但导入本身不允许改密、改 owner 或删除。
- Retain 后 Database 保持 Released 与旧绑定身份，人工确认数据、权限和凭据后才可重新绑定。
- 回收策略属于资源侧；Tenant 与 Database 不是可随申请级联 GC 的父子关系。
- 绑定 UID 防止同名新申请继承权限。双向记录的单边写入不代表绑定完成。
- 普通失败按 reconcile 重试；可靠确认的步骤幂等继续；不确定创建/未知同名对象报告 Conflict。
- Kubernetes status 是持久进度和观察，不是外部事实，也不是 controller 内存。 不引入“status 任意丢失后自动恢复所有权”的附加要求。
分层
| 层 | 责任 |
|---|---|
| 领域 | 值、身份、允许动作、不变量、完成与冲突判定；不做 IO |
| 应用 | 装载记录与事实、协调 API 更新和 adapter、回读、交回领域判定 |
| controller | watch/调度、映射、conditions/status/finalizer；不重写领域规则 |
| adapter | Kubernetes、PostgreSQL、OpenBao、ESO 的具体访问与安全错误分类 |
| 装配 | 客户端与成熟连接池的生命周期，不是领域状态 |
不引入通用 Repository CRUD、跨系统 Unit of Work、事务队列或第二套 phase 存储。 resourceVersion 解决 API 对象并发更新，不宣称 PostgreSQL 与 Kubernetes 原子提交。
API 切片前需明确
- Database 的 scope、引用格式、谁可以预留/绑定/释放，以及绑定字段和更新顺序。
- 资源侧回收策略与 Tenant/Database finalizer 配合。
- 导入时角色/凭据的管理范围，稳定凭据定位、旧使用者撤权及新投射授权。
- 绑定/导入同一实际目标的重复声明如何拒绝，且不引入 registry。
- 管理员确认冲突、解除旧绑定的具体可审计操作入口。
这些细节不阻止已确认的三资源设计，但必须先于对应 API 与生命周期实现获得评审。