diff --git a/AGENTS.md b/AGENTS.md index ff58dbc..8abc673 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ - 区分设计、配置、部署记录与现场验证。没有访问现场，不得写“运行正常”。 - 查询服务或项目状态前先问维护者：哪些工作正在动态进行、由哪个 ticket 跟踪、哪些现状尚未记录。已有明确授权的范围无需重复询问；不能从一个项目扩大到其他项目或现场查询。 - 维护者指定 ticket 为依据时，先读正文和讨论，区分已完成阶段与开放的后续范围。issue open 不等于尚未部署，README 与 ticket 不同也不能立即认定为运行异常。 +- Samba AD、OCI、Proxmox 已获维护者明确指定为 IaC 优先：以 Ansible/Terraform 代码为配置依据，README 为解释。此范围内读取仓库配置无需再次询问；现场查询仍按授权范围处理，不能把代码声明当作部署验收。 - 修改前读取对应源码 README/runbook；需要现场核实时先取得维护者对范围的确认。发现差异先记录来源，不能自行把计划升级为事实。 - 新增服务同时补用途、入口、登录方式、第一次使用示例、依赖和故障入口。 - 改变行为、入口、依赖、状态或恢复方法时，在同一任务更新对应文档与服务索引。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19a8876..5d1e036 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,9 @@ 2026-09-16 维护者指定 SPIFFE/SPIRE 基本以 homelab-infra #34 的记录为依据； 本轮仅查该 ticket 及其直接引用的 runbook，没有查询现场。其他项目仍需先询问。 +2026-09-16 维护者指定 Samba AD、OCI、Proxmox 优先 IaC、以代码为准。 +可直接核对其仓库中的配置与任务，README 与代码不一致时优先解释代码；此授权不等于现场变更或验收。 + 稳定设计与使用方法放知识库，动态进度链接到 ticket。知识库只保留注明查阅日期的阶段摘要， 不复制维护第二份实时任务列表。issue open 可能表示后续阶段未完成，不能据此推断基础服务未部署。 diff --git a/README.md b/README.md index 47d95ca..d16583a 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ ## 从这里开始 +- [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。 diff --git a/architecture/constraints.md b/architecture/constraints.md index 5dcbc3f..72bf24f 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -5,6 +5,7 @@ | 约束 | 原因与边界 | 来源 | |---|---|---| +| Samba AD、OCI、Proxmox 优先 IaC，以代码为准 | Ansible/Terraform 声明及任务优先于旧 README；声明不等于已验证部署 | 维护者于 2026-09-16 明确、各服务使用指南 | | 服务独立部署，Terraform root/state 按服务隔离 | 避免认证和变更影响范围绑在一起 | `AGENTS.md`、`CLAUDE.md` | | OpenBao 恢复不能依赖 k3s 或读取自己内部的恢复凭据 | 先恢复信任根，再恢复消费者 | `infrastructure/openbao/README.md`、`CLAUDE.md` | | Terraform 管 API 配置，Ansible 管主机及不能安全纳管的密钥材料 | 不可读回秘密和根密钥不能靠反复重建实现收敛 | `infrastructure/openbao/README.md` | diff --git a/documentation-backlog.md b/documentation-backlog.md index 4de23ac..0324cc2 100644 --- a/documentation-backlog.md +++ b/documentation-backlog.md @@ -21,11 +21,14 @@ - [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)：已有资料中的日常管理路径，动态状态未重查。 + 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。 ## 后续使用说明 -1. Samba AD、OCI、Proxmox：按已有来源补日常管理入口，涉及动态状态前先对齐维护者。 +本轮列出的使用指南已补齐。后续以实际接入任务补充细节，不自动启动全量现场检查。 +Samba AD、OCI、Proxmox 已按维护者指定采用 IaC 优先、以代码为准，并核对关键配置入口；未查询现场。 codex-proxy 已按维护者“应该是退役的”的说明移至归档范围，不再补新接入指南。 LiteLLM、Tailscale、ps3netsrv、vlmcsd 与 k3s 的 wiki 指南已补；源码目录仍缺根 README，配置入口已在各页列出。 @@ -34,4 +37,5 @@ LiteLLM、Tailscale、ps3netsrv、vlmcsd 与 k3s 的 wiki 指南已补；源码 - 源码仓库中 Authelia OIDC、LAN DNS、SPIRE 的旧说明后续与知识库结论同步。 - cert-manager / Envoy Gateway README 的 DNS 修改入口仍写旧变量，待同步为受管 records.yml 流程。 +- Proxmox README 的早期身份方案与 runner bootstrap 描述待与当前 SPIFFE 原则对齐；Samba README 的通用示例域名/地址待清理。 - 未提交工作区来源合并后，补充正式 commit/PR 链接。 diff --git a/services/index.md b/services/index.md index 2396bcf..d192332 100644 --- a/services/index.md +++ b/services/index.md @@ -55,10 +55,10 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 | 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（历史目录名） | 动态 runner 的 homelab 基础设施记录 | 当前项目接口见 [Dynamic Runner](gitea-dynamic-runner.md) | 独立项目已更名并扩展到 Pod/VM，正在积极开发 | `infrastructure/microvm-runner/README.md`、独立项目文档 | 具体启用范围和实现进度以独立项目文档为准 | -| oci | 云主机、网络与站点互联 | `OCI ap-osaka-1` | 有恢复、接管与网络实施记录 | `infrastructure/oci/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` | 已有登录、取密与运维入口指南 | -| 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) | 补入域和日常管理入口 | +| [proxmox](proxmox.md) | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施；README 混有设计设想 | `infrastructure/proxmox/README.md` | 已有管理入口；历史身份设想与当前原则分开 | +| [samba-ad](samba-ad.md) | AD 身份、域 DNS 与域成员管理 | `dc1 / 192.168.10.5` | 有部署记录；维护者说明 DNS 部分已完成 | `infrastructure/samba-ad/README.md`、[LAN DNS](lan-dns.md) | 已有入域、目录浏览与日常管理入口 | ## 集群 diff --git a/services/oci.md b/services/oci.md new file mode 100644 index 0000000..25828bb --- /dev/null +++ b/services/oci.md @@ -0,0 +1,69 @@ +--- +title: OCI 登录与维护入口 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# OCI 云上基础设施 + +OCI 部分由独立 Terraform root 管理云 API 资源，实例内的软件与网络配置由 Ansible 管理。 +本页仅提取 homelab-infra 工作区 `infrastructure/oci/README.md` 与 `ansible/README.md` +中已有的使用路径，不查询云资源、SSH、WireGuard 或 BGP 状态。 +已核对 Terraform 的 OCI backend、provider profile 与两台实例的 `prevent_destroy` 声明。 +README 有工作区修改，Ansible/Terraform 目录包含尚未提交内容；正式版本来源仍需补全。 + +维护者于 2026-09-16 明确：本组件优先 IaC，以代码为准。Ansible/Terraform 的声明及任务 +是配置依据，README 负责解释；代码存在不等于本轮已验证部署结果。 + +## 第一次登录 + +源码记录大阪区域 `ap-osaka-1`，提供两个 DNS 登录入口： + +```bash +ssh ubuntu@oci-arm.ddupan.top +ssh ubuntu@oci-amd.ddupan.top +``` + +选择自己获准访问的实例，用既有 SSH agent/key 登录；不复制私钥或禁用 host-key 校验。 +以上名称对应直连公网 A 记录，不能当成 Cloudflare HTTP 代理入口。 +实际权限、主机密钥与登录成功情况本轮未验证；首次使用从维护者取得可信主机信息。 + +DNS 记录的声明源为 `infrastructure/dns/records.yml`。 +源 README 记录 DNS 尚未纳入 OCI Terraform state，公网 IP 变更时需协调更新记录， +不能认为修改实例就自动完成 DNS 同步。 + +## 访问家中网络与 DN42 + +站点网络细节统一查阅 `infrastructure/oci/ansible/README.md`，其中包含 VyOS、OCI AMD、 +WireGuard、BGP 和 DN42 的地址、过滤与检查步骤。本页不维护第二份邻居或路由实时清单。 + +使用已有网络的应用无需自行创建 WireGuard peer 或修改 BGP。 +遇到私网不可达，先区分 DNS、目标服务、路由、隧道与过滤；隧道握手成功不代表业务前缀已安装。 +内部家中/OCI 业务前缀不得通告给外部 DN42 邻居，不能为临时接通扩大所有前缀的 export 规则。 +Docker 地址池还须避开 DN42 `172.20.0.0/14`，相关记录见 `infrastructure/docker/README.md`。 + +## 管理变更走哪个入口 + +| 修改内容 | 原有管理入口 | +|---|---| +| 实例、VCN、NSG、云路由等 API 对象 | `infrastructure/oci/terraform/` | +| 主机/路由器软件、隧道及 BGP 配置 | `infrastructure/oci/ansible/` | +| DNS 名称 | `infrastructure/dns/records.yml` 与所属 DNS 后端 | + +Terraform 使用 OCI Object Storage 的既有远端 state，认证依赖本机 OCI profile。 +新 checkout 按源 README 准备受限 metadata 输入后才能 plan，不能复制 wiki 中不存在的“通用 tfvars”。 +恢复目录的 state 副本不作为日常 backend，也不能上传覆盖远端对象。 + +维护者审查 plan 或 Ansible check/diff 后再实施对应变更；plan/state/metadata 可能包含秘密，不进 Git 或公开文档。 +保留实例 `prevent_destroy`，遇到替换计划先查原因，不能为了让 apply 通过直接移除保护。 +所读 README 的历史配额与免费机型检查不是持续费用保证，新增资源时另行核对。 + +## 恢复与依赖 + +实例登录依赖 DNS、公网路径、SSH 授权与主机；站点访问另依赖家中路由器、云端网络规则和路由协议。 +云 API 状态正常与客户机内部服务正常是不同层面的证据。 + +恢复设计和接管历史见 `infrastructure/oci/README.md`，网络维护及私钥边界见 `ansible/README.md`。 +不把旧 state 恢复步骤、迁移收尾 playbook 或历史验证命令当作每次登录前要执行的初始化。 diff --git a/services/proxmox.md b/services/proxmox.md new file mode 100644 index 0000000..6f0e1cc --- /dev/null +++ b/services/proxmox.md @@ -0,0 +1,76 @@ +--- +title: Proxmox 日常管理入口 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# Proxmox + +Proxmox 承载 VM/LXC 与相应主机、网络和存储资源。 +本页依据 homelab-infra 工作区 `infrastructure/proxmox/README.md`、`README-ha.md` +及已有 DNS 名称整理使用入口，不检查集群成员、VM、HA 或存储现场状态。 +源码 README 尚未跟踪，HA 文档有工作区修改；配置已进一步核对 `auth.yml`、`site.yml`、 +`ha.yml` 与对应 role defaults，不将文档中的历史阶段备注当作当前配置。 + +维护者于 2026-09-16 明确：本组件优先 IaC，以代码为准。Ansible/Terraform 的声明及任务 +是配置依据，README 负责解释；代码存在不等于本轮已验证部署结果。 + +## 打开管理界面 + +DNS 清单记录 `pve1.ad.ddupan.top`、`pve2.ad.ddupan.top`、`pve3.ad.ddupan.top`。 +Proxmox 默认 HTTPS 管理端口是 `8006`，因此可按维护者确认的节点尝试： + +```text +https://pve1.ad.ddupan.top:8006/ +``` + +这是节点名与上游默认端口组合出的入口示例，未验证可达性或证书配置。 +端口与节点代理行为见 [Proxmox pveproxy 文档](https://github.com/proxmox/pve-docs/blob/master/pveproxy.adoc)。 +`pve_auth` role 声明 `ad` realm，通过 LDAPS 连接 `dc1.ad.ddupan.top:636`，启用证书校验； +域用户按此配置选择 `ad` realm，实际可用权限取决于账号同步及 ACL。`auth.yml` 独立管理该配置。 +`pve_acme` role 使用 OpenBao 内部 CA 为节点域名签证书，浏览器需具有相应 CA 信任。 +这些是代码声明，不是新的登录验证；不能因 Authelia 是 Web SSO 主入口就推断 PVE 已接入 OIDC。 + +## 第一次定位一台虚拟机 + +1. 登录后在资源树中找到目标 VM/LXC，核对名称、VMID 和所在节点。 +2. 查看 Summary 与任务记录，区分 guest 状态、节点状态和最近操作结果。 +3. 查看 Hardware/Resources 与网络、磁盘配置，确认对应的业务服务。 +4. 需要 guest 内部诊断时，再按授权使用 Console 或该 guest 的 SSH 入口。 + +VMID 可能被复用，不能仅凭一个旧 VMID 判断当前对象归属。 +控制台可打开也不等于客户机网络、存储和业务健康。 +启动、关闭、迁移、克隆及删除都是独立变更，不作为“查看状态”的附带动作。 + +## 持久配置与短命 VM 的职责 + +源目录使用 Ansible 管理节点软件、内核、网络、LINSTOR/DRBD 与 watchdog 等主机配置。 +VM 和集群对象的具体管理工具以对应目录为准，不把迁移到 Terraform 的设想写成全部完成。 +UI 中临时改动需回写对应受管来源，避免后续自动化覆盖。 + +动态 CI VM 的使用接口见 [Gitea Dynamic Runner](gitea-dynamic-runner.md)， +其生命周期由 runner controller 负责，不能逐台登记进长期 Terraform state。 +每个动态 Pod/VM 应独立取得 SPIFFE 身份；workflow 决定登录与请求 token。 +源码 README 的 SDN-backed identity 和 AppRole bootstrap 段落属于早期设计记录， +不作为当前统一身份原则或最新 runner 实现的依据。 + +## 网络、HA 与存储边界 + +现有设计记录中的 VLAN/VNet 分段不能直接证明 guest 的机器身份； +IP、MAC、VMID 的自报值不能代替可信身份验证。 +修改 bridge、SDN 或路由 guest 时，先明确承载哪些业务与管理路径，不能只看当前登录是否仍连通。 + +`README-ha.md` 记录了 VyOS guest 的 HA 和 watchdog 工作。它描述的是故障后重新启动的路径， +不应承诺无中断切换，也不能推断其他 guest 全部启用 HA。 +`pve_ha` role 的资源默认值只列 `vm:100`，`ha.yml` 独立于节点基线 `site.yml`， +避免基线维护顺带改变 HA/fencing 行为。watchdog 的实际选择还需结合 inventory 覆盖与任务实现； +本轮不从旧 README 的 softdog 标题推断当前现场状态。 + +PVE 主机存储、DRBD 副本和 k3s 的 [OpenEBS](openebs.md) 是不同管理层， +不能互相替代容量、冗余或恢复验证。快照和副本也不能自动证明具备独立备份。 + +故障入口依次为目标任务日志、guest、宿主节点、存储和集群网络； +涉及 quorum、fencing 或 watchdog 的处理先读 `README-ha.md`，不要套用普通单机重启排障。 +长期配置入口为 `infrastructure/proxmox/ansible/`，并按实际变更选择对应 playbook。 diff --git a/services/samba-ad.md b/services/samba-ad.md new file mode 100644 index 0000000..ab191a8 --- /dev/null +++ b/services/samba-ad.md @@ -0,0 +1,78 @@ +--- +title: Samba AD 日常使用入口 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# Samba Active Directory + +Samba AD 提供人的目录身份、Kerberos、LDAP、域 DNS 和组策略； +[Authelia](authelia.md) 在此之上提供 Web 登录，[SPIFFE](spire.md) 负责 workload 身份。 +AD 组成员资格与每个服务最终授予的权限仍需分别配置。 + +本页根据 homelab-infra 工作区 `infrastructure/samba-ad/README.md` 整理。 +已核对 Ansible 的域变量、`join-windows.yml`、`join-member.yml` 与 member role 任务。 +这些来源含未提交修改；没有查询域成员、用户或现场配置。 +DNS 的已确认口径见 [LAN DNS](lan-dns.md)，不重新盘点主机。 + +维护者于 2026-09-16 明确：本组件优先 IaC，以代码为准。Ansible/Terraform 的声明及任务 +是配置依据，README 负责解释；代码存在不等于本轮已验证部署结果。 + +## 域与管理入口 + +| 项目 | 已有资料中的值 | +|---|---| +| DNS domain | `ad.ddupan.top` | +| Kerberos realm | `AD.DDUPAN.TOP` | +| NetBIOS domain | `DDUPAN` | +| 域控 | `dc1.ad.ddupan.top` / `192.168.10.5` | +| 图形管理 | Windows 管理机上的 RSAT：AD Users & Computers、GPMC、DNS | + +管理机地址与登录身份由维护者提供。日常 Web 登录从对应应用进入 Authelia， +无需登录域控，也不向普通应用交付 Domain Administrator 凭据。 + +## 入域之前与入域路径 + +入域设备需要准确时间、域控连通性和能找到 AD SRV 记录的 DNS 路径。 +不能直接照抄源 README 通用示例中的 `10.10.10.10`、`ad.example.com` 或 `EXAMPLE`。 +也不要为入域统一改写所有 LAN 主机 DNS；按该设备的域解析需求配置，保留既有 LAN 设计。 + +Windows 管理机按 `infrastructure/samba-ad/ansible/` 的 inventory 与 `join-windows.yml` +管理，先核对目标主机、WinRM 与所用账号，再由维护者执行入域流程。 +README 的手工命令用于解释角色行为，不是重新建域的日常操作步骤。 + +Linux 的 `join-member.yml` 面向 Samba member fileserver：它配置 winbind、NSS、SMB 与域解析， +明确不安装 `libpam-winbind`。因此文件服务器入域成功不等于已经启用 Linux 系统域账号登录。 +修改前阅读角色对现有 `smb.conf`、共享与 UID/GID 映射的处理，不能将普通客户端套成文件服务器。 + +## 第一次查看用户与组 + +在已获管理授权的域控会话中，可使用以下只读命令；`YOUR_GROUP` 替换为目标组： + +```bash +sudo samba-tool user list +sudo samba-tool group listmembers YOUR_GROUP +``` + +也可在 RSAT 的 AD Users & Computers 中查找用户，打开其组成员关系。 +命令语义见 [Samba samba-tool 手册](https://www.samba.org/samba/docs/current/man-html/samba-tool.8.html)。 +输出含账号信息，按任务范围使用，不把完整人员目录复制进公开 wiki。 +本轮没有执行这些命令。 + +新增用户、组、权限或重置密码会改变目录状态，按现有 Ansible 声明或维护流程实施， +避免 UI 临时改动与下一次配置同步互相覆盖。密码通过受控交互或秘密管理提供，不写进命令示例。 +应用权限排障先核对 AD 组，再核对 Authelia 策略与应用内映射。 + +## 故障与维护边界 + +入域失败先区分 DNS/SRV、时间、连通性与账号权限；已有成员认证异常再看信任关系及 winbind。 +`runbook-winbind-rpcd.md` 保存 laptop 文件服务器的相关排障记录，不将该问题直接套用所有成员。 + +静态 DNS 声明入口为 `infrastructure/dns/records.yml`，只管理明确列出的 RRset， +不清理 Samba 自动维护的域控制器 locator、Kerberos 等记录。 +新服务 DNS 接入见[发布新服务](../guides/publish-service.md)。 + +域备份、第二域控和恢复方案回到源码 README；有备份命令不代表已建立定时异机备份或演练过恢复。 +域控身份数据库与应用数据不同，不能通过重跑建域、清空数据库来排查普通登录失败。 diff --git a/verification.md b/verification.md index 7bcb518..b65ccbd 100644 --- a/verification.md +++ b/verification.md @@ -44,6 +44,9 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom ## 已确认的归属与范围 +- 维护者于 2026-09-16 指定 Samba AD、OCI、Proxmox 优先 IaC、以代码为准； + 后续可直接核对仓库配置，不重复询问同一资料范围。配置声明与现场验证仍分开记录。 + - 维护者于 2026-09-16 说明 codex-proxy“应该是退役的”，已从现役应用列表移至归档范围； 未查询运行环境，也没有删除源码或数据。LiteLLM、Tailscale、ps3netsrv、vlmcsd 无需补充动态事项， 已基于仓库配置补使用指南；这不等于新增的现场验收。