wangdefa/tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加项目主 README 文档

Browse Source 
## 新增内容

添加项目根目录 README.md，提供完整的项目介绍和使用指南。

## 文档内容

### 核心章节

1. **项目简介**: 概述项目目标和核心特性
2. **项目结构**: 清晰的目录树和模块说明
3. **快速开始**: 三种使用模式的快速指南
4. **功能模块**: 详细的工具功能和使用示例
5. **远程库加载**: 智能加载机制说明
6. **公共库**: logging.sh 和 error_handler.sh 使用方法
7. **文档导航**: llmdoc 文档系统链接
8. **开发指南**: 编码规范和贡献流程

### 特色内容

- ✅ Shields.io 徽章（版本、Shell、许可证）
- ✅ Emoji 图标增强可读性
- ✅ 代码示例和命令行演示
- ✅ 环境变量配置表格
- ✅ 完整的使用场景覆盖
- ✅ 内部文档交叉引用
- ✅ 版本更新日志

### 使用场景

- 📖 新用户快速了解项目
- 🚀 快速开始使用工具
- 📚 查找功能和使用方法
- 🔗 导航到详细文档
This commit is contained in:
Wang Defa
2025-12-26 15:02:30 +08:00
parent b34e1ef872
commit f6d9274306
1 changed files with 363 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

363
README.md Normal file
View File

@@ -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
---
⭐ 如果这个项目对你有帮助，请给我们一个星标！