记录内置 API 与实现组件解耦原则

architecture/ayatori-control-plane.md

@@ -0,0 +1,41 @@
+---
+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 契约明确表达。
+
+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 只有出现实际需求时才评估，不是
+产品路线的必达终点。
+
+详细设计以 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 已部署或达到生产可用状态。

architecture/constraints.md

@@ -1,10 +1,14 @@
 # 架构约束索引
 
-审阅日期：2026-09-16。以下是现有仓库明确记录的约束摘要，不是本轮新增的架构决策。
+审阅日期：2026-09-20。以下是现有仓库明确记录的约束摘要；Ayatori 条目来自其独立项目的
-来源路径相对于 homelab-infra；修改时必须读原文和对应代码，新出现的差异先向维护者确认；[首轮状态对齐](../verification.md)已完成。
+已接受设计，其余来源路径相对于 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) |
 | 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-16
+last_reviewed: 2026-09-20
 ---
 
 # 按任务查找文档
@@ -10,8 +10,10 @@ last_reviewed: 2026-09-16
 
 | 要做什么 | 先读 | 需要时再读 |
 |---|---|---|
+| 设计或实现 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) |
 | 拉取或发布容器镜像 | [zot](../services/zot.md) | [SPIFFE](../services/spire.md)；S3 后端维护才读 SeaweedFS |
 | 使用 S3 对象存储 | [SeaweedFS](../services/seaweedfs.md) | [OpenBao](../services/openbao.md) |
 | 给应用分配数据库 | [共享 PostgreSQL](../services/shared-postgresql.md) | [计划中的 DBaaS](../services/postgresql-tenant-operator.md) |

services/index.md

@@ -1,6 +1,6 @@
 # 服务总览
 
-审阅日期：2026-09-16。以下覆盖源码工作区 apps/、platform/、infrastructure/ 的一级组件，以及集群入口。
+审阅日期：2026-09-18。以下覆盖源码工作区 apps/、platform/、infrastructure/ 的一级组件，以及集群入口。
 **除旧 VictoriaMetrics Compose 已获授权检查并清理外，其余条目未在本轮现场验证。**
 状态栏区分维护者说明、文档、ticket、配置与现场证据，不提供持续的实时健康判断。
 SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护者说明更新，
@@ -22,6 +22,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 | [marker](marker.md) | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；未附上线记录 | `apps/marker/README.md` | 已有转换示例；部署镜像仍为占位符 |
 | netboot | PXE 与系统安装 | `192.168.10.127` | 有部署及使用记录 | `apps/netboot/README.md` | 已有客户端启动说明 |
 | [netbox](netbox.md) | 网络资产与地址管理评估 | `netbox.ad.ddupan.top` | 记录已部署；评估用途 | `apps/netbox/README.md` | 已有浏览与 Git 修改入口指南 |
+| [nexus](nexus.md) | CI 包代理与统一制品仓库 POC | `nexus.ad.ddupan.top` | 仅有未提交配置，尚未部署验证 | `apps/nexus/README.md` | 先验收 Ansible/Go，再补 OCI 声明式管理与 BuildKit 测试 |
 | [openviking](openviking.md) | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 已有导入、任务查询、检索与原文读取指南 |
 | [ps3netsrv](ps3netsrv.md) | PS3 网络内容服务 | `宿主 TCP 38008；地址未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 已有客户端与内容目录指南 |
 | [seaweedfs](seaweedfs.md) | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 已有客户端读写指南与备份边界说明 |
@@ -51,13 +52,13 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 |---|---|---|---|---|---|
 | cloudflared | 公网 Tunnel 与 DNS | `Cloudflare 边缘配置` | 有现有资源接管记录 | `infrastructure/cloudflared/terraform/README.md` | 明确配置权威位置与服务发布流程 |
 | [dns](lan-dns.md) | 跨视图 DNS 声明 | `records.yml` | LAN 角色已按维护者说明对齐；声明接管范围未重查 | `infrastructure/dns/README.md`、维护者说明 | 同步旧描述；补新增记录流程 |
-| docker | 宿主 Docker 网络管理 | `laptop` | 记录已迁移地址池 | `infrastructure/docker/README.md` | 已有 DN42 与挂载路径约束 |
+| docker | 宿主 Docker 网络管理 | `laptop` | 记录已迁移地址池 | [架构约束](../architecture/constraints.md) 与 IaC | Docker bridge 使用 `172.28.0.0/16`，避免 DN42 |
 | kata-lab | Kata VM 试验环境 | `历史 VMID 147` | 记录 9 月 14 日已销毁 | `infrastructure/kata-lab/README.md` | 保留验证历史，勿当现役 VM |
 | kata-lxc-lab | LXC 内 Kata worker 试验 | `pve2 / 记录地址 192.168.10.128` | 记录 PoC 验证；非正式生产服务 | `infrastructure/kata-lxc-lab/README.md` | 明确与 microVM runner 的职责 |
 | microvm-runner（历史目录名） | 动态 runner 的 homelab 基础设施记录 | 当前项目接口见 [Dynamic Runner](gitea-dynamic-runner.md) | 独立项目已更名并扩展到 Pod/VM，正在积极开发 | `infrastructure/microvm-runner/README.md`、独立项目文档 | 具体启用范围和实现进度以独立项目文档为准 |
 | [oci](oci.md) | 云主机、网络与站点互联 | `OCI ap-osaka-1` | 有恢复、接管与网络实施记录 | `infrastructure/oci/README.md` | 已有登录、站点网络与维护入口 |
 | [openbao](openbao.md) | 秘密管理与内部 CA | `bao.ad.ddupan.top` | 有部署与接管记录 | `infrastructure/openbao/README.md` | 已有登录、取密与运维入口指南 |
-| [proxmox](proxmox.md) | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施；README 混有设计设想 | `infrastructure/proxmox/README.md` | 已有管理入口；历史身份设想与当前原则分开 |
+| [proxmox](proxmox.md) | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施 | `infrastructure/proxmox/ansible/` 与 `README-ha.md` | 已有管理入口；身份与 runner 设计见独立项目 |
 | [samba-ad](samba-ad.md) | AD 身份、域 DNS 与域成员管理 | `dc1 / 192.168.10.5` | 有部署记录；维护者说明 DNS 部分已完成 | `infrastructure/samba-ad/README.md`、[LAN DNS](lan-dns.md) | 已有入域、目录浏览与日常管理入口 |
 
 ## 集群

services/lan-dns.md

@@ -45,16 +45,30 @@ Samba AD → 保留域 DNS 职责，相关配置已完成
 主机通过 DHCP 自动获取 DNS 配置：主 DNS 为 Blocky，副 DNS 为路由器。
 当前知识库以此作为 LAN 客户端配置口径，无需另行进行主机覆盖盘点。
 
+## NEC IX DHCP 地址池
+
+2026-09-14 将主 LAN 动态池从 `192.168.10.10–250` 收窄为
+`192.168.10.128–250`，并为 Buffalo AP（`d4:2c:46:09:07:b0`）固定分配
+`192.168.10.10`。`.251–.254` 保留，尚未分配；不能因为扫描无响应就将其用于新设备。
+DHCP 下发网关 `192.168.10.1`、主 DNS `192.168.10.127`、备用 DNS
+`192.168.10.1`，租期为 4 小时。
+
+地址池修改会清空 NEC IX 当前租约表，但终端可能继续使用旧地址直到续租。
+变更后 Kata LXC 实验节点已续租为 `.128`；迁移其他动态客户端前应先检查活动任务，
+并在续租后分别验证主机网络和其内部 k3s 等服务。地址池及预留段的声明同时维护在
+`apps/netbox/terraform/topology.yml`。
+
+回滚时不能直接恢复整份路由器配置；应先确认 `.10–.127` 没有静态占用，再在 DHCP
+profile 中恢复原范围并移除 AP 固定绑定，保存后重新核对租约、DNS 和 NetBox 声明。
+
 ## 维护入口与待补充范围
 
 以下路径相对于 homelab-infra，保留部署与操作细节的原有归属：
 
 - `apps/blocky/README.md`：Blocky 部署、分流和检查方法。
 - `infrastructure/samba-ad/README.md`：域 DNS 与 Samba 配置。
-- `infrastructure/samba-ad/router-dhcp-nec-ix.md`：路由器 DHCP 记录。
 - `infrastructure/samba-ad/router-dns-nec-ix.md`：路由器 DNS 记录。
 - `infrastructure/dns/README.md`、`records.yml`：跨视图 DNS 声明与所有权。
 
-本次只更新知识库；原工作区中“Blocky 未成为正式 resolver”的旧描述尚待同步。
 路由器自身的更上游和 AD/DN42 条件转发明细未在本次补充，也不因此自动产生核查任务。
 需要进一步查询时，先向维护者确认当前工作和范围，不因旧文档差异直接发起现场检查。

services/nexus.md

@@ -0,0 +1,97 @@
+---
+title: Nexus Repository POC
+lifecycle: experimental
+evidence: configuration
+last_reviewed: 2026-09-18
+last_verified: null
+sources: []
+---
+
+# Nexus Repository POC
+
+Nexus Repository Community Edition POC 计划为一次性 CI runner 提供共享的 Ansible Galaxy、
+Go Modules 与 OCI/BuildKit 缓存，减少每个 job 从公网重新下载依赖的时间。当前只有未提交的
+GitOps 与 Terraform 配置，尚未部署、初始化或完成端到端验证；现役 zot 保持不变。
+
+## 从哪里使用
+
+- 计划入口：`https://nexus.ad.ddupan.top`，仅 LAN。
+- 人类管理：POC 首次使用本地管理员；后续正式化优先使用 Samba AD LDAP。Community
+  Edition 不提供原生 OIDC/SAML，因此不能把 Authelia OIDC 写成已支持入口。
+- CI 读取：目标是对 public/group repository 开放 LAN 匿名只读。
+- CI 发布：目标是少量按信任边界划分的本地 service account，凭据由 OpenBao 保存；
+  当前 POC 尚未创建 publisher 或授予写权限。
+
+不能在整个入口套用 Authelia browser forward-auth：`ansible-galaxy`、Go 和 OCI 客户端
+不会完成浏览器登录。若以后给 UI 单独加 RUT/forward-auth，必须使用与 package API 分离
+且不可绕过的入口，并先完成 Header 信任边界审计。
+
+## 第一次使用
+
+部署与 Terraform 初始化完成后，Ansible 客户端将 Galaxy server 指向：
+
+```ini
+[galaxy]
+server_list = nexus
+
+[galaxy_server.nexus]
+url = https://nexus.ad.ddupan.top/repository/ansible-public/
+```
+
+然后在已有 `collections/requirements.yml` 的项目中运行：
+
+```bash
+ansible-galaxy collection install -r collections/requirements.yml \
+  -p .ansible/collections
+```
+
+预期首次请求从上游获取 collection，第二次在全新 runner 中由 Nexus 返回已缓存内容。
+该预期尚未现场验证；验证时同时记录冷/热耗时和 Nexus 日志，不能只看命令退出码。
+
+Go POC 使用：
+
+```bash
+GOPROXY=https://nexus.ad.ddupan.top/repository/go-public/ go mod download
+```
+
+私有 module 的 `GOPRIVATE`、认证和 fallback 需由实际 workflow 明确配置，不能把内部 module
+路径意外发送到公共 proxy。
+
+## POC 限制
+
+- 单副本、50 GiB OpenEBS RWO PVC，资源上限 2 CPU / 4 GiB。
+- 当前使用 embedded H2，仅用于 POC；正式保存唯一制品前迁移至外部 PostgreSQL。
+- 当前没有独立备份或恢复验收，PVC 不能被视为备份。
+- Terraform provider 已声明 Ansible 与 Go proxy/group；provider 1.17.0 尚未暴露 Nexus
+  3.94 新增的原生 OCI repository resource。
+- OCI 必须在补齐声明式 REST/provider 管理后再测试，不保留仅通过 UI 创建的长期配置。
+- BuildKit registry cache 有待单独验证，普通 OCI image push 成功不能替代该测试。
+
+## 出问题时
+
+先检查 Flux、Pod、PVC、Route 与最近日志：
+
+```bash
+kubectl -n flux-system get kustomization nexus
+kubectl -n nexus get pod,pvc,service,httproute
+kubectl -n nexus logs deployment/nexus --tail=100
+```
+
+首次启动可能持续数分钟。PVC 未 Bound 时先查 OpenEBS；Route 未 Accepted/ResolvedRefs 时查
+Gateway parentRef 与 Service；公网依赖获取失败时区分 Nexus 本身、LAN DNS 和已知不稳定
+WAN，不以重建 PVC 作为排障手段。
+
+## 运维入口
+
+实现入口为 homelab-infra 工作区中尚未提交的 `apps/nexus/` 与
+`clusters/homelab/apps/nexus.yaml`。DNS 期望记录位于 `infrastructure/dns/records.yml`。
+源码 README 维护部署、初始化、Terraform、验收与恢复边界。
+
+部署依赖 Envoy Gateway、OpenEBS 和 LAN DNS；Terraform 管理依赖 Nexus 初始化后的受限管理
+账号及 OpenBao 注入凭据。现阶段不依赖共享 PostgreSQL，正式化时才建立独立数据库与 role。
+
+## 当前状态与证据
+
+2026-09-18 已准备未提交的 Kubernetes、Flux、DNS 与 Terraform POC 配置，并完成本地渲染和
+schema 检查后方可交付；未访问现场、未部署 Nexus、未申请凭据，也未修改或迁移 zot。
+后续状态必须以合并记录、Flux 状态和客户端冷/热缓存验收分别更新，不能仅凭本页推断上线。

services/samba-ad.md

@@ -68,7 +68,20 @@ sudo samba-tool group listmembers YOUR_GROUP
 ## 故障与维护边界
 
 入域失败先区分 DNS/SRV、时间、连通性与账号权限；已有成员认证异常再看信任关系及 winbind。
-`runbook-winbind-rpcd.md` 保存 laptop 文件服务器的相关排障记录，不将该问题直接套用所有成员。
+### Laptop 上的 Winbind RPC 子进程堆积
+
+2026-09-14，`laptop` 的 `winbind.service` 下曾堆积 1677 个 `rpcd_lsad`。现场日志同时显示
+SAMR/LSARPC pipe 断连，以及 AppArmor `samba-rpcd` profile 拒绝
+`/run/samba/ncalrpc/np/samr` 和 `lsarpc` 的写访问。仅重启 winbind 会暂时释放内存，
+但拒绝仍会触发新的 worker，因此不应把重启视为根治。
+
+已在 `/etc/apparmor.d/local/samba-rpcd` 精确允许这两个 pipe 的 `rw` 权限，重载 profile
+并重启 winbind。修复后 `wbinfo -t` 及域/BUILTIN 名称查询通过，短期复测没有新增拒绝；
+该结论只适用于 laptop 的 Samba member，不应套用到 `dc1`。
+
+复发时先采集 `free -h`、`pgrep -xc rpcd_lsad`、winbind cgroup 内存、内核 AppArmor
+拒绝和 Samba 日志，再决定是否重启。不要关闭 AppArmor 或放宽整个目录；出现新路径时
+应按审计日志逐项分析。此规则仍应纳入 `samba_member` Ansible role，避免主机重建后丢失。
 
 静态 DNS 声明入口为 `infrastructure/dns/records.yml`，只管理明确列出的 RRset，
 不清理 Samba 自动维护的域控制器 locator、Kerberos 等记录。