docs: 分离 Database 资源与 Tenant 申请生命周期

docs/database/deployment.md

@@ -1,13 +1,13 @@
 # 部署与配置
 
 > 本页迁入作为 Database 模块的目标部署合同。Ayatori manager flags、manifests 与发布装配尚未
-> 实现；原设计行为保持有效，但当前仓库不能直接按本页完成部署。
+> 实现；当前行为以修订后的系统规格为准，本页不能直接用于部署。
 
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Review |
 | 环境 | homelab Kubernetes + 外部 PostgreSQL/OpenBao |
-| 最后更新 | 2026-09-10 |
+| 最后更新 | 2026-09-24 |
 
 本文定义 v1alpha1 的运行依赖、启动顺序和部署级配置。当前 manifests 尚未实现这些
 配置，示例是后续实现合同，不可直接用于现有脚手架。
@@ -30,8 +30,9 @@
 
 ## Controller 配置合同
 
-controller 使用以下 CLI flags。必填项缺失、路径无效或 duration 不为正数时，进程必须
-在启动 manager 前失败；不得等到 reconcile 时才逐个资源报告配置错误。
+以下是尚待实现的部署配置合同，凭据定位随三资源 API 继续细化。controller 使用这些 CLI flags。
+必填项缺失、路径无效或 duration 不为正数时，进程必须在启动 manager 前失败；
+不得等到 reconcile 时才逐个资源报告配置错误。
 
 | CLI flag | 必填/默认 | 说明 |
 | --- | --- | --- |
@@ -51,9 +52,9 @@ address 必须是绝对 `http` 或 `https` URL，不允许 userinfo、query 或
 `/` 开头，不含空段、`.` 或 `..`；base path 还不得编码 KV v2 的 `data`/`metadata`
 API 层。生产环境的 `--openbao-address` 必须使用 HTTPS；HTTP 只用于明确的开发 fixture。
 
-Tenant 路径固定推导为 `<base-path>/<namespace>/<metadata.name>`。namespace/name 都已通过
-Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer
-address 拼为 `<address>/v1/<mount>/data/<base-path>/<namespace>/<metadata.name>`。
+Tenant 不能选择任意凭据路径。凭据必须能随 Database 保留并安全交付给被授权的新 Tenant；
+原 `<base-path>/<namespace>/<metadata.name>` 定位规则不再直接作为新 API 合同。
+稳定位置与导入关联方式待 API 评审；consumer URL 仍使用无认证信息的 KV v2 API URL。
 
 base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空段、`.`、`..`、
 `data`/`metadata` API 层。ExternalSecret 固定命名为
@@ -61,8 +62,8 @@ base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空
 满足 Kubernetes Secret 名称校验，不限制命名内容，默认与 ExternalSecret 同名。
 
 配置变化不得隐式迁移既有凭据。修改 KV mount/base path 或 consumer address 前必须
-停止 controller、评估现有 Tenant，并走明确迁移；实现应把 mount/base path 视为安装
-身份的一部分并在 registry 留存，以便检测错误配置。
+停止 controller、评估现有 Database 与绑定，并走明确迁移。资源记录应能定位原凭据，
+不能根据新部署参数静默切换；不再使用 registry 保存安装身份。
 
 ## PostgreSQL 管理 role
 
@@ -73,7 +74,6 @@ base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空
 - 创建 database 并指定 owner；
 - 撤销 `PUBLIC` CONNECT、授予租户 role CONNECT；
 - 连接租户 database 并创建实例实际支持、租户申请的 extension；
-- 创建和维护 controller 专属 registry schema/table；
 - `Delete` 时禁止连接、终止目标 database session、删除已验证归属的 database/role。
 
 部分 PostgreSQL 操作天然要求较高权限，尤其终止其他 session 和安装某些 extension。
@@ -90,13 +90,15 @@ data 和 metadata，Delete 必须能永久删除全部版本及 metadata；不
 只读对应管理路径，不能供 Tenant 使用。租户 ESO 身份只读 tenant base path，不得
 读取 PostgreSQL 管理凭据。controller 不创建或修改管理 ExternalSecret／Secret。
 `ClusterSecretStore` 由平台管理员创建，controller 只引用，不创建或修改 Store。
-controller 创建的 ExternalSecret 与 Tenant 同 namespace，并设置 ownerReference；目标
+controller 创建的 ExternalSecret 与 Tenant 同 namespace；其 ownerReference 和 Retain 时的
+保留/清理须与凭据交付协议一起确定，不能把投射关系等同于 Database 的 GC 关系。目标
 Secret 包含固定七键：`username`、`password`、`database`、`host`、`hostaddr`、`port`、
 `sslmode`。
 
 ## Kubernetes RBAC
 
-- controller 可读/写 Instance、Tenant 的 status/finalizer 和 Event。
+- controller 按用例读/写 Instance、Database、Tenant 及其 status/finalizer 和 Event。
+- Database 不设置随 Tenant 级联删除的 ownerReference；导入、预留、回收和重新绑定授权限管理员。
 - controller 可在 Tenant namespace 创建、读取、更新、删除 ExternalSecret，并只读检查
   对应 Secret 是否完成投射。
 - namespace 用户可以管理本 namespace Tenant，但不能管理 Instance、Store、controller
@@ -108,9 +110,9 @@ Secret 包含固定七键：`username`、`password`、`database`、`host`、`hos
 
 ## 升级与回滚
 
-v1alpha1 尚不承诺跨版本转换。升级前备份 CR、PostgreSQL registry 和 OpenBao metadata，
+v1alpha1 尚不承诺跨版本转换。升级前备份 CR/绑定、PostgreSQL 数据与 OpenBao，
 先在隔离 Kind 环境运行 E2E。禁止在同一组 CR 上同时运行两个 controller 版本。若新版本
-在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或 registry schema 迁移时，
+在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或凭据定位迁移时，
 必须先写独立升级规格和回滚步骤。
 
 ## 上线验证