From 641db531a89921ab6aa51e4f8f2141f562d646c0 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Sun, 20 Sep 2026 19:18:12 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=E5=AE=9E=E9=99=85=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E7=BC=BA=E5=8F=A3=E9=99=90=E5=AE=9A=E4=BA=A7=E5=93=81?= =?UTF-8?q?=E8=8C=83=E5=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 ++++ README.md | 6 ++- docs/architecture/overview.md | 17 ++++--- .../0006-demand-driven-resource-scope.md | 45 ++++++++++++++++++ docs/roadmap.md | 46 +++++++++---------- docs/vision.md | 16 +++++++ 6 files changed, 106 insertions(+), 32 deletions(-) create mode 100644 docs/decisions/0006-demand-driven-resource-scope.md diff --git a/AGENTS.md b/AGENTS.md index 5a49f7d..a0c1098 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,12 @@ - 本仓库是 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 的调度与数据面语义。 @@ -20,6 +26,8 @@ 核心及成熟开源 controller/operator 的实现；优先复用经过验证的模式，并记录有意偏离的 理由。 - 不要引入统一包装所有能力的 Application CRD；应用应直接组合正交的平台资源。 +- Proxmox VM 的北向管理不能假定单一 API 覆盖完整生命周期。允许按能力组合 Proxmox API、节点 + 上的受限强类型 Agent/CLI 操作和 ManualTask；节点 Agent 不得退化为无版本契约的任意远程 shell。 - 所有 controller 必须考虑幂等、observe、finalizer、conditions、删除策略和恢复行为。 - Secret、token、kubeconfig 及具体生产凭据不得提交到仓库。 - `deploy/dev/` 与 `deploy/prod/` 使用相同制品；生产版本只通过 promotion 更新。 diff --git a/README.md b/README.md index 759c7ea..896e547 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,10 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube - [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，具体顺序按纵向价值决定。 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 723b03b..61f5b2c 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -45,16 +45,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。 @@ -67,6 +67,11 @@ 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、删除语义、 错误分类和恢复行为。 diff --git a/docs/decisions/0006-demand-driven-resource-scope.md b/docs/decisions/0006-demand-driven-resource-scope.md new file mode 100644 index 0000000..2cdb464 --- /dev/null +++ b/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 不自动产生新的产品层。 diff --git a/docs/roadmap.md b/docs/roadmap.md index d2a1d79..76bedbc 100644 --- a/docs/roadmap.md +++ b/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，控制面完全由平台托管。 +- 本节记录候选实现边界，不构成路线图承诺。 ## 首个业务里程碑 diff --git a/docs/vision.md b/docs/vision.md index 2109cb0..b242298 100644 --- a/docs/vision.md +++ b/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；它是需求驱动的候选能力。