From 8f71414f5cbf6e4695f914998e2d34ebbcaa1f47 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Wed, 16 Sep 2026 16:35:17 +0000 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20OpenBao=20=E4=B8=8E=20NetB?= =?UTF-8?q?ox=20=E6=97=A5=E5=B8=B8=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + documentation-backlog.md | 7 ++-- services/index.md | 4 +- services/netbox.md | 57 ++++++++++++++++++++++++++ services/openbao.md | 86 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 151 insertions(+), 5 deletions(-) create mode 100644 services/netbox.md create mode 100644 services/openbao.md diff --git a/README.md b/README.md index db6583e..0abcd37 100644 --- a/README.md +++ b/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 两种一次性执行环境。 diff --git a/documentation-backlog.md b/documentation-backlog.md index 0738dc4..2964ecc 100644 --- a/documentation-backlog.md +++ b/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：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。 -2. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。 -3. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。 +1. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。 ## 文档同步与来源链接 diff --git a/services/index.md b/services/index.md index d3a6325..821f264 100644 --- a/services/index.md +++ b/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) | 补入域和日常管理入口 | diff --git a/services/netbox.md b/services/netbox.md new file mode 100644 index 0000000..0bce1ce --- /dev/null +++ b/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。 +本地管理员属于故障恢复入口，日常浏览不使用该路径。 diff --git a/services/openbao.md b/services/openbao.md new file mode 100644 index 0000000..6e0a1fd --- /dev/null +++ b/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 自身解密的秘密； +日常登录成功不等于已完成备份或灾难恢复验收。