7 changed files with 177 additions and 16 deletions
@@ -0,0 +1,64 @@
+---
+title: Ayatori 控制面边界
+last_reviewed: 2026-09-24
+---
+
+# Ayatori 控制面边界
+
+Ayatori 是规划和早期实现中的 homelab 基础设施控制平面。它使用 kube-apiserver、etcd、CRD
+和 Kubernetes API machinery 作为版本化 API 与状态协调平面，主要复用对象并发控制、
+list/watch、informer、RBAC、admission、审计和 API 版本机制，而不是复用 Kubernetes 的容器
+编排产品边界。
+
+Ayatori controller-manager 负责领域资源的调度、生命周期、故障恢复、垃圾回收和后端收敛。
+这部分职责近似 Kubernetes 的 controller-manager，但面向 VM、LB、数据库、对象存储、任务、
+托管 Kubernetes 和人工操作等 Ayatori 领域。
+
+Kubernetes workload 集群只是与 OpenSandbox、Proxmox 等并列的 backend/executor，可能位于
+远端，也可能在某个部署 profile 中不存在。除 Flux、Ayatori controllers 等管理组件的部署外，
+领域 API 不得默认依赖同集群 Pod、Job、Service、NetworkPolicy、namespace 共置或 owner
+reference；跨后端能力必须由领域 API 和 adapter 契约明确表达。
+
+Kubernetes 内置资源也只是可选择复用的 API contract，不绑定其传统实现组件。例如 Ayatori
+可以让 Compute Agent 更新 `core/v1 Node` 和 Lease，并由自有 controller 调度 VM，而不部署
+kubelet、Pod、CRI 或 kube-scheduler。每个复用资源都必须单独明确 producer、consumer、
+ownership、采用字段和有意舍弃的上游语义。
+
+当前选择继续使用 kube-apiserver + CRD。generic-apiserver 或聚合 API Server 不会替代领域
+controller，只会让项目额外接管资源服务端、watch、RBAC、API 兼容和存储迁移责任。只有 CRD
+或 kube-apiserver 的限制形成经过验证的阻碍时，才重新评估自建 API Server。
+
+Ayatori 不按传统私有云产品目录建设。当前已确认的首要管理缺口是 Database、LoadBalancer 与
+Bucket/Object Storage；VirtualMachine 同样具有明确价值，但需要组合 Proxmox API、节点受限
+Agent/CLI 和人工任务。当前 Job controller 是控制循环与 adapter 的验证切片，长期只可能收敛为
+内部 Run 能力，不构成 FaaS、Cloud Run 或应用托管承诺。KaaS 只有出现实际需求时才评估，不是
+产品路线的必达终点。
+
+Compute 方向已被记录但延后实施：选择性复用 `core/v1 Node` 与 Lease，由 Ayatori Compute Agent
+实现节点状态并由自有 controller 调度，不引入 kubelet、Pod 或 kube-scheduler。长期 VM 主路径
+可以是普通 Linux 节点上的 libvirt/QEMU；Proxmox 用于 brownfield adopt 和过渡。OpenSandbox/Kata
+microVM 属于 Run/Sandbox 的隔离实现，不因此成为 VirtualMachine 资源。
+
+Database 资源模型于 2026-09-24 明确采用官方 PV/PVC 的资源/申请分离模式：Instance 提供
+管理入口，独立 Database 表示实际资源，Tenant 表示用户申请。Retain 保留资源对象，支持
+人工导入和明确授权后的重新绑定；不维护 PostgreSQL ownership registry，不为创建结果不确定
+提供自动认领保证。详见 [DBaaS 设计](../services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认)。
+
+新增 Kubernetes 资源生命周期前须核对官方设计方式，记录采用与偏离的语义；参考模式不意味着
+部署对应上游组件，也不意味着复制全部字段与抽象。
+
+详细设计以 Ayatori 仓库的
+[ADR-0001](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0001-kubernetes-api-machinery.md)
+、[ADR-0006](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0006-demand-driven-resource-scope.md)
+和[总体架构](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/architecture/overview.md)为准。
+本页记录跨 homelab 的稳定边界，不表示 Ayatori 已部署或达到生产可用状态。
+
+## CI 验证约定
+
+2026-09-24 维护者决定：全量验证自动在 PR 执行，main push 不再重复运行；保留手动入口。
+直接推送 main 不会自动验证，常规变更仍应经 PR；基线有实质变化时需更新分支并重验，
+不能把分支 head 的成功当成任何合并结果的成功。测试项目未减少，不修改分支保护设置。
+配置与边界见 Ayatori
+[f347ee5 的环境文档](https://git.ddupan.top/panxiao81/ayatori/src/commit/f347ee5292ecf39ac0ecbb21e162ee406d8ce382/docs/concepts/environments.md)，
+已随 [PR #9](https://git.ddupan.top/panxiao81/ayatori/pulls/9) 合并 main；合并后未触发重复全量验证。
+这不是整个 homelab 的统一 CI 策略。
@@ -1,10 +1,16 @@
 # 架构约束索引

-审阅日期：2026-09-16。以下是现有仓库明确记录的约束摘要，不是本轮新增的架构决策。
-来源路径相对于 homelab-infra；修改时必须读原文和对应代码，新出现的差异先向维护者确认；[首轮状态对齐](../verification.md)已完成。
+审阅日期：2026-09-24。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
+已接受设计，其余来源路径相对于 homelab-infra。修改时必须读原文和对应代码，新出现的差异
+先向维护者确认；[首轮状态对齐](../verification.md)已完成。

 | 约束 | 原因与边界 | 来源 |
 |---|---|---|
+| Ayatori 复用 Kubernetes API machinery，不复用其容器编排产品边界 | kube-apiserver/etcd 提供 API、watch、RBAC 与状态协调；领域调度、生命周期、恢复和 GC 属于 Ayatori controllers；Kubernetes workload 只是可替换 backend | [Ayatori 控制面边界](ayatori-control-plane.md) |
+| Kubernetes 内置资源不绑定上游实现组件 | 可由 Ayatori Agent/controller 实现和消费 Node、Lease 等 API；使用 Node 不推导必须部署 kubelet、Pod 或 kube-scheduler | [Ayatori 控制面边界](ayatori-control-plane.md) |
+| Ayatori 只为已验证的管理缺口新增北向资源 | 当前优先 Database、LoadBalancer、Bucket/Object Storage；VM 价值已确认但南向较重；Run 是内部切片，KaaS 按需，FaaS/PaaS 默认不做 | [Ayatori 控制面边界](ayatori-control-plane.md) |
+| Ayatori Compute 复用 Node/Lease API，但不引入 Kubernetes workload plane | Compute Agent 实现 Node 状态；libvirt 是长期候选主路径，PVE 是 brownfield 过渡；Kata microVM 属于 Sandbox backend | [Ayatori 控制面边界](ayatori-control-plane.md) |
+| Database 采用独立资源与用户申请分离 | Instance → Database → Tenant；Retain 保留资源并人工回收，显式导入，不维护 PG registry；替代旧所有权持久化合同 | [DBaaS 设计修订](../services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认) |
 | Samba AD、OCI、Proxmox 优先 IaC，以代码为准 | Ansible/Terraform 声明及任务优先于旧 README；声明不等于已验证部署 | 维护者于 2026-09-16 明确、各服务使用指南 |
 | 服务独立部署，Terraform root/state 按服务隔离 | 避免认证和变更影响范围绑在一起 | `AGENTS.md`、`CLAUDE.md` |
 | OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` |
@@ -1,6 +1,6 @@
 ---
 title: 按任务查找文档
-last_reviewed: 2026-09-18
+last_reviewed: 2026-09-20
 ---

 # 按任务查找文档
@@ -10,6 +10,7 @@ last_reviewed: 2026-09-18

 | 要做什么 | 先读 | 需要时再读 |
 |---|---|---|
+| 设计或实现 Ayatori 控制面能力 | [Ayatori 控制面边界](../architecture/ayatori-control-plane.md) | Ayatori 仓库 ADR、对应领域 API 与 adapter 文档 |
 | 发布新的 LAN Web 服务 | [发布新服务](publish-service.md) | [DNS](../services/lan-dns.md)、[Authelia](../services/authelia.md) |
 | 写 CI 或选择 Pod/VM runner | [Gitea / Actions](../services/gitea.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[SPIFFE](../services/spire.md) |
 | 为 CI 缓存 Ansible/Go 依赖 | [Nexus POC](../services/nexus.md) | [Dynamic Runner](../services/gitea-dynamic-runner.md)、[OpenBao](../services/openbao.md) |
@@ -2,7 +2,7 @@
 title: Gitea Dynamic Runner
 lifecycle: experimental
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-21
 last_verified: null
 sources:
  - https://git.ddupan.top/panxiao81/gitea-dynamic-runner/src/branch/main/README.md
@@ -48,13 +48,23 @@ runs-on: [self-hosted, vm]

 | 接口 | 执行方式 | 使用时需要理解的边界 |
 |---|---|---|
-| `pod` | 动态 Kubernetes privileged Pod；workflow 使用 host executor | Docker、BuildKit、kind 等工具由 pipeline 按需 setup；这里的 host executor 指 Pod 内执行环境 |
+| `pod` | 动态 Kubernetes privileged Pod；workflow 使用 host executor | 旧 README 要求 pipeline 按需 setup Docker；Docker 的新约定见下文。host executor 指 Pod 内执行环境 |
 | `vm` | 动态 Cloud Hypervisor microVM | 每个任务创建独立 COW disk、seed 和 TAP，guest runner 执行一个 job 后关机并清理 |

 两种接口不能仅凭“环境一次性”就认定具有相同的隔离边界。
 接入前需要结合项目设计约束和实际部署确认任务的信任范围。
 旧 homelab-infra 文档中的 `kind-microvm` 是早期记录，不作为本项目当前 workflow 接口。

+### Docker 可用性约定更新
+
+维护者于 2026-09-21 明确：CI 后端正在修复，后续由 runner 保证 dockerd 默认可用。
+这取代旧说明中要求业务 workflow 自行启动 Docker daemon 的部分；不能据此推断 BuildKit、
+kind 等其他工具也默认就绪。数据库集成测试不因使用 Docker 而要求 VM。
+消费方 workflow 应检查 Docker 是否可用，而不重复启动 daemon、强制 storage driver 或
+覆盖 runner 提供的 endpoint。[Ayatori #6](https://git.ddupan.top/panxiao81/ayatori/pulls/6)
+正在按此约定调整。此处依据维护者说明，不表示后端修复已经部署或远端集成已经通过，
+`last_verified` 保持不变。
+
 ## 组件如何协作

 当前 README 描述的 bootstrap 路径为：
@@ -75,7 +75,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护

 - [e5renew、research-auto](external-consumers.md)：GitHub 上的外部消费者，不属于 homelab 基础设施；仅保留归属入口。
 - [Gitea Dynamic Runner](gitea-dynamic-runner.md)：正在积极开发的动态 Pod/VM runner，原名 gitea-microvm-runner；具体启用范围、调度和队列约定以项目文档为准。
- [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；README 记录为 API 骨架阶段，不代表服务已上线。
+- [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；现转入 Ayatori Database，采用独立 Database 资源与 Tenant 申请；设计修订不代表服务上线。
 - [workload-sts](../architecture/workload-sts-history.md)：已归档的早期机器身份方案；停止开发、不部署 PoC，由 SPIFFE/SPIRE 替代。
 - Backstage：规划中的服务目录与文档入口；本轮未发现独立部署目录。
 - Keycloak、Casdoor：`archive/` 下有明确退役记录，替代入口为 Authelia。
@@ -2,7 +2,7 @@
 title: PostgreSQL Tenant Operator（计划中的 DBaaS）
 lifecycle: planned
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-24
 last_verified: null
 sources:
  - https://git.ddupan.top/panxiao81/postgresql-tenant-operator
@@ -26,16 +26,77 @@ homelab 资源有限，为每个应用维护一套数据库会浪费资源。绝

 ## 当前进度

-2026-09-16 查阅[项目 README](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/branch/main/README.md)
-与架构文档时，项目记录为 **API 骨架阶段，尚未对 PostgreSQL 或 OpenBao 执行写操作**。
-已批准的设计合同不等于已经实现的功能，本文不表示 DBaaS 已上线。
-项目首页还注明 `config/samples` 保留旧 API 骨架，不能将其直接当作最终使用接口。
+维护者于 2026-09-20 提供的阶段状态如下：
+
+- 已合并 Instance 的 Endpoint、凭据引用、身份/版本、定义与观测目标等值对象；
+- 已合并扩展支持能力模型，以及 Instance 最小生命周期与状态 checkpoint；
+- CI PR #14 已合并：lint/test 使用 Pod runner，e2e 使用 VM runner；当前没有开放 PR；
+- 上述领域基础尚未接入实际运行链路，不能理解为新设计已经可用；
+- 仍缺完整 Ready 判定、Kubernetes Secret 管理凭据与连接刷新、应用层/数据库 adapter/controller
+  接入、CRD 与批准规格对齐及集成验证；
+- Tenant 的完整创建、凭据交付和 Retain/Delete 生命周期仍未完成；
+- 旧运行链路仍包含直接读取 OpenBao 管理凭据的逻辑。
+
+本地暂停在 `feature/instance-extension-observations`，有两个未提交文件，实现 Instance 接收扩展
+观测及其测试。该部分此前只通过领域包 lint，未运行本地测试、未提交、未推送；分支仍基于 #13，
+未包含刚合并的 CI 改动。该工作区必须原样保留，不能作为已合并能力或迁移来源。
+
+已批准的设计合同不等于已经实现的功能，本文不表示 DBaaS 已上线。生成的 CRD/API 与 samples
+仍可能落后于批准规格，不能直接作为最终使用接口。
+
+2026-09-20，维护者决定将该项目合并为 Ayatori 的 Database 领域模块。已批准的规格、领域模型、
+状态机和测试继续作为迁移合同；不会把独立仓库的 manager、生成文件和当前工作树整仓复制。
+首个迁移基线使用包含已合并 Instance 领域基础与 CI #14 的最新 main commit，再按领域层、API、
+adapter 和 controller 的纵向切片进入 Ayatori；暂停中的两个未提交文件不进入首个切片。旧仓库
+在迁移完成并验收前仍是现有设计与代码的来源，本决定不表示 DBaaS 已上线。
+
+维护者同时确认目前没有可用版本，也没有 PostgreSQL 实例或 Tenant 被该 operator 托管。因此
+合并不承担旧运行链路、旧 CRD/status 或数据的兼容责任：直接读取 OpenBao 管理凭据的旧路径可以
+删除，未投入使用且落后于规范的 CRD/samples/实现结构不保留兼容层。
+
+2026-09-20 的迁移决定原要求整体沿用源设计。2026-09-24，维护者明确批准下述资源/申请
+分离修订，替代 registry、自动所有权恢复与原 Retain 合同；管理凭据、TLS、OpenBao/ESO 和
+其他适用安全边界继续保留。这是显式设计修订，不是已完成运行验证。
+
+原 `database.ddupan.top/v1alpha1` API group 也不保留。Ayatori 中的目标 API 使用
+`database.ayatori.ddupan.top/v1alpha1`，并纳入统一的 `api/database/v1alpha1` 与 Database 模块
+结构；由于不存在已部署消费者，不建立 alias 或 conversion 入口。
+
+合并边界记录在 Ayatori PR
+[#3 的 ADR-0008](https://git.ddupan.top/panxiao81/ayatori/src/commit/33fb3ec9725dca8a10f2ad4bcd71cf83413932ee/docs/decisions/0008-merge-postgresql-tenant-operator.md)；
+该决定已于 2026-09-21 合并 main，链接固定到合并版本；设计合并不表示 Database 实现已完成。
+
+## 当前资源模型（2026-09-24 已确认）
+
+参考 [Kubernetes 官方 PV/PVC](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) 的
+资源/申请分离：Instance 是资源来源与管理入口；独立 Database 类似 PV；Tenant 是类似 PVC
+的用户申请。Instance 一对多 Database，每个 Database 同时最多绑定一个 Tenant。
+
+Database 自带 instanceRef，手工登记不依赖 Tenant；动态申请由 Tenant 选择 Instance，
+引用已有 Database 时从资源获取 Instance，不重复声明另一份来源。
+
+Retain 在申请删除后保留 Database 对象和外部数据，进入 Released，等待管理员处理数据、
+旧访问权限和凭据后显式授权重新绑定。已有数据库可由管理员显式登记导入，初始验证不改密、
+不改 owner；发现未知同名资源仍报 Conflict。回收策略位于资源侧，Database 不随 Tenant GC。
+
+撤销 PostgreSQL ownership registry 和任意 status 丢失自动重建所有权的要求。CR 记录持久
+身份、绑定和进度；普通失败幂等重试，无法确认外部创建结果时报告足够人工诊断的冲突。
+不引入 CSI 协议、存储调度或通用 Claim。资源 scope、绑定字段和凭据重新交付协议仍需细化。
+
+本轮依据为维护者设计讨论和 Ayatori 已推送的
+[ADR-0009](https://git.ddupan.top/panxiao81/ayatori/src/commit/6db8a495fb9f8981d336c9e6288253628ab478b6/docs/decisions/0009-database-resource-and-claim.md)、
+[系统规格](https://git.ddupan.top/panxiao81/ayatori/src/commit/6db8a495fb9f8981d336c9e6288253628ab478b6/docs/database/specification.md)。
+registry 实现、迁移与 Instance 初始化依赖已在
+[23a2d81](https://git.ddupan.top/panxiao81/ayatori/commit/23a2d81b5041f8589baab1c234136cd2c701bb06)
+撤除；本地测试与真实 PostgreSQL/API server 集成验证通过，但新三资源链路尚未完成。
+上述设计与撤除已随 [PR #9](https://git.ddupan.top/panxiao81/ayatori/pulls/9) 合并 main，
+合并版本为 `347a667`；不表示三资源链路已实现或部署。见 [同步记录](../verification.md#ayatori-database-设计修订同步)。

 ## 计划中的使用方式

 1. 平台管理员通过 `PostgreSQLInstance` 注册已有 PostgreSQL 实例及管理连接。
-2. 下游以 namespaced `PostgreSQLTenant` 声明所需 database、login owner 和扩展。
-3. controller 校验所有权与冲突，幂等创建凭据、role、database 和授权等资源。
+2. 下游以 namespaced `PostgreSQLTenant` 申请数据库，或显式引用管理员登记的 Database。
+3. controller 建立独立 Database 记录与排他绑定，供应或验证资源；未知同名及不确定创建报冲突。
 4. 应用凭据以 OpenBao KV 为事实来源，由 ESO 投射为 Kubernetes Secret。
   非 Kubernetes 消费者使用提供的 OpenBao API URL，并通过自身授权获取凭据。
 5. ESO 投射成功且应用凭据实际登录成功后，Tenant 才能进入 Ready。
@@ -47,7 +108,8 @@ GitOps、Terraform、kubectl 和未来 Backstage 计划共用这套 Kubernetes A

 - operator 管理实例内的租户资源，不运行 PostgreSQL/OpenBao，也不管理 VM、存储、备份或 OpenBao PKI。
 - 应用密码写入 OpenBao，不进入 CR、Event 或日志；ESO 负责向 Kubernetes 消费者投射。
- 默认删除策略为 `Retain`，删除声明不会默认删除业务数据；显式 `Delete` 需重新校验所有权。
+- Database 默认 Retain；删除 Tenant 保留资源对象与数据，Released 不自动重新分配。
+- 资源侧 Delete 需明确授权、finalizer 与实际管理范围检查，导入不隐含删除或改密授权。
 - 遇到未知 database/role 等资源报告 Conflict，不能自动接管、覆盖或删除；现有数据库迁移需遵循迁移合同。
 - namespace 是 Kubernetes 身份与 RBAC 边界；database/role 名称在一个 PostgreSQL Instance 内仍全局唯一。

@@ -63,5 +125,6 @@ GitOps、Terraform、kubectl 和未来 Backstage 计划共用这套 Kubernetes A
 - [部署](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。本页保留设计定位和带日期的阶段摘要。
+迁移前的具体实现进度仍回到[项目仓库](https://git.ddupan.top/panxiao81/postgresql-tenant-operator)
+查询；迁移后的实现与发布进度转到 Ayatori。后续查询前先向维护者对齐当前工作与 ticket。
+本页保留设计定位和带日期的阶段摘要。
@@ -63,3 +63,20 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom
 - Backstage 为计划中的统一入口，不作为已部署服务记录。

 后续出现新的状态问题时，先向维护者对齐，再按授权范围更新对应服务文档。
+
+## Ayatori Database 设计修订同步
+
+2026-09-24，维护者批准 Instance → Database → Tenant 资源/申请分离，替代原 PostgreSQL
+registry 与自动所有权恢复合同。源仓库设计和 wiki 已同步，Ayatori 设计与 registry 撤除
+已推送到 `feat/database-registry-inspection`；本记录随 wiki 来源同步提交发布。
+registry 撤除通过本地全量测试、lint 及真实 API server/PostgreSQL 集成测试；
+新资源 API 与三资源运行链路未完成，不属于部署或现场验证。
+
+源设计：[6db8a49](https://git.ddupan.top/panxiao81/ayatori/commit/6db8a495fb9f8981d336c9e6288253628ab478b6)；
+代码撤除：[23a2d81](https://git.ddupan.top/panxiao81/ayatori/commit/23a2d81b5041f8589baab1c234136cd2c701bb06)；
+wiki 权威摘要：[DBaaS 设计](services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认)。
+来源链接固定到实现提交；相关设计、registry 撤除与 CI 去重修复已随
+[PR #9](https://git.ddupan.top/panxiao81/ayatori/pulls/9) 合并为
+[347a667](https://git.ddupan.top/panxiao81/ayatori/commit/347a667c0c1737bc4e2703dec5f11358f0425e43)。
+最新 head 的 CI #781 已全部通过；无日志启动失败的 test 单项重试后通过。
+旧仓库固定基线及受保护工作树未修改。