整理任务导航与源码版本追溯并暂缓原仓库文档同步

2026-09-16 18:45:34 +00:00
parent b177741efb
commit cf4430526a
26 changed files with 359 additions and 37 deletions
@@ -1,8 +1,10 @@
 # 人与 AI 共用的知识库

-先读 README.md，按任务从 services/index.md 和 architecture/constraints.md 查找资料，
+先读 README.md，按 guides/task-index.md 定位所需服务，再读 services/index.md 和 architecture/constraints.md，
 并检查 verification.md 中的相关冲突。不要求把整个仓库一次性放入上下文。

+- 原仓库 README 同步已按维护者要求暂缓；当前优先维护 wiki，不将源码文档同步作为其他工作的前置步骤。
+- 原仓库来源的固定版本与工作区差异见 sources.md；不能把基线链接当成未提交内容已经合并的证据。
 - 正式知识写给人和 AI 共同阅读；本文件只放工作规则，不另存一份服务事实。
 - 以中文维护正文、commit、PR；配置键、命令和上游专有名称保留原文。
 - 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。
@@ -4,38 +4,17 @@

 ## 从这里开始

- [Samba AD](services/samba-ad.md)、[OCI](services/oci.md)、[Proxmox](services/proxmox.md)：身份、云主机与虚拟化的日常管理入口。
- [发布新服务](guides/publish-service.md)：串联 LAN DNS、证书、HTTPRoute、认证与 GitOps。
- [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。
- [Gitea / Actions 入门](services/gitea.md)：登录、创建仓库、运行第一个 CI 与选择 runner。
- [Grafana 使用指南](services/grafana.md)：内存看板、指标查询和日志搜索。
- [zot 使用指南](services/zot.md)：匿名拉取、SPIFFE 发布身份与仓库授权。
- [SeaweedFS 使用指南](services/seaweedfs.md)：S3 客户端接入、对象读写与存储边界。
- [OpenBao 使用指南](services/openbao.md)：日常登录、按权限取密与机器身份边界。
- [NetBox 使用指南](services/netbox.md)：浏览设备和 IPAM，按 Git 来源维护资产镜像。
- [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。
- [LiteLLM 网关](services/litellm-gateway.md)：模型 API 接入参数与请求示例。
- [Tailscale](services/tailscale.md)：远程客户端、子网路由与 Service 入口。
- [ps3netsrv](services/ps3netsrv.md) / [vlmcsd](services/vlmcsd.md)：客户端接入与故障入口。
- [Marker](services/marker.md) / [OpenViking](services/openviking.md)：文档转换与上下文检索。
- [SMTP relay](services/smtp-relay.md)：应用发信参数、测试与投递排障。
- [External Secrets](services/external-secrets.md)：应用秘密投射与更新流程。
- [OpenEBS](services/openebs.md)：PVC 申请、绑定和数据回收边界。
- [k3s DNS](services/k3s-dns.md)：Pod 解析、内部域分流与缓存规则。
- [共享 PostgreSQL 使用指南](services/shared-postgresql.md)：应用接入、连接示例与共享实例维护边界。
- [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
- [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。
- [NATS](services/nats.md)：已部署的集群共享消息服务，目前仅 Dynamic Runner 消费。
- [旧 VictoriaMetrics 栈](services/victoriametrics-legacy.md)：旧运行栈、配置及数据卷已清理。
- [LAN DNS](services/lan-dns.md)：Blocky 主 DNS、路由器上游与备用、Samba AD 域 DNS 的现状。
- [Authelia](services/authelia.md)：active 的唯一主 OIDC broker 与登录入口。
- [首轮状态对齐记录](verification.md)：本轮已完成，没有开放的状态核实任务。
- [文档完善清单](documentation-backlog.md)：后续补充使用说明、同步旧文档和完善来源链接。
- [架构约束](architecture/constraints.md)：修改环境前必须遵守的设计及原始依据。
- [workload-sts 设计历史](architecture/workload-sts-history.md)：已归档的早期身份方案及 SPIRE 替代决策。
- [文档维护规则](CONTRIBUTING.md)：人和 AI 如何共同维护知识。
- [服务文档模板](templates/service.md)：新服务必须同时提供使用说明。
- [AI 工作入口](AGENTS.md)：新上下文按任务查找资料。
+- [按任务查找文档](guides/task-index.md)：接入服务、写 CI、查日志、取秘密或接续 AI 任务。
+- [服务总览](services/index.md)：组件、用途、入口和状态依据。
+- [发布新服务](guides/publish-service.md)：LAN DNS、证书、HTTPRoute、认证与 GitOps。
+- [架构约束](architecture/constraints.md)：修改环境前必须遵守的设计。
+- [来源追溯](sources.md)：固定源码版本，以及与工作区的差异。
+- [文档维护规则](CONTRIBUTING.md)、[服务模板](templates/service.md)、[AI 工作入口](AGENTS.md)：如何共同维护知识。
+- [首轮状态对齐记录](verification.md)：已完成的澄清与历史处置。
+- [文档完善清单](documentation-backlog.md)：已补指南与暂缓事项。
+
+设计历史与范围外项目见[workload-sts](architecture/workload-sts-history.md)、
+[旧监控栈](services/victoriametrics-legacy.md)及[外部消费者](services/external-consumers.md)。

 ## 当前证据边界

@@ -43,7 +22,8 @@
 `ebe0ec154dab557598075b5cf6d3629c3c23fe2a`。该工作区包含未提交修改和未跟踪文件。
 后续按维护者提供的线索补读了 SPIFFE/SPIRE #34 与 runbook、workload-sts 归档决策、
 PostgreSQL Tenant Operator 的 README 与架构文档，以及 Gitea Dynamic Runner README。
-具体来源和查阅范围见各页；其余条目仍以初轮工作区证据为限。
+具体来源和查阅范围见各页；后续使用指南已按对应源码和上游接口文档逐项补充。
+未补充的状态仍以初轮证据为限；来源文件与已提交版本的比较见[来源追溯](sources.md)。
 LAN DNS 已按维护者于 2026-09-16 提供的现状更新，未查询现场。
 Authelia 同日由维护者明确为 active、唯一的主 OIDC broker，已同步到服务总览。
 后续状态查询先向维护者确认动态工作与资料来源，授权范围内不重复询问。
@@ -20,7 +20,6 @@
 - [Marker](services/marker.md)、[OpenViking](services/openviking.md)：转换与导入、等待、检索、读取示例。
 - [SMTP relay](services/smtp-relay.md)：应用配置、测试邮件与投递边界。
 - [发布新服务](guides/publish-service.md)：LAN DNS、证书、Envoy 路由、认证与 GitOps 的完整路径。
-
 - [Samba AD](services/samba-ad.md)、[OCI](services/oci.md)、[Proxmox](services/proxmox.md)：已有资料中的日常管理路径，动态状态未重查。

 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
@@ -33,9 +32,15 @@ Samba AD、OCI、Proxmox 已按维护者指定采用 IaC 优先、以代码为
 codex-proxy 已按维护者“应该是退役的”的说明移至归档范围，不再补新接入指南。
 LiteLLM、Tailscale、ps3netsrv、vlmcsd 与 k3s 的 wiki 指南已补；源码目录仍缺根 README，配置入口已在各页列出。

-## 文档同步与来源链接
+## 来源与导航
+
+- 已新增[按任务查找](guides/task-index.md)，首页改为任务入口与服务总览。
+- 已核对 62 个主要来源文件，提供[固定版本与工作区差异](sources.md)。
+- 仍有差异或未收录的来源，等内容合并后再补对应版本；不自动提交原仓库工作区。
+
+## 原仓库文档同步（按维护者要求暂缓）

 - 源码仓库中 Authelia OIDC、LAN DNS、SPIRE 的旧说明后续与知识库结论同步。
 - cert-manager / Envoy Gateway README 的 DNS 修改入口仍写旧变量，待同步为受管 records.yml 流程。
 - Proxmox README 的早期身份方案与 runner bootstrap 描述待与当前 SPIFFE 原则对齐；Samba README 的通用示例域名/地址待清理。
- 未提交工作区来源合并后，补充正式 commit/PR 链接。
+上述项目仅保留记录，本轮不修改原仓库文档。
@@ -162,3 +162,5 @@ homelab-infra：`platform/cert-manager/README.md`、`certificate-wildcard-ad.yam
 `apps/http-echo/httproute.yaml` 是已排除出 Kustomization 的历史 Contour 示例，
 `archive/traefik/` 也不是当前接入模板；不要因文件存在就直接应用。
 上述源码 README 的旧描述尚待同步，本页按实际所读配置与维护者已经确认的结论整理。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#publish-service)。
@@ -0,0 +1,56 @@
+---
+title: 按任务查找文档
+last_reviewed: 2026-09-16
+---
+
+# 按任务查找文档
+
+先找任务，再读相关服务页；不必一次读取整个仓库。
+需要环境清单时看[服务总览](../services/index.md)，准备变更时先读[架构约束](../architecture/constraints.md)。
+
+| 要做什么 | 先读 | 需要时再读 |
+|---|---|---|
+| 发布新的 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) |
+| 拉取或发布容器镜像 | [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) |
+| 给应用提供秘密或存储 | [External Secrets](../services/external-secrets.md)、[OpenEBS](../services/openebs.md) | [OpenBao](../services/openbao.md) |
+| 排查内存、日志或追踪 | [Grafana](../services/grafana.md) | 对应服务源码 runbook |
+| 排查域名解析 | [LAN DNS](../services/lan-dns.md)或[Pod DNS](../services/k3s-dns.md) | [Tailscale](../services/tailscale.md)，如果请求来自远程客户端 |
+| 排查登录或域权限 | [Authelia](../services/authelia.md)、[Samba AD](../services/samba-ad.md) | 具体应用的权限说明 |
+| 为 workload 提供机器身份 | [SPIFFE](../services/spire.md) | 目标服务的 token 与权限规则；进度回到 #34 |
+| 使用消息队列 | [NATS](../services/nats.md) | consumer 项目自己的协议与队列文档 |
+| 调用模型或处理文档 | [LiteLLM](../services/litellm-gateway.md)、[Marker](../services/marker.md) | [OpenViking](../services/openviking.md)，如果需要检索 |
+| 让应用发送邮件 | [SMTP relay](../services/smtp-relay.md) | 消费者的发信配置 |
+| 远程访问或查看网络资产 | [Tailscale](../services/tailscale.md)、[NetBox](../services/netbox.md) | NetBox 的权威来源是 Git，不能代替运行状态 |
+| 管理云主机或虚拟机 | [OCI](../services/oci.md)、[Proxmox](../services/proxmox.md) | 对应 IaC 和网络/HA runbook |
+| 使用 PS3 内容或 KMS 服务 | [ps3netsrv](../services/ps3netsrv.md)、[vlmcsd](../services/vlmcsd.md) | 各自客户端配置 |
+
+## 给 AI 接续一个任务
+
+提供目标、目标服务、已经授权的操作范围，以及你掌握但尚未写入文档的变化。
+一个简短的任务交接可以这样写：
+
+```text
+目标：为某个新应用增加 LAN HTTPS 入口。
+入口文档：guides/publish-service.md。
+已有条件：应用 namespace、Service 名称与端口、计划域名。
+本次范围：先准备配置与文档 PR；尚未授权现场部署。
+动态背景：相关 ticket / PR，或维护者最新说明。
+完成条件：配置可审阅，检查通过，说明来源与未执行的验证。
+```
+
+这个例子的范围仅用于演示，不能覆盖具体任务已经获得的授权。
+Samba AD、OCI、Proxmox 已明确以 IaC 为准，可直接核对其代码；其他动态项目按既定规则对齐来源。
+身份设计、配置声明、历史实施记录和本次现场证据应分别表达。
+
+## 找到资料后如何判断是否足够
+
+服务页中的 `last_reviewed` 表示文档审阅时间，`last_verified` 才表示对应现场验证时间。
+查阅[来源追溯](../sources.md)可定位固定源码版本，并看到它与工作区是否一致。
+索引中的“内容一致”只确认文件，不确认服务健康。
+
+检索、转换或 AI 摘要用于定位原文；结论仍应关联到源码、维护者说明或 ticket。
+工作完成后，将持久使用方法写入服务页，将一次变化留在 commit/PR，动态进度回到原项目 ticket。
+原仓库 README 同步目前按维护者要求暂缓，不将其列为每次任务的前置条件。
@@ -83,3 +83,5 @@ env:
 新增引用先确定由哪个 GitOps/部署入口管理；把文件改好不等于 Flux 已经应用。
 部署和接管细节回到 `platform/external-secrets/README.md`。
 依赖包括 OpenBao、Kubernetes TokenReview、集群 DNS 与 ESO controller。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#external-secrets)。
@@ -80,3 +80,5 @@ workflow 路径、启用方式与事件规则见 [Gitea 官方入门](https://do

 服务部署与升级恢复以 homelab-infra `apps/gitea/README.md` 为入口；常驻 runner 以
 `platform/gitea-runner/README.md` 为入口。本页不复制 token、密码或部署命令。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#gitea)。
@@ -80,3 +80,5 @@ VictoriaLogs 使用 LogsQL。上述 limit 限制返回数量，不保证返回
 内存指标解释见 `platform/observability/metrics/exporters/README.md`。
 看板配置由 Git/ConfigMap 管理，网页临时调整不作为持久配置的权威来源。
 旧 Compose 栈与数据已[清理](victoriametrics-legacy.md)，不要再使用旧实例作为排障入口。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#grafana)。
@@ -62,3 +62,5 @@ DNS 成功只证明解析路径，不证明应用认证和业务请求成功。
 故障定位先区分集群 Service 解析、AD 转发、固定分流、默认上游和客户端搜索域。
 依赖包括 CoreDNS、Kubernetes API、网络、Samba AD DNS 及默认上游；
 Authelia/Gitea 的业务可达性还依赖 Envoy 和各自后端。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#k3s-dns)。
@@ -66,3 +66,5 @@ Compose 还挂载配置文件及宿主 `auth.json`，后者属于上游认证材
 连接失败先核对宿主与端口；401/403 需区分网关认证和上游认证；模型错误先核对别名及上游权限；
 超时或限额错误再检查上游响应。不要通过打印认证文件或完整带鉴权请求排障。
 部署来源为 homelab-infra `apps/litellm-gateway/`；消费者清单与备份情况未在所读文件中记录。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#litellm-gateway)。
@@ -61,3 +61,5 @@ Pod 没有业务 PVC，消费者应保存转换结果，不能将容器临时目
 转换结果需要复核表格、代码、顺序及遗漏，再写入知识库；转换工具不确认文档事实或当前服务状态。
 连接失败检查部署入口与监听地址，转换失败检查文件、模型加载及 GPU 资源。
 依赖为 Kubernetes、GPU 设备支持、模型与临时磁盘；部署维护入口为 `apps/marker/README.md`。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#marker)。
@@ -55,3 +55,5 @@ NetBox 中的地址状态来自资产记录，不会自动证明主机在线、
 部署、依赖、认证边界、拓扑同步与配置生成细节见 homelab-infra `apps/netbox/README.md`。
 应用使用数据库与 Redis，登录链路依赖 LAN DNS、Envoy、Authelia 和 Samba AD。
 本地管理员属于故障恢复入口，日常浏览不使用该路径。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#netbox)。
@@ -67,3 +67,5 @@ Terraform 使用 OCI Object Storage 的既有远端 state，认证依赖本机 O

 恢复设计和接管历史见 `infrastructure/oci/README.md`，网络维护及私钥边界见 `ansible/README.md`。
 不把旧 state 恢复步骤、迁移收尾 playbook 或历史验证命令当作每次登录前要执行的初始化。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#oci)。
@@ -84,3 +84,5 @@ Dynamic Runner 提供执行环境和 workload 身份，具体向 OpenBao 请求
 `infrastructure/openbao/README.md`。服务依赖主机持久存储及 Raft 数据，人的登录还依赖 Authelia。
 根密钥与恢复身份不应依赖 Kubernetes 或只能由 OpenBao 自身解密的秘密；
 日常登录成功不等于已完成备份或灾难恢复验收。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#openbao)。
@@ -74,3 +74,5 @@ StorageClass 配置 `WaitForFirstConsumer`，PVC 在没有可调度消费者时
 运维与 break-glass 入口为 `platform/openebs/README.md`。
 StorageClass 独立于 Helm release 管理；不要通过卸载 chart、删除 CRD 或业务卷验证升级。
 依赖包括 OpenEBS ZFS CSI、宿主 ZFS、文件系统与 Kubernetes 调度。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#openebs)。
@@ -98,3 +98,5 @@ HTTP 成功之外，还要检查各次响应中的应用状态与错误信息；
 连接失败核对宿主端口；导入失败区分来源可达性与解析；任务卡住或结果缺失再查看 VLM、embedding
 与队列处理。数据在 `./data`，模型缓存可重新下载，两者不能按同一种可丢弃缓存处理。
 部署、模型初始化与认证维护回到 `apps/openviking/README.md`。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#openviking)。
@@ -74,3 +74,5 @@ PVE 主机存储、DRBD 副本和 k3s 的 [OpenEBS](openebs.md) 是不同管理
 故障入口依次为目标任务日志、guest、宿主节点、存储和集群网络；
 涉及 quorum、fencing 或 watchdog 的处理先读 `README-ha.md`，不要套用普通单机重启排障。
 长期配置入口为 `infrastructure/proxmox/ansible/`，并按实际变更选择对应 playbook。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#proxmox)。
@@ -45,3 +45,5 @@ last_verified: null
 Compose 的 `USER_ID` / `GROUP_ID` 控制容器读文件时的身份；调整前核对宿主所有权，
 不要为排障递归修改整个存储池的权限。挂载目录属于内容数据，重建容器不会替代数据备份。
 依赖为 Docker、宿主存储、网络和相容客户端；本页不修改容器或数据目录。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#ps3netsrv)。
@@ -76,3 +76,5 @@ sudo samba-tool group listmembers YOUR_GROUP

 域备份、第二域控和恢复方案回到源码 README；有备份命令不代表已建立定时异机备份或演练过恢复。
 域控身份数据库与应用数据不同，不能通过重跑建域、清空数据库来排查普通登录失败。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#samba-ad)。
@@ -83,3 +83,5 @@ zot 的 S3 身份只允许相应 bucket 的 Read/Write/List/Tagging，不能访
 部署与配置来源：homelab-infra `apps/seaweedfs/README.md`、`apps/zot/README.md`。
 单一存储系统内的数据副本不等于独立备份；zot 源文档尚未记录已建立独立异机/离线备份。
 其他应用的数据保留与恢复策略应由各自用途明确，不能从“已接入 S3”推断已经完成备份。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#seaweedfs)。
@@ -78,3 +78,5 @@ AI 接续任务时先确认操作范围，再执行现场查询；不能因为
 源码入口为 homelab-infra 的 `apps/shared-postgresql/migration.md`、
 `cloudnativepg-cluster.yaml` 和 `shared-postgresql-service.yaml`（后两者位于同一目录）。
 服务依赖 Kubernetes、CNPG、集群 DNS 与持久存储；Tailscale 入口另依赖对应网络及授权。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#shared-postgresql)。
@@ -72,3 +72,5 @@ refresh token 持久化在 `smtp-relay-tokens` PVC，SASL 层负责更新；
 初始化、重新授权、DKIM 与恢复入口为 `apps/smtp-relay/README.md`。
 其中 DKIM 等日期属于历史记录，本文不将其升级为新一次验证。
 依赖为 Kubernetes/DNS、token PVC、Microsoft 365 邮箱与授权、上游网络及域名邮件配置。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#smtp-relay)。
@@ -60,3 +60,5 @@ IP 可达而域名失败时，先查看远程客户端 DNS 路径，不直接改
 依赖为 Tailscale 控制与数据路径、laptop 转发及目标网络；SDN 另依赖 VyOS/OSPF，
 operator Service 另依赖 Kubernetes 和 operator。
 本页没有记录 tailnet OAuth、设备密钥或凭据内容。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#tailscale)。
@@ -39,3 +39,5 @@ cscript.exe "$env:SystemRoot\System32\slmgr.vbs" /dlv
 依赖为 Docker 与客户端到宿主的网络。所读 Compose 未声明持久卷；
 这只描述此服务配置，不代表客户端状态可以随意清除。
 维护配置入口为 homelab-infra `apps/vlmcsd/compose.yaml`。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#vlmcsd)。
@@ -81,3 +81,5 @@ zot 的持久数据在 SeaweedFS `zot` bucket 的 `registry/` 前缀；zot Pod
 不能将同一 SeaweedFS 的副本视为独立灾备；重装 zot 不得删除该 bucket。

 部署、授权变更、凭据轮换及验收细节以 homelab-infra `apps/zot/README.md` 为准。
+
+来源文件的固定版本与工作区差异见[来源追溯](../sources.md#zot)。
@@ -0,0 +1,237 @@
+---
+title: 使用指南来源追溯
+last_reviewed: 2026-09-16
+---
+
+# 使用指南来源追溯
+
+这份索引帮助读者打开使用指南所依赖的源码，并区分可复现版本与工作区材料。
+2026-09-16 对照的是 homelab-infra 本地已有 `origin/main` 对应的
+[提交 `5ba4411`](https://git.ddupan.top/panxiao81/homelab-infra/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5)。
+本轮没有 fetch、查询服务或修改原仓库；它不是“此刻远端最新版本”的保证。
+
+只对明确列出的来源文件比较 Git blob 与工作区文件哈希，未复制秘密内容或访问运行凭据。
+下表是本次文件来源核对，不追认旧指南编写时的内容完全一致，也不验证部署结果。
+
+| 标记 | 如何使用链接 |
+|---|---|
+| 内容一致 | 固定版本与本次工作区文件一致，可用来复现该文件内容 |
+| 工作区有差异 | 链接只供比较已提交基线，不能证明工作区新增内容已合并 |
+| 该提交未收录 | 不编造远端文件链接，仍按指南注明的工作区路径读取 |
+
+共核对 62 个不同文件：内容一致 44，工作区有差异 12，该提交未收录 6。
+某文件本地显示 untracked，不代表它一定不存在于别的分支；以这里指定提交的树为比较对象。
+查更新资料可从 [homelab-infra](https://git.ddupan.top/panxiao81/homelab-infra) 进入，但不要把旧固定链接当实时状态。
+
+维护者说明、独立项目 README、SPIRE ticket 和历史 PR 仍以各页直接链接为准。
+本索引只补 homelab-infra 中近期使用指南的主要来源，不替代每页证据范围。
+
+## gitea
+
+[返回使用指南](services/gitea.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/gitea/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/gitea/README.md) |
+| `platform/gitea-runner/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/gitea-runner/README.md) |
+
+## grafana
+
+[返回使用指南](services/grafana.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `platform/observability/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/observability/README.md) |
+| `platform/observability/grafana/values.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/observability/grafana/values.yaml) |
+
+## zot
+
+[返回使用指南](services/zot.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/zot/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/zot/README.md) |
+
+## seaweedfs
+
+[返回使用指南](services/seaweedfs.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/seaweedfs/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/seaweedfs/README.md) |
+| `apps/zot/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/zot/README.md) |
+
+## openbao
+
+[返回使用指南](services/openbao.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `infrastructure/openbao/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/openbao/README.md) |
+
+## netbox
+
+[返回使用指南](services/netbox.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/netbox/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/netbox/README.md) |
+| `apps/netbox/terraform/topology.yml` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/netbox/terraform/topology.yml) |
+
+## shared-postgresql
+
+[返回使用指南](services/shared-postgresql.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/shared-postgresql/migration.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/shared-postgresql/migration.md) |
+| `apps/shared-postgresql/cloudnativepg-cluster.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/shared-postgresql/cloudnativepg-cluster.yaml) |
+| `apps/shared-postgresql/shared-postgresql-service.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/shared-postgresql/shared-postgresql-service.yaml) |
+
+## litellm-gateway
+
+[返回使用指南](services/litellm-gateway.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/litellm-gateway/docker-compose.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/litellm-gateway/docker-compose.yml) |
+| `apps/litellm-gateway/config.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/litellm-gateway/config.yaml) |
+
+## tailscale
+
+[返回使用指南](services/tailscale.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/tailscale/subnet-routes.sh` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/tailscale/subnet-routes.sh) |
+
+## ps3netsrv
+
+[返回使用指南](services/ps3netsrv.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/ps3netsrv/docker-compose.yml` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/ps3netsrv/docker-compose.yml) |
+
+## vlmcsd
+
+[返回使用指南](services/vlmcsd.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/vlmcsd/compose.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/vlmcsd/compose.yaml) |
+
+## external-secrets
+
+[返回使用指南](services/external-secrets.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `platform/external-secrets/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/external-secrets/README.md) |
+| `platform/external-secrets/clustersecretstore.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/external-secrets/clustersecretstore.yaml) |
+| `platform/external-secrets/externalsecrets.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/external-secrets/externalsecrets.yaml) |
+| `platform/external-secrets/kustomization.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/external-secrets/kustomization.yaml) |
+
+## openebs
+
+[返回使用指南](services/openebs.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `platform/openebs/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/openebs/README.md) |
+| `platform/openebs/storageclasses.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/openebs/storageclasses.yaml) |
+
+## k3s-dns
+
+[返回使用指南](services/k3s-dns.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `platform/k3s/Corefile.desired` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/k3s/Corefile.desired) |
+| `platform/k3s/coredns-custom.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/k3s/coredns-custom.yaml) |
+
+## marker
+
+[返回使用指南](services/marker.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/marker/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/marker/README.md) |
+| `apps/marker/Dockerfile` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/marker/Dockerfile) |
+| `apps/marker/deployment.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/marker/deployment.yaml) |
+| `apps/marker/service.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/marker/service.yaml) |
+
+## openviking
+
+[返回使用指南](services/openviking.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/openviking/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/openviking/README.md) |
+| `apps/openviking/docker-compose.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/openviking/docker-compose.yml) |
+
+## smtp-relay
+
+[返回使用指南](services/smtp-relay.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `apps/smtp-relay/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/smtp-relay/README.md) |
+| `apps/smtp-relay/service.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/smtp-relay/service.yaml) |
+| `apps/smtp-relay/deployment.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/smtp-relay/deployment.yaml) |
+
+## samba-ad
+
+[返回使用指南](services/samba-ad.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `infrastructure/samba-ad/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/README.md) |
+| `infrastructure/samba-ad/ansible/join-windows.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/ansible/join-windows.yml) |
+| `infrastructure/samba-ad/ansible/join-member.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/ansible/join-member.yml) |
+| `infrastructure/samba-ad/ansible/roles/samba_member/tasks/main.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/ansible/roles/samba_member/tasks/main.yml) |
+
+## oci
+
+[返回使用指南](services/oci.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `infrastructure/oci/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/oci/README.md) |
+| `infrastructure/oci/ansible/README.md` | 该提交未收录 | — |
+| `infrastructure/oci/terraform/providers.tf` | 该提交未收录 | — |
+| `infrastructure/oci/terraform/versions.tf` | 该提交未收录 | — |
+| `infrastructure/oci/terraform/compute.tf` | 该提交未收录 | — |
+| `infrastructure/oci/terraform/amd.tf` | 该提交未收录 | — |
+
+## proxmox
+
+[返回使用指南](services/proxmox.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `infrastructure/proxmox/README.md` | 该提交未收录 | — |
+| `infrastructure/proxmox/README-ha.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/proxmox/README-ha.md) |
+| `infrastructure/proxmox/ansible/auth.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/proxmox/ansible/auth.yml) |
+| `infrastructure/proxmox/ansible/site.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/proxmox/ansible/site.yml) |
+| `infrastructure/proxmox/ansible/ha.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/proxmox/ansible/ha.yml) |
+
+## publish-service
+
+[返回使用指南](guides/publish-service.md)
+
+| 源码路径 | 与工作区比较 | 提交链接 |
+|---|---|---|
+| `platform/cert-manager/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/cert-manager/README.md) |
+| `platform/cert-manager/certificate-wildcard-ad.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/cert-manager/certificate-wildcard-ad.yaml) |
+| `platform/envoy-gateway/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/envoy-gateway/README.md) |
+| `platform/envoy-gateway/gateway.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/platform/envoy-gateway/gateway.yaml) |
+| `infrastructure/dns/README.md` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/dns/README.md) |
+| `infrastructure/dns/records.yml` | 工作区有差异 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/dns/records.yml) |
+| `infrastructure/samba-ad/ansible/provision-dc.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/ansible/provision-dc.yml) |
+| `infrastructure/samba-ad/ansible/roles/samba_ad_dc/tasks/dns_records.yml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/infrastructure/samba-ad/ansible/roles/samba_ad_dc/tasks/dns_records.yml) |
+| `apps/netbox/securitypolicy.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/netbox/securitypolicy.yaml) |
+| `apps/netbox/networkpolicy.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/netbox/networkpolicy.yaml) |
+| `apps/authelia/referencegrant-extauth.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/authelia/referencegrant-extauth.yaml) |
+| `apps/gitea/httproute.yaml` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/apps/gitea/httproute.yaml) |
+| `clusters/homelab/README.md` | 内容一致 | [固定版本](https://git.ddupan.top/panxiao81/homelab-infra/src/commit/5ba441164661bdff24700595e0e6cd7ddb33eec5/clusters/homelab/README.md) |