From f6d9274306600b38926b2e32530095e4881408fa Mon Sep 17 00:00:00 2001 From: Wang Defa Date: Fri, 26 Dec 2025 15:02:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E4=B8=BB=20README=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 新增内容 添加项目根目录 README.md，提供完整的项目介绍和使用指南。 ## 文档内容 ### 核心章节 1. **项目简介**: 概述项目目标和核心特性 2. **项目结构**: 清晰的目录树和模块说明 3. **快速开始**: 三种使用模式的快速指南 4. **功能模块**: 详细的工具功能和使用示例 5. **远程库加载**: 智能加载机制说明 6. **公共库**: logging.sh 和 error_handler.sh 使用方法 7. **文档导航**: llmdoc 文档系统链接 8. **开发指南**: 编码规范和贡献流程 ### 特色内容 - ✅ Shields.io 徽章（版本、Shell、许可证） - ✅ Emoji 图标增强可读性 - ✅ 代码示例和命令行演示 - ✅ 环境变量配置表格 - ✅ 完整的使用场景覆盖 - ✅ 内部文档交叉引用 - ✅ 版本更新日志 ### 使用场景 - 📖 新用户快速了解项目 - 🚀 快速开始使用工具 - 📚 查找功能和使用方法 - 🔗 导航到详细文档 --- README.md | 363 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 363 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..57ce901 --- /dev/null +++ b/README.md @@ -0,0 +1,363 @@ +# 云计算和系统管理工具集 + +> 一个跨云平台和 Linux 系统管理的自动化脚本工具集 + +[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/wangdefa/tools) +[![Shell](https://img.shields.io/badge/shell-bash-green.svg)](https://www.gnu.org/software/bash/) +[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE) + +## 📋 项目简介 + +该工具集为系统管理员、云工程师和 DevOps 人员提供一站式的自动化管理解决方案，简化云基础设施管理、系统配置和部署流程。 + +### ✨ 核心特性 + +- 🌐 **跨云平台支持**：GCP、Oracle Cloud Infrastructure (OCI) +- 🔧 **系统管理自动化**：RAID、磁盘分区、环境配置 +- 📦 **模块化设计**：可重用的公共库和独立脚本 +- 🚀 **远程加载支持**：脚本可独立运行，无需本地依赖 +- 📝 **统一规范**：标准化的命名、日志和错误处理 +- 🎨 **友好输出**：彩色终端输出和详细日志 + +## 🗂️ 项目结构 + +``` +tools/ +├── gcp/ # Google Cloud Platform 工具 +│ ├── create_ai_projects.sh # 批量创建 AI 项目 +│ └── delete_all_projects.sh # 批量删除项目 +├── oci/ # Oracle Cloud Infrastructure 工具 +│ └── create_instance.sh # 批量部署虚拟机 +├── linux/ # Linux 系统管理工具 +│ ├── create_raid0_array.sh # 创建 RAID 0 阵列 +│ ├── repartition_disks.sh # 重新分区磁盘 +│ └── install_oh_my_zsh.sh # 安装 Oh My Zsh +├── common/ # 公共函数库 +│ ├── logging.sh # 日志系统 +│ ├── error_handler.sh # 错误处理 +│ ├── remote_loader.sh # 远程加载器 +│ ├── demo_usage.sh # 功能演示 +│ └── README.md # 库文档 +├── examples/ # 使用示例 +│ ├── remote_example.sh # 纯远程模式示例 +│ ├── hybrid_loader_template.sh # 混合模式模板 +│ └── REMOTE_LOADER_README.md # 远程加载文档 +└── llmdoc/ # 项目文档系统 + ├── index.md # 文档索引 + ├── overview/ # 项目概览 + ├── guides/ # 使用指南 + ├── architecture/ # 架构文档 + └── reference/ # 参考文档 +``` + +## 🚀 快速开始 + +### 前置要求 + +- Bash 4.0+ +- curl 或 wget（用于远程加载） +- 对应云平台的 CLI 工具（gcloud、oci-cli 等） + +### 基本使用 + +#### 1. 本地模式（默认） + +克隆仓库后直接运行： + +```bash +git clone https://gitea.bcde.io/wangdefa/tools.git +cd tools + +# 运行 Linux 工具 +sudo ./linux/create_raid0_array.sh + +# 运行 GCP 工具 +./gcp/create_ai_projects.sh -n 5 --prefix my-project + +# 运行 OCI 工具 +./oci/create_instance.sh -n 3 --shape VM.Standard.A1.Flex +``` + +#### 2. 远程模式（独立运行） + +无需克隆仓库，直接下载并运行： + +```bash +# 下载并运行 RAID 创建脚本 +curl -fsSL https://gitea.bcde.io/wangdefa/tools/raw/branch/main/linux/create_raid0_array.sh | bash + +# 或使用 wget +wget -qO- https://gitea.bcde.io/wangdefa/tools/raw/branch/main/linux/create_raid0_array.sh | bash +``` + +#### 3. 强制远程模式 + +在本地环境中强制使用远程库（获取最新版本）： + +```bash +FORCE_REMOTE=1 ./linux/create_raid0_array.sh +``` + +## 📦 功能模块 + +### GCP 管理工具 + +#### create_ai_projects.sh - 批量创建 AI 项目 + +批量创建 Google Cloud AI Platform 项目并配置相关服务。 + +```bash +./gcp/create_ai_projects.sh -n 10 --prefix ml-project --region us-central1 +``` + +**主要功能：** +- 批量创建项目 +- 自动启用 AI Platform API +- 配置项目计费 +- 设置项目权限 + +#### delete_all_projects.sh - 批量删除项目 + +批量删除 Google Cloud 项目（带保护机制）。 + +```bash +./gcp/delete_all_projects.sh --prefix ml-project --confirm +``` + +**安全特性：** +- 二次确认机制 +- 排除生产项目 +- 详细删除日志 + +### OCI 管理工具 + +#### create_instance.sh - 批量部署虚拟机 + +在 Oracle Cloud 上批量创建和配置虚拟机实例。 + +```bash +./oci/create_instance.sh -n 5 \ + --shape VM.Standard.A1.Flex \ + --shape_config 2+12 \ + --image_name "Canonical-Ubuntu-20.04-aarch64-2025.05.20-0" +``` + +**功能特性：** +- 自动创建 VCN 和子网 +- IPv4/IPv6 双栈支持 +- 自定义实例规格 +- 自动配置 SSH 访问 +- 密码自动生成和标签记录 + +### Linux 系统管理工具 + +#### create_raid0_array.sh - 创建 RAID 0 阵列 + +自动创建并挂载 RAID 0 存储阵列。 + +```bash +sudo ./linux/create_raid0_array.sh +``` + +**功能：** +- 自动检测可用磁盘 +- 创建 RAID 0 阵列 +- 格式化为 ext4 +- 配置自动挂载 + +#### repartition_disks.sh - 重新分区磁盘 + +删除所有非系统盘的分区并创建新的 GPT 分区表。 + +```bash +sudo ./linux/repartition_disks.sh +``` + +**安全特性：** +- 自动识别系统盘并排除 +- 逐个磁盘处理 +- 详细操作日志 + +#### install_oh_my_zsh.sh - 安装 Oh My Zsh + +一键安装和配置 Oh My Zsh 开发环境。 + +```bash +./linux/install_oh_my_zsh.sh +``` + +**配置项：** +- 自动安装 Zsh +- 配置 Oh My Zsh +- 安装常用插件 +- 切换默认 Shell + +## 🌐 远程库加载 + +所有脚本支持智能远程库加载机制，可在无本地依赖的情况下运行。 + +### 加载策略 + +1. **FORCE_REMOTE=1** → 强制使用远程库 +2. **本地库存在** → 优先使用本地（默认） +3. **本地不存在** → 自动回退远程 +4. **远程失败** → 友好错误提示 + +### 环境变量 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `REMOTE_LIB_URL` | 远程仓库 URL | `https://gitea.bcde.io/wangdefa/tools/raw/branch/main` | +| `FORCE_REMOTE` | 强制使用远程库 | `0` | + +### 使用示例 + +```bash +# 使用本地库（默认） +./linux/create_raid0_array.sh + +# 强制使用远程库 +FORCE_REMOTE=1 ./linux/create_raid0_array.sh + +# 使用自定义仓库 URL +REMOTE_LIB_URL=https://example.com/repo ./script.sh + +# 完全独立运行（无需克隆） +curl -fsSL https://gitea.bcde.io/wangdefa/tools/raw/branch/main/linux/create_raid0_array.sh | bash +``` + +详细文档：[examples/REMOTE_LOADER_README.md](examples/REMOTE_LOADER_README.md) + +## 📚 公共库 + +### logging.sh - 日志系统 + +提供统一的日志输出功能，支持多级别和彩色输出。 + +```bash +source common/logging.sh + +log_debug "调试信息" +log_info "普通信息" +log_warning "警告信息" +log_error "错误信息（不退出）" +log_success "成功信息" +``` + +**功能：** +- 5 个日志级别（DEBUG/INFO/WARNING/ERROR/SUCCESS） +- 彩色终端输出 +- 时间戳支持 +- 日志文件输出 + +### error_handler.sh - 错误处理 + +提供错误检查和命令执行辅助函数。 + +```bash +source common/error_handler.sh + +check_command "jq" # 检查命令是否存在 +check_file "/path/to/file" # 检查文件是否存在 +check_not_empty "$var" "var_name" # 检查变量非空 +check_return $? "操作失败" # 检查返回码 + +run_command "描述" command args # 执行命令并检查结果 +retry_command 3 2 "失败" command # 重试执行命令 +``` + +详细文档：[common/README.md](common/README.md) + +## 📖 文档 + +完整的项目文档位于 `llmdoc/` 目录： + +- [llmdoc/index.md](llmdoc/index.md) - 文档索引 +- [llmdoc/overview/project-overview.md](llmdoc/overview/project-overview.md) - 项目概览 +- [llmdoc/guides/getting-started.md](llmdoc/guides/getting-started.md) - 快速开始 +- [llmdoc/guides/common-library-usage.md](llmdoc/guides/common-library-usage.md) - 库使用指南 +- [llmdoc/architecture/common-libraries.md](llmdoc/architecture/common-libraries.md) - 架构设计 +- [llmdoc/reference/coding-conventions.md](llmdoc/reference/coding-conventions.md) - 编码规范 +- [llmdoc/reference/common-library-reference.md](llmdoc/reference/common-library-reference.md) - API 参考 + +## 🔧 开发 + +### 编码规范 + +本项目遵循严格的 Bash 编码规范： + +- **命名规范**：snake_case（函数、变量、文件） +- **文件命名**：`动词_名词.sh`（如 `create_raid0_array.sh`） +- **函数注释**：使用标准化的文档注释格式 +- **错误处理**：使用 `set -euo pipefail` 严格模式 +- **代码风格**：4 空格缩进，ShellCheck 检查 + +详见：[llmdoc/reference/coding-conventions.md](llmdoc/reference/coding-conventions.md) + +### 添加新脚本 + +1. 参考 [examples/hybrid_loader_template.sh](examples/hybrid_loader_template.sh) 创建脚本 +2. 添加远程库加载支持 +3. 使用公共库函数 +4. 遵循命名和注释规范 +5. 执行 `shellcheck` 检查 +6. 更新文档 + +### 测试 + +```bash +# 语法检查 +bash -n script.sh + +# ShellCheck 检查 +shellcheck script.sh + +# 功能测试 +./common/demo_usage.sh +``` + +## 🤝 贡献 + +欢迎贡献代码、报告问题或提出建议！ + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/amazing-feature`) +3. 提交更改 (`git commit -m 'feat: add amazing feature'`) +4. 推送到分支 (`git push origin feature/amazing-feature`) +5. 创建 Pull Request + +## 📝 更新日志 + +### v2.1.0 (2025-01-XX) + +- ✨ 新增远程库加载支持 +- ✨ 新增混合加载模式（本地优先 + 远程回退） +- ✨ 新增环境变量配置（FORCE_REMOTE、REMOTE_LIB_URL） +- 📝 完善文档系统 +- 🔧 统一文件命名规范 + +### v2.0.0 (2025-01-XX) + +- ✨ 重构所有脚本使用公共库 +- ✨ 新增统一日志系统 +- ✨ 新增错误处理机制 +- 📝 添加完整的函数注释 +- 🐛 修复 Bash 兼容性问题 + +## 📄 许可证 + +本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 + +## 👥 作者 + +Cloud Tools Project + +## 🔗 相关链接 + +- **仓库地址**: https://gitea.bcde.io/wangdefa/tools +- **问题反馈**: https://gitea.bcde.io/wangdefa/tools/issues +- **在线文档**: https://gitea.bcde.io/wangdefa/tools/wiki + +--- + +⭐ 如果这个项目对你有帮助，请给我们一个星标！