diff --git a/.claude/index.json b/.claude/index.json index aec7387..e2beede 100644 --- a/.claude/index.json +++ b/.claude/index.json @@ -1,96 +1,187 @@ { "meta": { "project": "PVE-Tools-9", - "description": "Proxmox VE 9.x 一键运维脚本与文档站", - "version": "7.2.0", + "description": "Proxmox VE 9.x 模块化 Bash 运维工具集", + "version": "9.0.0", "license": "GPL-3.0", - "generated_at": "2026-04-28T20:59:34+08:00", + "generated_at": "2026-07-08T10:41:03+08:00", "generator": "claude-init 自适应架构师", - "truncated": false + "truncated": false, + "major_changes_since_last_scan": "项目完成模块化重构：430KB 单文件拆分为 lib/ (4文件) + src/modules/ (10子模块, 66文件)。新增 build.sh/dev.sh 构建系统。Web/ VitePress 文档站已移除。" }, "scan_coverage": { - "estimated_total_files": 75, - "scanned_files": 62, - "coverage_percent": 82.7, - "skipped_by_ignore": 8, - "skipped_binary_large": 2, - "skipped_other": 3, + "estimated_total_files": 140, + "scanned_files": 80, + "coverage_percent": 57.1, + "skipped_by_ignore": 20, + "skipped_binary_large": 28, + "skipped_other": 12, "skip_reasons": { "binary_large": [ "Modules/VGPU/libvgpu_unlock_rs_20230207_44d5bb3.so", - "Web/assets/images/Proxmox-Corporate-Brandguideline.pdf" + "images/ 下 27 个 PNG/JPG/SVG 文件（仅记录路径）", + "dist/PVE-Tools.sh（构建产物，已忽略）" ], "ignore_rules": [ - "Web/bun.lock (类似 bun.lockb)", - "Web/.vitepress/dist/ (构建产物)", - "Web/.vitepress/cache/ (缓存)", - "node_modules/ (依赖)", - ".codebuddy/ (项目忽略)", - ".cache/ (缓存)", - ".spec-workflow/ (项目忽略)", - ".claude/ (项目忽略)" + "dist/ (构建产物)", + "node_modules/ (不存在于当前仓库)", + ".git/ (版本控制)", + "test.txt" ], - "too_large_full_read": [ - "PVE-Tools.sh (430KB，使用分段读取，覆盖率约60%)" + "too_large_or_not_prioritized": [ + "src/modules/ 下 ~56 个非 init.sh 文件（仅 init.sh 已读，实现文件通过重构计划文档交叉验证）", + "Tools/ 下 13 个 .sh 脚本（仅记录文件名，内容已在上次扫描中确认来自 tteck 社区）" ] } }, "modules": [ { "path": "/", - "name": "根模块 (主脚本)", + "name": "根模块 (入口脚本)", "language": "Bash", "claude_md": "CLAUDE.md", - "entry_points": ["PVE-Tools.sh"], - "interfaces": ["主菜单 (9个一级选项，多个二级/三级子菜单)"], - "dependencies": ["bash", "curl/wget", "qm/pct/pvesh (PVE CLI)"], - "data_models": ["VERSION文件", "legal_acceptance marker文件", "/var/lib/pve-tools/ 运行时数据"], - "tests": ["CI: shellcheck, bash -n, 版本一致性检查"], + "entry_points": ["PVE-Tools.sh (169行)", "build.sh", "dev.sh"], + "interfaces": [ + "pve_tools_entry_source_tree() -- 本地模块加载", + "pve_tools_entry_prepare_remote_tree() -- 远程模块下载", + "main() -- 脚本主入口 (lib/runtime.sh)" + ], + "dependencies": ["bash", "curl/wget", "find", "sort"], + "data_models": ["VERSION", "legalese acceptance marker"], + "tests": ["CI: shellcheck, bash -n (入口+构建产物), 版本一致性检查"], "config_files": ["VERSION", "UPDATE"], "scanned_sections": [ - "颜色系统 (lines 23-55)", - "日志函数 (lines 103-137)", - "许可与风险体系 (lines 209-241)", - "配置文件管理 (lines 244-331)", - "GRUB 管理 (lines 333-410)", - "主菜单 (lines 5480-5499)", - "VM 高级运维 (lines 6065+)", - "宿主机网络 (lines 7873+)" + "PVE-Tools.sh 完整读取 (169行)", + "build.sh 完整读取 (50行)", + "dev.sh 完整读取 (22行)", + "AGENTS.md 完整读取" ], "scan_gaps": [ - "RDM/NVMe 直通完整逻辑 (lines 1954-2240 仅部分阅读)", - "引导配置辅助 (lines 2669+ 仅部分阅读)", - "所有子菜单实现函数体 (数量庞大，仅了解入口)", - "GPU 直通各子功能详细实现", - "存储/磁盘维护二级菜单实现" - ], - "coverage": "medium" - }, - { - "path": "Web/", - "name": "Web 文档站", - "language": "TypeScript/Vue/Markdown", - "claude_md": "Web/CLAUDE.md", - "entry_points": ["Web/index.md", "Web/.vitepress/config.mts"], - "interfaces": ["VitePress 配置 (nav/sidebar)", "5个自定义Vue组件", "18个Markdown页面"], - "dependencies": ["vitepress ^1.6.4", "vue ^3.5.27", "lucide-vue-next ^0.563.0", "bun"], - "data_models": ["todo-data.json (开发计划+时间线)"], - "tests": ["构建验证 (bun run build)"], - "config_files": ["package.json", "wrangler.jsonc", ".vitepress/config.mts"], - "scanned_files": [ - "index.md", "guide.md", "features.md", "faq.md", "update.md", - "todo.md", "submit-plugin.md", "ula.md", "sponsor.md", "pay.md", - "config.mts", "theme/index.ts", "theme/custom.css", - "Announcement.vue", "CopyCodeBox.vue", "Giscus.vue", - "HomeFeaturesWithTimeline.vue", "TodoList.vue", - "package.json", "bun.lock", "wrangler.jsonc", "index.js", - "todo-data.json", "advanced/index.md" - ], - "scan_gaps": [ - "advanced/ 下 10 篇 Markdown 教程详情（仅读取了索引，未逐篇阅读内容）" + "README.md / README_EN.md / REAMDE-JP.md 未读取（项目说明文档）", + "UPDATE 文件未读取", + "proxmoxlib.js 未读取（Proxmox Web UI 补丁）" ], "coverage": "high" }, + { + "path": "lib/", + "name": "基础设施层", + "language": "Bash", + "claude_md": "lib/CLAUDE.md", + "entry_points": ["config.sh", "core.sh", "network.sh", "runtime.sh"], + "interfaces": [ + "config.sh -- 全局变量（版本/镜像/URL/路径）", + "core.sh -- 颜色/日志/UI/确认/备份/GRUB（28个函数）", + "network.sh -- 网络检测/镜像选择/横幅（21个函数）", + "runtime.sh -- root守卫/调试/PVE检测/main()（8个函数）" + ], + "dependencies": ["bash", "curl/wget", "pveversion (运行时)"], + "data_models": ["legal_acceptance marker 文件"], + "tests": ["CI: shellcheck, bash -n"], + "config_files": ["config.sh (全局变量定义)"], + "scanned_files": [ + "config.sh 完整读取 (254行)", + "core.sh 完整读取 (507行)", + "network.sh 头部读取 (50行, 函数签名已确认)", + "runtime.sh 完整读取 (235行)" + ], + "scan_gaps": [ + "network.sh 后半部分 (~170行未读，包含镜像选择UI函数体，但函数签名已从重构计划获取)" + ], + "coverage": "high" + }, + { + "path": "src/modules/", + "name": "功能模块层", + "language": "Bash", + "claude_md": "src/CLAUDE.md", + "entry_points": ["各子模块的 init.sh"], + "interfaces": [ + "10 个子模块的菜单入口函数", + "menu_optimization() / menu_sources_updates() / menu_boot_kernel() / ...", + "main() 中的 case 分发 (lib/runtime.sh)" + ], + "dependencies": ["lib/config.sh", "lib/core.sh", "lib/network.sh (部分模块)"], + "data_models": ["无独立数据模型，操作 PVE 系统配置"], + "tests": ["CI: shellcheck, bash -n (通过构建产物)"], + "config_files": [], + "sub_modules": [ + { + "path": "src/modules/01-optimization/", + "files": 6, + "init_read": true, + "coverage": "medium", + "description": "日常优化与通知：弹窗/温度/电源/邮件" + }, + { + "path": "src/modules/02-sources/", + "files": 4, + "init_read": true, + "coverage": "medium", + "description": "软件源与系统升级：换源/更新/PVE8->9升级" + }, + { + "path": "src/modules/03-boot-kernel/", + "files": 3, + "init_read": true, + "coverage": "medium", + "description": "启动与内核管理：内核切换/清理/GRUB" + }, + { + "path": "src/modules/04-gpu-passthrough/", + "files": 12, + "init_read": true, + "coverage": "medium", + "description": "硬件直通与显卡：Intel/AMD/NVIDIA GPU/RDM/NVMe", + "scan_gaps": ["11个非init.sh文件未逐文件读取，函数归属已通过重构计划文档交叉验证"] + }, + { + "path": "src/modules/05-vm-container/", + "files": 15, + "init_read": true, + "coverage": "medium", + "description": "虚拟机运维与导入：备份/恢复/克隆/Cloud-Init/快照/磁盘/迁移", + "scan_gaps": ["14个非init.sh文件未逐文件读取，函数归属已通过重构计划文档交叉验证"] + }, + { + "path": "src/modules/06-networking/", + "files": 10, + "init_read": true, + "coverage": "medium", + "description": "宿主机网络与防火墙：网桥/VLAN/Bond/MAC绑定/防火墙/IPv6", + "scan_gaps": ["9个非init.sh文件未逐文件读取，函数归属已通过重构计划文档交叉验证"] + }, + { + "path": "src/modules/07-storage-disk/", + "files": 6, + "init_read": true, + "coverage": "medium", + "description": "存储与磁盘维护：查询/挂载/LVM/Ceph/Swap" + }, + { + "path": "src/modules/08-tools-about/", + "files": 3, + "init_read": true, + "coverage": "high", + "description": "诊断工具与项目信息：系统信息/救砖/更新/卸载" + }, + { + "path": "src/modules/09-security/", + "files": 3, + "init_read": true, + "coverage": "high", + "description": "安全中心：风险检查/SSH加固" + }, + { + "path": "src/modules/10-third-party/", + "files": 4, + "init_read": true, + "coverage": "high", + "description": "第三方工具：插件市场/CoolerControl/社区脚本" + } + ], + "coverage": "medium" + }, { "path": "Tools/", "name": "第三方工具集", @@ -102,9 +193,9 @@ "data_models": ["无持久化数据模型"], "tests": ["无CI覆盖，由tteck社区人工验证"], "config_files": ["Tools/README.md"], - "scanned_files": ["README.md"], + "scanned_files": ["README.md (上次扫描)", "CLAUDE.md (本次更新)"], "scan_gaps": [ - "13个.sh脚本均未读取详细内容（仅记录文件名和来源）" + "13个.sh脚本均未读取详细内容（仅记录文件名和来源，未发生变化）" ], "coverage": "low" }, @@ -119,9 +210,9 @@ "data_models": ["插件元信息 (name/author/version/github)"], "tests": ["无自动化测试"], "config_files": [], - "scanned_files": ["install-zsh.sh (前30行)"], + "scanned_files": ["install-zsh.sh (上次扫描前30行)", "CLAUDE.md (本次更新)"], "scan_gaps": [ - "install-zsh.sh 完整实现 (仅读了前30行)", + "install-zsh.sh 完整实现 (未变化)", "VGPU/*.so 二进制文件 (仅记录路径)" ], "coverage": "low" @@ -131,94 +222,137 @@ "name": "补充文档", "language": "Markdown", "claude_md": null, - "entry_points": ["Docs/future-guide.md", "Docs/README-EN.md"], - "interfaces": ["2个 Markdown 文档"], + "entry_points": [ + "Docs/重构计划-PVE-Tools模块化拆分.md", + "Docs/future-guide.md", + "Docs/README-EN.md" + ], + "interfaces": ["3个 Markdown 文档"], "dependencies": [], "data_models": [], "tests": [], "config_files": [], - "scanned_files": [], + "scanned_files": [ + "重构计划-PVE-Tools模块化拆分.md (完整读取, 1362行 -- 关键架构文档)" + ], "scan_gaps": [ "future-guide.md 和 README-EN.md 均未读取" ], - "coverage": "none" + "coverage": "medium" }, { "path": ".github/", "name": "CI/CD 与社区", "language": "YAML", - "claude_md": null, - "entry_points": ["workflows/release.yml", "workflows/beta-release.yml", "workflows/pr-validation.yml"], - "interfaces": ["release流水线 (shc编译+GitHub Release)", "beta-release流水线", "PR验证 (shellcheck+版本检查+安全扫描)"], - "dependencies": ["GitHub Actions", "shc", "shellcheck"], + "claude_md": ".github/CLAUDE.md", + "entry_points": [ + "workflows/release.yml", + "workflows/beta-release.yml", + "workflows/pr-validation.yml" + ], + "interfaces": [ + "release流水线 (build.sh + shc编译 + GitHub Release)", + "beta-release流水线", + "PR验证 (shellcheck + bash -n + 版本检查 + 安全扫描)" + ], + "dependencies": ["GitHub Actions", "shc", "shellcheck", "build.sh"], "data_models": [], "tests": ["PR验证流水线自动执行"], - "config_files": ["FUNDING.yml", "ISSUE_TEMPLATE/*.yml"], + "config_files": ["FUNDING.yml", "ISSUE_TEMPLATE/config.yml"], "scanned_files": [ - "release.yml (前60行)", "beta-release.yml (前40行)", "pr-validation.yml (前50行)" + "release.yml (前50行)", + "pr-validation.yml (前50行)", + "FUNDING.yml", + "5个 Issue 模板文件" ], "scan_gaps": [ - "FUNDING.yml 未读取", - "4个 Issue 模板未读取" + "beta-release.yml 未读取", + "release.yml 后半部分 (release notes生成+上传逻辑)" ], "coverage": "medium" + }, + { + "path": "images/", + "name": "截图与图片资源", + "language": "二进制 (PNG/JPG/SVG)", + "claude_md": null, + "entry_points": [], + "interfaces": ["27个图片文件，用于 README 和文档"], + "dependencies": [], + "data_models": [], + "tests": [], + "config_files": [], + "scanned_files": [], + "scan_gaps": ["全部为二进制图片，不读取内容"], + "coverage": "none (intentionally skipped)" + } + ], + "modules_removed_since_last_scan": [ + { + "path": "Web/", + "reason": "VitePress 文档站已从仓库移除 (git log: 'Web文档站移除')，相关 CLAUDE.md 成为孤立文件" } ], "next_steps": { "priority": [ { - "module": "根模块", - "action": "深度扫描 PVE-Tools.sh 未覆盖区域", + "module": "src/modules/04-gpu-passthrough", + "action": "逐文件扫描非 init.sh 实现文件", "paths": [ - "RDM 裸磁盘映射完整实现 (约1954-2240行)", - "PCIe/NVMe 控制器直通 (约2240-2669行)", - "GPU 直通各子菜单 (Intel/NVIDIA/AMD)", - "存储与磁盘维护二级菜单", - "软件源与系统升级二级菜单", - "诊断工具与项目信息菜单" + "src/modules/04-gpu-passthrough/nvidia.sh", + "src/modules/04-gpu-passthrough/iommu.sh", + "src/modules/04-gpu-passthrough/controller.sh" ], - "reason": "主脚本是项目的核心，但目前仅覆盖了约60%的关键区域" + "reason": "GPU 直通是高风险功能域，且文件最多(12个)、内部依赖最复杂" }, { - "module": "Tools", - "action": "抽样阅读代表性脚本", + "module": "src/modules/05-vm-container", + "action": "逐文件扫描非 init.sh 实现文件", "paths": [ - "Tools/post-pve-install.sh", - "Tools/kernel-clean.sh", - "Tools/netdata.sh" + "src/modules/05-vm-container/backup.sh", + "src/modules/05-vm-container/garbage-cleanup.sh", + "src/modules/05-vm-container/disk.sh" ], - "reason": "了解第三方脚本的代码风格和风险等级" + "reason": "VM 运维为第二大模块(15文件)，涉及数据安全" }, { - "module": "Web", - "action": "补充阅读高级教程内容", + "module": "src/modules/06-networking", + "action": "逐文件扫描非 init.sh 实现文件", "paths": [ - "Web/advanced/gpu-passthrough.md", - "Web/advanced/host-network-firewall-ipv6.md", - "Web/advanced/vm-backup-migration-cloudinit.md" + "src/modules/06-networking/firewall.sh", + "src/modules/06-networking/addressing.sh", + "src/modules/06-networking/interface.sh" ], - "reason": "这些教程直接对应主脚本的高风险功能区域" + "reason": "网络模块文件最多(10文件)、子模块交叉引用最密" }, { - "module": "Docs", - "action": "首次读取", + "module": "lib/", + "action": "完整读取 network.sh 后半部分", "paths": [ - "Docs/future-guide.md", - "Docs/README-EN.md" + "lib/network.sh (offset: 50)" ], - "reason": "此前未覆盖，含项目发展路线和英文文档" + "reason": "镜像选择UI函数体尚未完整读取" } ], "optional": [ { - "module": "Modules", - "action": "完整阅读 install-zsh.sh", - "reason": "作为插件规范参考示例" + "module": "Docs", + "action": "读取 future-guide.md 和 README-EN.md", + "reason": "了解项目发展路线和英文文档内容" + }, + { + "module": "Tools", + "action": "抽样读取代表性脚本", + "paths": [ + "Tools/post-pve-install.sh", + "Tools/kernel-clean.sh" + ], + "reason": "验证脚本是否随项目模块化有所变化" }, { "module": ".github", - "action": "阅读 FUNDING.yml 和 Issue 模板", - "reason": "了解社区治理流程" + "action": "读取 beta-release.yml 和 ISSUE_TEMPLATE 文件", + "reason": "完整理解 CI/CD 和社区治理流程" } ] } diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md new file mode 100644 index 0000000..eaa3d85 --- /dev/null +++ b/.github/CLAUDE.md @@ -0,0 +1,117 @@ +[根目录](../CLAUDE.md) > **.github** + +# .github -- CI/CD 工作流与社区治理 + +## 模块职责 + +管理项目的持续集成/持续部署流水线和社区 Issue 模板。三条工作流覆盖 PR 验证、正式发布和测试版发布。 + +## 入口与启动 + +| 项目 | 说明 | +|---|---| +| 触发方式 | GitHub Actions，由 push/pull_request 事件触发 | +| 运行环境 | `ubuntu-latest` | +| 权限 | `contents: write`（Release 工作流需要） | + +## 工作流清单 + +### release.yml -- 正式发布工作流 + +**触发条件**: 推送版本标签 (`v*.*.*`, `*.*.*`, `v*.*.*-stable`, `*.*.*-stable`) + +**步骤**: +1. `actions/checkout@v4`（fetch-depth: 0 以获取完整历史） +2. 从 tag 提取版本号 +3. **`bash build.sh`** -- 将 lib/ + src/modules/ 组装为 `dist/PVE-Tools.sh` +4. 安装 `shc`（via neurobin/ppa） +5. `shc -f dist/PVE-Tools.sh -o pve-tools` -- 编译为二进制 +6. 生成 release notes（基于 git 提交历史） +7. `softprops/action-gh-release@v2` 创建 GitHub Release，上传 `pve-tools` + `dist/PVE-Tools.sh` + +**构建产物**: +- `pve-tools` -- 编译后的二进制文件 +- `dist/PVE-Tools.sh` -- 拼接后的单文件脚本 + +### beta-release.yml -- 测试版发布工作流 + +**触发条件**: 推送 beta/alpha 标签 + +功能与 release.yml 类似，但标记为 prerelease。 + +### pr-validation.yml -- PR 验证工作流 + +**触发条件**: PR 合并到 `main` 或 `beta` 分支 + +**检查项**: + +| 检查 | 命令 | 说明 | +|---|---|---| +| Shellcheck | `shellcheck -f gcc PVE-Tools.sh` | 静态分析，有 error/warning 则失败 | +| 语法检查 | `bash -n PVE-Tools.sh`、`bash -n dev.sh`、`bash -n dist/PVE-Tools.sh` | 先运行 `bash build.sh` 构建再检查 | +| 构建验证 | `bash build.sh` | 验证构建不报错 | +| 版本一致性 | 比较 `lib/config.sh` 中的 `CURRENT_VERSION` 与 `VERSION` 文件 | 不一致则失败 | +| 安全扫描 | grep 检测 `eval`/`source` 使用 | 发现则告警 | + +## Issue 模板 + +| 文件 | 用途 | +|---|---| +| `fast-bugs-report.md` | 快速 Bug 报告 | +| `feature-request.md` | 功能请求 | +| `plugin-submit.md` | 插件提交 | +| `report-bugs.md` | 详细 Bug 报告 | +| `config.yml` | Issue 模板配置 | + +## 其他文件 + +| 文件 | 用途 | +|---|---| +| `FUNDING.yml` | GitHub Sponsors 赞助配置 | + +## 关键依赖与配置 + +- **GitHub Actions**: 免费额度，`ubuntu-latest` runner +- **shc**: 来自 `ppa:neurobin/ppa`，用于 Bash 编译 +- **softprops/action-gh-release@v2**: 第三方 GitHub Action，用于创建 Release +- **shellcheck**: Ubuntu 自带或通过 apt 安装 + +## 测试与质量 + +CI/CD 本身即为项目的测试与质量保障体系： +- 每次 PR 自动执行静态分析、语法检查、版本一致性校验、安全扫描 +- Release 前自动构建并验证构建产物 + +## 常见问题 (FAQ) + +**Q: 为什么 Release 要用 shc 编译？** +shc 将 Bash 脚本编译为二进制文件，提供基础的源码保护，同时便于分发。构建产物 `dist/PVE-Tools.sh` 同时发布以保持 `bash <(curl ...)` 兼容性。 + +**Q: PR 验证中 build.sh 会失败怎么办？** +检查 lib/ 和 src/modules/ 中的文件是否存在、语法是否正确。`bash -n` 仅检查语法不执行代码。 + +**Q: 如何添加新的 Issue 模板？** +在 `ISSUE_TEMPLATE/` 目录添加 `.md` 文件并更新 `config.yml` 即可，GitHub 会自动识别。 + +## 相关文件清单 + +``` +.github/ + workflows/ + release.yml # 正式发布工作流 + beta-release.yml # 测试版发布工作流 + pr-validation.yml # PR 验证工作流 + ISSUE_TEMPLATE/ + fast-bugs-report.md # 快速 Bug 报告模板 + feature-request.md # 功能请求模板 + plugin-submit.md # 插件提交模板 + report-bugs.md # 详细 Bug 报告模板 + config.yml # Issue 模板配置 + FUNDING.yml # 赞助配置 +``` + +## 变更记录 (Changelog) + +| 日期 | 变更 | +|---|---| +| 2026-07-08 | 初始化 .github 模块 CLAUDE.md。PR 验证已适配模块化（build.sh/build -n dist）。Release 已添加 build.sh 步骤。 | diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 44adcab..4c1d090 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -21,10 +21,13 @@ jobs: - name: Shell syntax check run: | bash -n PVE-Tools.sh + bash -n dev.sh + bash build.sh + bash -n dist/PVE-Tools.sh - name: Version consistency check run: | - SCRIPT_VERSION=$(grep "CURRENT_VERSION=" PVE-Tools.sh | cut -d'"' -f2) + SCRIPT_VERSION=$(grep "CURRENT_VERSION=" lib/config.sh | cut -d'"' -f2) VERSION_FILE_VERSION=$(cat VERSION 2>/dev/null) if [ "$SCRIPT_VERSION" != "$VERSION_FILE_VERSION" ]; then echo "Version inconsistency: script($SCRIPT_VERSION) != version file($VERSION_FILE_VERSION)" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 75676e4..34ab676 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,6 +25,9 @@ jobs: VERSION=${TAG#v} echo "TAG=$TAG" >> $GITHUB_OUTPUT echo "VERSION=$VERSION" >> $GITHUB_OUTPUT + + - name: Build single script from modules + run: bash build.sh - name: Install shc run: | @@ -34,7 +37,7 @@ jobs: - name: Compile script to binary run: | - shc -f PVE-Tools.sh -o pve-tools + shc -f dist/PVE-Tools.sh -o pve-tools chmod +x pve-tools - name: Generate release notes @@ -81,7 +84,7 @@ jobs: ``` files: | pve-tools - PVE-Tools.sh + dist/PVE-Tools.sh draft: false prerelease: false env: diff --git a/.gitignore b/.gitignore index 51104fa..3d1459f 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,6 @@ _bmad/ _bmad-output/ test.txt + +# ignore docs +Docs/ diff --git a/CLAUDE.md b/CLAUDE.md index 8a52c78..a226065 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,38 +8,12 @@ PVE Tools Pro 是一个面向 Proxmox VE 9.x 的交互式 Bash 运维工具集 ## 架构总览 -```mermaid -graph TD - A["(根) PVE Tools Pro"] --> B["PVE-Tools.sh (主脚本)"] - A --> C["Web"] - A --> D["Tools"] - A --> E["Modules"] - A --> F["Docs"] - A --> G[".github"] +项目已完成模块化重构（v9.0.0），从单一 430KB 脚本拆分为基础设施层（lib/）与功能模块层（src/modules/），通过 build.sh 组装为单文件发布，用户侧零感知。 - C --> C1["VitePress 文档站"] - C --> C2["Vue 组件 (5个)"] - C --> C3["高级教程 (10篇)"] - - D --> D1["PVE 后安装配置"] - D --> D2["LXC 容器管理"] - D --> D3["系统维护工具"] - D --> D4["监控工具"] - - E --> E1["插件市场"] - E --> E2["VGPU .so"] - - G --> G1["CI/CD Workflows"] - G --> G2["Issue Templates"] - - click B "./PVE-Tools.sh" "主入口脚本" - click C "./Web/CLAUDE.md" "查看 Web 模块文档" - click D "./Tools/CLAUDE.md" "查看 Tools 模块文档" - click E "./Modules/CLAUDE.md" "查看 Modules 模块文档" -``` - -- **核心入口**: `PVE-Tools.sh`（约 430KB，单一 Bash 脚本），通过 `bash <(curl -sSL ...)` 方式分发执行。 -- **文档站**: `Web/` 目录承载 VitePress 构建的官方文档网站，部署于 Cloudflare Pages。 +- **入口层**: `PVE-Tools.sh`（169 行）-- 本地开发时 source lib/ + src/modules/；远程 curl 运行时自动下载 dist/ 构建产物或逐个下载源码模块。 +- **基础设施层**: `lib/` -- 全局变量(config.sh)、日志/UI/备份/GRUB(core.sh)、网络检测/镜像选择(network.sh)、运行时守卫(runtime.sh)。 +- **功能模块层**: `src/modules/` -- 10 个子目录对应主菜单 1-10 项，每个子目录内按功能拆分文件（init.sh 为菜单入口）。 +- **构建系统**: `build.sh` 按顺序拼接 lib/*.sh + src/modules/**/*.sh 为 `dist/PVE-Tools.sh`；`dev.sh` 直接 source 全部源码供开发调试。 - **辅助工具集**: `Tools/` 集成来自 tteck 社区的 13 个系统维护脚本。 - **插件市场**: `Modules/` 提供第三方脚本的自动发现与执行框架。 - **CI/CD**: `.github/workflows/` 提供 release、beta-release、pr-validation 三条流水线。 @@ -48,63 +22,76 @@ graph TD ```mermaid graph TD - ROOT["PVE Tools Pro (根)"] --> MAIN["PVE-Tools.sh
主脚本 430KB"] - ROOT --> WEB["Web/"] + ROOT["PVE Tools Pro (根)"] --> MAIN["PVE-Tools.sh
入口脚本 169行"] + ROOT --> LIB["lib/
基础设施层"] + ROOT --> SRC["src/modules/
功能模块层"] ROOT --> TOOLS["Tools/"] ROOT --> MODS["Modules/"] ROOT --> DOCS["Docs/"] ROOT --> GHA[".github/"] + ROOT --> BUILD["build.sh + dev.sh
构建与开发入口"] - WEB --> VITEPRESS[".vitepress/
主题/配置/组件"] - WEB --> PAGES["*.md 文档页面"] - WEB --> ADVANCED["advanced/
高级教程 10篇"] - WEB --> ASSETS["assets/ + public/
图片/Logo/SVG"] + LIB --> LIBC["config.sh
全局变量/镜像/URL"] + LIB --> LIBCORE["core.sh
颜色/日志/UI/备份/GRUB"] + LIB --> LIBNET["network.sh
网络检测/镜像选择"] + LIB --> LIBRUN["runtime.sh
root守卫/调试/PVE检测"] - TOOLS --> SYS["系统配置: 5个脚本"] - TOOLS --> LXC["容器管理: 3个脚本"] - TOOLS --> MAINT["系统维护: 4个脚本"] - TOOLS --> MONITOR["监控: 2个脚本"] + SRC --> M01["01-optimization
日常优化与通知"] + SRC --> M02["02-sources
软件源与系统升级"] + SRC --> M03["03-boot-kernel
启动与内核管理"] + SRC --> M04["04-gpu-passthrough
硬件直通与显卡"] + SRC --> M05["05-vm-container
虚拟机运维与导入"] + SRC --> M06["06-networking
宿主机网络与防火墙"] + SRC --> M07["07-storage-disk
存储与磁盘维护"] + SRC --> M08["08-tools-about
诊断工具与项目信息"] + SRC --> M09["09-security
安全中心"] + SRC --> M10["10-third-party
第三方工具"] - MODS --> PLUGINS["插件脚本 (.sh)"] - MODS --> VGPU["VGPU/libvgpu_*.so"] + TOOLS --> T1["系统配置: 5个脚本"] + TOOLS --> T2["容器管理: 3个脚本"] + TOOLS --> T3["系统维护: 4个脚本"] + TOOLS --> T4["监控: 1个脚本"] - GHA --> WF["workflows/
release/beta/PR"] + MODS --> P1["install-zsh.sh"] + MODS --> P2["VGPU/*.so"] + + GHA --> W1["workflows/
release/beta/PR"] click ROOT "./CLAUDE.md" "返回根文档" - click WEB "./Web/CLAUDE.md" "查看 Web 模块文档" + click LIB "./lib/CLAUDE.md" "查看 lib 模块文档" + click SRC "./src/CLAUDE.md" "查看 src 模块文档" click TOOLS "./Tools/CLAUDE.md" "查看 Tools 模块文档" click MODS "./Modules/CLAUDE.md" "查看 Modules 模块文档" + click GHA "./.github/CLAUDE.md" "查看 CI/CD 模块文档" ``` ## 模块索引 | 模块路径 | 语言 | 职责 | 入口文件 | 文档 | |---|---|---|---|---| -| `/` (根) | Bash | 主脚本，全部功能入口 | `PVE-Tools.sh` | `README.md` | -| `Web/` | TypeScript/Vue/Markdown | VitePress 文档站 | `Web/index.md`, `Web/.vitepress/config.mts` | [Web/CLAUDE.md](./Web/CLAUDE.md) | -| `Tools/` | Bash | 第三方系统维护脚本集 | 各 `.sh` 文件 | [Tools/CLAUDE.md](./Tools/CLAUDE.md) | +| `/` (根) | Bash | 入口脚本，本地/远程模块加载 | `PVE-Tools.sh` (169行) | `README.md` | +| `lib/` | Bash | 基础设施层：全局变量、日志、UI、网络、运行时 | `config.sh`, `core.sh`, `network.sh`, `runtime.sh` | [lib/CLAUDE.md](./lib/CLAUDE.md) | +| `src/modules/` | Bash | 功能模块层：10 个子模块，对应主菜单 1-10 | 各 `*/init.sh` | [src/CLAUDE.md](./src/CLAUDE.md) | +| `Tools/` | Bash | 第三方系统维护脚本集（13个） | 各 `.sh` 文件 | [Tools/CLAUDE.md](./Tools/CLAUDE.md) | | `Modules/` | Bash/二进制 | 插件市场与模块 | `install-zsh.sh`, `VGPU/*.so` | [Modules/CLAUDE.md](./Modules/CLAUDE.md) | -| `Docs/` | Markdown | 补充文档 | `future-guide.md`, `README-EN.md` | -- | -| `.github/` | YAML | CI/CD 工作流与 Issue 模板 | `workflows/*.yml` | -- | +| `Docs/` | Markdown | 补充文档与重构计划 | `future-guide.md`, `重构计划-PVE-Tools模块化拆分.md` | -- | +| `.github/` | YAML | CI/CD 工作流与 Issue 模板 | `workflows/*.yml` | [.github/CLAUDE.md](./.github/CLAUDE.md) | ## 技术栈 | 层面 | 技术 | 版本/说明 | |---|---|---| | 运行环境 | Proxmox VE 9.x (Debian 13 Trixie) | 要求 root 权限 | -| 主脚本语言 | GNU Bash | 单一文件，通过 curl 管道分发执行 | -| 文档站构建 | VitePress | v1.6.4，部署于 Cloudflare Pages | -| 前端框架 | Vue 3 | v3.5.27，仅用于文档站主题组件 | -| 图标库 | lucide-vue-next | v0.563.0 | -| 运行时 | Bun | Web 目录依赖管理（bun.lock） | +| 主脚本语言 | GNU Bash | 模块化源码；通过 build.sh 组装为单文件分发 | +| 构建系统 | bash + find + sort | `build.sh` 顺序拼接 lib/ -> src/modules/ -> dist/PVE-Tools.sh | +| 开发模式 | bash dev.sh | 直接 source 全部源文件，无需构建 | | CI/CD | GitHub Actions | release / beta-release / PR validation | -| 编译工具 | shc | 将 Bash 编译为二进制（仅 release 流程） | +| 编译工具 | shc | 将 dist/PVE-Tools.sh 编译为二进制（仅 release 流程） | | 许可证 | GPL-3.0 | 详见 `LICENSE` | -| 分析 | Umami | 文档站匿名访问统计 | ## 运行与开发 -### 使用脚本（用户侧） +### 用户使用 ```bash # Cloudflare 短域名（推荐） @@ -113,45 +100,62 @@ bash <(curl -sSL https://pve.oowo.cc/PVE-Tools.sh) # 中国大陆网络 bash <(curl -sSL https://ghfast.top/raw.githubusercontent.com/PVE-Tools/PVE-Tools-9/main/PVE-Tools.sh) -# 国际网络 / 本地 -wget https://raw.githubusercontent.com/PVE-Tools/PVE-Tools-9/main/PVE-Tools.sh -chmod +x PVE-Tools.sh -sudo ./PVE-Tools.sh +# 本地开发 +bash dev.sh ``` -### 开发文档站（Web 模块） +### 开发工作流 ```bash -cd Web -bun install # 或 npm install -bun run dev # 启动本地开发服务器 -bun run build # 构建到 .vitepress/dist/ -bun run preview # 预览构建结果 +# 改代码 -> 直接运行验证 +bash dev.sh + +# 确认改好了 -> 构建单文件 +bash build.sh + +# 验证构建产物 +bash dist/PVE-Tools.sh + +# 静态检查 +bash -n PVE-Tools.sh +bash -n dist/PVE-Tools.sh +shellcheck -f gcc PVE-Tools.sh +shellcheck -f gcc dist/PVE-Tools.sh ``` +### 构建原理 + +`build.sh` 按以下固定顺序拼接： +1. `lib/config.sh` -- 全局变量定义（必须最先加载） +2. `lib/core.sh` -- 日志/UI/备份/GRUB（依赖 config.sh 中的变量） +3. `lib/network.sh` -- 网络检测/镜像选择 +4. `lib/runtime.sh` -- 运行时守卫/main()函数 +5. `src/modules/**/*.sh` -- 按路径名排序（`sort -z`），确保 init.sh 先于同目录其他文件加载 + ### CI/CD 流水线 - **PR 合并到 main/beta**: 触发 shellcheck、Bash 语法检查、版本一致性校验、安全扫描。 -- **推送版本标签 (v*.*.*)**: 触发 Release 工作流，用 shc 编译二进制，自动生成 GitHub Release。 +- **推送版本标签 (v*.*.*)**: 触发 Release 工作流，先执行 `bash build.sh` 构建，再用 shc 编译二进制，自动生成 GitHub Release。 - **推送 beta/alpha 标签**: 触发 Beta Release 工作流。 ## 测试策略 | 类型 | 方式 | 说明 | |---|---|---| -| 语法检查 | `bash -n PVE-Tools.sh` | CI 中强制通过 | -| 静态分析 | `shellcheck -f gcc PVE-Tools.sh` | CI 中强制通过 | +| 语法检查 | `bash -n PVE-Tools.sh`、`bash -n dist/PVE-Tools.sh` | CI 中强制通过 | +| 静态分析 | `shellcheck -f gcc PVE-Tools.sh` | CI 中强制通过，需额外关注多文件 source 模式 | | 版本一致性 | 比较脚本内 `CURRENT_VERSION` 与 `VERSION` 文件 | CI 中强制通过 | | 安全扫描 | 检测 `eval`/`source` 使用 | CI 中告警 | | 功能测试 | 手动在 PVE 9.x 环境验证 | 无自动化 E2E 测试 | -**注意**: 本项目目前没有自动化单元测试或集成测试。所有功能验证依赖人工在真实或模拟的 PVE 9.x 环境中测试。 +**注意**: 本项目目前没有自动化单元测试或集成测试。所有功能验证依赖人工在真实或模拟的 PVE 9.x 环境中测试。模块化后，建议在每次 PR 时同时验证 `bash dev.sh` 和 `bash build.sh && bash dist/PVE-Tools.sh` 的行为一致性。 ## 编码规范 ### Bash 脚本规范 - Shebang: `#!/bin/bash` +- 版权声明: 每个文件头部包含 `# SPDX-License-Identifier: GPL-3.0-only` 和 `# Copyright (C) 2026 Ciriu Networks` - 缩进: 4 空格 - 函数命名: `snake_case`（如 `vm_validate_new_vmid`、`host_network_get_bridges`） - 变量命名: `UPPER_SNAKE`（全局配置常量）、`lower_case`（局部变量） @@ -162,23 +166,21 @@ bun run preview # 预览构建结果 - 配置备份: 修改系统配置文件前调用 `backup_file()` 自动备份到 `/var/backups/pve-tools/` - 幂等性: GRUB 参数等配置通过专用幂等管理函数修改，支持增删查 - 日志文件: 所有操作记录到 `/var/log/pve-tools.log` - -### 文档站 (Vue/TypeScript) 规范 - -- 使用 VitePress 默认主题扩展 -- 自定义组件放置在 `Web/.vitepress/theme/components/` -- 组件使用 `