docs: 解耦内置 API 与上游实现组件

AGENTS.md

@@ -3,10 +3,36 @@
 - 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。
 - 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。
 - 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。
+- 不要按传统私有云或公有云产品清单推导 Ayatori 应实现的资源。新增北向 API 前必须证明 homelab
+  存在真实、重复的管理缺口，现有成熟 API/IaC 不能提供足够的生命周期、状态或权限体验；“后端
+  能做到”或“其他云平台提供”本身不是产品需求。
+- 当前已确认的首要产品方向是 Database、LoadBalancer、Bucket/Object Storage；VirtualMachine
+  也具有明确价值，但南向实现较重。Run/Job 是验证 controller 与 adapter 的内部执行切片，不应
+  自动演化为 FaaS、Cloud Run 或应用托管产品。KaaS 仅在出现真实需求时评估，不是必达终点。
+- Ayatori 复用 Kubernetes 的核心目标是 API machinery：对象存储与并发控制、list/watch、
+  informer、RBAC、admission、版本化 API 和审计；不要据此推断 Ayatori 是 Kubernetes
+  workload 平台，也不要默认复用 Kubernetes 的调度与数据面语义。
+- 复用 Kubernetes 内置资源只表示采用其 API contract，不表示必须运行或模拟上游实现组件。
+  例如 Ayatori Compute Agent 可以直接实现 `core/v1 Node` 与 Lease 的状态语义，Ayatori
+  controller 可以自行消费 Node；不得仅因使用 Node 推导必须引入 kubelet、Pod、CRI、
+  kube-scheduler 或 kube-controller-manager。对每个复用资源分别明确 producer、consumer、
+  ownership 与实际采用的字段语义。
+- kube-apiserver 是 Ayatori 的 API 与状态协调平面，不是领域调度器。资源的调度、生命周期、
+  故障恢复、垃圾回收和后端收敛由 Ayatori controllers 实现；新增能力前应明确其属于 API
+  machinery、Ayatori 领域控制循环还是外部 backend，避免把职责放错层。
+- Kubernetes、OpenSandbox、Proxmox 等均是 Ayatori 的可替换 backend/executor。除管理组件自身
+  的部署外，不得仅因 controller 运行在 Kubernetes 中，就把原生 Pod、Job、Service、
+  NetworkPolicy、owner reference 或同 namespace 行为作为领域 API 的隐含语义；需要这些能力时
+  必须由 adapter 契约显式表达，并考虑后端位于其他集群或完全不是 Kubernetes 的情况。
+- 不要以减少自有 controller 数量为目的引入 generic-apiserver、聚合 API Server 或自行实现
+  API Server。只有 CRD/kube-apiserver 在存储、API 语义或扩展能力上形成已验证的阻碍时，才评估
+  接管 watch、RBAC、版本兼容和存储迁移等复杂度；controller 工作本身不会因此消失。
 - 在自行设计通用控制循环、资源生命周期、调度、回收或故障恢复机制前，先调查 Kubernetes
   核心及成熟开源 controller/operator 的实现；优先复用经过验证的模式，并记录有意偏离的
   理由。
 - 不要引入统一包装所有能力的 Application CRD；应用应直接组合正交的平台资源。
+- Proxmox VM 的北向管理不能假定单一 API 覆盖完整生命周期。允许按能力组合 Proxmox API、节点
+  上的受限强类型 Agent/CLI 操作和 ManualTask；节点 Agent 不得退化为无版本契约的任意远程 shell。
 - 所有 controller 必须考虑幂等、observe、finalizer、conditions、删除策略和恢复行为。
 - Ayatori 会联动 Kubernetes API、虚拟化、存储、网络及其他外部控制面；集成测试是功能完成
   标准的一部分，不得仅凭 fake client 或 mock 测试宣告 controller、adapter 或生命周期变更完成。

README.md

@@ -28,11 +28,13 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube
 - [执行模型](docs/concepts/execution-model.md)
 - [环境与发布](docs/concepts/environments.md)
 - [路线图](docs/roadmap.md)
-- [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md)
+- [ADR-0001：采用 Kubernetes API machinery 作为状态协调平面](docs/decisions/0001-kubernetes-api-machinery.md)
 - [ADR-0002：采用 k0s 与可选工作负载运行时](docs/decisions/0002-k0s-optional-workload-runtime.md)
 - [ADR-0003：直接连接 Dev API 的开发循环](docs/decisions/0003-dev-api-development-loop.md)
+- [ADR-0006：按实际管理缺口扩展资源 API](docs/decisions/0006-demand-driven-resource-scope.md)
 
 ## 当前状态
 
-Ayatori 处于设计与早期实现阶段。第一个纵向切片计划是统一 Job API 与 Kubernetes
-Pod executor，随后接入 OpenSandbox executor。
+Ayatori 处于设计与早期实现阶段。当前使用 Job controller 验证第一个完整控制循环与 adapter
+边界；它不是通用 Job Service 或 FaaS 产品承诺。首批实际产品方向是 Database、LoadBalancer
+和 Bucket/Object Storage，具体顺序按纵向价值决定。

docs/architecture/overview.md

@@ -4,9 +4,11 @@
 Git / CLI / Backstage
           │
           ▼
- Kubernetes API + CRD
+ kube-apiserver + etcd + CRD
+   API / state coordination plane
           │
-   Ayatori controllers
+   Ayatori controller-manager
+ scheduling / lifecycle / recovery / GC
           │
    ┌──────┼──────────────┐
    │      │              │
@@ -19,6 +21,20 @@ Terraform            OpenBao / DNS / KaaS
 Ansible
 ```
 
+Ayatori 复用 Kubernetes 的 API machinery，而不是 Kubernetes 的容器编排产品边界。
+kube-apiserver 提供版本化对象、并发控制、list/watch、RBAC、admission 和审计；Ayatori
+controller-manager 承担所有领域控制循环。Kubernetes workload 集群只是与 OpenSandbox、
+Proxmox 等并列的 executor/backend，不默认等于运行 controller 的 management environment。
+
+因此，领域 API 不得依赖“资源最终一定变成同集群原生对象”的假设。原生 Pod、Job、Service、
+NetworkPolicy、namespace 共置与 owner reference 只有在 Kubernetes adapter 内才具有原生含义；
+跨后端所需能力必须由领域模型显式定义。
+
+内置 API 类型也按相同原则选择性复用。采用 `core/v1 Node` 作为计算节点 API 时，可以由
+Ayatori Compute Agent 写入状态、由 Ayatori 自有调度 controller 消费；这不会引入 kubelet、
+Pod 或 kube-scheduler。API contract、负责实现它的 controller/agent 和数据面是三个独立决策，
+不得从其中一个自动推导另外两个。
+
 ## 控制面
 
 Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以
@@ -34,16 +50,16 @@ Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与
 
 ## 资源分层
 
-平台提供正交产品能力，例如：
+平台只为已经验证的管理缺口提供正交产品能力。当前优先资源为：
 
-- `Job`、`Sandbox`、`ManualTask`
-- `VirtualMachine`
 - `LoadBalancer`
 - `Database`
 - `Bucket`
-- `DNSRecord`
-- `Credential`
-- `KubernetesCluster`
+- `VirtualMachine`
+
+`Run`/当前实验性的 `Job`、`ManualTask` 等可以作为控制面执行原语，但不是因为底层能运行 OCI
+image 就自动成为面向使用者的计算产品。`DNSRecord`、`Credential`、`KubernetesCluster` 等只在
+出现独立生命周期和真实消费者后加入；尤其 KaaS 不是预定终点。
 
 只有具备独立领域生命周期的能力才应成为高阶资源。应用本身通过 GitOps 组合上述资源，
 重复组合可通过模板或 Composition 表达，而不是扩展中央 Application API。
@@ -56,5 +72,17 @@ Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与
 2. 通过固定版本的 Terraform module 或 Ansible playbook 执行。
 3. 仅在必要时使用 GitOps bridge。
 
+Proxmox 是已知例外：其远程 API 不能覆盖所需的完整 VM 生命周期。VirtualMachine adapter 可以
+按操作能力选择 Proxmox API、部署在节点上的受限强类型 Agent/CLI，或生成 `ManualTask`。Agent
+必须提供版本化操作、幂等查询、operation ID 与审计，不能暴露任意 shell，也不能把 CLI 输出
+直接当作长期稳定协议。
+
 Controller 无论采用哪种执行方式，都必须提供一致的 ownership、conditions、删除语义、
 错误分类和恢复行为。
+
+## API Server 边界
+
+首选 kube-apiserver + CRD，持续复用其成熟的 watch、RBAC、版本化存储和 API 生态。
+generic-apiserver 或聚合 API Server 不会减少领域 controller 的数量，只会把资源服务端、
+兼容性和存储迁移责任转移给 Ayatori。只有 CRD 的限制已经形成可复现、不可通过合理领域建模
+解决的阻碍时，才重新评估自建 API Server。

docs/decisions/0001-kubernetes-api-machinery.md

@@ -1,4 +1,4 @@
-# ADR-0001：采用 Kubernetes API 作为资源模型
+# ADR-0001：采用 Kubernetes API machinery 作为状态协调平面
 
 - 状态：Accepted
 - 日期：2026-09-17
@@ -10,16 +10,49 @@ homelab 的基础设施状态分散在多套工具和后端中。仅集中 IaC
 
 ## 决策
 
-Ayatori 使用 Kubernetes API machinery 与 CRD 表达平台资源、引用和状态，但不将平台
-限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外
-的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
+Ayatori 使用 kube-apiserver、etcd、Kubernetes API machinery 与 CRD 构成 API 和状态协调
+平面。主要复用的是以下难以可靠重建的能力：
+
+- 版本化对象 API、schema、defaulting、validation 与 admission；
+- 带 `resourceVersion` 的乐观并发、list/watch 与断线恢复；
+- informer/cache/workqueue 生态；
+- authentication、RBAC、namespace、审计与 API discovery；
+- spec/status、conditions、finalizer 等控制面约定。
+
+这项选择不把 Ayatori 限定为容器编排系统，也不意味着原生 Kubernetes workload API 是领域
+模型。kube-apiserver 保存期望、引用和观察状态；Ayatori controller-manager 实现平台领域的
+调度、生命周期、故障恢复、垃圾回收和后端收敛。Controller 可以运行于专用 management
+environment，并管理集群外的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
+
+Ayatori 可以选择性复用 Kubernetes 内置资源的 API contract，而不采用其上游实现组件。例如，
+`core/v1 Node` 可以表达计算节点身份、capacity、conditions、labels、taints 和维护状态，由
+Ayatori Compute Agent 更新并由 Ayatori controller 消费；这不要求部署或模拟 kubelet，也不
+要求存在 Pod、CRI、kube-scheduler 或 kube-controller-manager。`Lease`、`Namespace`、
+`Secret`、`ConfigMap`、`Event` 和 RBAC 等资源同样按各自适用的 API 语义独立选择。
+
+复用内置资源前必须明确其 producer、consumer、ownership、采用的字段和未采用的上游语义。
+不能因为 Kubernetes 通常将若干组件一起部署，就把这些实现关系重新带入 Ayatori。
+
+Kubernetes workload 集群与 OpenSandbox、Proxmox 等一样，是通过 adapter 接入的 backend 或
+executor。它可以是远端集群，也可以完全不存在。除 Flux 和 Ayatori controllers 等管理组件的
+部署外，领域 API 不得隐含依赖 controller 所在集群的 Pod、Job、Service、NetworkPolicy、
+namespace 共置或 owner reference 语义；确有需要的能力必须由领域 API 和 adapter 契约显式表达。
 
 GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系和状态的在线控制面；真实后端
 仍是运行事实来源。Controller 负责三者之间持续收敛。
 
+`generic-apiserver` 或 Kubernetes API aggregation 只会让 Ayatori 接管资源的服务端实现，并不会
+替代上述领域 controller。除非 CRD/kube-apiserver 的存储模型、API 语义或扩展边界形成经过验证的
+阻碍，Ayatori 不自行承担 watch、RBAC、API 兼容、存储版本迁移和高可用 API Server 的实现与运维。
+
 ## 结果
 
 - 获得统一声明式 API、watch、RBAC、admission、conditions 和 controller 生态。
+- Ayatori controller-manager 实际承担类似 kube-controller-manager 的领域控制循环职责，必须把
+  reconcile、状态迁移、恢复与后端契约作为产品核心，而不是把它们误交给 kube-apiserver。
+- 原生 Kubernetes workload 对象不能成为所有 adapter 的最低公共语义；Kubernetes 只是其中一种
+  执行后端。
+- 允许由 Ayatori 自己实现合适的内置 API 资源语义；API 类型与上游 controller/runtime 不绑定。
 - 可以把机器与人工执行统一建模为异步控制循环。
 - 必须维护 CRD 版本、conversion、认证、备份和控制面升级。
 - 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。

docs/decisions/0006-demand-driven-resource-scope.md

@@ -0,0 +1,45 @@
+# ADR-0006：按实际管理缺口扩展资源 API
+
+- 状态：Accepted
+- 日期：2026-09-20
+
+## 背景
+
+Ayatori 可以在技术上逐步加入 VM、任务、数据库、负载均衡、对象存储、KaaS、FaaS 与应用
+托管等能力。如果按传统私有云产品目录推进，项目会把后端“能够实现”的能力误当成 homelab
+实际需要的产品，并承担没有消费者的 API、controller、升级和恢复成本。
+
+当前真正反复出现的问题，是 Database、LoadBalancer 和 Bucket/Object Storage 缺少符合本环境
+需求的稳定管理 API。Proxmox VM 也存在明确缺口：远程 API 能力有限，一部分操作只能登录节点
+使用 CLI 完成，因此单靠 Terraform provider 或 Proxmox API 无法覆盖期望生命周期。
+
+当前 `Job` controller 是验证 Kubernetes API machinery、状态机、finalizer、回收和 adapter 边界
+的首个纵向切片。OpenSandbox 和 microVM 可以成为内部执行后端，但这不等于平台需要 Lambda、
+Cloud Run 或其他 FaaS/PaaS 产品。
+
+## 决策
+
+Ayatori 不设置必须完成的云产品清单。新增北向资源必须由现实消费者、重复管理缺口和持续
+reconcile 的明确收益驱动。
+
+当前优先方向是：
+
+1. `Database`；
+2. `LoadBalancer`；
+3. `Bucket` / Object Storage；
+4. `VirtualMachine`，其价值已确认，但实现成本更高。
+
+`Run`/当前实验性的 `Job` 定位为控制面执行原语和架构验证切片，不自动扩展为面向用户的计算
+产品。KaaS 是可能有真实需求的候选能力，但不是必达终点。FaaS、Cloud Run 和应用托管默认不做，
+除非未来以新的需求和 ADR 改变决定。
+
+VirtualMachine controller 对外提供稳定北向 API；南向允许根据操作选择 Proxmox API、节点上的
+受限强类型 Agent/CLI 或 `ManualTask`。节点 Agent 必须提供版本化、幂等、可观察和可审计的操作，
+不能退化为任意远程 shell。
+
+## 结果
+
+- 路线图可以根据当前收益调整，不把技术可行性误作产品承诺。
+- 第一个 Job controller 的实现仍有测试和架构验证价值，但其 API 不约束长期产品形态。
+- VM 被保留为核心高价值方向，同时承认其南向集成不是单一 provider 能解决的问题。
+- 每个新增资源都要独立证明生命周期和管理价值；已有 backend 不自动产生新的产品层。

docs/roadmap.md

@@ -9,49 +9,47 @@
 - 定义 API、conditions、ownership 和 executor 公共约定。
 - 建立不可变制品与 Dev 到 Prod promotion。
 
-## 1. Job Service
+## 1. Controller 纵向验证切片
 
-- 实现最小 `Job` API。
-- Kubernetes Pod executor。
-- 统一日志、退出状态、超时、workspace、cache 与 artifact。
-- 接入 Gitea Actions 和平台内部 IaC 执行。
+- 使用当前最小 `Job` API 验证 watch、状态机、finalizer、取消、TTL、external reference 与
+  backend adapter。
+- Kubernetes executor 不能与 management API client 或同集群 namespace 语义绑定。
+- 验证完成后，将可复用机制收敛为内部 `Run`/execution 能力；不把这一切片扩展为 FaaS、
+  Cloud Run 或通用 Job Service。
 
-## 2. OpenSandbox Executor
+## 2. 首批资源产品
 
-- 通过 OpenSandbox lifecycle 与 execd API 创建、执行和清理 sandbox。
-- 支持强隔离任务、未知代码、嵌套容器和 AI agent。
-- 增加交互式 `Sandbox` API、TTL、endpoint 与 snapshot。
+- `Database`：PostgreSQL database、role、credential 与回收。
+- `LoadBalancer`：Envoy 配置/xDS、健康检查、固定 VIP 与 GoBGP 路由宣告。
+- `Bucket`：SeaweedFS bucket、policy、credential 与删除策略。
+- 按纵向价值选择先后，不为三者预先建立统一 provider 框架。
 
-## 3. Human Executor
+## 3. Human Executor 与延迟自动化
 
 - `ManualTask`、`TaskReport` 和版本化 Runbook。
 - Telegram/Email 通知、领取、提醒和升级。
 - 后端验证与上游 reconcile 恢复。
 
-## 4. LBaaS
+## 4. Compute 与节点生命周期
 
-- Envoy 配置/xDS adapter。
-- 健康检查与 GoBGP 路由宣告。
-- 固定 VIP、listener/backend 引用和故障恢复。
-
-## 5. Compute 与节点生命周期
-
-- Proxmox VM adapter 与现有资源 adopt。
+- 建立稳定的 `VirtualMachine` 北向 API，并支持现有资源 adopt。
+- 南向按能力组合 Proxmox API、节点受限 Agent/CLI 与 `ManualTask`，不假设 Proxmox API 完整。
 - ComputeNode 加入、drain 和 `SafeToRemove`。
 - StorageClass、StoragePool、Volume 与迁移计划。
-- 先支持人工磁盘迁移，再通过 Job executor 自动化。
+- 先支持人工磁盘迁移，再按实际收益自动化。
 
-## 6. 数据服务
+## 5. 条件性扩展
 
-- PostgreSQL database/role/credential。
-- SeaweedFS bucket/policy/credential。
-- DNS 与证书资源。
+- OpenSandbox/microVM 可以作为内部 Run backend，但不由此产生 FaaS 产品承诺。
+- DNS、证书和 Credential 只有在跨系统协调收益明确时形成独立资源。
+- KaaS 只有出现托管控制面、租户隔离或频繁集群生命周期的真实需求时才立项。
 
-## 7. KaaS
+### KaaS 候选方案
 
 - 采用成熟 hosted-control-plane 后端。
 - 组合控制面、worker、LB、DNS、网络和凭据。
 - 用户集群只暴露 worker node，控制面完全由平台托管。
+- 本节记录候选实现边界，不构成路线图承诺。
 
 ## 首个业务里程碑
 

docs/vision.md

@@ -29,6 +29,20 @@ Ayatori 是具有产品质量的内部平台，而非初期即面向公众的通
 平台允许对当前环境形成明确意见：Proxmox、OpenSandbox、Envoy、GoBGP、OpenBao、
 PostgreSQL、SeaweedFS、Samba AD DNS、Cloudflare 和 Flux 都可以是已知实现。
 
+Ayatori 不以补齐传统私有云或公有云的产品目录为目标。一个资源只有同时满足以下条件，才进入
+北向 API：
+
+1. homelab 存在现实消费者和重复需求；
+2. 现有后端 API 或 IaC 无法提供足够的管理体验；
+3. 持续 observe/reconcile 明显优于一次性自动化；
+4. 统一生命周期、状态、组合或权限能产生可验证的收益；
+5. 收益足以承担长期 API 兼容、controller 和恢复测试成本。
+
+当前最明确的管理缺口是 Database、LoadBalancer 与 Bucket/Object Storage。VirtualMachine 同样
+具有明确价值：Proxmox 的 API 不能覆盖所需的全部生命周期，一部分操作必须在节点上通过 CLI
+完成，因此 Ayatori 可以提供稳定北向 API，并在南向组合 Proxmox API、受限节点 Agent 与人工
+任务。KaaS 只有在出现托管控制面的实际需求时才进入实现，不是产品路线的必达终点。
+
 ## 非目标
 
 - 不替代 hypervisor、microVM runtime、数据库、对象存储或网络协议栈。
@@ -36,3 +50,5 @@ PostgreSQL、SeaweedFS、Samba AD DNS、Cloudflare 和 Flux 都可以是已知
 - 不以隐藏全部后端信息或制造虚假多云可移植性为目标。
 - 不创建理解所有应用需求的中央 Application controller。
 - 不要求所有人工步骤立即自动化。
+- 不因为已有 Run、OpenSandbox 或 microVM backend，就构建 FaaS、Cloud Run 或应用托管产品。
+- 不预先承诺 KaaS；它是需求驱动的候选能力。