PVE-Tools-9/lib/CLAUDE.md

根目录 > lib

lib -- 基础设施层

模块职责

提供 PVE Tools Pro 全部功能模块所需的基础设施函数与全局变量，零业务逻辑。按固定顺序加载：config.sh -> core.sh -> menu.sh -> network.sh -> runtime.sh。

入口与启动

项目	说明
加载方式	由 PVE-Tools.sh（本地模式）、dev.sh（开发）source，或由 build.sh 拼接进 dist
加载顺序	config.sh -> core.sh -> menu.sh -> network.sh -> runtime.sh（三处入口硬编码同一列表）
对外暴露	全部函数和全局变量对后续加载的 src/modules/ 可见

文件清单

config.sh -- 全局变量与常量（约 259 行，无函数）

类别	变量	说明
版本信息	CURRENT_VERSION, BUILD_NICKNAME, VERSION_FILE_URL, UPDATE_FILE_URL, PVE_TOOLS_SCRIPT_URL	版本号与更新 URL（脚本更新指向 GitHub Releases latest）
镜像源注册表	MIRROR_NAMES[], MIRROR_IDS[], MIRROR_DEBIAN_URIS[], MIRROR_SECURITY_URIS[], MIRROR_PVE_URIS[], MIRROR_CEPH_URIS[], MIRROR_CT_URIS[]	24 个镜像源并行数组
镜像选择状态	MIRROR_SELECTED_*	当前选中的镜像索引（-1 未选）
网络检测	CF_TRACE_URL, GITHUB_MIRROR_PREFIX, USER_COUNTRY_CODE, NETWORK_MODE, IS_OFFLINE_MODE, USE_MIRROR_FOR_UPDATE	Cloudflare 地区检测、镜像加速
URL 常量	FASTPVE_INSTALLER_URL, COOLERCONTROL_*_URL, NVIDIA_*_URL, THIRD_PARTY_*_URL	各功能的外部资源地址
路径常量	VM_CONFIG_EXPORT_DIR, VM_BACKUP_CRON_FILE, HOST_NETWORK_*_FILE, PVE_CLUSTER_FIREWALL_FILE, PVE_KVM_ROM_DIR	运行时文件路径
PVE 版本	PVE_VERSION_DETECTED, PVE_MAJOR_VERSION	运行时检测结果
安全	RISK_ACK_BYPASS, DEBUG_MODE, LEGAL_VERSION	风险控制标志

core.sh -- 核心工具函数（约 505 行）

函数	说明
setup_colors()	颜色系统初始化，遵循 no-color.org（设置 NO_COLOR 即禁色）
log_info(), log_warn(), log_error(), log_step(), log_success(), log_tips()	统一日志（带时间戳，写入 /var/log/pve-tools.log）
display_error(), display_success()	增强错误/成功反馈（均不内置 pause，由菜单框架统一节奏）
confirm_action()	轻档确认（输入 'yes'），用于可逆配置写入
confirm_high_risk_action()	重档确认（输入指定确认词），用于 GRUB/LVM/磁盘槽位等高危操作
vm_show_data_risk_banner()	VM 数据风险横幅（每会话仅完整展示一次）
ensure_legal_acceptance()	许可条款首次接受检查
backup_file()	配置文件备份到 /var/backups/pve-tools/，可回填备份路径
pve_tools_download_url(), pve_tools_download_file()	curl/wget 封装的下载工具
pve_tools_choose_update_urls(), pve_tools_version_gt()	更新 URL 选择与版本比较（剥离预发布后缀）
apply_block(), remove_block()	marker 配置块写入/删除（# PVE-TOOLS BEGIN/END <MARKER>，写前自动备份、幂等）
grub_has_param(), grub_add_param(), grub_remove_param()	GRUB 内核参数查/增/删：数组化按 key 精确匹配，兼容 key 与 key=value 传参
show_status()	状态行反馈
pause_function()	"按任意键继续..."
show_menu_header(), show_menu_footer(), show_menu_option()	菜单 UI 三件套（被 menu.sh 框架复用）

menu.sh -- 统一菜单交互框架（约 186 行）

全项目菜单一致性的唯一事实来源，使用规范见根 CLAUDE.md「交互层规范」。

函数	说明
run_menu <标题> <渲染函数> <分发函数> <范围>	统一菜单循环：清屏/标题/渲染/统一 0 返回项/读取/EOF 与 Ctrl+C 守卫/分发/pause 节奏
menu_prompt <变量名> <范围>	统一读取；EOF/中断视为选 0（返回上级），杜绝死循环刷屏
prompt_value <变量名> <提示> [默认值] [校验函数]	单值输入：默认值统一 [默认值] 标注；无默认时空回车=取消(return 2)
prompt_yes_no <提示> [默认]	是/否询问（EOF 一律按 no 保守处理）
prompt_pick_from_list <变量名> <提示> <数组名>	编号列表选择器：0=返回(return 2)，与 vm_select_* 约定一致
show_report	长输出分页展示（tty + less 时走分页器，否则 cat）
全局状态	MENU_DEPTH（嵌套深度，决定返回文案）、MENU_SKIP_PAUSE（子菜单返回时跳过父层 pause）

network.sh -- 网络基础设施（约 444 行）

函数	说明
detect_network_region()	Cloudflare Trace 检测用户地区（CN 自动启用镜像）
fetch_session_tip()	一言 API 获取会话提示
network_show_diagnostics(), network_can_access_internet(), network_offline_guard()	网络诊断/连通性/离线守卫
disable_ups_service(), enable_ups_service(), show_ups_diagnostics()	NUT UPS 服务管理（菜单入口在 01 模块顶级项）
show_banner()	启动横幅显示
mirror_*() 系列	镜像注册表查询/选择状态管理
select_mirror(), select_mirror_unified(), select_mirror_per_source(), select_mirror_for_source()	镜像选择交互（"单选即退"选择器语义，未套 run_menu 属有意设计）

runtime.sh -- 运行时守卫与主入口（约 232 行）

函数	说明
check_root()	root 权限检查
check_debug_mode()	解析 --i-know-what-i-do 和 --debug 参数
check_pve_version()	PVE 版本检测（非 PVE9 环境需确认风险，拦截高危自动化）
block_non_pve9_destructive()	非 PVE9 环境拦截换源/升级等破坏性操作
show_menu()	主菜单（11 个功能入口 + 一言 Tips）
main()	脚本主入口：trap INT（Ctrl+C 中断当前输入回上级而非杀进程）-> 权限/许可/调试/PVE 版本/网络检查 -> 更新检查 -> 主循环（read 带 EOF 守卫优雅退出；子菜单返回不重复 pause）

关键依赖与配置

• 运行环境: Proxmox VE 9.x (Debian 13 Trixie)，root 权限
• 外部依赖: curl 或 wget（网络操作）
• 加载顺序严格: config.sh 定义全局变量必须最先；runtime.sh 含 main() 必须最后；menu.sh 在 core.sh 之后（复用其 UI 三件套与 pause）
• 全局变量: 大写变量为全局，src/modules/ 中所有脚本可直接访问

测试与质量

• 语法检查: bash -n 对每个 lib/*.sh
• 静态分析: CI 对 lib/ 全量执行 shellcheck --severity=error
• 行为验证: 菜单框架的 EOF/返回节奏可用管道按键序列冒烟（见根 CLAUDE.md 测试策略）

常见问题 (FAQ)

Q: 为什么加载顺序很重要？ config.sh 定义全局变量；core.sh 的颜色/日志/UI 被后续所有文件使用；menu.sh 依赖 core 的 UI 三件套；runtime.sh 的 main() 调用前面所有层。函数定义顺序本身不影响 bash 运行，但变量初始化（如 setup_colors 在 source 时执行）有先后依赖。

Q: 可以在 src/modules/ 中重新加载 lib 文件吗？ 不需要。所有入口在加载任何模块之前已经 source 了全部 lib 文件。

Q: config.sh 中新增镜像源如何操作？ 在每个并行数组末尾追加对应元素即可，MIRROR_* 数组索引一一对应。

相关文件清单

lib/
  config.sh                       # 全局变量与常量（~259 行）
  core.sh                         # 核心工具函数（~505 行）
  menu.sh                         # 统一菜单交互框架（~186 行）
  network.sh                      # 网络检测与镜像选择（~444 行）
  runtime.sh                      # 运行时守卫与 main()（~232 行）

变更记录 (Changelog)

日期	变更
2026-07-26	新增 menu.sh 菜单框架；display_error 去内置 pause；grub 参数函数数组化并新增 grub_has_param；main() 加 trap INT 与 EOF 守卫；移除死代码 check_packages/show_progress/update_progress/show_progress_bar；行数与函数索引按现实修正
2026-07-08	初始化 lib 模块 CLAUDE.md（模块化重构新增模块）