SOP — lustre_ins 纳入 Git 版本管理并推送到 GitHub 私有仓库¶

主题目录 git-init/。变更对象：本工程 lustre_ins 的版本管理状态（新建 .git/、修订 .gitignore、重命名 venv 内 .pth），以及 GitHub 上新建的私有远程仓库 raincheny/lustre_ins。

本次未执行任何网络变更。用户初拟先把本机网关与 DNS 改为旁路网关 192.168.31.2，实测本机直连 GitHub 完全可用，故跳过（依据见 1.2）。

本次无实现体脚本（用户明确要求「正常跑命令、留 SOP 即可」），第 5 章即为实际执行的操作序列。

1. 背景¶

1.1 触发条件¶

本工程自 2026-09-22 起建设，此前没有 git 版本管理：仓库根已有 .gitignore，但从未执行 git init，所有代码与文档均无版本留痕。本次将其纳入版本管理，并推送到 GitHub 私有仓库，作为异地备份与变更追溯基础。

1.2 关于网络变更的决策（已跳过）¶

用户提示「旁路路由 192.168.31.2 具备海外 GitHub 访问能力」，要求先把本机（192.168.31.250）的网关与 DNS 改为 .2。执行前实测，本机当前即可直连 GitHub：

探测项	实测结果
`curl -sI https://github.com`	`200`
`curl -sI https://api.github.com`	`200`
`git ls-remote https://github.com/octocat/Hello-World`	成功返回 refs（退出码 0）
当前 DNS 上游	`192.168.31.1`、`223.5.5.5`

同时探明两处与初始描述不符的事实：

默认路由不在 eno2（.250）上，而在 br0（192.168.31.249），网关 192.168.31.1。改 .250 的网关并不等于改整机出口。
本机同时运行 KVM 相关网络（br0、virbr0），改默认网关与 DNS 的影响面是整机级，会波及本工程之外的虚拟机网络与域名解析。

结论：改网络既不必要、又引入整机风险，本次未执行。后续若确需旁路，须单独作为一次变更评估，并按第 8 章风险表处理。

2. 目标¶

变更完成后应达到以下可验证状态：

工程根存在 git 仓库，默认分支 main，首次提交完成
.gitignore 覆盖 .venv/、logs/、reports/*.md、任意层级 backup/ 下的备份内容、config/deploy.yaml、skill-*/、.trae/
忽略规则实测生效：上述路径均不被纳入提交
venv 内 .pth 更名为 py_public_modules.pth，与其余 10 个挂载工程及技能口径一致，import base_module 仍正常
私有远程仓库 raincheny/lustre_ins 建立，main 分支推送成功且与本地 HEAD 一致

3. 前置条件¶

项	要求	检查命令
SSH 凭据	本机公钥已作为 GitHub 账号 `raincheny` 的认证 key	`ssh -T git@github.com`（预期 `Hi raincheny! ...`）
git 版本	≥ 2.28（用到 `git init -b main`）	`git --version`
远程仓库	私有仓库 `raincheny/lustre_ins` 已存在（SSH 只能推送，不能创建仓库）	`git ls-remote git@github.com:raincheny/lustre_ins.git`
网络	直连 GitHub 可达	`curl -sI https://github.com`
提权	不需要（全部为普通用户操作）	—
在跑业务	无关：不触碰任何 Lustre 主机，不涉及 Slurm / LSF 节点	—

4. 影响范围¶

维度	说明
主机	操作机 `192.168.31.250`（本机）一台；不触达 `192.168.31.21` / `.22` / `.24` 等任何远端主机
组件	工程根 `.gitignore`（修订）；`.venv/lib/python3.12/site-packages/` 下 `.pth`（重命名）；新建 `.git/`；GitHub 私有仓库
受影响资产	`.gitignore` 净增 8 行、改 4 行；`.pth` 更名 1 处（`lib64` 为 `lib` 的软链，同一文件）；首次提交 37 个文件
是否停服	否。不触碰 `edafs` 文件系统，无客户端 IO 影响
窗口期	无限制
在跑业务	无
网络	未改动：默认路由与 DNS 保持原样
行为变化	工程内文件自此受版本控制；`.venv` 内共享库挂载方式不变，仅文件名变化

5. 分步操作¶

本次无实现体脚本，以下即为实际执行的等价操作序列，供复核与手工复现。

# 1. 备份受改文件（高危前置：备份先于一切修改）
cd /home/rain/Documents/lustre_ins
TS=$(date +%Y%m%d-%H%M%S)                                   # 备份时间戳
D=git-init/backup
mkdir -p "$D/.venv/lib/python3.12/site-packages"            # 保留来源路径层次
cp -p .gitignore "$D/.gitignore.bak.$TS"                    # 忽略规则改前留档
cp -p .venv/lib/python3.12/site-packages/public_modules.pth \
      "$D/.venv/lib/python3.12/site-packages/public_modules.pth.bak.$TS"   # .pth 改名前留档

# 2. 修订 .gitignore（两处定点替换）
#    2a 备份规则由「仅根目录」改为「任意层级」，并保留台账 README.md：
#       backup/*.bak.*  ->  **/backup/*.bak.*
#       backup/*/       ->  **/backup/*/
#       !backup/README.md ->  !**/backup/README.md
#    2b 末尾追加两类忽略：skill-*/（全局技能改造档案，非本工程代码）、.trae/（IDE 本地配置）

# 3. .pth 统一命名（高危：改名，先确认无同名的现存文件）
SP=.venv/lib/python3.12/site-packages
mv "$SP/public_modules.pth" "$SP/py_public_modules.pth"     # 对齐其余 10 个工程与技能口径

# 4. 初始化仓库并配置身份（仓库级配置，不动全局）
git init -b main
git config user.name  "raincheny"
git config user.email "raincheny@users.noreply.github.com"

# 5. 暂存并核对清单（推送到远程前必须核对，确认无凭据/大文件/本地配置混入）
git add -A
git status --porcelain                                      # 预期 37 项
git check-ignore -v .venv config/deploy.yaml .trae skill-verify-r4 logs   # 逐项确认被忽略

# 6. 首次提交
git commit -m "首次纳入版本管理：Lustre 2.15.8 部署与运维工程"

# 7. 关联远程（SSH 方式，凭据为 `~/.ssh/id_ed25519`，不落任何明文）
git remote add origin git@github.com:raincheny/lustre_ins.git

# 8. 推送并建立跟踪
git push -u origin main

失败判断依据：任一步返回码非 0，或第 6 章校验任一项不通过，即视为失败，按第 7 章回滚。

高危提示：第 3 步为文件改名、第 5 步的 git add -A 会整目录纳管，执行前须完成第 1 步备份；第 5 步的清单核对不可省略——一旦把本地配置或凭据提交并推送，需改写历史才能清除。

6. 验证¶

cd /home/rain/Documents/lustre_ins
export GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=15"

# 1. 忽略规则逐项生效
git check-ignore -v .venv config/deploy.yaml .trae skill-verify-r4 logs \
  reports/inspect-20260922-145115.md

# 2. 误纳检查（应为空）
git status --porcelain | grep -E '\.venv|\.trae/|^.. skill-|logs/|\.bak\.|deploy\.yaml$'

# 3. .pth 改名与导入
ls "$SP"/py_public_modules.pth && .venv/bin/python -c "import base_module; print(base_module.__file__)"

# 4. 本地与远程一致性
git log --oneline -1
git ls-remote origin
git rev-parse HEAD origin/main

实测结果（2026-09-24 01:38）：

校验项	结果
纳入文件总数	37
忽略规则生效	`.venv` / `config/deploy.yaml` / `.trae` / `skill-verify-r4` / `logs` / `reports/*.md` / `backup` 子目录均命中
误纳敏感项	无（`grep` 无输出）
`.pth` 更名	旧名无残留；`lib64` 与 `lib` inode 同为 `1574664`，确为同一文件
`import base_module`	`-> /home/rain/py_public_modules/base_module.py`
首次提交	`38e3f8a 首次纳入版本管理：Lustre 2.15.8 部署与运维工程`
推送结果	`* [new branch] main -> main`，`main` 已跟踪 `origin/main`
本地 / 远程 HEAD	均为 `38e3f8acb0e9062cb4487a8644bf31467cbf4f41`
工作区	干净（`## main...origin/main`）

7. 回滚¶

备份位置：git-init/backup/，逐条登记见 backup/README.md。

# 高危：覆盖与改名，执行前先确认目标路径与本轮时间戳
cd /home/rain/Documents/lustre_ins
B=git-init/backup
TS=20260924-013404

# 7.1 回滚忽略规则
cp -p "$B/.gitignore.bak.$TS" .gitignore

# 7.2 回滚 .pth 命名
SP=.venv/lib/python3.12/site-packages
mv "$SP/py_public_modules.pth" "$SP/public_modules.pth"

# 7.3 撤销远程仓库内容（高危：删除 GitHub 上的分支，需用户确认后执行）
#     git push origin --delete main          # 仅在确需清空远程时使用

# 7.4 彻底退出版本管理（高危：删除 .git 会丢失全部本地提交历史）
#     rm -rf .git                            # 确认无需保留历史后再执行

回滚后验证：

cd /home/rain/Documents/lustre_ins
grep -c '^\*\*/backup' .gitignore    # 预期 0（已回到「仅根目录」规则）
.venv/bin/python -c "import base_module; print('ok')"

注意：7.1、7.2 相互独立，可只执行其一；7.3、7.4 为破坏性操作，本次未执行，仅在确实需要撤销仓库时由用户确认后使用。

8. 风险说明¶

风险	等级	缓解措施
把本地配置或凭据误提交并推送	高	`.gitignore` 预先排除 `config/deploy.yaml`、`.trae/`；第 5 步强制核对 `git status --porcelain` 清单与 `git check-ignore`；已核对 37 项清单确认干净
若改用账号密码推送，凭据会落入 shell history 与 `.git/config`	中	本次全程使用 SSH key，凭据仅存在于 `~/.ssh/id_ed25519`；文档不记录任何口令
`.pth` 改名导致共享库挂载失效	中	文件名变化不影响 Python 对 `.pth` 的加载；改后实测 `import base_module` 正常
误改网关/DNS 导致整机断网或解析失败	高（本次规避）	实测直连 GitHub 可用故未改；若后续确需改，须先备份 NetworkManager 连接配置、保留 console 通道，并准备回滚
远程仓库为公开，内网拓扑与地址外泄	高	建库时选择私有；`.gitignore` 已排除真实配置文件
`skill-*/` 被忽略后，技能改造档案失去版本管理	低	属既定取舍（全局资产非本工程代码）；其备份台账仍留在本地 `skill-*/backup/README.md`

附录 A — 交付物清单¶

文件	说明
`git-init/SOP.md`	本文件
`git-init/backup/README.md`	备份台账（2 条）
`git-init/backup/.gitignore.bak.20260924-013404`	忽略规则修订前版本
`git-init/backup/.venv/lib/python3.12/site-packages/public_modules.pth.bak.20260924-013404`	`.pth` 改名前版本

变更后资产：本地仓库 /home/rain/Documents/lustre_ins/.git（分支 main，提交 38e3f8a，37 个受控文件）；远程仓库 git@github.com:raincheny/lustre_ins.git（私有）。

附录 B — `.pth` 命名不一致：方案与决策¶

B.1 事实¶

Python 只在 site-packages/ 下查找以 .pth 结尾的文件并逐行读入 sys.path，文件名本身不参与语义——只要后缀是 .pth 即被加载。因此该问题不影响功能，只是命名口径不一致：本工程用 public_modules.pth，其余 10 个工程用 py_public_modules.pth。

（另：.venv/lib64 是指向 lib 的软链，两处出现实为同一文件，只需改一处。）

B.2 候选方案¶

方案	做法	评价
A. 就多统一（本次采用）	本工程 2 处更名 `py_public_modules.pth`	改动面最小（1 个文件）；与其余 10 个工程及技能口径一致；推荐
B. 就少统一	其余 10 个工程改为 `public_modules.pth`	改动面大（10 个工程、20 个路径），无收益
C. 保持不动	仅在文档中登记差异	零风险，但口径长期分叉，后续按名字检索会漏

B.3 决策与理由¶

选 A。判据是「改动面 / 一致性收益」：方案 A 只动 1 个文件即可收敛全部差异，且不需要触碰其它工程；方案 B 方向相反且成本高；方案 C 把问题留给未来。

B.4 遗留建议¶

技能 deployment-tool-engineering 中列举挂载工程的命令目前用 *modules.pth 通配，能同时命中两种命名，故本次不构成阻塞。若后续新建工程，建议在建工程时即采用 py_public_modules.pth，避免再次分叉。

来源：/home/rain/Documents/lustre_ins/git-init/SOP.md ｜最后更新：2026-09-24 01:42（由 build/sync.py 同步，请勿在站点侧修改）