记录 Ayatori 控制面架构边界

architecture/ayatori-control-plane.md

@@ -0,0 +1,29 @@
+---
+title: Ayatori 控制面边界
+last_reviewed: 2026-09-20
+---
+
+# 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 契约明确表达。
+
+当前选择继续使用 kube-apiserver + CRD。generic-apiserver 或聚合 API Server 不会替代领域
+controller，只会让项目额外接管资源服务端、watch、RBAC、API 兼容和存储迁移责任。只有 CRD
+或 kube-apiserver 的限制形成经过验证的阻碍时，才重新评估自建 API Server。
+
+详细设计以 Ayatori 仓库的
+[ADR-0001](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/decisions/0001-kubernetes-api-machinery.md)
+和[总体架构](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/architecture/overview.md)为准。
+本页记录跨 homelab 的稳定边界，不表示 Ayatori 已部署或达到生产可用状态。

architecture/constraints.md

@@ -1,10 +1,12 @@
 # 架构约束索引
 
-审阅日期：2026-09-16。以下是现有仓库明确记录的约束摘要，不是本轮新增的架构决策。
-来源路径相对于 homelab-infra；修改时必须读原文和对应代码，新出现的差异先向维护者确认；[首轮状态对齐](../verification.md)已完成。
+审阅日期：2026-09-20。以下是现有仓库明确记录的约束摘要；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) |
 | 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` |

guides/task-index.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) |