项目地图（PROJECT-MAP）— k8s_ins

接任务先查第 1 节路由表；问「现在什么状态、下一步做什么」去 HANDOFF.md；问「怎么操作、怎么排障」去对应工程的 RUNBOOK.md / SOP.md。 本文件只描述工程的身份与结构（有哪些工程、谁依赖谁、任务该进哪个门），不写当前状态、待办与操作步骤。 身份标签四档：活工程（仍在用、会被重跑或继续开发）/ 服务档案（对应一个在运行的服务）/ 留档（已结束的一次性主题，供追溯）/ 数据源（提供事实与索引，不承载变更）。

1. 任务路由表

任务 / 症状	进哪个目录	先读哪份文档	入口命令
K8s 集群重建、重跑部署、单节点基线变更	k8s_136_cluster_deploy	docs/RUNBOOK.md 第 4、5 章	python main.py --config config/deploy.yaml [--dry-run]
控制面多 master HA ↔ 单 master 扩缩容	k8s_136_cluster_deploy	docs/SOP.md 5.10、docs/RUNBOOK.md 第 4.3 节	python control_plane_scale.py --config config/deploy.yaml --shrink\|--expand [--dry-run]
kubectl 连不上 apiserver（connection refused / EOF / TLS timeout）	k8s_136_cluster_deploy	docs/RUNBOOK.md 第 8 章场景 1（含 SELinux 分支）	无专用入口，按 RUNBOOK 逐步诊断
入口 VIP:16443 不通、haproxy 起不来、SELinux 拒绝	k8s-restart-16443-selinux-20260929	SOP.md	ssh root@192.168.31.10 "systemctl is-active haproxy; getenforce"
haproxy 日志出现已关机后端告警 / SELinux 残留隐患复核	k8s-followup-20260929	SOP.md、20260929-K8s全节点-SELinux-AVC巡检报告.md	无
部署工程为何不再关闭 SELinux	k8s-deploy-yaml-selinux-20260929	SOP.md	无
集群入口证书 / 端口 / 路由不生效 / Dashboard 401	traefik_deploy	RUNBOOK.md	helm upgrade --install traefik ... -f values.yaml（OCI 源）
新增公网或内网暴露面、某域名公网 502、frpc 无转发	ingress_tunnel_deploy	RUNBOOK.md 第 1 节与附录 A	python main.py --config config/ingress.yaml
StorageClass / PVC 动态供给异常、快照恢复、卷扩缩容	nfs-storage	RUNBOOK.md 第 1 节	无专用入口（helm + kubectl apply -f manifests/）
NFS 元数据延迟高、挂载参数需要重调	nfs-mount-tuning	docs/SOP.md	.venv/bin/python main.py --config config/tune.yaml [--dry-run\|--rollback]
MariaDB 不可用、取 root 口令、数据盘异常	mariadb-deploy	RUNBOOK.md 第 1 节	helm install -f charts/mariadb/values.yaml
监控体系要建成什么样、当前差哪些、下一步做什么	docs/MONITORING-ROADMAP.md	该文件第 3 节（G1–G8 缺口台账）、第 4 节（P0–P2 三步蓝图）	无（蓝图与台账）
日志查不到 / 要查容器或主机日志、按集群域看日志、纳管 deb 系主机或网络设备日志、探测目标持续失败、证书到期告警、Kibana 打不开	monitoring-p2-20261001	docs/RUNBOOK.md（日常与故障处置；§4.5 分域视图、§4.6 宿主 rsyslog 与网络设备日志）、docs/SOP.md、docs/SOP-kibana-domain-view.md、docs/SOP-onboard-deb-network.md	.venv/bin/python main.py {precheck\|deploy\|verify\|drift\|rollback\|kibana}
日志与指标互跳 / Grafana 大盘的日志入口 / 指标侧裸主机名标签（hostname）	log-metrics-crosslink-20261002	SOP.md	无（展示层与抓取标签变更，两侧工程各自 deploy）
监控 / 告警 / Grafana 不可用、抓取目标 down、TSDB 容量	prometheus_deploy	RUNBOOK.md 第 1 节	helm upgrade --install ... -f values.yaml + kubectl apply -f manifests/
Dell R620 硬件温度/风扇监控、本机 IPMI 指标缺失或陈旧、硬件告警邮件收不到	dell-r620-monitor-20260929	docs/RUNBOOK.md 第 8 章、docs/SOP.md	sudo -n .venv/bin/python main.py {precheck\|deploy\|verify\|drift\|rollback}
环境主机监控扩面：14 台非 K8s 主机（Slurm/Lustre/LSF/HPC/FlexLM）无指标、主机侧告警缺失、大盘无 HPC 语义	env-monitor-deploy	docs/RUNBOOK.md 第 3、8 节；docs/SOP.md	.venv/bin/python main.py {precheck\|fetch-dashboards\|deploy\|verify\|drift\|rollback}
集群外主机（14 台非 K8s）只读取数、摸清远端执行接口（交互式取值，非工程子命令）	monitoring-p2-20261001（utils/cmd.py 的 SSHRunner）	docs/BASELINE.md 第 4 节	cd monitoring-p2-20261001 && .venv/bin/python -c "from utils.cmd import SSHRunner; print(SSHRunner().run('<ip>','<cmd>').stdout)"
GitLab Web/API 异常、升级 chart、调整 webservice 资源	gitlab-deploy-v2	RUNBOOK.md 第 1、2 节	helm upgrade --install gitlab ... -f values-gitlab.yaml -n server
GitLab 502 / webservice OOM / Puma worker 被回收	gitlab-502-webservice-oom	INCIDENT-20260920-webservice-oom-502.md	无
LDAP 登录或条目异常、phpLDAPadmin 报错	ldap-deploy（子工程 pla-frame409-fix/）	SOP.md；子工程 pla-frame409-fix/SOP.md	helm install -f values-phpldapadmin.yaml
需要主机角色 / IP 拓扑，或要取服务口令	env-inventory	inventory.yaml、k8s-services.yaml	python build_secrets_env.py（刷新凭据快照，幂等）
追溯「为什么业务都在 server 命名空间」	ns_migration	RUNBOOK.md 第 1 节	无
追溯旧集群某组件当年的清单或排障过程	已清理，见 cleanup-server-legacy-20260929	SOP.md（删除范围与「无备份」事实）	无
追溯 monitoring_upgrade/ 的去向或恢复	cleanup-20260929	SOP.md、backup/README.md	无
提升 agent 执行效率 / 让每日成本审查的行为建议落地、压缩工具调用步数与 token 消耗	agent-efficiency-skill-20260930	SOP.md；全局技能 ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md	无（技能为按需加载的规则文本）
SSH 连接慢 / 握手次数多 / 共享库连接池是否复用 / 改 py_public_modules 后要回归哪些工程	conn-reuse-refactor-20260930	SOP.md；共享库契约 ~/.trae-cn/skills/deployment-tool-engineering/references/shared-lib-contract.md	无（改动对象为项目外共享库；回归命令见契约文件）
追溯 precheck 耗时收益归属（合并 vs 并发）／预检并发度配置改不动	attribution-split-20260930	MEASUREMENT.md	测量对象为 env-monitor-deploy；复测命令见其第 4 节
追溯「效率规则为何没拦住我」／准备做规则改动的对照验证	agent-efficiency-rule-fix-20260930	SOP.md（含缓存计费实测与改前基线）	无（改动对象为全局规则与全局技能，不承载运行服务）
SELinux / firewalld 干扰排查（某主机端口被挡、配置被拒），或需复核/改/回滚强制访问控制与包过滤	selinux-firewall-20261003	docs/SOP.md（本次变更全过程）、docs/RUNBOOK.md（日常复核与故障处置）	.venv/bin/python main.py {precheck\|verify\|drift\|deploy\|rollback}
监控 helm values 与现场漂移、升级怕丢配置、要复核 values.yaml 是否为现场基线	prometheus-baseline-align-20261003	docs/SOP.md	python3 prometheus-baseline-align-20261003/compare_values.py（逐键比对）；helm template -f prometheus_deploy/values.yaml（渲染复核）
控制面指标抓不到（etcd/scheduler/controller-manager/kube-proxy target down）、K8s 控制面盲区（G2）、容量水位告警缺失或失真（#14）	control-plane-metrics-20261003	docs/SOP.md（八章变更档案；附录 B 为 G8 容量复核，附录 C 为决策落点）	python3 control-plane-metrics-20261003/apply.py --check（只读）；kubectl apply -f control-plane-metrics-20261003/manifests/capacity-watermark-alerts.yaml

2. 分层依赖图

【物理 / 宿主层】
  KVM 宿主 dell-R620（本机，192.168.31.249=br0 / .250=eno2，**同机双网口**；也是 NFS 服务端）
    ├── k8s      .10(k8s-master-01) + .13/.14/.15(node-01~03)
    ├── slurm    .16/.17(控制主备) + .18/.19/.20(计算)
    ├── lustre   .21(MGS/MDS) + .22(OSS)
    ├── lsf      .23/.24(主控主备) + .25/.26/.27(计算)
    ├── hpc      .28(统一提交节点)
    ├── license  .29(FlexLM)
    └── registry .31(harbor-01，内网镜像仓库)
  链路外旁挂：[公网] 香港 129.226.138.204 (nginx + frps) ←→ OpenWrt 192.168.31.2 (frpc)
             [控制面 VIP] 192.168.31.8（keepalived + haproxy 承载，转发 apiserver 6443）
        │
        │ 装机/装载来源：各集群均无专属部署工程，由 `env-inventory` 提供事实索引
        ▼
【兼容 / OS 层】  ← 决定服务能否启动，本层曾致 16443 事故
  SELinux（2026-10-03 起 13 台由 Enforcing 统一为 permissive；lsf 5 台 + hpc 保持 disabled）、
  firewalld（2026-10-03 起全内网 19 台停止并禁用）、Lustre 定制内核（计算节点）、
  haproxy 所需的 SELinux 端口标签与布尔（permissive 下不再需要，策略保留备查）
        │
        ▼
【服务层】
  非 K8s：Slurm(.16~.20)  Lustre(.21/.22)  LSF(.23~.27)  FlexLM(.29)  NFS 服务端(宿主)
  K8s v1.36.4 命名空间：
    kube-system      coredns、etcd/apiserver/controller-manager/scheduler(静态 Pod@master-01)、
                     kube-proxy、csi-nfs-controller/-node、snapshot-controller、metrics-server、headlamp
    calico-system    calico-node(DS)、calico-typha、calico-kube-controllers、csi-node-driver
    tigera-operator  tigera-operator
    cnpg-system      cnpg-cloudnative-pg
    mariadb-system   mariadb-operator(+cert-controller/webhook)
    monitoring       prometheus / alertmanager / grafana / operator / kube-state-metrics / node-exporter
                     + elasticsearch / kibana / filebeat / blackbox-exporter（P2，2026-10-01）
    server           业务主体：GitLab 全栈 + OpenLDAP + phpLDAPadmin + MariaDB + Redis + MinIO
                     + Traefik + Envoy Gateway
    ldap             已空置（仅残留 PVC）
        │
        ▼
【入口层】
  公网链路：DNS → 香港 nginx(LE 证书) → frps → frpc(OpenWrt) → Traefik(.10:80/443) → 业务 Service
  集群内 HTTP(S)：Traefik ─→ phpldapadmin / grafana / prometheus / traefik-dashboard
                  Envoy Gateway ─→ gitlab / registry / kas（GitLab 三域，不经 Traefik）
  集群内 TCP：   Traefik ─→ openldap:389/636、mariadb:3306
  控制面：       keepalived + haproxy → VIP:16443 → apiserver 6443
        │
        ▼
【数据 / 存储层】
  NFS(宿主 .249)：/srv/nfs/k8s(SSD,→SC nfs-csi)、/srv/nfs/k8s-hdd(→SC nfs-csi-hdd)、
                  /data/nfs-k8s-snap(快照归档)、/data/nfs/slurm-state(属 Slurm，非 K8s 交付)
  Lustre：MGS/MDS .21 + OSS .22（计算节点挂载）
  local-ssd：GitLab 的 PostgreSQL / Redis / Gitaly（节点本地盘，非 NFS）
  消费方：mariadb-deploy、prometheus_deploy、gitlab-deploy-v2、ldap-deploy

结构性的关键点：NFS 后端与 4 台 K8s VM 的磁盘同处宿主 dell-R620，属同源故障域。

3. 子项目卡片

活工程

目录	定位	关键产物与入口	上下游
k8s_136_cluster_deploy	K8s HA 集群的 Python 部署工程（含控制面扩缩容）	main.py、deployer.py、control_plane_scale.py、config/deploy.yaml、docs/{SOP,RUNBOOK}.md	上游：无（依赖 KVM 宿主）；下游：几乎所有集群内服务工程
monitoring-p2-20261001	监控 P2：EFK 日志聚合（ES + Kibana + Filebeat）+ 黑盒探测 + 保留期容量规划；含 deb 系主机（dell-R620）与网络设备（OpenWrt）日志接入	main.py、deployer.py、modules/（含 network_logs.py）、manifests/、config/default.yaml、docs/{SOP,RUNBOOK,SOP-onboard-deb-network}.md	上游：k8s_136_cluster_deploy、nfs-storage、traefik_deploy（ES TCP 入口）、prometheus_deploy（Probe/Rule 选择器）、ghcr-slow-20261001（Harbor 镜像源）；下游：无
ingress_tunnel_deploy	服务暴露编排：内网（Traefik）与公网（frp + nginx）投放	main.py、config/ingress.yaml、modules/、RUNBOOK.md	上游：traefik_deploy、mariadb-deploy
nfs-mount-tuning	NFS 挂载参数调优（async + nfsvers=4.2 + nconnect=4）	main.py、config/tune.yaml、modules/、docs/SOP.md	上游/对象：nfs-storage
dell-r620-monitor-20260929	Dell R620（本机 192.168.31.250）硬件温度/风扇监控接入 monitoring 内的 kube-prometheus-stack	main.py、config/monitor.yaml、artifacts/、manifests/、docs/{SOP,RUNBOOK}.md	上游：prometheus_deploy（kube-prometheus-stack release）；对象：本机 apt node-exporter + IPMI 采集（systemd timer）
env-monitor-deploy	环境主机监控扩面：把 14 台非 K8s 主机（Slurm/Lustre/LSF/HPC/FlexLM）接入 monitoring —— 主机层（node-exporter）、领域指标（Slurm/Lustre/LSF/FlexLM，textfile collector）、主机与领域告警、环境总览与角色看板；长期工程，三步蓝图与缺口台账见 docs/MONITORING-ROADMAP.md（P2 黑盒与日志待立项）	main.py、deployer.py、modules/、utils/、config/env-monitor.yaml、manifests/、artifacts/（含 collectors/）、docs/{SOP,RUNBOOK}.md、docs/INCIDENT-20260930-monitoring-fullstack-rollout.md	上游：prometheus_deploy（kube-prometheus-stack release）、env-inventory（主机清单口径）；对象：14 台 Rocky 9 主机（.16–.29）；边界：宿主 R620 的采集仍归 dell-r620-monitor-20260929，本工程只读它的指标画进总览
selinux-firewall-20261003	强制访问控制与包过滤统一：19 台内网主机 SELinux 统一 permissive（免重启、不回改 disabled）、firewalld 停止并禁用，消除排查期与后续业务放行的干扰；含只读复核、漂移检测与按原值回滚	main.py、deployer.py、utils/、config/selinux-firewall.yaml、docs/{SOP,RUNBOOK}.md、backup/（逐台 pre-state.json）	上游：env-inventory（主机清单口径）；对象：19 台（k8s 4 / slurm 5 / lustre 2 / lsf 5 / hpc 1 / FlexLM 1 / harbor-01）；边界：不含香港 frps（公网入口）与 OpenWrt 旁路由（NAT 网关），也不含 Dell R620（Ubuntu，无 SELinux）
control-plane-metrics-20261003	K8s 控制面指标接入 + 容量水位告警（G2/G8 收口）：在 k8s-master-01 打开 etcd/scheduler/controller-manager/kube-proxy 的 metrics 监听，四个孤儿 ServiceMonitor 收编回 helm release，并补齐宿主 NFS 后端盘与 Prometheus TSDB 的容量水位告警	apply.py（幂等变更，含 --check/--dry-run）、manifests/capacity-watermark-alerts.yaml、probe_g8.py（容量取数）、docs/SOP.md、backup/README.md	上游：prometheus_deploy（kube-prometheus-stack release）、env-inventory；对象：k8s-master-01 控制面静态 Pod + monitoring 命名空间

服务档案

目录	定位	关键产物与入口	上下游
traefik_deploy	集群唯一 HTTP/HTTPS/TCP 入口代理（Traefik v3）	SOP.md、RUNBOOK.md、values.yaml	上游：k8s_136_cluster_deploy
nfs-storage	宿主 NFS 服务端 + csi-driver-nfs StorageClass（nfs-csi / nfs-csi-hdd）	SOP.md、RUNBOOK.md、values-nfs-csi.yaml、manifests/、examples/	上游：k8s_136_cluster_deploy；下游：mariadb-deploy、prometheus_deploy、gitlab-deploy-v2、ldap-deploy
mariadb-deploy	server 内 MariaDB 单实例（mariadb-operator 托管）	SOP.md、RUNBOOK.md、charts/mariadb/	上游：k8s_136_cluster_deploy、nfs-storage；下游：ingress_tunnel_deploy；对外承载 Slurm 记账库
prometheus_deploy	monitoring 内 kube-prometheus-stack 全新部署	SOP.md、RUNBOOK.md、values.yaml、manifests/（CRD 在其下 crds/）	上游：k8s_136_cluster_deploy、nfs-storage；取代已删除的 monitoring_upgrade/
gitlab-deploy-v2	server 内 GitLab 全栈（chart 交付，自备 PG/Redis/MinIO）	SOP.md、values-gitlab.yaml、rendered-*.yaml	上游：k8s_136_cluster_deploy、nfs-storage、Traefik/Envoy Gateway；下游：gitlab-502-webservice-oom
ldap-deploy	server 内 OpenLDAP + phpLDAPadmin，含子工程 pla-frame409-fix/（独立活工程式修复）	SOP.md、values-phpldapadmin.yaml、charts/*.tgz	上游：k8s_136_cluster_deploy、nfs-storage、Traefik HTTPRoute

数据源

目录	定位	关键产物与入口	上下游
env-inventory	环境事实与凭据索引的唯一来源（21 台主机拓扑 + K8s 服务清单）	inventory.yaml、k8s-services.yaml、scan_credentials.py、build_secrets_env.py、SOP.md	被全项目依赖；产物落地 ~/.secrets/prod.env

留档

目录	定位	关键产物	关联
k8s-restart-16443-selinux-20260929	宿主机重启后 16443 入口被 SELinux 拦截的修复	SOP.md、evidence/、backup/	事件链起点，回指 k8s_136_cluster_deploy
k8s-followup-20260929	上一故障收尾：haproxy 后端清理 + 全节点 AVC 巡检报告	SOP.md、20260929-K8s全节点-SELinux-AVC巡检报告.md	承接上一条
k8s-deploy-yaml-selinux-20260929	收敛部署工程基线开关 disable_selinux	SOP.md、backup/config/	改的是 k8s_136_cluster_deploy/config/deploy.yaml
gitlab-502-webservice-oom	GitLab webservice OOM 致 502 的故障报告	INCIDENT-20260920-webservice-oom-502.md、SOP.md、backup/	修复对象为 gitlab-deploy-v2/values-gitlab.yaml
ns_migration	把 traefik / gitlab / ldap 等统一迁入 server 命名空间	SOP.md、RUNBOOK.md、INCIDENT-20260918-01-ns迁移期排障.md、replace_ns.py	横向触及 traefik_deploy、gitlab-deploy-v2、ldap-deploy
cleanup-20260929	删除旧集群遗留工程 monitoring_upgrade/	SOP.md、backup/monitoring_upgrade.bak.*.tar.gz	替代者为 prometheus_deploy
cleanup-server-legacy-20260929	删除旧集群遗留资料目录 server/（312 文件 / 4.71 MB，经用户决定不留备份）	SOP.md	同类先例 cleanup-20260929（该次保留了 tar.gz 备份）
agent-efficiency-skill-20260930	改写全局技能 ops-execution-efficiency：重新定位目标（约束=任务效果不打折／首要=执行效率／次要=token），拆分成本章节、新增收尾自查与实时消耗自查	SOP.md、backup/README.md	改写对象为全局技能 ~/.trae-cn/skills/ops-execution-efficiency/；度量口径来自项目外 token_proxy 工程的 logs/usage.jsonl 与每日审查
conn-reuse-refactor-20260930	共享库 SSHConnectionPool 由「每次新建」改为真复用（close() 池内归还/池外真关 + close_force() + keepalive 30s）	SOP.md、backup/README.md	改动对象为项目外 ~/py_public_modules/paramiko_module.py；6 个挂载工程零改动、回归全过
conn-reuse-measure-20260930	连接/握手计数测量：改造前基线与改造后验证（零侵入 monkeypatch 脚本）	measure_conn.py、MEASUREMENT.md、raw-deploy.json	为 conn-reuse-refactor-20260930 提供改前基线（44 次握手）与改后验证（14 次）
attribution-split-20260930	效率收益归因拆分：补测「只合并、不并发」一格（precheck 136.84 → 46.20 → 11.06 s）	measure_serial.py、MEASUREMENT.md、各组原始日志	为技能 ops-execution-efficiency 的实测基线提供拆分结论；顺带查出 env-monitor-deploy 预检并发度配置失效
agent-efficiency-rule-fix-20260930	修机制而非改文案：技能触发表加「多步执行类任务 → 先加载效率技能」横切项、执行方式表加「涉具体工程先读路由表」「检索列举须限定目录」两条，并把「有地图却越过路由表扫目录」案例与改前基线入档	SOP.md、backup/README.md	改动对象为全局 ~/.trae-cn/user_rules/{rule-skill-index,rule-agent-efficiency}.md 与全局技能 ops-execution-efficiency 的 references/；承接 agent-efficiency-skill-20260930
log-metrics-crosslink-20261002	日志 ↔ 指标互跳第一阶段（静态入口）：指标侧加 hostname 裸主机名标签、Grafana 5 大盘加「查看日志」链接、Kibana 加「查看指标」markdown 面板	SOP.md、backup/README.md	改动对象为 env-monitor-deploy（relabel + 大盘）与 monitoring-p2-20261001（Kibana 对象）；对齐键结论见 docs/HANDOFF.md §2，来源 docs/LOGGING-GAP.md #1
optimization-backlog-20261002	token_proxy「优化点总账」挂账项在本工程的落地：#8 补「集群外主机只读取数」入口（docs/BASELINE.md 第 4 节 + 本文件 §1 路由表）、#1 给 env-monitor-deploy 加 --hosts-only	SOP.md、backup/README.md、backup/docs/、backup/env-monitor-deploy/	同批 token_proxy 侧变更见 ~/Documents/services/token_proxy/backlog-20261002/
prometheus-baseline-align-20261003	把 prometheus_deploy/values.yaml 回写为现场完整基线，消除"文件≠现场"漂移（13 项；SMTP 授权码不入库、运行时注入）	docs/SOP.md、compare_values.py（逐键比对脚本，可复用于日后 drift 复核）、backup/	变更对象为 prometheus_deploy/values.yaml；上游为 log-metrics-crosslink-20261002/SOP.md §11.2、组三 #12 与第四阶段的 overlay 式升级

项目外强相关路径

路径	用途
~/.trae-cn/skills/rainchen-env/SKILL.md	全局技能：本项目之外获取环境事实指针与凭据取用约定
~/.trae-cn/skills/ops-execution-efficiency/SKILL.md	全局技能：运维任务的执行效率与 token 消耗规范（含收尾自查清单与实时消耗自查，后者带阶段开关）
~/Documents/services/token_proxy/	项目外工程：Trae LLM 透明计量代理 + 每日成本/行为审查，产出 logs/usage.jsonl（准实时，延迟约 1s）与 reports/daily-review-*.md
~/.secrets/prod.env	凭据快照（600，禁止读取内容，只在命令内 source）
192.168.31.2（OpenWrt）	frpc 隧道客户端（不在项目目录内）
129.226.138.204（香港）	公网入口：nginx + frps（不在项目目录内）
~/py_public_modules/	共享库（base_module / paramiko_module / ssh_executor / logger_module / precheck_module 等），被 6 个工程的 venv 以 .pth 挂载；未纳入 git，改动需先备份并登记台账、改后对全部挂载工程跑回归

4. 存疑与待澄清

• 无专属工程目录的集群：slurm / lustre / lsf / hpc / license 在本仓库内只有 env-inventory 的拓扑条目，无部署或运行文档；其内部结构（调度配置、License 清单）未纳管。
• lsf-work-01~03 探测到的进程是 lim 而非 sbatchd，inventory.yaml 已注明"角色以 hostname 为准、进程构成待核对"。
• 公网 fps.rainchen.top（frps 面板）在 ingress_tunnel_deploy/RUNBOOK.md 中标注"未纳入本工程"，未进服务清单。
• GitLab PostgreSQL 版本口径不一致：ns_migration/RUNBOOK.md 写 17.6，k8s-services.yaml 未给版本。

5. 工程命名与文档约定

目录命名

• 服务类工程：<组件>-deploy 或 <组件>_deploy（如 gitlab-deploy-v2、prometheus_deploy）
• 一次性主题：<主题>-YYYYMMDD（如 k8s-restart-16443-selinux-20260929、cleanup-20260929）
• 常态设施：env-inventory（数据源）、docs（根级档案）

docs 根级档案（位置与角色）

文件	位置	管什么
HANDOFF.md	docs/	当前状态、待办、红线（覆盖式重写，SessionStart 注入）
PROJECT-MAP.md	docs/	本文件：工程身份与结构（定点修订）
MONITORING-ROADMAP.md	docs/	跨工程的监控建设蓝图与缺口台账（八维度口径 / 18 台覆盖矩阵 / G1–G8 / P0–P2 三步）
SOP.md	各工程目录	该工程的变更档案（累积式，八章）
RUNBOOK.md	各工程目录	该工程的运行与排障手册
INCIDENT-YYYYMMDD-<主题>.md	各工程目录	事故台账与复盘

backup 台账

• 每个主题的备份放在该主题目录下的 backup/，命名 <原名>.bak.<YYYYmmdd-HHmmss>，并必须有 backup/README.md 逐条登记（文件、原路径、时间、因何产生、回滚什么、何时可删）。
• 例外：含凭据明文的备份（如 deploy.yaml）不复制进交付物目录，保持远程/原位，仅在台账登记位置。

工程形态

• 复杂变更（多主机、多步编排、需回滚）以 Python 工程实现：main.py + modules/ + config/ + .venv/
• 服务交付以 helm values + manifests/ 为主
• 全局技能 rainchen-env 承载"本项目之外"的环境事实指针

退役纪律

• 工程退役或被取代时：不删目录，改身份标签为 留档，在卡片注明被谁取代、何时。
• 新增子项目时：在路由表加一行 + 在卡片区加一条。

---

来源：/home/rain/Documents/k8s_ins/docs/PROJECT-MAP.md ｜ 最后更新：2026-10-03 15:49（由 build/sync.py 同步，请勿在站点侧修改）