文档地图）¶

由 docs/HANDOFF.md 第 5 节指针按需读取；只放「长期不变」的内容，变动内容在 HANDOFF。修订方式：定点修订，只改受影响行。拆分日期：2026-10-01（依据 writing-handoff 技能的稳定层约定）。

1. 环境事实【已确认】¶

项	值
宿主	`dell-R620`，单机、本机执行（`virsh qemu:///system`），不走 SSH
存储池	`hdd-pool`（target 路径 `/data/kvm/img`）、`ssd-pool`、`iso`；均 active
ISO	`/data/kvm/iso/Rocky-9-latest-x86_64-dvd.iso`、`CentOS-7-x86_64-DVD-1511.iso`
网络	桥 `br0` 静态 IP，网关与 DNS `192.168.31.2`；本工具不碰物理网络与 netplan
公钥	`/home/rain/.ssh/id_ed25519.pub`（guest 仅公钥登录，禁口令）
共享库	`/home/rain/py_public_modules/`（`base_module` 等），经 `.pth` 挂载
日志	Rocky 9：`logs/kvm-rocky9-deploy.log`；CentOS 7：`logs/kvm-centos7-deploy.log`
进程锁	`logs/kvm_rocky9_deploy.lock`（两入口共用）
宿主 CPU	仅支持 x86-64-v2，故 guest 必须用 Rocky 9（不能用更新的发行版）

IP / MAC 段占用¶

批次	IP	MAC 第五字节
k8s	`.10–15`	`0a`
slurm	`.16–20`	`0b`
lustre	`.21–22`	`0c`
lsf	`.23–27`	`0d`
rocky9-01	`.28`	`0e`
Flexlm	`.29`	`0e`
harbor-01	`.31`	`0f`
空闲	`.30`（原 centos7，随销毁释放）	`10` 起

2. 机制性陷阱¶

必须以 sudo 执行：漏加会在日志初始化阶段抛 PermissionError（logs/ 属 root），业务逻辑一行未执行、无副作用，补 sudo 重跑即可；诊断见 RUNBOOK 第 8 章场景 6。
三态探测：ProbeState(DONE/PENDING/UNKNOWN)；UNKNOWN（查不到）一律中止变更，不得当作「没有」。
两个入口共用同一进程锁：Rocky 9 与 CentOS 7 批次不能并发执行，属刻意保护（避免并发 virt-install 争抢宿主资源）。
utils/kvm_utils.py 是共享能力层，所有批次共用：改它之后须对全部配置各跑一次 --drift 回归。
config/credentials*.yaml 含明文 root 口令，已 gitignore，禁止提交或外传。
数据盘默认格式是 raw，会按名义容量在池内预占；需要稀疏时须显式写 format: qcow2。
数据盘分区须显式 --ondisk=vda（模板已固化）：否则当数据盘容量 ≥ 系统盘时，Anaconda 会把 / 建到数据盘上。

3. 命令速查（工程根目录下执行，需 root）¶

sudo .venv/bin/python main.py --precheck --config <cfg>   # 只读体检（CentOS 7 换 main_centos7.py）
sudo .venv/bin/python main.py --drift    --config <cfg>   # 只读漂移（0 无漂移）
sudo .venv/bin/python main.py --dry-run  --config <cfg>   # 预演，零系统改动
sudo .venv/bin/python main.py            --config <cfg>   # 真实执行
sudo .venv/bin/python main.py --rollback --force --config <cfg>  # 高危销毁
# <cfg> ∈ config/{deploy.yaml, hosts-20260918.yaml, lustre-20260921.yaml,
#          hosts-20260924-lsf.yaml, hosts-20260925-rocky9.yaml,
#          hosts-20260928-centos7.yaml, hosts-20261001-harbor.yaml}
virsh --connect qemu:///system list --all                  # 全部域
tail -n 50 logs/kvm-rocky9-deploy.log                      # Rocky 9 日志
tail -n 50 logs/kvm-centos7-deploy.log                     # CentOS 7 日志

4. 文档地图¶

文件	管什么
`runbook-20260925/RUNBOOK.md`	部署工具使用手册（12 章；第 8 章 6 个故障场景、第 12 章 CentOS 7 批次）
`.trae/skills/kvm-guest-preflight/`	项目级技能：跨发行版建机前预检与装后自检；下次适配新发行版先加载它
`harbor-20261001/SOP.md`	harbor-01 创建变更档案 + 范围外事项（Harbor 本体安装）
`centos7-20260928/SOP.md`	CentOS 7 适配变更档案 + 销毁实录
`centos7-perf-20261007/SOP.md`	建机执行效率复验与轮询间隔下沉（墙钟对照与归因）
`rocky9-20260925/SOP.md`	rocky9-01 创建变更档案
`lsf-20260924/SOP.md`	LSF 批次变更档案（含改造遗留事项登记）
`docs/SOP.md`、`docs/SOP-hosts-20260918.md`	k8s 与 slurm 批次旧 SOP；CLI 用法已过时（`--rollback` 现需 `--force`）
`config/deploy.yaml.example`	新批次配置模板（含全部可选项注释）
`main.py`、`deployer.py`、`config_schema.py`	Rocky 9 入口、生命周期编排与业务、配置校验
`main_centos7.py`、`deployer_centos7.py`、`templates/centos7/`	CentOS 7 入口、适配子类、专属 kickstart 模板
`utils/kvm_utils.py`	本工程私有工具：命令执行 + 三态探测
`build/plans/`、`build/reports/`	计划文件与只读报告（实现体产物，可清理）
各批次 `backup/README.md`	备份台账（`lsf-20260924`、`rocky9-20260925`、`centos7-20260928`、`harbor-20261001`）

来源：/home/rain/Documents/kvm/kvm_rocky9_deploy/docs/BASELINE.md ｜最后更新：2026-10-07 21:25（由 build/sync.py 同步，请勿在站点侧修改）