fanhuadesenlinnn/PVE-Tools-9
1
0
Fork 0
mirror of https://hubproxy.babadafafafafa.cn/https://github.com/Mapleawaa/PVE-Tools-9.git synced 2026-09-20 08:03:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d8b3d9fbdf017eb9bbf957194b1601a0b2280148
PVE-Tools-9/lib/CLAUDE.md
Maple d8b3d9fbdf feat: release v11.0.0 Liino — menu framework, risk guards, CI gates 
Unify all menus on lib/menu.sh (run_menu), harden GPU/GRUB writes with
two-tier confirms and markers, fix remote/self-update to Releases assets,
and close real CI quality gates with SHA256SUMS. Bump to 11.0.0 / Liino.
2026-07-28 14:43:58 +08:00

8.2 KiB
Raw Blame History

根目录 > 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() 主菜单（10 个功能入口 + 一言 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（模块化重构新增模块）