From 36138f835a5ba4a330712e07b1a1f78fb25b320b Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Sun, 20 Sep 2026 20:11:41 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=81=E8=AE=B8=20Database=20?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=97=A0=E5=85=BC=E5=AE=B9=E8=B4=9F=E6=8B=85?= =?UTF-8?q?=E9=87=8D=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../0008-merge-postgresql-tenant-operator.md | 44 +++++++++++++------ 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/docs/decisions/0008-merge-postgresql-tenant-operator.md b/docs/decisions/0008-merge-postgresql-tenant-operator.md index 78f0197..e4568e9 100644 --- a/docs/decisions/0008-merge-postgresql-tenant-operator.md +++ b/docs/decisions/0008-merge-postgresql-tenant-operator.md @@ -13,13 +13,25 @@ Database 是 Ayatori 当前最优先的真实管理缺口之一。继续把该 c 维护 manager、API machinery、发布、认证、可观测性和通用 controller 约定，也会使后续应用组合 必须跨两个控制平面理解状态。 -源仓库当前实现仍在按规格逐片完成，部分生成的 CRD/API 代码落后于批准规范；迁移不能把当前 -工作树或全部脚手架原样复制到 Ayatori。 +截至 2026-09-20，源仓库已经合并 Instance 的 Endpoint、凭据引用、身份/版本、定义与观测目标 +等值对象，以及扩展支持模型和最小生命周期/checkpoint。它们尚未接入实际运行链路。完整 Ready +判定、Kubernetes Secret 管理凭据与连接刷新、应用层/数据库 adapter/controller 接入、CRD 规格 +对齐及集成验证仍未完成；Tenant 的创建、凭据交付与 Retain/Delete 生命周期也未落地。 + +现有运行链路仍是直接读取 OpenBao 管理凭据的旧实现，不能作为新设计已经可用的证据。源仓库 +本地 `feature/instance-extension-observations` 还保留两个未提交文件，用于 Instance 接受扩展观测 +及测试；该工作已暂停，不能作为已合并能力或迁移基线。部分生成的 CRD/API 代码也仍落后于批准 +规范，因此迁移不能把当前工作树或全部脚手架原样复制到 Ayatori。 ## 决策 -PostgreSQL Tenant Operator 合并为 Ayatori 的 Database 领域模块。保留已经批准且仍适用的外部 -行为，不重新发明 database、role、credential、ownership 和删除语义。 +PostgreSQL Tenant Operator 合并为 Ayatori 的 Database 领域模块。保留已经批准且仍适用的安全、 +所有权、幂等与删除行为，不重新发明 database、role、credential 和 registry 语义。 + +当前没有可用发布版本、没有被该 operator 托管的 PostgreSQL 实例或 Tenant，也没有需要在线 +转换的已部署 CR。因此此次合并不承担旧实现兼容性：旧运行链路可以直接撤销，不保留直接读取 +OpenBao 管理凭据的路径，不兼容旧 status checkpoint、samples 或落后于规范的 CRD。API 字段若 +妨碍清晰领域模型、恢复行为或测试，可以在 `v1alpha1` 阶段修改并重新生成。 目标结构遵守 Ayatori 的模块化单体边界： @@ -36,20 +48,23 @@ docs/database/ 最终目录可按 Kubebuilder 与现有模块约定微调，但 Database 不依赖 execution/Job 模块，也不把 PostgreSQL、OpenBao 或 External Secrets 客户端放入共享万能 service/repository 层。 -首轮迁移保留现有 `database.ddupan.top/v1alpha1` API group，避免仅为仓库归属制造无收益的 API -重命名。迁移前逐项核对批准规格与当前 Go types；冲突时以批准规格为基线，并在 Ayatori 中记录 -任何有意改变。数据库尚未实际由该 operator 纳管，因此不需要执行已部署 CRD 的在线 conversion。 +首轮保留现有 `database.ddupan.top/v1alpha1` API group，避免仅为仓库归属制造无收益的名称变化； +这不是对旧字段或行为的兼容承诺。迁移前逐项核对批准规格、领域模型与当前 Go types；冲突时以 +批准规格和代码质量为基线，并在 Ayatori 中记录有意改变。无需实现在线 CRD conversion 或数据迁移。 ## 迁移方式 -1. 等源仓库当前未提交的 Instance 工作形成可引用 commit；迁移期间不读取或复制脏工作树作为 - 权威实现。 -2. 记录 source commit，并先迁移规范、领域模型和纯单元测试；保持行为与测试可追溯。 +1. 以包含已合并 Instance 领域基础和 CI #14 的最新 `main` commit 作为 source reference；记录 + commit，并先提取规范、领域模型和纯单元测试中仍然成立的部分。目标是保留知识与验证，不是 + 逐文件复制旧实现。 +2. 保留源仓库暂停中的脏工作树，不移动、提交或复制两个 extension observation 文件。以后可以 + 先在源仓库形成独立 commit，或在 Ayatori 根据批准合同重新实现，但不得把未提交内容描述为来源。 3. 在 Ayatori multi-group 项目中用 Kubebuilder 注册 Database API，按批准规格迁移 types，重新 生成 CRD、DeepCopy 与 RBAC；不直接复制旧生成文件或旧 `PROJECT`。 -4. 将依赖升级到 Ayatori 当前 Go、Kubernetes 与 controller-runtime 版本，并先迁移 PostgreSQL - registry/adapter contract tests。 -5. 逐片迁移 Instance observe、Tenant provisioning、OpenBao、ExternalSecret、删除与恢复流程； +4. 删除旧运行链路假设，以 Ayatori 当前 Go、Kubernetes 与 controller-runtime 版本重新建立 + application ports 和 adapter contract；先恢复 PostgreSQL registry/adapter contract tests。 +5. 逐片实现 Instance observe、Kubernetes Secret 管理凭据与连接刷新、Tenant provisioning、 + OpenBao、ExternalSecret、删除与恢复流程； 每片必须包含对应单元、envtest 和真实 PostgreSQL/OpenBao 集成测试。 6. Ayatori 中的 Database 模块达到原项目验收标准并完成迁移演练后，冻结旧仓库并将其 README 指向 Ayatori；不同时运行两个 controller 管理同一组 CR。 @@ -62,4 +77,5 @@ PostgreSQL、OpenBao 或 External Secrets 客户端放入共享万能 service/re - Ayatori 获得第一个真实产品领域，而不是继续围绕实验性 Job 扩张。 - 已批准的 DBaaS 设计与测试投资得到保留。 - 单一 manager/release 不意味着领域耦合；Database 仍保持独立 package、adapter 和测试边界。 -- 在源仓库当前并行工作提交前，只进行文档与迁移准备，不移动其代码。 +- 可以从已合并的领域基础开始迁移；旧运行链路和未提交 extension observation 不进入首个切片。 +- 无部署兼容负担允许优先修正 API 和架构，不为尚未使用的旧代码保留技术债。