docs: 明确 Ayatori 公共 infra 与领域适配边界

Reviewed-on: #7

architecture/ayatori-control-plane.md

@@ -1,6 +1,6 @@
 ---
 title: Ayatori 控制面边界
-last_reviewed: 2026-09-24
+last_reviewed: 2026-09-25
 ---
 
 # Ayatori 控制面边界
@@ -53,6 +53,19 @@ Database 资源模型于 2026-09-24 明确采用官方 PV/PVC 的资源/申请
 和[总体架构](https://git.ddupan.top/panxiao81/ayatori/src/branch/main/docs/architecture/overview.md)为准。
 本页记录跨 homelab 的稳定边界，不表示 Ayatori 已部署或达到生产可用状态。
 
+## Controller 公共基础设施边界
+
+2026-09-25 维护者确认：OpenBao 认证、客户端及 Kubernetes 读写访问是整个 controller 的
+infra 能力，不属于第一个使用它们的 Database 领域。启动入口统一装配和注入；公共层不反向
+依赖产品领域，也不为复用而增加全局注册中心或统一包装所有后端的 reader/writer。
+优先使用官方 SDK 和 manager 已提供的接口；不同身份与权限范围仍须显式隔离。
+
+领域按用例需要定义 repository，adapter 保留对象映射、凭据格式、路径、冲突与恢复语义。
+例如 Database 七键凭据及 UID 路径不是通用 KV 规则。此次修订纠正原实现把 Bao 认证放在
+Database adapter 的归属，认证方式与部署位置约定不变。源码拆分由
+[PR #13](https://git.ddupan.top/panxiao81/ayatori/pulls/13) 跟踪，尚未合并；实现与详细约定见
+[65c60cc 的总体架构](https://git.ddupan.top/panxiao81/ayatori/src/commit/65c60cca4528bc8bf14783fb7b59922283059c02/docs/architecture/overview.md#进程内依赖边界)。
+
 ## CI 验证约定
 
 2026-09-24 维护者决定：全量验证自动在 PR 执行，main push 不再重复运行；保留手动入口。

architecture/constraints.md

@@ -6,6 +6,7 @@
 
 | 约束 | 原因与边界 | 来源 |
 |---|---|---|
+| Ayatori 公共 infra 与领域 repository 分离 | 连接、认证和官方读写客户端统一装配；领域保留对象映射和业务语义，不引入万能仓储 | [Controller 公共基础设施边界](ayatori-control-plane.md#controller-公共基础设施边界) |
 | 新增监控配置优先使用 ServiceMonitor、PodMonitor、PrometheusRule | VictoriaMetrics Operator 负责转换，避免同一目标/规则维护两套声明；历史 VM 配置按需另行迁移 | 维护者 2026-09-25 明确要求；[基础监控运维](../guides/monitoring-foundation.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) |
@@ -13,6 +14,7 @@
 | Ayatori Compute 复用 Node/Lease API，但不引入 Kubernetes workload plane | Compute Agent 实现 Node 状态；libvirt 是长期候选主路径，PVE 是 brownfield 过渡；Kata microVM 属于 Sandbox backend | [Ayatori 控制面边界](ayatori-control-plane.md) |
 | Database 采用独立资源与用户申请分离 | Instance → Database → Tenant；Retain 保留资源并人工回收，显式导入，不维护 PG registry；替代旧所有权持久化合同 | [DBaaS 设计修订](../services/postgresql-tenant-operator.md#当前资源模型2026-09-24-已确认) |
 | Samba AD、OCI、Proxmox 优先 IaC，以代码为准 | Ansible/Terraform 声明及任务优先于旧 README；声明不等于已验证部署 | 维护者于 2026-09-16 明确、各服务使用指南 |
+| 新建 etcd 按全 homelab 共享基础设施设计，PostgreSQL 为首个消费者 | 替代 PostgreSQL 专属 DCS 定位，避免每个服务重复部署；三成员及消费者 RBAC 隔离已部署，不迁移现有 k3s datastore | [共享 etcd](../services/shared-etcd.md)，维护者于 2026-09-25 明确 |
 | 服务独立部署，Terraform root/state 按服务隔离 | 避免认证和变更影响范围绑在一起 | `AGENTS.md`、`CLAUDE.md` |
 | OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` |
 | Terraform 管 API 配置，Ansible 管主机及不能安全纳管的密钥材料 | 不可读回秘密和根密钥不能靠反复重建实现收敛 | `infrastructure/openbao/README.md` |

guides/monitoring-controllers.md

@@ -0,0 +1,49 @@
+---
+title: 证书、秘密同步与 GitOps 监控
+last_reviewed: 2026-09-25
+---
+
+# 证书、秘密同步与 GitOps 监控
+
+采集与规则由 observability Flux Kustomization 管理，以 ServiceMonitor、PodMonitor 和
+PrometheusRule 声明；VM Operator 转换后交给 vmagent/vmalert。
+通知和静默入口见 [Grafana](../services/grafana.md#从告警进入-grafana)。
+
+## 采集与阈值
+
+| 对象 | 采集 | 告警 |
+|---|---|---|
+| cert-manager controller | ServiceMonitor，:9402，job=cert-manager | Certificate Ready=True 的值为 0 持续 15m；到期不足 7 天且至少 1 天 warning 15m；不足 1 天（含已过期）critical 5m |
+| ESO 三个组件 | PodMonitor，:8080，以各组件名称为 job | ExternalSecret Ready=True 值为 0 持续 10m；ClusterSecretStore 同条件 5m critical |
+| Flux 四个 controller | PodMonitor，:8080，以 controller 名称为 job | 八个已接入 controller job 各自 down 或整个 job 消失 5m warning |
+| Flux 六类对象 | KSM 自定义资源状态 gotk_resource_info | 非暂停对象未 Ready 持续 15m；根 Kustomization 状态指标消失 5m |
+
+controller 存活规则共 8 条，状态与证书规则共 7 条。证书 warning 和 critical 范围互斥。
+采集使用 honorLabels，证书和 Secret 的 namespace/name 是被观测对象，不能覆盖为 exporter 命名空间。
+目前只采集 cert-manager controller；webhook/cainjector 继续依赖通用 workload 健康规则。
+
+Flux 自定义指标覆盖 Kustomization、HelmRelease、GitRepository、HelmRepository、HelmChart、
+OCIRepository。KSM 只增加这些资源与 CRD 发现所需的 list/watch，保留 Kubernetes collectors。
+resource_namespace 保存对象命名空间。suspended=true 排除；默认省略 suspend 仍参与判断。
+OCI 类型 HelmRepository 正常没有 Ready 条件，repository_type=oci 排除；OCIRepository 本身仍检测。
+不以旧 gotk_reconcile_condition 指标编写规则，也不通过告警自动解除暂停或修改配置。
+
+## 排障
+
+- 证书：先查 Certificate conditions，再沿 CertificateRequest、Issuer、Order、Challenge 找原因。
+  本规则只覆盖 cert-manager 管理的证书，不证明实际 HTTPS 入口已经加载新证书。
+- Secret 同步：查 ExternalSecret/ClusterSecretStore conditions 与 ESO 日志，核对 provider 网络、身份和授权；
+  不输出 Secret 内容。旧的成功副本可能仍可用，但不能据此认为后续轮换可靠。
+- Flux：按 customresource_kind、resource_namespace、name 定位对象，查 conditions 与依赖。
+  15m 用于容忍正常升级。主动维护使用暂停或有期限的静默，禁止永久屏蔽失败。
+- 指标缺失：依次看原生监控 CR、转换对象、targets、即时查询和 KSM 的 RBAC/配置日志。
+  up==0 不能发现已移除目标，因此各预期 job 另用 absent 检测；同 job 单副本以外的拓扑缺失仍有盲点。
+
+实现：[PR #160](https://git.ddupan.top/panxiao81/homelab-infra/pulls/160)、
+[OCI 例外 #161](https://git.ddupan.top/panxiao81/homelab-infra/pulls/161)。
+上游依据：[Flux 自定义指标](https://fluxcd.io/flux/monitoring/custom-metrics/)。
+19 个规则语义测试覆盖暂停、缺省 suspend、OCI 例外、证书级别切换及 ESO 状态零值等。
+2026-09-25 现场已确认这 8 个 controller target up，4 个证书到期样本、12 个 Ready Secret 状态样本，
+KSM 已输出 Flux 对象状态。未人为使生产证书过期或中断 Secret 同步；通知链路沿用此前端到端验收。
+
+最终 Flux 应用版本为 `655ca567baa58767fcb6a0fd45c78c1044c2b95f`，KSM HelmRelease Ready。

guides/monitoring-coverage.md

@@ -17,7 +17,12 @@ last_reviewed: 2026-09-25
 具体阈值、降噪边界、声明转换关系与验收方法见 [基础监控与告警运维](monitoring-foundation.md)。
 
 下面的规模、矩阵和盲点保留初轮盘点基线，不能再当作第一批实施后的现状。
-第二批数据库/OpenBao/存储/备份、外部探测和集群外心跳尚未实施。
+第二批已补 [证书、ESO 与 Flux](monitoring-controllers.md) 的 15 条规则，
+以及 [CNPG、NATS 与 SeaweedFS](monitoring-data-services.md) 的 14 条规则和 12 个新采集目标。
+OpenBao 已完成受鉴权 telemetry、ServiceMonitor 与采集不可用规则，维护者人工解封后验收通过；
+并修复快照续期、生成维护前快照及 VM 外副本；随后增加内部健康和独立 node_exporter
+快照失败/新鲜度/指标缺失告警，详见 [维护 runbook](openbao-monitoring-maintenance.md)。
+备份独立验收、NATS consumer 维度、外部探测和集群外心跳仍待补齐。
 
 ## 证据和范围
 

guides/monitoring-data-services.md

@@ -0,0 +1,48 @@
+---
+title: CNPG、NATS 与 SeaweedFS 监控
+last_reviewed: 2026-09-25
+---
+
+# CNPG、NATS 与 SeaweedFS 监控
+
+本批仅增加指标采集与 14 条 PrometheusRule 告警，数据库范围按维护者要求限于 CNPG。
+共享 Patroni PostgreSQL 与 etcd 的变更由对应任务管理。
+
+## 采集与规则
+
+| 服务 | 采集与范围 | 告警 |
+|---|---|---|
+| CNPG shared-db/shared-postgresql | PodMonitor 抓取已有实例 :9187，job=cnpg | exporter/目标不可用 5m critical；PostgreSQL down 2m critical；SQL 采集错误 5m；连接使用率 >80% 10m；非 idle 事务超过 300s 持续 5m |
+| NATS | 沿用 job=nats/nats | JetStream 服务端文件或内存容量 >80% 10m；10m 内慢消费者计数增加并持续 5m |
+| SeaweedFS | ServiceMonitor 仅选择 master/filer/volume 三个服务的 :9327 | 各组件采集不可用 5m critical；volume 可用磁盘 <10% 10m；因磁盘不足限制写入 5m critical；5m 内写失败增加持续 2m |
+
+CNPG 使用内置 exporter，不新增数据库账号、不改数据库实例配置、不执行业务写入。
+连接数按 Pod 汇总数据库与用户，再除以同实例 max_connections；长事务排除普通 idle 连接。
+当前单实例没有复制冗余，不添加必然无法满足的副本告警。本批没有建立或验证备份流程。
+
+NATS 本批是服务端容量，不能代替 Account、stream 限额与 consumer pending/redelivery 监控。
+当前 exporter 未输出这些 consumer 维度，后续需明确 exporter 开关与业务阈值再补。
+慢消费者使用增量，历史累计值不持续触发。
+
+SeaweedFS 排除 filer-client 的重复发现，组件分别使用 seaweedfs-master/filer/volume job。
+只把 isDiskSpaceLow 视为这条只读故障，避免满卷轮转或主动只读造成误报。
+这些指标不证明 S3 请求端到端成功，也不证明副本和异机备份可恢复。
+
+## 使用与故障定位
+
+在 [Grafana Explore](https://grafana.ad.ddupan.top/explore) 选择 VictoriaMetrics，可查询：
+
+```promql
+cnpg_collector_up{job="cnpg"}
+```
+
+预期 CNPG 实例值为 1。告警中的 pod/namespace 对应数据库实例；先看 CNPG Cluster conditions、
+Pod 日志及 PVC，再查连接池和事务。禁止仅为消除告警盲目提高连接上限或终止业务事务。
+NATS 先查服务端配额、保留策略和消费者处理能力；不同 Account 的队列必须分别解释。
+SeaweedFS 先查 volume 文件系统/ZFS 与日志，不能直接删除底层卷文件。
+通知和临时静默见 [Grafana](../services/grafana.md#从告警进入-grafana)。
+
+实现：[PR #160](https://git.ddupan.top/panxiao81/homelab-infra/pulls/160)。
+2026-09-25 现场确认新增 CNPG 与 SeaweedFS 共 4 个 target up，CNPG collector_up=1，
+SeaweedFS 容量指标有当前样本；NATS 沿用已验证采集。新增规则无评估错误。
+测试覆盖连接数聚合、磁盘指标 type 标签匹配及慢消费者历史值；未制造生产数据库/磁盘故障。

guides/openbao-monitoring-maintenance.md

@@ -0,0 +1,264 @@
+---
+title: OpenBao 监控接入维护 runbook
+last_reviewed: 2026-09-25
+---
+
+# OpenBao 监控接入维护 runbook
+
+用于本次 OpenBao 自身指标接入中央监控。2026-09-25 维护者要求现在开始准备维护，
+先完成顺序和 runbook；本文同时保留执行顺序与最终验收，实际完成范围见下方“本次执行状态”。
+建议从明确宣布开始计时预留 30 分钟，实际起止记录 UTC，并注明维护者当地时区。
+
+维护者确认使用人工解封：解封材料保存在 Bao VM，经 GPG 加密，解密私钥由 YubiKey 持有。
+文件确切位置、封装格式以及是否另有残留明文未核实；agent 不搜索或读取这些材料。
+解密、PIN/触摸确认和提交 unseal share 由维护者在自己的终端完成。
+
+## 本次执行状态（2026-09-25）
+
+维护者已确认 YubiKey 解密可用并明确同意进入重启/人工解封交接。
+20:34:42 UTC 应用已校验 telemetry 配置并重启，随后维护者完成 unseal。
+现场确认 initialized=true、sealed=false、health=200、受鉴权 Prometheus metrics=200，
+cluster_id 与维护前一致，匿名 metrics 仍为 403。
+
+停机前已更换失效的快照 token，修正每日续期命令为现场支持的 `bao token renew`（不带 -self）。
+新快照 `openbao-20260925-203149.snap` 为 183334 bytes，VM 外副本保存在管理工作站
+`/home/panxiao81/.local/state/openbao-maintenance/`，权限 0600，SHA-256 一致。
+这是配置维护前的备份核验，不等于完成异机灾难恢复演练。
+快照 service Result=success、timer active；文件只在写入成功后更名，失败不清理旧快照。
+
+metrics policy/role 已按候选源配置应用：实际 vmagent-main SA 登录与 token 续期成功，
+无权读取业务 Secret，测试 token 已撤销。随后已将 `vault_policy.metrics` 与
+`vault_kubernetes_auth_backend_role.metrics` 导入现有 SeaweedFS S3 主远端 state，
+仅针对这两项的 plan 均为 no-op；这不代表整个 Terraform 配置已经全量 zero-diff。
+重启后 ClusterSecretStore 和 12 个 ExternalSecret Ready；monitoring/alertmanager-telegram
+已定向刷新，refreshTime 更新为 20:39:33 UTC，状态 SecretSynced。
+[PR #162](https://git.ddupan.top/panxiao81/homelab-infra/pulls/162) 已合并，Flux 应用
+`834f65494195ba5e139e1fc6ee0221fd705b9656`，vmagent 新 Pod 3/3 Ready。
+Bao Agent 日志确认自动登录成功、token 写入内存卷及首次自动续期成功；up{job="openbao"}=1，
+已观察连续三次 up=1，当前指标可查询，单次抓取约 636 个样本，OpenBaoMetricsUnavailable 规则已加载，无评估错误。
+本次未设置维护静默，无需清理 silence；没有撤销维护者自己的登录会话。
+真实长周期重新登录、快照未来定时运行和独立灾难恢复演练不包含在本次验收内。
+
+以下保留操作顺序和回滚方法；其中“待执行”描述须结合本节判断，不能重复重启。
+
+## 内部健康和快照日常监控
+
+2026-09-25 后续部署未重启 Bao（启动时间仍为 20:34:43 UTC）。真实快照任务
+Result=success、退出码 0，新快照 194598 bytes；VM 指标报告 success=1、textfile scrape error=0。
+Flux 已应用 `7137426e8f5c99ca1514c508501e07c2066dd769`；API 和 VM exporter 两类 target 均为 up，
+快照结果与成功时间已进入 VictoriaMetrics。21:02:27 UTC 六条 OpenBao 规则均 inactive，
+部署初期缺数据 pending 已解除；全栈 108 条规则无评估错误。Ansible 部署后 check mode 零变更。
+本次通过 28 个告警语义场景及 4 个快照脚本测试，未通过制造真实故障验证 Telegram。
+
+[PR #163](https://git.ddupan.top/panxiao81/homelab-infra/pulls/163) 补齐内部健康、健康 gauge 缺失、
+快照失败、快照超时/无成功记录和快照采集失联五条规则；原有受鉴权采集不可用规则保留。
+仍由 ServiceMonitor 和 PrometheusRule 声明。内部 active 判定面向当前单节点，扩容为多节点前需修改。
+
+VM 使用 Ubuntu node_exporter，监听 `192.168.10.8:9100`；没有公共入口，当前 UFW 未启用，
+LAN 地址绑定不是逐来源 ACL。采集标签为 `job=node-exporter,node=bao1`，复用主机内存和文件系统规则。
+textfile 目录 `/var/lib/prometheus/node-exporter/` 只由 root 写入，指标不带 token 或快照内容。
+独立 exporter 在 Bao sealed 或快照 token 失效时仍能报告快照结果。
+
+每日任务失败会记录 result=0，保留旧的最后成功时间；只有完整快照原子更名后才更新成功时间并清理旧文件。
+失败持续 5 分钟为 warning，距最后成功超过 36 小时或没有成功指标持续 15 分钟为 critical；
+exporter 失联、textfile 解析错误、结果指标缺失持续 5 分钟为 warning。
+本地快照成功不等于已复制到独立故障域，更不等于恢复演练通过。
+
+部署和回滚使用独立的 `ansible/monitor-openbao.yml`，只处理 exporter、快照脚本和 timer；
+不改 Bao 服务配置，不轮换 token，不需要再次人工解封。首次部署必须执行一次真实快照建立基线。
+参数、验证命令与回滚边界见
+[源码监控运维说明](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/infrastructure/openbao/MONITORING.md)。
+
+
+
+## 目标、分工与影响
+
+- 执行者：准备配置与采集声明、检查、备份核对、部署、观测和配置回滚。
+- 维护者：确认 GPG 文件与 YubiKey 可用、人工解封；整个重启及回滚期间保持在线。
+- 本次只涉及 telemetry、最小权限采集身份与必要采集/告警，不升级 Bao、不改 seal 类型、
+  不重新初始化、不轮换解封密钥，也不恢复 Raft 数据。
+- 停机或 sealed 期间，秘密读取、动态凭据签发/续租、PKI/ACME 和 Bao 登录不可用。
+  已投射的 Kubernetes Secret 不会因 Bao sealed 自动消失，但 ESO 刷新会失败；
+  不能保证所有依赖应用都无影响，窗口内避免启动依赖新凭据的部署和轮换。
+- Telegram 使用现有挂载 token，预计仍可发通知；维护前核对，不能把“预计”当作保证。
+
+## 顺序与交接点
+
+| 顺序 | 负责方 | 操作和通过条件 |
+|---|---|---|
+| 1，停机前 | 执行者 | 核对版本、运行配置来源、seal 状态和受鉴权 metrics；判断是否真的需要重启 |
+| 2，停机前 | 执行者 | 准备并审查 IaC 差异、采集身份及续期方式、监控 CR 与回滚配置；离线校验通过 |
+| 3，停机前 | 维护者 | 在自己的终端确认 YubiKey 解密路径可用、所需 share 数量可满足，回复“人工解封已就绪” |
+| 4，停机前 | 执行者 | 确认独立 VM 登录/控制台、快照与配置备份、依赖基线；所有恢复材料不依赖运行中的 Bao |
+| 5，T+0 | 双方 | 明确宣布窗口开始，记录时间；只对预期告警设置 30 分钟到期的精确静默 |
+| 6，T+0～5m | 执行者 | 应用已审查配置；若确需重启，只重启一次，确认进程启动及 sealed 状态后立即交接 |
+| 7，T+5～10m | 维护者 | YubiKey 解密并人工 unseal，直到 initialized=true、sealed=false；不向 agent 发送 key |
+| 8，T+10～20m | 执行者 | 验证 Bao 和依赖恢复，再上线/验证受鉴权采集、规则及凭据自动续期/重新登录 |
+| 9，T+20～30m | 双方 | 满足验收则结束窗口；否则停止扩大变更，按下述回滚/故障分支处理 |
+
+时间段是预算，不是自动执行信号。维护者没有完成解封准备时，不执行重启。
+若受鉴权检查表明现有 telemetry 已满足需求，直接完成无需停机的采集接入，不为走流程重启。
+
+## 1. 停机前检查
+
+从能够验证 TLS 的客户端检查，无需登录或解封材料：
+
+```bash
+export BAO_ADDR=https://bao.ad.ddupan.top:8200
+bao status -format=json
+```
+
+记录 initialized、sealed、seal 类型、threshold、版本和节点身份，不从旧初始化示例推断 threshold=1。
+`bao status` 在 sealed 时通常返回退出码 2；不能把这个预期状态当作进程崩溃。
+若已经异常 sealed 或 initialized=false，停止本次常规维护，先定位现有故障，绝不执行 init。
+
+在 VM 上确认服务状态、实际二进制和配置路径，不输出配置中的秘密：
+
+```bash
+sudo systemctl is-active openbao
+sudo systemctl show openbao -p MainPID -p ExecMainStatus
+/usr/local/bin/bao version
+```
+
+仓库默认配置路径 `/etc/openbao/config.hcl`、数据路径 `/opt/openbao/data`；执行前核对现场。
+保持一条已建立的 VM 管理会话，并确认断开后仍能通过独立控制台或既有维护身份恢复访问。
+不要依赖 Bao 在停机期间签发新的 SSH 凭据。
+
+受鉴权请求 `/v1/sys/metrics?format=prometheus`，只记录 HTTP 状态、格式和必要指标名。
+此前匿名请求返回 403，只证明访问受限；模板未显式写 telemetry 也不等于运行时禁用了它。
+鉴权材料只通过受控内存/文件引用传递，不放命令行、Git 或日志。
+
+## 2. 配置与采集准备
+
+如确需显式配置，候选最小变更为：
+
+```hcl
+telemetry {
+  prometheus_retention_time = "5m"
+  disable_hostname = true
+}
+```
+
+采集间隔规划为 30 秒。以上是待审查片段，需按现场版本校验；已有 telemetry 配置应合并，
+不要重复添加。保留 TLS、Raft、seal、认证与现有 listener 设置。
+指标标签和前缀以实际返回为准，不能预先假设所有指标都以 bao_ 开头。
+
+采集身份限定 `sys/metrics` GET 所需 read 能力，先验证权限和实际请求；不要复用 root token，
+也不开放匿名 metrics。明确身份取得、自动续期/重新登录与重启恢复方式后，才认为采集准备完成。
+优先复用现有机器身份机制；若需 agent/proxy，应在窗口前写好最小配置并验证访问边界，
+不在停机后临时决定长期 token 或新增服务架构。
+
+监控声明优先 ServiceMonitor/PodMonitor/PrometheusRule；外部 VM 的发现方式应与最终采集架构匹配。
+HTTPS 使用正确域名/CA，不关闭校验；metrics path 为 `/v1/sys/metrics`，`format=prometheus`
+放 query params，不能把问号串在 path 里。sealed 期间 metrics 不可用，因此还需独立 health/目标缺失检测，
+不能仅靠 Bao 内部指标证明 sealed 状态可被发现。
+
+配置见 [PR #162](https://git.ddupan.top/panxiao81/homelab-infra/pulls/162)，已合并部署，状态以本次执行记录为准。
+使用绑定 monitoring/vmagent-main 的 Kubernetes auth metrics role，由 Bao Agent sidecar 自动登录/续期，
+token 仅存 Pod 内存卷供 vmagent 只读消费。采集用 ServiceMonitor + 外部 Service/Endpoints；
+现有 converter 的 Endpoints 发现保留，EndpointSlice 迁移另行处理。
+role 权限、认证/首次续期与受鉴权 metrics 已验收；未来维护仍须重新核对现场，不只依靠历史记录。
+使用现场版本支持的配置校验方式，先检查对应命令 help；禁止启动第二个 server 验证同一 Raft 数据目录。
+现有 Ansible 写配置会通知 restart，不能把正式 apply 当作无停机预演。
+
+## 3. 回滚材料与维护静默
+
+- 以 root-only 权限备份实际配置，记录原权限/属主和 checksum；备份留在独立可访问的管理位置。
+  不把完整配置贴到聊天或 wiki。
+- 使用已有快照流程核对最近成功快照；必要时在停机前生成一次并检查退出状态、文件大小、校验和和副本可访问性。
+  现有来源为 `openbao-snapshot.service` / timer 与 `/usr/local/bin/bao-snapshot.sh`，先核对现场存在再运行。
+  不打印 snapshot token；快照文件存在不等于恢复演练成功。
+- 记录 ESO ClusterSecretStore 与 ExternalSecret 当前状态、refreshTime，以及代表性认证/PKI 流程的基线。
+- 在 Grafana 选择外部 Alertmanager，仅对 `ClusterSecretStoreNotReady{name="openbao"}` 及已确认受影响的
+  ExternalSecret 精确设置限时静默，记录 silence ID。不要静默全部 critical、Telegram 发送故障或无关服务。
+
+## 4. 重启与人工解封
+
+仅在前置条件全部满足且窗口已明确开始后，由执行者在 VM 执行：
+
+```bash
+sudo systemctl restart openbao
+sudo systemctl is-active openbao
+```
+
+随后检查 `bao status`。服务 active 而 sealed=true 是人工解封流程的预期交接点，
+此时停止自动操作，告诉维护者“Bao 已启动，等待人工 unseal”。
+
+维护者在自己掌控、无录屏/日志采集的终端按既有 GPG 流程解密所需 share，随后使用隐藏输入提示：
+
+```bash
+export BAO_ADDR=https://bao.ad.ddupan.top:8200
+bao operator unseal
+bao status
+```
+
+按现场 threshold 提交足够的不同 share。不要使用 `xargs bao operator unseal`、命令替换或明文参数，
+也不要把解密结果交给 agent。仓库旧初始化示例中的 xargs 方式不用于本次维护。
+加密文件可能是 GPG 文件、base64 包装 share 或初始化 JSON；由维护者按真实格式处理，本文不猜文件路径或格式。
+完成后只回报 sealed=false 与非敏感状态；清理自己产生的临时解密副本/剪贴板，不删除原始加密备份。
+
+## 5. 验收与结束
+
+必须逐项记录结果，不以 systemd active 代替可用性：
+
+1. initialized=true、sealed=false，节点/集群身份未变化，TLS 校验正常；预期 active 节点健康接口成功。
+2. 既有机器身份登录正常；代表性秘密消费/PKI 流程按既有权限验证，结果不输出秘密。
+3. ClusterSecretStore/openbao Ready；窗口前健康的 ExternalSecret 恢复 Ready，并观察一次新的实际刷新。
+   需要加速时选择一个受影响对象触发 reconcile，不把所有 ESO 对象批量强制刷新。
+4. 受鉴权 metrics 返回有效 Prometheus 数据，匿名请求仍被拒绝；中央 target 连续至少三次 up，关键指标有当前样本。
+5. 采集身份续期/重新登录机制验证通过；规则已加载且无评估错误，目标消失/鉴权失败有可识别告警。
+6. 若做临时告警演练，标注维护测试并记录 firing/resolved；没有做真实故障演练时明确注明。
+7. 取消本次 silence，记录窗口实际结束时间、配置 commit/PR、验证与未完成项，更新来源文档。
+
+## 6. 停止与回滚分支
+
+- 新配置校验失败：不应用、不重启，修正候选配置。
+- 重启后进程无法启动：检查有限范围日志，恢复原配置及权限，再启动服务；维护者仍需准备 unseal。
+- 进程已启动但 YubiKey/解密/份额不可用：停止反复重启，维护者处理解封流程。
+  恢复旧配置不会自动解封；若接近窗口截止则按故障处置，不能宣布回滚已恢复。
+- Bao 已恢复，仅采集鉴权/指标失败：优先撤回新增采集配置/身份变更，保持核心服务可用；
+  不为修监控反复重启 Bao。记录监控尚未完成，安排后续修复。
+- 必须恢复原服务配置时：恢复备份、重启、再次人工解封，并重复核心与依赖验收。
+- 本次配置回滚不包含 Raft snapshot restore、清空数据目录、init、rekey 或 seal migration。
+
+## 来源与证据边界
+
+维护者 2026-09-25 确认 VM 保存 GPG 加密解封材料，YubiKey 解密且需人工 unseal。
+本轮已进行只读预检及候选文件准备；没有读取解封材料、替换运行配置、设置静默或执行重启。
+
+### 2026-09-25 停机前预检
+
+- Bao API 与 VM 二进制均为 2.6.1，Shamir threshold/shares 为 1/1，initialized=true、sealed=false。
+- 管理入口为 `ssh [email protected]`，sudo 可用。按维护者明确要求，将管理工作站
+  panxiao81 的 authorized_keys 中两条受信任公钥追加到 VM 的 ansible 用户，保留原公钥，
+  修改前已在该账号 `.ssh/` 备份 authorized_keys；此次是现场授权变更，尚未纳入 cloud-init/IaC。
+- 运行配置未显式设置 telemetry。原配置与候选文件分别保存为 VM root-only 目录
+  `/etc/openbao/maintenance-monitoring-20260925/config.before.hcl`、`config.candidate.hcl`。
+  候选文件通过现场 `bao operator validate-config -config=...`；原运行配置未变。
+  若后续其他任务改动运行配置，必须重新比较后再使用，不能覆盖新改动。
+- 快照服务 9 月 23–25 日日志均为 403，9 月 25 日退出码 2；默认 `/var/backups/openbao`
+  未发现 .snap。尚未证明存在其他有效副本，此项阻止进入重启。
+- 源码快照使用 periodic token，但没有续期步骤。候选补丁增加每日续期、显式 rotate 开关、
+  私有 partial 文件及成功后原子更名；403 的精确原因仍需检查 token 状态，不能直接断言已过期。
+- 当前本地 Bao 管理员会话不可用；受鉴权 metrics、Terraform plan/apply、快照身份恢复待完成。
+- 候选通过 Kustomize、规则检查、server dry-run、Terraform fmt；Agent 只在关闭的本机端口验证
+  解析/启动，未做真实登录。快照模拟测试验证续期失败与写失败不删旧备份，成功才清理保留数量。
+
+源码：[OpenBao 部署与恢复入口](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/infrastructure/openbao/README.md)，
+配置模板与 restart handler 位于同目录 `ansible/roles/openbao/`。
+命令依据：[人工 unseal](https://openbao.org/docs/2.6.x/commands/operator/unseal/)、
+[telemetry 配置](https://openbao.org/docs/2.6.x/configuration/telemetry/)。
+
+### 人工解封准备确认
+
+维护者已在插有 YubiKey 的 working PC 成功验证解密。VM 的 `/home/ansible/unseal.txt`
+包含带 `Unseal Key 1:` 前缀的 base64 GPG 密文；正文不保存其内容。
+实际解封由维护者在 working PC 解密后通过 HTTPS 提交，不能将密文直接当作 unseal key。
+这次验证未执行解封或重启。
+
+随后只读确认：快照 token 的 lookup-self 也返回 403，VM root 没有可用的 Bao CLI 会话。
+需要维护者先登录管理会话，恢复快照身份并完成受鉴权预检后才能进入停机。
+若在 VM 使用 OIDC CLI 登录，应从 working PC 建立
+`ssh -t -L 8250:127.0.0.1:8250 [email protected]`，再在 VM 的 root shell 设置
+`BAO_ADDR=https://bao.ad.ddupan.top:8200` 并运行 `bao login -method=oidc -no-print role=admin`。
+登录网址在 working PC 浏览器打开，账号需符合现有 vault-admins 组约束；不把 token 发给 agent。

guides/task-index.md

@@ -58,3 +58,8 @@ Samba AD、OCI、Proxmox 已明确以 IaC 为准，可直接核对其代码；
 检索、转换或 AI 摘要用于定位原文；结论仍应关联到源码、维护者说明或 ticket。
 工作完成后，将持久使用方法写入服务页，将一次变化留在 commit/PR，动态进度回到原项目 ticket。
 原仓库 README 同步目前按维护者要求暂缓，不将其列为每次任务的前置条件。
+
+- [证书、秘密同步与 GitOps 监控](monitoring-controllers.md)：证书临期、ESO 同步与 Flux Ready 排障。
+- [CNPG、NATS 与 SeaweedFS 监控](monitoring-data-services.md)：数据库连接、消息容量与存储故障。
+
+- [OpenBao 监控接入维护](openbao-monitoring-maintenance.md)：窗口准备、YubiKey 人工解封交接与回滚。

services/index.md

@@ -27,7 +27,8 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 | [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` | 已有客户端读写指南与备份边界说明 |
-| [shared-postgresql](shared-postgresql.md) | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 已有连接、应用接入与共享资源边界指南 |
+| [shared-etcd](shared-etcd.md) | homelab 共享协调与选主存储 | 三个 mTLS endpoints，见服务页 | 三成员已部署并现场验证，experimental | `infrastructure/etcd/README.md` | 原生指标与规则已接入；自动续签已启用；备份/证书年龄告警待补 |
+| [shared-postgresql](shared-postgresql.md) | CNPG 与新 k3s 外共享 PG | 旧 `shared-db`；新 `pg-prod` / `pg-dev.ad.ddupan.top` | 新生产主从与开发实例上线，旧应用未迁移 | `infrastructure/shared-postgresql/README.md`、旧 migration.md | 切换/备份恢复已验证；Ayatori 独立控制面仅备齐声明 |
 | [smtp-relay](smtp-relay.md) | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；未附上线记录 | `apps/smtp-relay/README.md` | 已有应用参数、测试邮件与投递边界指南 |
 | [tailscale](tailscale.md) | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 已有远程访问与路由边界指南 |
 | [vlmcsd](vlmcsd.md) | KMS 兼容服务，使用范围未记录 | `宿主 TCP 1688；地址未记录` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 已有协议入口与客户端指南；未查询现场 |
@@ -58,7 +59,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 | 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` | 已有登录、取密与运维入口指南 |
+| [openbao](openbao.md) | 秘密管理与内部 CA | `bao.ad.ddupan.top` | 人工解封、中央采集与本地快照已验收 | `infrastructure/openbao/README.md` | 内部健康和快照新鲜度有告警；异地恢复演练待完成 |
 | [proxmox](proxmox.md) | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施 | `infrastructure/proxmox/ansible/` 与 `README-ha.md` | 已有管理入口；sandbox LB/根盘恢复流程见服务页；身份与 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/nats.md

@@ -45,5 +45,6 @@ Dynamic Runner 的 stream、subject、durable 名称、worker 配置和具体启
 
 2026-09-25 已现场确认既有 :7777 prom-exporter 经 PodMonitor → VMPodScrape 接入中央采集，
 job 为 `nats/nats`，target up 且 nats_* 指标有当前样本。已有采集不可用/整个 job 消失告警；
-JetStream 容量、consumer 积压等业务规则仍待第二批。
+已增加 JetStream 服务端容量与慢消费者规则；consumer 积压仍待后续。
+范围和阈值见 [数据服务监控](../guides/monitoring-data-services.md)。
 转换器故障处理与验证依据见 [基础监控运维](../guides/monitoring-foundation.md#nats-转换故障经验)。

services/openbao.md

@@ -1,9 +1,9 @@
 ---
 title: OpenBao 使用指南
 lifecycle: active
-evidence: documented
+evidence: live-verified
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
-last_verified: null
+last_verified: 2026-09-25
 ---
 
 # OpenBao
@@ -12,7 +12,8 @@ OpenBao 提供秘密管理与内部 CA，部署在 Kubernetes 之外的独立主
 日常使用是以自己的身份登录，按已有 policy 读取秘密或申请短期凭据。
 
 本页依据 homelab-infra 工作区 `infrastructure/openbao/README.md` 整理，
-CLI 语法参考下列官方文档。本轮未登录服务、读取秘密或验证现场。
+CLI 语法参考下列官方文档。登录和取密指南仍以文档为据；2026-09-25 已现场验证
+服务解封、中央指标、ESO 秘密刷新及本地快照监控，范围见本文末节。
 
 ## 人的登录入口
 
@@ -86,3 +87,23 @@ Dynamic Runner 提供执行环境和 workload 身份，具体向 OpenBao 请求
 日常登录成功不等于已完成备份或灾难恢复验收。
 
 来源文件的固定版本与工作区差异见[来源追溯](../sources.md#openbao)。
+
+## 监控接入与维护窗口
+
+2026-09-25 已启用受鉴权 Prometheus telemetry，ServiceMonitor 通过现有 vmagent 采集，
+job 为 `openbao`。同 Pod 的 Bao Agent 使用 Kubernetes SA 登录 metrics role，自动续期，
+token 仅保存于内存卷；指标身份不能读取业务秘密，匿名 metrics 仍被拒绝。
+已有目标 down/消失持续 3 分钟的 critical 告警，通知沿用 Telegram。
+内部健康规则另检查当前单节点的 active、unsealed、Raft autopilot node healthy，
+并单独告警健康 gauge 缺失。以后改为多节点时必须调整 active 判定；尚未覆盖全部 Raft 或 PKI 风险。
+
+维护中已修复快照 token 失效及脚本缺少续期的问题，生成新快照并核对 VM 外副本。
+快照 timer 已启用；独立的 VM node_exporter 通过 textfile 上报最近结果、完成时间和最后成功时间，
+不依赖 Bao 解封或 API token。快照失败持续 5 分钟为 warning，超过 36 小时无成功快照
+或无成功记录持续 15 分钟为 critical；采集失联/损坏也有专用告警。
+标准主机指标复用现有主机规则。异地副本与恢复演练仍需独立验收。
+
+维护者用 working PC 的 YubiKey 解密 VM 上保存的加密 unseal share，重启后人工解封。
+本次服务配置变更、采集上线与恢复验收已完成，详细操作与证据见
+[OpenBao 监控接入维护 runbook](../guides/openbao-monitoring-maintenance.md)。
+后续重启仍需同样的人在场解封流程；不能因本次恢复成功假定已经自动解封。

services/postgresql-tenant-operator.md

@@ -159,15 +159,33 @@ Instance 观测、Secret watch 与删除引用保护已在 CI 通过后，经维
 [模块说明](https://git.ddupan.top/panxiao81/ayatori/src/commit/f4deb98a7fcf61fb97ce52bbf190beb816d0141a/docs/database/README.md)
 与安全文档为准；合并不表示部署或完整供应链路已完成。
 
-后续应用凭据存储切片已签名提交为
+应用凭据存储切片及测试准备修复已通过三项 CI，并经维护者批准合并
-[f6bb9e4](https://git.ddupan.top/panxiao81/ayatori/commit/f6bb9e4599afca49a9cdc3d40789e11d118db9c5)，
+[PR #12](https://git.ddupan.top/panxiao81/ayatori/pulls/12)，合并提交为
-由 [PR #12](https://git.ddupan.top/panxiao81/ayatori/pulls/12) 跟踪，尚未合并。
+[22ab72e](https://git.ddupan.top/panxiao81/ayatori/commit/22ab72ec60dd5a0bf852e4563e107597dd56e81f)。
 复用 OpenBao 官方 Go SDK 的 KV v2 CAS=0、回读七键与版本，禁止覆盖
 或自动认领；明确权限拒绝等待依赖恢复，写入结果不确定则停止并人工处理。本地真实
-OpenBao 测试已覆盖并发、软删除、固定前缀权限和响应丢失，尚未接入 manager、Kubernetes
+OpenBao 测试已覆盖并发、软删除、固定前缀权限和响应丢失，尚未接入 manager、
-auth、Database 供应或 ESO。源码模块文档与 wiki 已关联，见
+Database 供应或 ESO。源码模块文档与 wiki 已关联，见
 [同步记录](../verification.md)。
 
+Kubernetes 认证会话的后续实现位于
+[PR #13](https://git.ddupan.top/panxiao81/ayatori/pulls/13)，提交
+[f0aa86f](https://git.ddupan.top/panxiao81/ayatori/commit/f0aa86f67673fbfb5f182f3ce35679c614be968d)，尚未合并。
+维护者指出并纠正了首版的 Pod 文件假设：controller 可以是 systemd service；Kubernetes auth
+仍是正确路径，但应复用 manager 的标准 kubeconfig/in-cluster 配置，通过 RBAC 授权的指定
+ServiceAccount TokenRequest 申请短期 JWT。集群内外共用同一客户端路径，不另建机器身份。
+重新登录重新申请 JWT，申请失败不回退投射文件或静态 token；官方 SDK 负责 Bao 登录与
+LifetimeWatcher，续期失败及停止时清空本地 token。kubeconfig 的签发、更新与撤销属于部署管理。
+manager 已增加显式 HTTPS/CA、auth role、目标 SA/audience 配置、Runnable 与 readiness，
+默认停用；controller 不自动创建身份或授予权限。真实受限 kubeconfig 启动 manager 的测试
+验证 TokenRequest、续期、跨 namespace/其他 SA 拒绝、RBAC 撤回恢复与 Bao audience 校验，
+三轮 race、本地全量测试和两种 lint 通过。生产 auth 配置与 Database 供应尚未接入，不代表已部署。
+认证客户端与生命周期按维护者确认的
+[公共 infra 边界](../architecture/ayatori-control-plane.md#controller-公共基础设施边界)整理，
+Database 保留凭据 repository/adapter 语义；重构继续由同一 PR 跟踪，不表示供应链路已完成。
+具体使用边界见该提交的
+[认证会话说明](https://git.ddupan.top/panxiao81/ayatori/src/commit/f0aa86f67673fbfb5f182f3ce35679c614be968d/docs/database/README.md#openbao-kubernetes-认证会话)。
+
 - operator 管理实例内的租户资源，不运行 PostgreSQL/OpenBao，也不管理 VM、存储、备份或 OpenBao PKI。
 - 应用密码写入 OpenBao，不进入 CR、Event 或日志；ESO 负责向 Kubernetes 消费者投射。
 - Database 默认 Retain；删除 Tenant 保留资源对象与数据，Released 不自动重新分配。

services/seaweedfs.md

@@ -2,7 +2,7 @@
 title: SeaweedFS S3 使用指南
 lifecycle: active
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
 last_verified: null
 ---
 
@@ -85,3 +85,8 @@ zot 的 S3 身份只允许相应 bucket 的 Read/Write/List/Tagging，不能访
 其他应用的数据保留与恢复策略应由各自用途明确，不能从“已接入 S3”推断已经完成备份。
 
 来源文件的固定版本与工作区差异见[来源追溯](../sources.md#seaweedfs)。
+
+## 中央监控
+
+2026-09-25 已接入 master、filer、volume 指标与容量/写入故障规则；
+使用方式与验证边界见 [数据服务监控](../guides/monitoring-data-services.md)。

services/shared-etcd.md

@@ -0,0 +1,71 @@
+---
+title: Homelab 共享 etcd
+lifecycle: experimental
+evidence: live-verified
+last_reviewed: 2026-09-25
+last_verified: 2026-09-25
+---
+
+# Homelab 共享 etcd
+
+为 homelab 服务提供共享的配置、协调与选主存储。维护者已接受共享定位；首个消费者是
+k3s 外 PostgreSQL 的 Patroni。三成员基础服务已部署，现有监控已接入，自动续签已启用；现有 k3s datastore 未迁移。
+
+## 入口与第一次接入
+
+部署拓扑为 laptop 原生 systemd、pve1/pve2 各一个无特权 LXC（150/151）。地址为
+192.168.10.127、10.60.0.20、10.60.0.21，客户端端口 2379，三端点健康检查已通过。两个 LXC 的 rootfs 位于 `pve-rg` SSD DRBD 池。
+实际接入前由管理流程交付三个 TLS endpoints、中央 CA、独立客户端证书和 Bao 秘密引用。
+使用分配身份在自己的 prefix 内 put/get/delete 验证，并确认跨 prefix 被拒绝；不要使用管理员证书接应用。
+
+证书由 OpenBao 中央 CA 签发，成员间 peer CN 受限。管理员原生 etcdctl 使用 CN=root 证书；
+Patroni etcd3 gateway 使用无 CN 的 mTLS 证书加独立账号密码，不能复用管理员证书。
+密码首次随机生成并存入 Bao，重复部署复用，缺失、读取失败或漂移均不静默重置。
+首个消费者秘密路径为 `kv/infra/etcd/consumers/patroni-pg-prod`，授权 prefix 为
+`/homelab/patroni/pg-prod/`；账号和随机密码已创建，真实 gateway 登录已验证；Patroni 已部署并通过自动切换验证。
+
+## 依赖、维护与恢复
+
+依赖主机网络、磁盘、systemd；证书签发及配置收敛依赖 Bao。运行使用本地证书，不要求 Bao 在线。
+共享 etcd 的创建、维护和快照与数据库生命周期分离；删除 PostgreSQL 不删除 etcd。
+全集群快照恢复必须协调所有消费者，不能作为单个业务的回滚。
+
+源码实现提供每日每成员本地快照、独立认证初始化、消费者收敛和逐成员更新入口。
+三个成员的原生指标已接入现有 VictoriaMetrics，不增加 exporter；内网 2381 listener 不提供 KV API。
+六条规则覆盖成员采集、采集可见成员不足、无 leader、容量、fsync 和选举，现场三目标 up=1、规则 health=ok。
+Alertmanager 已接入 [Telegram 通知](grafana.md#telegram-告警接入)，warning/critical 可向外通知；备份年龄与证书到期告警尚待补齐。
+
+自动续签已启用：维护者恢复 OIDC 管理会话后，独立 cert auth、受限 policy 与每日 timer 已部署。
+登录使用 laptop 现有 peer 证书，按 DNS SAN 限制身份；无 CN gateway 证书不能用于 Bao cert
+登录（identity alias 为空），不会改动 etcd gateway 的无 CN 要求。首次实际续签流程三成员均
+`changed=0`、service Result=success；程序固定副本由 root 管理，短期 token 用后撤销。
+运行仍只依赖本地证书；续签和恢复步骤见源码 README。
+业务负载下的存储延迟与完整灾难恢复演练仍待完成。
+故障时先查 `homelab-etcd` systemd 日志和三端点健康；成员替换不能通过删除数据目录、重跑初始化处理。
+详细操作与验收边界见 homelab-infra `infrastructure/etcd/README.md`。
+
+存储故障处理：单成员 `NoLeader` 与频繁选举告警可能来自底层 I/O，不能直接认定整个集群失去 quorum。
+2026-09-25 CT150 的 DRBD 根卷短暂丢失 quorum，ext4 journal 写入失败后进入 `emergency_ro`；
+另外两成员仍健康。保存快照后停止 CT150，以 PVE 离线 fsck 修复、复查干净再启动，三成员健康及
+Raft term/index 一致已重新验证，两容器根卷与新增 mp0 均可写。不要在挂载中的卷上 fsck 或直接强制 remount。
+本项目两块新 HDD 数据卷后台同步上限已通过 IaC 限制为各 10 MiB/s；限速后短期未再见 PingAck 超时，
+但唯一根因和长期稳定性未确证。没有更改全局 DRBD quorum/协议。对应入口为
+`infrastructure/shared-postgresql/ansible/limit-resync.yml`，重复执行无变更；详细恢复过程见上述 runbook。
+频繁选举规则包含 15 分钟历史窗口，故障恢复后需结合当前健康及计数判断。
+
+
+## 证据与阶段边界
+
+2026-09-25 维护者指定 laptop + 两台 PVE 各一个新 LXC，并明确复用 Bao 中央 CA；旧 Vault 迁移后置。
+现场部署已应用独立 Bao PKI roles/policies，创建 LXC 150/151 并启用三成员 mTLS、认证及消费者 RBAC。
+PVE 两个 LXC 已直接迁移底层 rootfs 到 `pve-rg`；逐成员停机迁卷、启动后检查 quorum，未重建容器或数据库。
+2026-09-25 现场核实两个 rootfs 的目标存储与运行状态，三个 endpoint 均成功提交健康探测。
+当前 PVE LXC `move-volume` 要求容器停止；操作入口为源码 `ansible/move-storage.yml`。
+
+本地临时三节点 etcd 3.7.2 测试通过：mTLS、认证和消费者幂等、prefix 隔离、gateway 登录/写入、
+密码缺失/漂移失败关闭、快照离线恢复与停止一成员后的写入。假 Bao 测试不证明真实 PKI/policy 正确；
+测试进程 RSS 约 37–40 MiB 不是生产容量承诺。Terraform validate 与 Ansible lint 通过。
+证书签发、秘密创建、gateway 登录和机器身份续签均已在真实服务验证。
+
+来源为维护者指令、只读前置核查及 homelab-infra `infrastructure/etcd/`；
+文档已直接发布 main（[文档 acd4b55](https://git.ddupan.top/panxiao81/homelab-infra/commit/acd4b55)），实现见 [IaC PR #159](https://git.ddupan.top/panxiao81/homelab-infra/pulls/159)，已合并。与数据库的关系见[共享 PostgreSQL](shared-postgresql.md#共享-etcd-设计边界)。

services/shared-postgresql.md

@@ -2,7 +2,7 @@
 title: 共享 PostgreSQL 使用指南
 lifecycle: active
 evidence: documented
-last_reviewed: 2026-09-16
+last_reviewed: 2026-09-25
 last_verified: null
 ---
 
@@ -80,3 +80,64 @@ AI 接续任务时先确认操作范围，再执行现场查询；不能因为
 服务依赖 Kubernetes、CNPG、集群 DNS 与持久存储；Tailscale 入口另依赖对应网络及授权。
 
 来源文件的固定版本与工作区差异见[来源追溯](../sources.md#shared-postgresql)。
+
+
+## 共享 etcd 设计边界
+
+2026-09-25 维护者确定：为计划中的 k3s 外 PostgreSQL 引入的 etcd，应作为全 homelab
+共享基础设施建设，PostgreSQL 是首个消费者。该共享定位已实现并完成首期部署验收；既有应用尚未迁移，
+不改变本页现有 CNPG 入口。原研究将 etcd 列入数据库部署角色，新边界将其生命周期独立，
+以便多个服务共用，减少重复部署与维护。
+
+首期三成员已跨 laptop 与两台 PVE 部署，可与其他服务物理共置；
+独立 IaC 管成员、认证、维护和快照，消费者只取得自己的账号与 key prefix 权限。
+数据库卸载不能删除共享 etcd，全集群快照恢复也不能用作单个数据库的回滚。
+现有 k3s 内部 datastore 不包含在本次迁移范围；其他消费者按实际需要接入。
+
+维护者同时确定 etcd mTLS 证书由 OpenBao 中央 CA 签发，复用现有信任根，不引入
+Pigsty 自建 CA。签发角色、peer 身份限制及消费者认证已部署；自动续签身份和 timer 已启用；
+证书本地保存，正常启动不要求实时访问 Bao，Bao 本身不依赖此共享 etcd。
+Patroni 的 etcd3 gateway 路径不支持证书 CN 对应的 RBAC 登录；维护者确定其独立随机密码
+存入 Bao，由 Ansible 执行时读取，重复部署复用，轮换显式执行。该 secret 已在共享 etcd 部署阶段创建并验证 gateway 登录；Patroni 已部署。
+PVE 改为裸机目前仅为后续倾向，没有迁移决定。
+
+来源为本轮维护者设计指令及 homelab-infra
+`infrastructure/shared-postgresql/RESEARCH.md`；文档来源为 [文档 acd4b55](https://git.ddupan.top/panxiao81/homelab-infra/commit/acd4b55)，实现由 [IaC PR #159](https://git.ddupan.top/panxiao81/homelab-infra/pulls/159) 跟踪。
+本节记录数据库设计边界；共享 etcd 的现场部署与验证见独立服务页，本页 CNPG 的 `last_verified` 不因此更新。
+
+共享 etcd 的首轮 IaC、隔离验证与部署前置条件见[共享 etcd](shared-etcd.md)。
+
+### k3s 外实例的实现与验收边界（2026-09-25）
+
+新 PostgreSQL 18.6 生产主从与独立开发实例已上线，现有 CNPG 应用数据尚未迁移。
+生产稳定入口 `pg-prod.ad.ddupan.top:5432` 指向 VyOS `192.168.10.2` 上独立 HAProxy；
+正常 primary 为 laptop SSD ZFS，PVE LXC150 为 standby。开发入口为
+`pg-dev.ad.ddupan.top:5433`，同机独立用户/数据集。客户端要求中央 CA 与 verify-full TLS。
+
+LXC151 的专属 HDD 卷存放 pgBackRest 仓库，真实 SSH/WAL 归档、首个 full 和每日 timer 已验收；
+保留 3 个 full、本地连续 WAL，尚无异地备份，开发实例当前不备份。
+真实备份已恢复到临时目录的隔离实例，SQL 可写与管理角色属性验证通过，未覆盖生产 PGDATA。
+低负载停止 laptop 主库服务后，完整通过的一次演练约 9.2 秒恢复经稳定入口写入；旧主重新作为
+replica 加入、计划回切 laptop 后复制与探针清理全部通过。这不是 SLA，也不覆盖冻结/网络分区等全部故障。
+
+Bao PKI 与专用 `homelab-postgresql` SPIFFE 身份已通过 OIDC 管理会话首次创建；之后受限身份
+完成签发、KV 读取与独立管理凭据交付。原始实例秘密不交给 Ayatori，控制面只读
+`kv/infra/postgresql/ayatori/{prod,dev}` 中的 username/password。
+生产与开发管理账号实际 TLS 登录和非 superuser CREATEDB/CREATEROLE 属性已验证。
+配置、备份传输、代理与凭据重跑 `changed=0`；PG 每日续签已启用，实际 systemd 运行成功，
+证书窗口检查与 SQL 验收无变更。只在续签后重载证书，不重启实例；尚未强制演练临期轮换。
+数据库日常运行独立于 k3s；机器身份续签依赖现有 SPIRE 与 Bao，不等于运行时依赖。
+
+生产 Patroni 原生指标已接入现有监控，两目标 up=1、五条 HA 规则 health=ok 且 inactive。
+SQL 级 exporter、开发实例、备份年龄和证书到期告警尚未补齐。存储事故与持续观察边界见
+[共享 etcd](shared-etcd.md#依赖维护与恢复)，不以短期验收证明底层长期稳定。
+
+维护者明确 Ayatori 沿用独立控制面规划：本轮只准备 Instance、ExternalSecret、公开 CA、
+Kustomize 与专用 ESO 只读 policy，没有向现有 k3s 安装 controller/CRD 或应用这些声明。
+独立控制面还需创建实际 SecretStore/认证绑定并验收 Instance Ready；完整 Database/Tenant
+供应能力以 Ayatori 自身实施为准。不能把现有 SQL 验证当作 Ayatori 已接管。
+
+源码为 homelab-infra `infrastructure/shared-postgresql/README.md` 与
+`ayatori/README.md`；部署、切换、恢复、续签及凭据引用的具体入口在那里维护，文档已发布 main；IaC 见 [IaC PR #159](https://git.ddupan.top/panxiao81/homelab-infra/pulls/159)，已合并；2026-09-25 核实 Flux observability 已应用 `f6d12d6`，四个监控对象均已进入 inventory。
+Terraform backend 已复用 `kv/k8s/seaweedfs-s3` 中受限 AK/SK；此前阻塞是 Bao 管理权限，已由
+维护者重新 OIDC 登录解决，不是 S3 凭据缺失。旧 Ansible Vault 迁移仍后置。

verification.md

@@ -107,11 +107,25 @@ controller、目标固定、finalizer 保留与生成 RBAC，真实 API server
 [f4deb98](https://git.ddupan.top/panxiao81/ayatori/commit/f4deb98a7fcf61fb97ce52bbf190beb816d0141a)；
 未部署或进行现场验收。
 
-后续凭据存储切片已签名提交并推送为
+凭据存储切片及冷缓存准备修复已通过 CI #815 的 test、lint、database-integration，
-[f6bb9e4](https://git.ddupan.top/panxiao81/ayatori/commit/f6bb9e4599afca49a9cdc3d40789e11d118db9c5)，
+维护者批准后合并 [PR #12](https://git.ddupan.top/panxiao81/ayatori/pulls/12)，合并提交
-由 [PR #12](https://git.ddupan.top/panxiao81/ayatori/pulls/12) 跟踪 CI 与 review。
+[22ab72e](https://git.ddupan.top/panxiao81/ayatori/commit/22ab72ec60dd5a0bf852e4563e107597dd56e81f)。
-全量测试、真实 PostgreSQL/API server/OpenBao 集成测试及两种 lint 本地通过；源码模块文档
+后续 Kubernetes 认证与短期会话续期已提交为
-和 wiki 已同步实现边界与正式链接。尚未合并或接入供应流程，不把本地验证等同于远端 CI。
+[f0aa86f](https://git.ddupan.top/panxiao81/ayatori/commit/f0aa86f67673fbfb5f182f3ce35679c614be968d)，
+由 [PR #13](https://git.ddupan.top/panxiao81/ayatori/pulls/13) 跟踪 CI 与 review。
+首版依赖投射 SA 文件的假设已按维护者意见撤除：集群外 kubeconfig 与集群内配置共用 manager
+客户端，通过受限 TokenRequest 获取登录 JWT。manager 显式配置、Runnable 与 readiness 已装配；
+三轮真实 API/OpenBao race、本地全量测试与两种 lint 通过，覆盖 RBAC 撤回/恢复和越权拒绝。
+源码文档与 wiki 已同步边界和正式链接。认证尚未合并，不把本地验证等同于新 head 的远端 CI；
+未部署生产 auth/RBAC，也未接入 Database 供应或 ESO 交付。
+
+同一 PR 的公共 infra 拆分已提交为
+[65c60cc](https://git.ddupan.top/panxiao81/ayatori/commit/65c60cca4528bc8bf14783fb7b59922283059c02)。
+Bao client/TLS 与认证不再归 Database；Secret 凭据适配器注入 manager 的直连 reader，
+领域继续维护凭据格式和写入结果语义。分层约定已同步
+[控制面边界](architecture/ayatori-control-plane.md#controller-公共基础设施边界)及源码文档。
+全量单元/API 测试、真实 PostgreSQL/OpenBao 集成、公共 infra race 与两种 lint 本地通过；
+新 head 的远端 CI 仍由 PR 跟踪，不把本地验证或本次文档同步当成合并、部署完成。
 
 ## 2026-09-25 sandbox 存储故障复盘的来源边界
 
@@ -122,5 +136,22 @@ controller、目标固定、finalizer 保留与生成 RBAC，真实 API server
 [Proxmox](services/proxmox.md#sandbox-lb-与根文件系统恢复)。
 
 事故报告与恢复手册在 wiki 统一维护，见[完整事故报告](incidents/2026-09-25-drbd-quorum-sandbox.md)。
-取证引用的 etcd/shared-postgresql 源码当时尚未提交，固定版本关联待源码合并后补齐；
+取证引用的 etcd/shared-postgresql 源码当时尚未提交，固定版本现关联 [合并提交 f6d12d6](https://git.ddupan.top/panxiao81/homelab-infra/commit/f6d12d6)；
 服务恢复不等于全部整改完成。
+
+## 共享 etcd 与 PostgreSQL 来源同步
+
+2026-09-25 shared etcd 三成员、新 PG 生产主从与开发实例、稳定入口、本地备份已部署，
+监控 CR 已现场应用。OIDC 恢复后，专用身份与 etcd/PG 每日续签均已启用；此前 Bao 权限阻塞已解除。
+真实 PG 自动切换、回切、SQL/TLS、备份恢复与配置幂等通过，边界见
+[共享 PostgreSQL](services/shared-postgresql.md#k3s-外实例的实现与验收边界2026-09-25)和
+[共享 etcd](services/shared-etcd.md)。
+
+源码 `infrastructure/etcd/`、`infrastructure/shared-postgresql/`、DNS 和监控已提交至 [IaC PR #159](https://git.ddupan.top/panxiao81/homelab-infra/pulls/159)，已合并。
+2026-09-25 合并后现场验证：Flux observability Ready，应用版本 `f6d12d6`；
+两份 VMRule 和两份 VMStaticScrape 均在 Flux inventory 中，状态 operational。
+三个 etcd 和两个 Patroni 目标均 up=1，相关 11 条规则 health=ok、inactive。
+监控声明已由 GitOps 接管。既有 CNPG 应用未迁移，异地备份后置；数据库细项告警仍待补齐。
+Ayatori 按维护者决定继续使用独立控制面，本轮只准备接入材料，尚未验收 controller/Instance Ready。
+两仓事实已同步，源码文档已直接推送 main：[文档 acd4b55](https://git.ddupan.top/panxiao81/homelab-infra/commit/acd4b55)；IaC 固定版本为
+[3a2fe5f](https://git.ddupan.top/panxiao81/homelab-infra/commit/3a2fe5f)。