建立人和 AI 共用的 Homelab 知识库及服务盘点

2026-09-16 14:26:05 +00:00
commit 5aa50d71ad
8 changed files with 270 additions and 0 deletions
@@ -0,0 +1,8 @@
+.obsidian/
+.DS_Store
+.trash/
+site/
+node_modules/
+.env
+.env.*
+!.env.example
@@ -0,0 +1,17 @@
+# 人与 AI 共用的知识库
+
+先读 README.md，按任务从 services/index.md 和 architecture/constraints.md 查找资料，
+并检查 verification.md 中的相关冲突。不要求把整个仓库一次性放入上下文。
+
+- 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。
+- 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。
+- 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。
+- 修改前读取对应源码 README/runbook，核实相关运行状态；发现冲突先记录，不能自行把计划升级为事实。
+- 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。
+- 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。
+- 跨仓库修改互相关联 commit/PR；未完成的文档同步明确记入 verification.md，不能宣称全部完成。
+- 架构约束变更必须明确说明旧规则、新规则和原因，不得静默删除约束来迁就实现。
+- 每项当前事实注明来源；last_verified 只在完成所述现场验证后更新，不随文字编辑刷新。
+- 凭据只记录取得方式和受管位置，不复制实际密码、token、私钥、state 或含敏感值的输出。
+- 不复制 apps/tailscale/helm.sh 的内容。迁移旧文档前先审查敏感内容，不能整库直接发布。
+- 遵守 CONTRIBUTING.md；不把临时检查日志和个人 agent memory 当成正式文档。
@@ -0,0 +1,41 @@
+# 文档维护规则
+
+## 状态与证据
+
+分别记录服务生命周期和验证程度，避免一个“完成”掩盖多个状态：
+
+- 生命周期：planned（计划）、experimental（试验）、active（投入使用）、retired（退役）、unknown（未知）。
+- 证据：configuration（仅配置）、documented（已有实施记录）、live-verified（现场验证）。
+- 存在冲突时明确标记 conflict，并链接待核实项；不按文件日期自动决定谁正确。
+
+设计另用 draft / accepted / implementing / implemented / superseded 表示进度；
+accepted 不代表部署完成，implemented 必须附实现和验收依据。
+
+`last_reviewed` 是文档审阅日期；`last_verified` 是对应运行事实的最近核实日期。
+没有核实就写 null。历史验证要说明日期、范围和来源，不能冒充本轮验证。
+
+## 一项工作的完成条件
+
+1. 修改前读取服务文档及相关约束，检查已知冲突。
+2. 实施和必要验证后，同步用途、入口、使用方法、依赖和恢复步骤中的变化。
+3. 新增或退役服务时更新服务总览；退役文档保留替代入口和原因。
+4. 代码与文档分属仓库时互相链接 commit/PR；未部署或未同步的部分明确写出。
+5. 报告分别说明已实施、已验证、仍待完成的内容。
+
+新增服务至少提供一次真实的使用路径。部署步骤不等于使用说明；不能只有 Helm/Compose 命令。
+页面上半部分面向使用者，下半部分说明运维和证据。
+
+## 来源与归属
+
+每份事实只维护一个权威正文位置，其他页面链接到它。链接源码时标明仓库与路径；
+历史验收尽量使用 commit permalink，现状入口可指向默认分支。引用未提交工作区时明确标记，
+合并后补正式链接。禁止把所有来源路径一律转换成可能不存在的远端链接。
+
+发生冲突时在 verification.md 记录两边来源、影响、核实方法和结果。核实完成后更新权威
+文档及引用它的总览，保留决策原因；不要长期维护两种“现状”。
+
+## 格式与检查
+
+使用普通 Markdown 链接、相对附件路径和文字说明；关键事实直接写入正文。
+可选 Obsidian 编辑，个人布局、缓存、插件和同步配置不提交。对外分享前检查敏感内容。
+提交前检查相对链接、服务目录覆盖，以及新增内容是否混淆计划和运行事实。
@@ -0,0 +1,32 @@
+# Homelab 知识库
+
+人和 AI 共用的 Markdown 知识库：了解当前环境、使用服务、遵守架构约束，以及接续尚未完成的工作。
+
+## 从这里开始
+
+- [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。
+- [待核实与文档缺口](verification.md)：互相矛盾的记录、缺少使用说明的服务、下一步核实方法。
+- [架构约束](architecture/constraints.md)：修改环境前必须遵守的设计及原始依据。
+- [文档维护规则](CONTRIBUTING.md)：人和 AI 如何共同维护知识。
+- [服务文档模板](templates/service.md)：新服务必须同时提供使用说明。
+- [AI 工作入口](AGENTS.md)：新上下文按任务查找资料。
+
+## 当前证据边界
+
+首轮盘点日期为 **2026-09-16**，依据 `/home/panxiao81/services` 工作区，基线 commit 为
+`ebe0ec154dab557598075b5cf6d3629c3c23fe2a`。该工作区包含未提交修改和未跟踪文件。
+本轮没有查询运行环境；“文档记录已部署”不等于今天已验证健康。
+本库中的入口地址来自原有记录，也尚未逐一验证可达性。
+
+基础设施源码仓库：[homelab-infra](https://git.ddupan.top/panxiao81/homelab-infra)。
+服务表中的来源路径均相对于该仓库；尚未提交的来源可能只能在上述工作区找到。
+
+## 内容归属
+
+本库保存全局导航、跨服务设计与约束、面向使用者的指南及跨服务 runbook。
+紧贴实现的部署参数与操作细节继续保存在源码仓库的 README/runbook，双方以链接关联，
+不复制维护两份事实。单次变更由 commit/PR 记录，历史计划不能代替现状说明。
+
+使用标准 Markdown、普通相对链接和 YAML frontmatter。可将仓库直接作为 Obsidian vault
+打开；核心信息不依赖插件、动态查询或嵌入内容才能理解。尚未选择或部署网页展示层，
+后续可接入 Backstage，文档仓库本身不依赖 Backstage 可用。
@@ -0,0 +1,21 @@
+# 架构约束索引
+
+审阅日期：2026-09-16。以下是现有仓库明确记录的约束摘要，不是本轮新增的架构决策。
+来源路径相对于 homelab-infra；修改时必须读原文和对应代码，冲突进入[核实清单](../verification.md)。
+
+| 约束 | 原因与边界 | 来源 |
+|---|---|---|
+| 服务独立部署，Terraform root/state 按服务隔离 | 避免认证和变更影响范围绑在一起 | `AGENTS.md`、`CLAUDE.md` |
+| OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` |
+| Terraform 管 API 配置，Ansible 管主机及不能安全纳管的密钥材料 | 不可读回秘密和根密钥不能靠反复重建实现收敛 | `infrastructure/openbao/README.md` |
+| LAN HTTP 入口为 Envoy Gateway；新增服务核对 parentRefs、DNS 和认证 | 不直接套用 archive 中的 Gateway 示例 | `platform/envoy-gateway/README.md`、`AGENTS.md` |
+| 人类身份由 Samba AD / Authelia 提供，workload 身份由 SPIRE 提供 | 身份签发不等于资源授权；SPIRE 实施状态见核实清单 | `platform/spire/README.md` |
+| 已由 Flux 接管的资源通过 Git 修改；brownfield 不全局开启 prune | 防止漂移回滚与误删；未接管资源不能假定受 Flux 管理 | `clusters/homelab/README.md` |
+| DNS 各视图保留权威边界；只管理明确声明的 RRset | 不清理 Samba 自动维护的域记录；DNS 文档尚有冲突 | `infrastructure/dns/README.md` |
+| Docker 地址池不得与 DN42 的 172.20.0.0/14 重叠 | 本地直连路由会干扰 DN42；已有网络不自动改地址 | `infrastructure/docker/README.md` |
+| NetBox 目前是评估，拓扑由 Git 管理 | 不把网页编辑结果当作新的权威数据 | `apps/netbox/README.md`、`CLAUDE.md` |
+| 现有 privileged DinD runner 只运行可信 workflow | 实例级 runner 不能视为不可信任务隔离边界 | `platform/gitea-runner/README.md` |
+| zot 匿名入口只读；鉴权入口必须按具体身份授权 | 能认证不代表可以推送；不得给整个 trust domain 写权限 | `apps/zot/README.md` |
+
+通用变更约束：先做适用的 plan/check/diff，再操作现场；不将凭据和 Terraform state
+写入知识库；不更新 homelab-infra 的冻结 `CHANGELOG.md`。
@@ -0,0 +1,75 @@
+# 服务总览
+
+审阅日期：2026-09-16。以下覆盖源码工作区 apps/、platform/、infrastructure/ 的一级组件，以及集群入口。
+**所有条目本轮均未现场验证。** 状态栏表示文档或配置证据，不表示实时健康状态。
+来源路径相对于 [homelab-infra](https://git.ddupan.top/panxiao81/homelab-infra)；包含未提交内容，见首页证据边界。
+
+入口按来源记录列出，访问范围和可达性仍需验证。缺口详情见[待核实清单](../verification.md)。
+
+## 应用
+
+| 组件 | 用途 | 记录入口 | 状态依据 | 来源 | 文档缺口 / 下一步 |
+|---|---|---|---|---|---|
+| authelia | 统一登录与 OIDC | `auth.ddupan.top` | 记录已部署；旧 README 冲突 | `apps/authelia/README.md` | 补当前登录与接入指南 |
+| blocky | LAN DNS、广告过滤、分流 | `192.168.10.127:53` | 记录已部署；DNS 记录冲突 | `apps/blocky/README.md` | 补日常排障入口 |
+| codex-proxy | 代理服务，具体接口待确认 | `待核实` | 仅发现配置 | `apps/codex-proxy/docker-compose.yml` | 缺 README 与使用说明 |
+| gitea | 代码托管与 Actions | `git.ddupan.top` | 记录已部署 | `apps/gitea/README.md` | 补首次使用与 runner 选择 |
+| http-echo | Flux 部署与漂移修复 canary | `集群内` | 记录已验证 | `apps/http-echo/README.md` | 已有验证步骤 |
+| litellm-gateway | 模型 API 网关，实际消费者待确认 | `待核实` | 仅发现配置 | `apps/litellm-gateway/docker-compose.yml` | 缺 README 与接入说明 |
+| marker | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；上线待核实 | `apps/marker/README.md` | 缺 API 使用例子 |
+| netboot | PXE 与系统安装 | `192.168.10.127` | 有部署及使用记录 | `apps/netboot/README.md` | 已有客户端启动说明 |
+| netbox | 网络资产与地址管理评估 | `netbox.ad.ddupan.top` | 记录已部署；评估用途 | `apps/netbox/README.md` | 补面向浏览者的使用路径 |
+| openviking | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；上线待核实 | `apps/openviking/README.md` | 缺导入、查询的完整例子 |
+| ps3netsrv | PS3 网络内容服务 | `待核实` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 缺客户端使用与挂载说明 |
+| seaweedfs | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 补客户端接入、备份与恢复 |
+| shared-postgresql | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 缺服务首页、租户接入说明 |
+| smtp-relay | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；上线待核实 | `apps/smtp-relay/README.md` | 核实发信链路与消费者 |
+| tailscale | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 缺 README、路由与客户端说明 |
+| victoriametrics | 旧 Compose 监控栈 | `待核实` | 文档称被平台栈替代；残留待查 | `apps/victoriametrics/compose.yaml` | 明确退役或现存职责 |
+| vlmcsd | KMS 兼容服务，使用范围待确认 | `待核实` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 缺 README 与状态说明 |
+| zot | OCI 镜像与制品仓库 | `zot.ad.ddupan.top / zot-push.ad.ddupan.top` | 文档记录 9 月 16 日验收 | `apps/zot/README.md` | 已有拉取示例；长期 CI 发布仍待接入 |
+
+## 平台
+
+| 组件 | 用途 | 记录入口 | 状态依据 | 来源 | 文档缺口 / 下一步 |
+|---|---|---|---|---|---|
+| cert-manager | 签发与续期 TLS 证书 | `ClusterIssuer API` | 记录已接管 Flux | `platform/cert-manager/README.md` | 已有签发和验证说明 |
+| envoy-gateway | LAN HTTP 入口与认证集成 | `192.168.10.127:443` | 记录已接管 Flux | `platform/envoy-gateway/README.md` | 已有服务接入说明 |
+| external-secrets | OpenBao 到 Kubernetes 的秘密投射 | `Kubernetes API` | Helm 记录已接管；对象范围需区分 | `platform/external-secrets/README.md` | 补新增秘密引用的使用流程 |
+| gitea-runner | 可信 Gitea Actions 任务执行 | `Gitea Actions` | 记录已接管 Flux | `platform/gitea-runner/README.md` | 补 workflow label 与使用限制 |
+| k3s | 集群 CoreDNS 定制 | `集群内 DNS` | 仅发现 DNS 配置 | `platform/k3s/Corefile.desired` | 缺组件 README |
+| nats | 共享消息与 JetStream 队列 | `nats.ad.ddupan.top:4222` | 有配置与拓扑记录；现场待核实 | `platform/nats/README.md` | 补生产/消费示例与队列检查 |
+| observability | Grafana、指标、日志和追踪 | `grafana.ad.ddupan.top` | 记录已接管 Flux；9 月 16 日变更入口 | `platform/observability/README.md` | 补看板和查询使用指南 |
+| openebs | k3s 本地 ZFS 持久卷 | `localpv-zfs-ceph StorageClass` | 记录已接管 Flux | `platform/openebs/README.md` | 已有运维检查；补 PVC 使用边界 |
+| spire | workload 身份签发 | `Workload API / spire-oidc.ad.ddupan.top` | zot 验收有运行证据；集群总览冲突 | `platform/spire/README.md` | 核实状态，补身份申请和消费流程 |
+
+## 基础设施
+
+| 组件 | 用途 | 记录入口 | 状态依据 | 来源 | 文档缺口 / 下一步 |
+|---|---|---|---|---|---|
+| cloudflared | 公网 Tunnel 与 DNS | `Cloudflare 边缘配置` | 有现有资源接管记录 | `infrastructure/cloudflared/terraform/README.md` | 明确配置权威位置与服务发布流程 |
+| dns | 跨视图 DNS 声明 | `records.yml` | 部分接管；LAN DNS 说明冲突 | `infrastructure/dns/README.md` | 补现状与新增记录流程 |
+| docker | 宿主 Docker 网络管理 | `laptop` | 记录已迁移地址池 | `infrastructure/docker/README.md` | 已有 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 | 按 job 创建临时 CI VM | `计划使用 kind-microvm label` | PoC 验证；正式启用有未完成前提 | `infrastructure/microvm-runner/README.md` | 核对独立 runner 仓库与实际部署 |
+| oci | 云主机、网络与站点互联 | `OCI ap-osaka-1` | 有恢复、接管与网络实施记录 | `infrastructure/oci/README.md` | 补跨站点使用入口 |
+| openbao | 秘密管理与内部 CA | `bao.ad.ddupan.top` | 有部署与接管记录 | `infrastructure/openbao/README.md` | 补日常使用和恢复入口 |
+| proxmox | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施；README 混有设计设想 | `infrastructure/proxmox/README.md` | 分离当前环境与 workload identity 设想 |
+| samba-ad | AD 身份、域 DNS 与域成员管理 | `dc1 / 192.168.10.5` | 有部署与变更记录 | `infrastructure/samba-ad/README.md` | 补入域和日常管理入口 |
+
+## 集群
+
+| 组件 | 用途 | 记录入口 | 状态依据 | 来源 | 文档缺口 / 下一步 |
+|---|---|---|---|---|---|
+| homelab | k3s 的 Flux reconciliation 入口 | `flux-system namespace` | 已有部署记录；部分汇总滞后 | `clusters/homelab/README.md` | 同步 SPIRE 与新增组件状态 |
+
+## 计划、归档与范围外
+
+- Backstage：规划中的服务目录与文档入口；本轮未发现独立部署目录。
+- Keycloak、Casdoor：`archive/` 下有明确退役记录，替代入口为 Authelia。
+- Traefik：归档目录保留历史 Gateway 示例，不作为当前接入流程。
+- `docs/superpowers/`：已退役工作流，记录已完成的 CNPG/ZFS 迁移。
+- `docs/cicd.md`、`docs/homelab-gitops-redesign.md`：部分实施设计，不代表所有阶段都上线。
+- `docs/gitea-upgrade-plan.md`：包含已完成升级记录，现状以服务 README 和现场为准。
+- 仓库外服务与独立源码仓库见[盘点盲区](../verification.md#盘点盲区)。
@@ -0,0 +1,41 @@
+---
+title: 服务名称
+lifecycle: unknown
+evidence: configuration
+last_reviewed: null
+last_verified: null
+sources: []
+---
+
+# 服务名称
+
+## 它解决什么问题
+
+用一段话说明用途、使用者和当前成熟程度。
+
+## 从哪里使用
+
+- 入口：URL / CLI / API；注明 LAN、Tailscale 或公网范围。
+- 登录：身份来源、所需权限和申请方式；不写实际凭据。
+- 前提：客户端、网络、证书和必要依赖。
+
+## 第一次使用
+
+给出一个具体任务、操作步骤和预期结果。示例不得依赖未说明的临时授权。
+
+## 日常操作与限制
+
+列出常用操作、数据归属和已知限制；明确试验功能。
+
+## 出问题时
+
+说明最小只读检查、正常结果、故障日志位置和对应 runbook。
+
+## 运维入口
+
+链接源码、部署方式、依赖、备份恢复及相关架构约束。缺失的恢复方案明确写“尚未建立”。
+
+## 当前状态与证据
+
+记录观察日期、验证范围、来源 commit/PR 或命令的非敏感结果摘要。
+区分配置存在、已部署和端到端可用；列出尚未完成部分。
@@ -0,0 +1,35 @@
+# 待核实与文档缺口
+
+审阅日期：2026-09-16；本轮只盘点仓库，未查询现场。
+以下路径相对于 homelab-infra。优先修复影响恢复、认证、DNS 和首次使用的问题。
+
+## 记录冲突
+
+| 项目 | 两边的记录 | 核实与收敛方式 |
+|---|---|---|
+| LAN DNS | `apps/blocky/README.md` 说已是主 DNS；`infrastructure/dns/README.md` 仍说未成为正式 resolver | 读取 NEC DHCP 配置、客户端 DNS 和 Blocky 查询结果，再同步两份说明 |
+| SPIRE | `clusters/homelab/README.md` 说首次上线待验证；`apps/zot/README.md` 记录 9 月 14/16 日真实 JWT-SVID 验收 | 核对 Flux revision、SPIRE 健康和 Workload API，再更新集群总览；zot 的部分验收不等于全部身份集成完成 |
+| Authelia | README 仍描述 OIDC 为后续阶段、旧 Contour/Traefik 路径；退役记录和 Envoy 文档已描述 Authelia 替代旧 IdP | 核对 OIDC discovery、登录及 forward-auth，重写过时段落；迁移旧文档前检查其中的敏感示例 |
+| microVM runner | `infrastructure/microvm-runner/README.md` 说 PoC 完成但正式启用仍有前提；远端已有独立 runner 仓库 | 查清两个仓库的职责、controller/worker 部署和一次 job 生命周期，不能把仓库存在当作服务已启用 |
+| NATS durable 名称 | NATS 文档示例为 `kind-microvm-pve2`；microVM 文档配置为 `kind-microvm`，要求同类 worker 共享 durable | 查运行配置和 consumer；统一文档，避免多 worker 队列语义不一致 |
+| 旧 VictoriaMetrics Compose | `platform/observability/README.md` 说已替代；`apps/victoriametrics/` 仍留配置 | 只读检查 Docker 与采集目标，确认是否仍承担职责，再标记退役或迁移 |
+
+## 优先补充的使用说明
+
+1. Gitea / Actions：登录、创建仓库、选择 runner，以及可信任务限制。
+2. Grafana：登录、找到内存与 Swap 看板、查询指标和日志的一个完整例子。
+3. zot / SeaweedFS：拉取、发布授权、S3 客户端接入，以及数据备份边界。
+4. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。
+5. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。
+6. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：补用途和当前状态；这些目录缺少根 README。
+
+## 盘点盲区
+
+- `docs/cicd.md` 提及 `e5renew`、`rustfs`，但无独立组件目录；需要确认现状与归属。
+- `infrastructure/docker/README.md` 提及仓库外 `research-auto`，不能在本轮算作已盘点服务。
+- 本轮发现远端仓库 `gitea-microvm-runner`、`postgresql-tenant-operator`、`workload-sts`，
+  尚未审阅内容或运行状态。后续将跨仓库服务纳入总览。
+- 新增 NATS、zot、microVM 等来源含未提交文件；合并后补可访问的 commit/PR 链接。
+- Backstage 仍作为计划入口记录；本轮没有证明已有部署。
+
+完成核实后，将结果写回对应权威文档，并更新服务总览的证据等级和验证日期。