补充 OpenBao 与 NetBox 日常使用指南

README.md

@@ -9,6 +9,8 @@
 - [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 入口。
 - [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
 - [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。

documentation-backlog.md

@@ -10,13 +10,14 @@
 - [zot](services/zot.md)：拉取、发布授权、workflow 身份职责与后端数据恢复边界。
 - [SeaweedFS](services/seaweedfs.md)：S3 入口、专用凭据、列举与上传下载示例。
 
+- [OpenBao](services/openbao.md)：人的登录、按权限取密及机器身份边界。
+- [NetBox](services/netbox.md)：浏览设备与 IPAM，明确 Git 来源与评估用途。
+
 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
 
 ## 后续使用说明
 
-1. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。
+1. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
-2. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。
-3. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
 
 ## 文档同步与来源链接
 

services/index.md

@@ -22,7 +22,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 | 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` | 补面向浏览者的使用路径 |
+| [netbox](netbox.md) | 网络资产与地址管理评估 | `netbox.ad.ddupan.top` | 记录已部署；评估用途 | `apps/netbox/README.md` | 已有浏览与 Git 修改入口指南 |
 | openviking | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 缺导入、查询的完整例子 |
 | ps3netsrv | PS3 网络内容服务 | `未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 缺客户端使用与挂载说明 |
 | [seaweedfs](seaweedfs.md) | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 已有客户端读写指南与备份边界说明 |
@@ -57,7 +57,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 ap-osaka-1` | 有恢复、接管与网络实施记录 | `infrastructure/oci/README.md` | 补跨站点使用入口 |
-| openbao | 秘密管理与内部 CA | `bao.ad.ddupan.top` | 有部署与接管记录 | `infrastructure/openbao/README.md` | 补日常使用和恢复入口 |
+| [openbao](openbao.md) | 秘密管理与内部 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` | 有部署记录；维护者说明 DNS 部分已完成 | `infrastructure/samba-ad/README.md`、[LAN DNS](lan-dns.md) | 补入域和日常管理入口 |
 

services/netbox.md

@@ -0,0 +1,57 @@
+---
+title: NetBox 使用指南
+lifecycle: experimental
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# NetBox
+
+NetBox 用于浏览网络设备、接口与 IP 地址关系，目前是已部署的评估环境。
+权威拓扑保存在 homelab-infra 的 `apps/netbox/terraform/topology.yml`，NetBox 是它的派生镜像。
+已有配置生成试验，不代表真实网络已由 NetBox 自动驱动。
+
+本页依据工作区 `apps/netbox/README.md` 及相关设计记录整理；本轮没有登录或查询现场。
+
+## 打开与登录
+
+在能访问 LAN 的环境打开 [NetBox](https://netbox.ad.ddupan.top)，通过 Authelia 登录并完成二次认证。
+源码记录入口访问限制为 AD 的 `netbox-admins` 组；有 AD 账号本身并不足以获得访问权限。
+
+这里使用网关的 Authelia **forward-auth**，NetBox 接收经网关认证的用户与组信息。
+NetBox 没有独立的 OIDC client；不要因 Authelia 是主 OIDC broker 就替它配置另一套 OIDC 登录。
+正常使用从域名入口进入，不能绕过网关或自行构造 Remote-User 等身份头。
+
+## 第一次浏览设备与地址
+
+1. 在 Devices 列表中搜索要了解的设备，打开详情，查看角色、主要地址与 Interfaces。
+2. 从接口查看关联的 IP 地址；有连接记录时，再沿关联对象查看另一端。
+3. 在 IPAM 的 Prefixes 中搜索目标网段，例如源拓扑记录中的 `192.168.10.0/24`。
+4. 查看该前缀下的地址记录，再打开地址详情，确认其关联接口和设备。
+
+这条路径用于回答“这个地址记录给谁、接口属于哪台设备”等问题。
+NetBox 中的地址状态来自资产记录，不会自动证明主机在线、地址当前无占用或 DHCP 已下发。
+排查实时故障仍需相应运行证据；AI 查询现场前须按本库规则先与维护者对齐范围。
+对象概念可参考 [NetBox IPAM 文档](https://netbox.readthedocs.io/en/stable/features/ipam/)。
+
+## 发现记录需要修改时
+
+先在 Git 中修改 `apps/netbox/terraform/topology.yml`，由维护者按该目录 README
+审查 Terraform plan 并同步镜像；不要把 UI 编辑作为持久修改入口。
+镜像中的手工改动可能与下次同步冲突；从拓扑文件移除对象也可能在 plan 中产生删除，需审查影响。
+
+资产记录不保存 Wi-Fi 密码等秘密，凭据由 [OpenBao](openbao.md) 等既有秘密管理流程提供。
+面向 VyOS OSPF 与 Samba AD DNS 的生成脚本属于评估成果，运行生成器与实际应用网络配置是不同步骤；
+看到 NetBox 记录更新，不能宣称路由、DNS 或 DHCP 已同步。
+
+## 遇到问题先看哪里
+
+- 无法访问域名：检查 LAN DNS、路由及共享 Envoy 入口。
+- 登录后被拒绝：核对 Authelia 访问规则及 AD 组；不要通过直接访问后端绕过认证。
+- 记录缺失或不一致：对照 Git 拓扑和上一次同步记录，区分来源缺失与镜像尚未同步。
+- 数据库或应用异常：转到部署 README，检查对应依赖和恢复流程。
+
+部署、依赖、认证边界、拓扑同步与配置生成细节见 homelab-infra `apps/netbox/README.md`。
+应用使用数据库与 Redis，登录链路依赖 LAN DNS、Envoy、Authelia 和 Samba AD。
+本地管理员属于故障恢复入口，日常浏览不使用该路径。

services/openbao.md

@@ -0,0 +1,86 @@
+---
+title: OpenBao 使用指南
+lifecycle: active
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# OpenBao
+
+OpenBao 提供秘密管理与内部 CA，部署在 Kubernetes 之外的独立主机上。
+日常使用是以自己的身份登录，按已有 policy 读取秘密或申请短期凭据。
+
+本页依据 homelab-infra 工作区 `infrastructure/openbao/README.md` 整理，
+CLI 语法参考下列官方文档。本轮未登录服务、读取秘密或验证现场。
+
+## 人的登录入口
+
+前提是客户端能解析并访问内部域名，已安装 `bao` CLI，且账号具备相应 OIDC 授权。
+
+```bash
+export BAO_ADDR=https://bao.ad.ddupan.top:8200
+bao login -method=oidc -no-print
+```
+
+按提示通过浏览器进入 Authelia，完成登录和二次认证。
+使用域名进行 TLS 校验，不用 IP 地址代替，也不关闭证书校验。
+`-no-print` 避免显示 token，但成功登录后仍会把它存入本机 token helper，供后续命令使用。
+因此应在自己的受控会话中登录。参见 [OpenBao login](https://openbao.org/docs/commands/login/)。
+
+登录成功后，只查看当前会话的权限与有效期：
+
+```bash
+bao token lookup -field=policies
+bao token lookup -field=ttl
+```
+
+这两个命令不打印完整 token；字段选项见
+[token lookup](https://openbao.org/docs/commands/token/lookup/)。能登录不代表能读取任意秘密。
+
+## 按授权路径读取一个字段
+
+先由服务所有者提供准确的 mount、秘密路径和字段名。
+下例 `YOUR_AUTHORIZED_PATH` 是占位符，须替换为 `kv` mount 下已授权且存在的路径；
+`password` 也应替换为实际字段名。命令仅适合已获相应权限的会话。
+
+```bash
+set +x
+APP_PASSWORD="$(bao kv get -mount=kv -field=password YOUR_AUTHORIZED_PATH)"
+# 在当前会话中交给实际消费者；不要 echo，也不要放入命令行参数或日志。
+unset APP_PASSWORD
+```
+
+示例只演示接收字段后清除变量，不会配置任何应用；接入脚本还应检查命令失败并停止后续操作。
+`kv get` 会处理 KV 引擎的 API 路径，CLI 的相对路径无需自行插入 `data/`。
+参见 [OpenBao kv get](https://openbao.org/docs/commands/kv/get/)。
+
+Kubernetes 应用通常消费 ESO 投射的 Secret。修改秘密应通过其受管来源及对应服务的轮换流程，
+不能只编辑 ESO 生成的副本。不要把完整秘密内容粘贴到 AI 上下文、issue 或 wiki。
+
+## 机器身份的使用边界
+
+| 调用者 | 本库已记录的认证路径 |
+|---|---|
+| 人 | Authelia OIDC 登录 |
+| laptop 本地 AI agent | 独立客户端证书，cert auth role 为 `local-agent` |
+| SPIFFE workload | 按 [SPIRE 接入说明](spire.md) 与对应 OpenBao role 配置换取 token |
+
+源码记录的本地 agent 证书与私钥由 Ansible 安装在 `/etc/homelab-agent/openbao/`，
+不要复制到仓库或 workflow。其 token TTL 为 15 分钟、最长 1 小时；权限包括受限的 SSH 签名、
+自身证书续期及 `kv/agents/local/*`，明确不包含 `kv/k8s/*`。
+证书注册、登录与续期按源码 README 操作，不能从 SPIFFE 的整体设计推断该路径已迁移。
+
+SPIFFE 验证机器身份，OpenBao 自己签发 token 并维护 policy。
+Dynamic Runner 提供执行环境和 workload 身份，具体向 OpenBao 请求什么 token 由 workflow 决定。
+
+## 权限申请与故障入口
+
+申请权限时提供调用者身份、准确路径、所需动作、有效期及用途，由维护者调整受管 role/policy。
+遇到拒绝访问先核对上述信息及会话有效期，不用管理员 token 代替应用身份。
+连接失败时先区分内部 DNS、网络、TLS 与认证问题；OIDC 回调问题需结合客户端浏览器所在位置排查。
+
+部署、PKI、SSH 签名、本地 agent 身份和恢复细节见 homelab-infra
+`infrastructure/openbao/README.md`。服务依赖主机持久存储及 Raft 数据，人的登录还依赖 Authelia。
+根密钥与恢复身份不应依赖 Kubernetes 或只能由 OpenBao 自身解密的秘密；
+日常登录成功不等于已完成备份或灾难恢复验收。