refactor: assemble and reuse Instance dependencies

docs/deployment.md

@@ -25,8 +25,8 @@
 
 ## Controller 配置合同
 
-controller 使用以下 CLI flags。必填项缺失、路径无效或 duration 不为正数时，进程必须
-在启动 manager 前失败；不得等到 reconcile 时才逐个资源报告配置错误。
+controller 使用以下 CLI flags。启动入口加载配置、检查本切片必需项并创建共享依赖，
+配置错误在启动 manager 前失败。外部服务暂时不可用由 reconcile 重试，不阻止进程启动。
 
 | CLI flag | 必填/默认 | 说明 |
 | --- | --- | --- |
@@ -35,16 +35,28 @@ controller 使用以下 CLI flags。必填项缺失、路径无效或 duration
 | `--openbao-auth-mount` | `kubernetes` | Kubernetes auth mount 名称 |
 | `--openbao-auth-role` | 必填 | controller ServiceAccount 对应 role |
 | `--openbao-kv-mount` | `kv` | KV v2 mount；开发可显式用 `secret` |
-| `--openbao-service-account-token-path` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | Kubernetes auth 使用的投射 token 文件 |
 | `--openbao-tenant-base-path` | 默认 `postgresql-tenants` | controller 专属 mount-relative 前缀 |
-| `--external-secret-store-name` | 必填 | controller 创建的 ExternalSecret 固定引用 |
+| `--external-secret-store-name` | Tenant 投射时必填 | controller 创建的 ExternalSecret 固定引用；Instance Ready 不依赖此项 |
 | `--postgresql-ca-bundle-path` | PostgreSQL TLS 模式必填 | 只读 PEM trust bundle，不含私钥 |
 | `--reconcile-timeout` | `30s` | 单轮 reconcile 中外部操作的总期限，必须大于零 |
 
-address 必须是绝对 `http` 或 `https` URL，不允许 userinfo、query 或 fragment，末尾 `/`
-在规范化后移除。mount、auth mount 和 base path 都使用 mount-relative path 语义，不以
-`/` 开头，不含空段、`.` 或 `..`；base path 还不得编码 KV v2 的 `data`/`metadata`
-API 层。生产环境的 `--openbao-address` 必须使用 HTTPS；HTTP 只用于明确的开发 fixture。
+连接地址由 OpenBao SDK 解析，移除末尾 `/`；配置错误不得携带原始地址中的认证信息。
+生产环境使用 HTTPS；HTTP 只用于开发 fixture。consumer URL 的认证信息限制和 Tenant
+派生路径限制由对应输出边界负责，Instance 服务不校验尚未使用的 Tenant 配置。
+Kubernetes auth 使用 SDK 默认的 ServiceAccount token 挂载路径，不单独暴露路径参数。
+
+启动时创建一个共享 OpenBao client 和凭据源，再注入 Instance 服务。凭据源在有读取需求且
+token 即将过期时重新登录；每次登录重新读取投射的 ServiceAccount token。token 被撤销导致
+403 时最多重新认证一次，持续 policy 拒绝仍返回错误。
+
+每个 Instance 首次使用时读取管理 username/password 并创建自己的 PostgreSQL 连接池。
+后续 reconcile 复用连接池和内存中的凭据，不做自动 PostgreSQL 密码轮换。UID、endpoint
+或管理凭据引用改变时释放旧连接并重新装配；只修改 extension allowlist 不重建连接。
+删除 Instance 或 controller 正常退出时关闭连接池；重启后按需重新读取 Bao。
+仅修改 Bao 中原路径的密码不会触发刷新，管理员需要重启 controller 或修改凭据引用。
+
+基础 manager manifest 不携带 OpenBao 地址、role 等环境值。实际部署通过环境专属
+Kustomize overlay 注入上述 args；E2E 由测试 fixture 注入一次性环境配置。
 
 Tenant 路径固定推导为 `<base-path>/<namespace>/<metadata.name>`。namespace/name 都已通过
 Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer

docs/operations.md

@@ -38,6 +38,12 @@ controller 自动重建/纠正。
 修复依赖后让正常 reconcile 自动重试。不要通过删除/重建 CR 规避 Conflict；新 UID 只会
 使已有保留资源继续冲突。
 
+Instance 管理凭据在首次装配连接时读取并缓存在进程内；连接故障重试不会重新读取 Bao
+或自动更换密码。Bao 暂时不可用不会影响已经装配的 PostgreSQL 连接，但会阻止新 Instance
+或新凭据引用的装配。手工更换 Bao 同一路径下的管理密码后，需要重启 controller，
+或将 Instance 改为引用新的凭据路径。修改 endpoint/凭据引用会关闭旧连接并重新装配；
+只修改 allowlist 不会刷新凭据。
+
 ## Retain 后的资源
 
 Retain 删除完成后，database、role、OpenBao record 和 registry 所有权记录仍存在但标记