From ce65a287b7ca467874b130f9fada086539790a6c Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Thu, 17 Sep 2026 16:00:54 +0000 Subject: [PATCH] docs: define Ayatori platform vision --- .gitignore | 16 +++++ AGENTS.md | 10 +++ README.md | 36 +++++++++++ api/.gitkeep | 1 + controllers/.gitkeep | 1 + deploy/dev/.gitkeep | 1 + deploy/prod/.gitkeep | 1 + docs/architecture/overview.md | 60 +++++++++++++++++ docs/concepts/api-design.md | 39 +++++++++++ docs/concepts/environments.md | 24 +++++++ docs/concepts/execution-model.md | 48 ++++++++++++++ .../0001-kubernetes-api-machinery.md | 25 ++++++++ docs/roadmap.md | 64 +++++++++++++++++++ docs/vision.md | 38 +++++++++++ examples/.gitkeep | 1 + executors/.gitkeep | 1 + 16 files changed, 366 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 api/.gitkeep create mode 100644 controllers/.gitkeep create mode 100644 deploy/dev/.gitkeep create mode 100644 deploy/prod/.gitkeep create mode 100644 docs/architecture/overview.md create mode 100644 docs/concepts/api-design.md create mode 100644 docs/concepts/environments.md create mode 100644 docs/concepts/execution-model.md create mode 100644 docs/decisions/0001-kubernetes-api-machinery.md create mode 100644 docs/roadmap.md create mode 100644 docs/vision.md create mode 100644 examples/.gitkeep create mode 100644 executors/.gitkeep diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2ad5e90 --- /dev/null +++ b/.gitignore @@ -0,0 +1,16 @@ +# Build output +/bin/ +/dist/ +/coverage/ + +# Local configuration and credentials +.env +.env.* +*.kubeconfig +*.key +*.pem + +# Editor and OS files +.idea/ +.vscode/ +.DS_Store diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6b33062 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,10 @@ +# Agent Notes + +- 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。 +- 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。 +- 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。 +- 不要引入统一包装所有能力的 Application CRD；应用应直接组合正交的平台资源。 +- 所有 controller 必须考虑幂等、observe、finalizer、conditions、删除策略和恢复行为。 +- Secret、token、kubeconfig 及具体生产凭据不得提交到仓库。 +- `deploy/dev/` 与 `deploy/prod/` 使用相同制品；生产版本只通过 promotion 更新。 +- 内部专用不构成降低测试、版本、恢复、安全和可审计要求的理由。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..339ee13 --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# Ayatori + +> Infrastructure, woven by intent. +> 意図から、インフラを編む。 + +Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kubernetes API +作为统一资源模型，通过薄适配器组合成熟后端，并让机器执行器与人工操作共同推动 +实际状态持续收敛到声明的期望状态。 + +本仓库公开源代码，但当前只面向一个确定的内部环境。它不是通用私有云发行版，暂不 +承诺开箱即用、后端可替换性或面向第三方的兼容性。 + +## 核心原则 + +- 内部专用只缩小需求与兼容范围，不降低软件工程质量。 +- 优先采用可以立即投入使用的成熟后端，不重新实现复杂的数据面。 +- 平台统一入口、策略、组合、状态与生命周期；后端保留领域实现。 +- 应用通过 GitOps 直接组合正交的平台原语，不引入 `ApplicationService` 上帝控制器。 +- Pod、OpenSandbox、Terraform、Ansible 和人都可以成为 executor。 +- 暂时不能自动化的操作必须被建模、追踪并验证，而不是遗落在文档和记忆中。 +- 控制面中断不得破坏已运行的数据面。 + +## 文档 + +- [产品愿景](docs/vision.md) +- [总体架构](docs/architecture/overview.md) +- [API 设计原则](docs/concepts/api-design.md) +- [执行模型](docs/concepts/execution-model.md) +- [环境与发布](docs/concepts/environments.md) +- [路线图](docs/roadmap.md) +- [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md) + +## 当前状态 + +Ayatori 处于设计与早期实现阶段。第一个纵向切片计划是统一 Job API 与 Kubernetes +Pod executor，随后接入 OpenSandbox executor。 diff --git a/api/.gitkeep b/api/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/api/.gitkeep @@ -0,0 +1 @@ + diff --git a/controllers/.gitkeep b/controllers/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/controllers/.gitkeep @@ -0,0 +1 @@ + diff --git a/deploy/dev/.gitkeep b/deploy/dev/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/deploy/dev/.gitkeep @@ -0,0 +1 @@ + diff --git a/deploy/prod/.gitkeep b/deploy/prod/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/deploy/prod/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..fe9655e --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,60 @@ +# 总体架构 + +```text +Git / CLI / Backstage + │ + ▼ + Kubernetes API + CRD + │ + Ayatori controllers + │ + ┌──────┼──────────────┐ + │ │ │ +Machine Human Direct adapters +runner runner │ + │ │ │ +Pod Runbook Proxmox / Envoy / BGP +OpenSandbox PostgreSQL / SeaweedFS +Terraform OpenBao / DNS / KaaS +Ansible +``` + +## 控制面 + +Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以 +共享物理宿主，但不能只依赖 namespace 隔离 cluster-scoped API 与高权限凭据。 + +Proxmox 作为稀缺物理基础设施可以共享，通过 pool、tag、token 和明确的资源范围区分 +环境。其他后端尽量使用独立数据库、角色、地址池、DNS 空间与凭据。 + +## 数据面 + +Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与变更，不应停止已有 VM、 +负载均衡、数据库、对象存储或租户 Kubernetes 集群。 + +## 资源分层 + +平台提供正交产品能力，例如： + +- `Job`、`Sandbox`、`ManualTask` +- `VirtualMachine` +- `LoadBalancer` +- `Database` +- `Bucket` +- `DNSRecord` +- `Credential` +- `KubernetesCluster` + +只有具备独立领域生命周期的能力才应成为高阶资源。应用本身通过 GitOps 组合上述资源， +重复组合可通过模板或 Composition 表达，而不是扩展中央 Application API。 + +## 后端策略 + +优先级如下： + +1. 直接调用成熟且可观察的后端 API。 +2. 通过固定版本的 Terraform module 或 Ansible playbook 执行。 +3. 仅在必要时使用 GitOps bridge。 + +Controller 无论采用哪种执行方式，都必须提供一致的 ownership、conditions、删除语义、 +错误分类和恢复行为。 diff --git a/docs/concepts/api-design.md b/docs/concepts/api-design.md new file mode 100644 index 0000000..b5902b5 --- /dev/null +++ b/docs/concepts/api-design.md @@ -0,0 +1,39 @@ +# API 设计原则 + +## 合理抽象 + +API 应当比后端简单，但不能剥夺自用场景真正需要的控制力。 + +- 用户主动做出的资源决策进入产品 API。 +- 平台稳定的运维策略进入 Profile、Class 或 Policy。 +- 能够稳定推导的机械参数由 adapter 生成。 +- 罕见但合理的特殊需求使用受控 override。 +- 解析结果、外部 ID 和后端摘要通过只读 status 展示。 + +例如 VM 用户可以指定 CPU、内存、磁盘、存储、镜像和逻辑网络；QEMU machine type、 +cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。 + +## 不做虚假可移植性 + +允许 API 表达当前真实后端的有用能力，但不接受任意 `rawConfig` 透传。未来出现第二个 +真实实现时，根据已经观察到的共同语义抽象，而不是预先猜测最低公分母。 + +## 引用与依赖 + +- 使用 typed reference 表达资源依赖，不复制动态地址和外部 ID。 +- 被引用资源暂时不存在或未 Ready 时，controller 应等待而不是要求 apply 顺序。 +- 长期依赖通过 API 关系推导；Flux `dependsOn` 只用于确实需要的提交顺序。 + +## 生命周期基线 + +所有受管资源必须定义： + +- `observedGeneration` +- 结构化 `status.conditions` +- ownership 与外部资源标识 +- finalizer 与删除策略 +- import/adopt/observe 行为 +- controller 重启后的恢复行为 +- 可重试错误与需要人工介入错误的区别 + +对数据库、bucket、持久磁盘等资源，默认删除行为必须保守并显式表达。 diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md new file mode 100644 index 0000000..ffd97d0 --- /dev/null +++ b/docs/concepts/environments.md @@ -0,0 +1,24 @@ +# 环境与发布 + +Ayatori 从第一天维护 Dev 与 Prod 两套控制面，因为首个稳定产品能力会立即承载真实服务， +同时后续能力仍需要破坏性集成测试。 + +```text +source commit + ↓ +immutable artifact + ↓ +Dev deployment + integration tests + ↓ +promotion review + ↓ +Prod deployment of the same artifact +``` + +不维护长期漂移的环境分支。Git 中分别声明 Dev 与 Prod 当前采用的不可变制品版本或 digest。 + +Dev 应连接真实后端，但使用独立身份、地址空间和资源范围。Dev 凭据在后端权限层面不应 +具备修改 Prod 资源的能力。 + +当前手工管理的基础设施视为 legacy 数据面，由 Prod 逐项 import/adopt 或替换；它不是 +第三套 Ayatori 控制面。 diff --git a/docs/concepts/execution-model.md b/docs/concepts/execution-model.md new file mode 100644 index 0000000..c353b1c --- /dev/null +++ b/docs/concepts/execution-model.md @@ -0,0 +1,48 @@ +# 执行模型 + +Ayatori 将执行者统一视为具有不同能力与延迟特性的 executor。 + +```text +Action +├── Machine executor +│ ├── Kubernetes Pod +│ ├── OpenSandbox +│ ├── Terraform +│ └── Ansible +└── Human executor + └── Versioned Runbook +``` + +## Job 与 Sandbox + +`Job` 表达一次有限时长、有退出结果的批处理。第一执行后端是 Kubernetes Pod，第二 +执行后端通过 OpenSandbox API 获得强隔离环境。调用者表达资源、隔离与 capability +需求，由调度策略选择后端。 + +`Sandbox` 表达带 TTL 的交互环境，可提供 shell、文件、快照或临时 endpoint。它与 +`Job` 共享镜像、资源、网络、凭据和回收能力，但具有不同生命周期，不合并为带大量 +互斥字段的上帝资源。 + +## 人工执行 + +无法自动化的步骤使用 `ManualTask` 建模： + +```text +Pending → Claimed → InProgress → Reported → Verifying → Succeeded +``` + +通知 controller watch 待处理任务，并发送到 Telegram、Email 或 UI。人依据绑定版本的 +Runbook 操作后提交 `TaskReport`；人只报告执行结果，不直接宣告系统状态成功。 + +验证 controller 必须 observe 后端并验证证据，验证成功后更新 status，上游 reconcile +自然继续。人工步骤因此是高延迟异步处理，而不是控制面之外的黑洞。 + +## 自动化演进 + +人工任务未来可以替换为机器 Job，但上游工作流不应改变： + +```text +executor: Human → executor: Job +``` + +平台优先做到任务可建模、可通知、可追踪、可验证和可恢复，再逐步降低人工参与。 diff --git a/docs/decisions/0001-kubernetes-api-machinery.md b/docs/decisions/0001-kubernetes-api-machinery.md new file mode 100644 index 0000000..4091c69 --- /dev/null +++ b/docs/decisions/0001-kubernetes-api-machinery.md @@ -0,0 +1,25 @@ +# ADR-0001：采用 Kubernetes API 作为资源模型 + +- 状态：Accepted +- 日期：2026-09-17 + +## 背景 + +homelab 的基础设施状态分散在多套工具和后端中。仅集中 IaC 文件不能提供持续观察、依赖 +关系、异步状态、漂移纠正和人工任务协调。 + +## 决策 + +Ayatori 使用 Kubernetes API machinery 与 CRD 表达平台资源、引用和状态，但不将平台 +限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外 +的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。 + +GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系和状态的在线控制面；真实后端 +仍是运行事实来源。Controller 负责三者之间持续收敛。 + +## 结果 + +- 获得统一声明式 API、watch、RBAC、admission、conditions 和 controller 生态。 +- 可以把机器与人工执行统一建模为异步控制循环。 +- 必须维护 CRD 版本、conversion、认证、备份和控制面升级。 +- 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。 diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..d2a1d79 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,64 @@ +# 路线图 + +路线图按能够立即产生价值的纵向切片推进，而不是先构建完整通用框架。 + +## 0. 平台基础 + +- 建立 Dev 与 Prod API/control plane。 +- 建立认证、RBAC、OpenBao 凭据和备份恢复。 +- 定义 API、conditions、ownership 和 executor 公共约定。 +- 建立不可变制品与 Dev 到 Prod promotion。 + +## 1. Job Service + +- 实现最小 `Job` API。 +- Kubernetes Pod executor。 +- 统一日志、退出状态、超时、workspace、cache 与 artifact。 +- 接入 Gitea Actions 和平台内部 IaC 执行。 + +## 2. OpenSandbox Executor + +- 通过 OpenSandbox lifecycle 与 execd API 创建、执行和清理 sandbox。 +- 支持强隔离任务、未知代码、嵌套容器和 AI agent。 +- 增加交互式 `Sandbox` API、TTL、endpoint 与 snapshot。 + +## 3. Human Executor + +- `ManualTask`、`TaskReport` 和版本化 Runbook。 +- Telegram/Email 通知、领取、提醒和升级。 +- 后端验证与上游 reconcile 恢复。 + +## 4. LBaaS + +- Envoy 配置/xDS adapter。 +- 健康检查与 GoBGP 路由宣告。 +- 固定 VIP、listener/backend 引用和故障恢复。 + +## 5. Compute 与节点生命周期 + +- Proxmox VM adapter 与现有资源 adopt。 +- ComputeNode 加入、drain 和 `SafeToRemove`。 +- StorageClass、StoragePool、Volume 与迁移计划。 +- 先支持人工磁盘迁移，再通过 Job executor 自动化。 + +## 6. 数据服务 + +- PostgreSQL database/role/credential。 +- SeaweedFS bucket/policy/credential。 +- DNS 与证书资源。 + +## 7. KaaS + +- 采用成熟 hosted-control-plane 后端。 +- 组合控制面、worker、LB、DNS、网络和凭据。 +- 用户集群只暴露 worker node，控制面完全由平台托管。 + +## 首个业务里程碑 + +完成 Laptop Rebuild Readiness： + +1. 临时节点加入。 +2. laptop 上的 workload 被重建、迁移或形成可执行人工任务。 +3. laptop 达到 `SafeToRemove=True`。 +4. laptop 重装并重新加入。 +5. 临时节点排空并安全退出。 diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 0000000..2109cb0 --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,38 @@ +# 产品愿景 + +## 问题 + +当前 homelab 的期望状态散落在 Kubernetes manifests、Terraform state、Ansible、 +Proxmox、libvirt、OpenBao、DNS、对象存储以及人工文档中。即使每一部分分别实现 +IaC，跨系统变更仍需要人工安排顺序、复制状态并确认结果，容易产生遗漏、错误和漂移。 + +文档不能成为运行状态的权威来源：它只能解释设计和操作背景，无法持续观察现实并纠偏。 + +## 目标 + +Ayatori 提供统一、声明式、可组合的基础设施 API： + +1. Git 保存经过 review 的长期期望状态。 +2. Kubernetes API 保存当前意图、资源关系与状态摘要。 +3. Controller 将请求翻译给成熟后端，并持续 observe/reconcile。 +4. 机器和人通过统一任务协议执行动作。 +5. 后端保存实际运行状态，数据面在控制面不可用时继续工作。 + +平台成功的直接标准是：新增 workload 时，使用者只需考虑它需要哪些资源，而不再回忆 +需要依次修改哪些系统、文件和文档。 + +## 产品定位 + +Ayatori 是具有产品质量的内部平台，而非初期即面向公众的通用私有云。源码公开不等于 +承担未知部署环境、任意后端和第三方兼容性的成本。 + +平台允许对当前环境形成明确意见：Proxmox、OpenSandbox、Envoy、GoBGP、OpenBao、 +PostgreSQL、SeaweedFS、Samba AD DNS、Cloudflare 和 Flux 都可以是已知实现。 + +## 非目标 + +- 不替代 hypervisor、microVM runtime、数据库、对象存储或网络协议栈。 +- 不从第一天构建通用 provider/plugin ABI。 +- 不以隐藏全部后端信息或制造虚假多云可移植性为目标。 +- 不创建理解所有应用需求的中央 Application controller。 +- 不要求所有人工步骤立即自动化。 diff --git a/examples/.gitkeep b/examples/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/examples/.gitkeep @@ -0,0 +1 @@ + diff --git a/executors/.gitkeep b/executors/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/executors/.gitkeep @@ -0,0 +1 @@ +