feat: 为所有脚本添加远程库加载支持
## 功能概述 实现了智能远程库加载机制，允许脚本从远程 Gitea 仓库动态下载公共库， 同时保留本地库优先的策略，确保脚本可以独立运行而不依赖本地项目结构。 ## 变更内容 ### 新增文件 - **common/remote_loader.sh**: 核心远程加载器 - 支持 curl/wget 双重下载方式 - 临时文件自动清理机制 - 环境变量可配置仓库 URL - **examples/remote_example.sh**: 纯远程模式示例 - 演示完全独立的远程加载脚本 - 适合单文件分发场景 - **examples/hybrid_loader_template.sh**: 混合模式模板 - 本地优先 + 远程回退策略 - 适合仓库内脚本 - **examples/REMOTE_LOADER_README.md**: 完整使用文档 - 三种使用模式详解 - 故障排除指南 - 最佳实践建议 ### 更新脚本（版本 2.1.0） 所有主要脚本均升级到 2.1.0 版本，支持智能库加载： - **linux/create_raid0_array.sh** - **linux/repartition_disks.sh** - **linux/install_oh_my_zsh.sh** - **gcp/create_ai_projects.sh** - **gcp/delete_all_projects.sh** - **oci/create_instance.sh** - **common/demo_usage.sh** ## 加载策略 1. 检查 FORCE_REMOTE=1 环境变量 → 强制远程 2. 检查本地库存在性 → 优先使用本地 3. 本地不存在 → 自动回退远程 4. 远程失败 → 友好错误提示 ## 使用示例 ### 本地模式（默认） ```bash ./linux/create_raid0_array.sh ``` ### 强制远程模式 ```bash FORCE_REMOTE=1 ./linux/create_raid0_array.sh ``` ### 自定义仓库 URL ```bash REMOTE_LIB_URL=https://example.com/repo ./script.sh ``` ## 技术特性 - ✅ 向后兼容：默认使用本地库，行为不变 - ✅ 离线可用：本地库存在时无需网络 - ✅ 独立分发：支持单文件脚本分发 - ✅ 错误处理：详细的错误信息和诊断建议 - ✅ 环境可配：REMOTE_LIB_URL 和 FORCE_REMOTE - ✅ 自动清理：临时文件通过 trap 自动删除
This commit is contained in:
289
examples/REMOTE_LOADER_README.md
Normal file
289
examples/REMOTE_LOADER_README.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 远程库加载器使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
远程库加载器允许脚本从 Gitea 仓库动态下载并加载公共库，使得脚本可以独立运行而不依赖本地的 `common/` 目录。
|
||||
|
||||
## 仓库 URL
|
||||
|
||||
```
|
||||
https://gitea.bcde.io/wangdefa/tools/raw/branch/main
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 方式 1: 纯远程模式（推荐用于独立脚本）
|
||||
|
||||
适用于需要独立分发的脚本，每次运行都下载最新版本的公共库。
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# 直接从远程加载
|
||||
if command -v curl &>/dev/null; then
|
||||
source <(curl -fsSL https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh)
|
||||
elif command -v wget &>/dev/null; then
|
||||
source <(wget -qO- https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh)
|
||||
else
|
||||
echo "[ERROR] 需要 curl 或 wget" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 现在可以使用公共库函数
|
||||
log_info "Hello World"
|
||||
```
|
||||
|
||||
### 方式 2: 混合模式（推荐用于仓库内脚本）
|
||||
|
||||
优先使用本地库，本地不存在时自动使用远程库。
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
readonly REMOTE_BASE_URL="https://gitea.bcde.io/wangdefa/tools/raw/branch/main"
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
|
||||
# 智能加载函数
|
||||
load_common_libs() {
|
||||
# 尝试本地
|
||||
if [[ -f "${PROJECT_ROOT}/common/logging.sh" ]]; then
|
||||
source "${PROJECT_ROOT}/common/logging.sh"
|
||||
source "${PROJECT_ROOT}/common/error_handler.sh"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# 回退到远程
|
||||
if command -v curl &>/dev/null; then
|
||||
source <(curl -fsSL "${REMOTE_BASE_URL}/common/remote_loader.sh")
|
||||
elif command -v wget &>/dev/null; then
|
||||
source <(wget -qO- "${REMOTE_BASE_URL}/common/remote_loader.sh")
|
||||
else
|
||||
echo "[ERROR] 无法加载库" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
load_common_libs
|
||||
|
||||
# 使用公共库
|
||||
log_info "使用混合模式"
|
||||
```
|
||||
|
||||
### 方式 3: 环境变量控制
|
||||
|
||||
通过环境变量灵活切换本地/远程模式。
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
|
||||
# 检查是否强制使用远程
|
||||
if [[ "${FORCE_REMOTE:-0}" == "1" ]]; then
|
||||
# 使用远程
|
||||
source <(curl -fsSL https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh)
|
||||
else
|
||||
# 使用本地
|
||||
source "${PROJECT_ROOT}/common/logging.sh"
|
||||
source "${PROJECT_ROOT}/common/error_handler.sh"
|
||||
fi
|
||||
```
|
||||
|
||||
使用方法：
|
||||
```bash
|
||||
# 使用本地库
|
||||
./script.sh
|
||||
|
||||
# 强制使用远程库
|
||||
FORCE_REMOTE=1 ./script.sh
|
||||
```
|
||||
|
||||
## 完整示例
|
||||
|
||||
### 示例 1: 纯远程脚本
|
||||
|
||||
参见 [remote_example.sh](./remote_example.sh)
|
||||
|
||||
运行：
|
||||
```bash
|
||||
chmod +x examples/remote_example.sh
|
||||
./examples/remote_example.sh
|
||||
```
|
||||
|
||||
### 示例 2: 混合模式脚本
|
||||
|
||||
参见 [hybrid_loader_template.sh](./hybrid_loader_template.sh)
|
||||
|
||||
运行：
|
||||
```bash
|
||||
chmod +x examples/hybrid_loader_template.sh
|
||||
|
||||
# 使用本地库（如果存在）
|
||||
./examples/hybrid_loader_template.sh
|
||||
|
||||
# 强制使用远程库
|
||||
FORCE_REMOTE=1 ./examples/hybrid_loader_template.sh
|
||||
```
|
||||
|
||||
## 更新现有脚本
|
||||
|
||||
### 步骤 1: 备份原脚本
|
||||
|
||||
```bash
|
||||
cp linux/create_raid0_array.sh linux/create_raid0_array.sh.bak
|
||||
```
|
||||
|
||||
### 步骤 2: 替换加载部分
|
||||
|
||||
**原代码：**
|
||||
```bash
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
|
||||
source "${PROJECT_ROOT}/common/logging.sh"
|
||||
source "${PROJECT_ROOT}/common/error_handler.sh"
|
||||
```
|
||||
|
||||
**新代码（纯远程）：**
|
||||
```bash
|
||||
# 远程加载
|
||||
if command -v curl &>/dev/null; then
|
||||
source <(curl -fsSL https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh)
|
||||
elif command -v wget &>/dev/null; then
|
||||
source <(wget -qO- https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh)
|
||||
else
|
||||
echo "[ERROR] 需要 curl 或 wget" >&2
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**新代码（混合模式）：**
|
||||
```bash
|
||||
readonly REMOTE_BASE_URL="https://gitea.bcde.io/wangdefa/tools/raw/branch/main"
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
|
||||
# 智能加载
|
||||
if [[ "${FORCE_REMOTE:-0}" == "1" ]] || [[ ! -f "${PROJECT_ROOT}/common/logging.sh" ]]; then
|
||||
if command -v curl &>/dev/null; then
|
||||
source <(curl -fsSL "${REMOTE_BASE_URL}/common/remote_loader.sh")
|
||||
elif command -v wget &>/dev/null; then
|
||||
source <(wget -qO- "${REMOTE_BASE_URL}/common/remote_loader.sh")
|
||||
else
|
||||
echo "[ERROR] 无法加载库" >&2
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
source "${PROJECT_ROOT}/common/logging.sh"
|
||||
source "${PROJECT_ROOT}/common/error_handler.sh"
|
||||
fi
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `REMOTE_LIB_URL` | 远程仓库 URL | `https://gitea.bcde.io/wangdefa/tools/raw/branch/main` |
|
||||
| `FORCE_REMOTE` | 强制使用远程库 | `0` |
|
||||
|
||||
示例：
|
||||
```bash
|
||||
# 使用自定义仓库 URL
|
||||
REMOTE_LIB_URL=https://example.com/repo ./script.sh
|
||||
|
||||
# 强制远程模式
|
||||
FORCE_REMOTE=1 ./script.sh
|
||||
```
|
||||
|
||||
## 优缺点对比
|
||||
|
||||
### 纯远程模式
|
||||
|
||||
**优点：**
|
||||
- ✅ 脚本完全独立，可单文件分发
|
||||
- ✅ 始终使用最新版本的公共库
|
||||
- ✅ 无需本地依赖
|
||||
|
||||
**缺点：**
|
||||
- ❌ 需要网络连接
|
||||
- ❌ 每次运行都需要下载（约 1-2 秒延迟）
|
||||
- ❌ 依赖 curl 或 wget
|
||||
|
||||
### 混合模式
|
||||
|
||||
**优点：**
|
||||
- ✅ 本地运行快速（无网络延迟）
|
||||
- ✅ 离线时仍可工作（如果有本地库）
|
||||
- ✅ 远程作为备用方案
|
||||
|
||||
**缺点：**
|
||||
- ❌ 代码稍复杂
|
||||
- ❌ 可能使用旧版本的本地库
|
||||
|
||||
### 本地模式（原方式）
|
||||
|
||||
**优点：**
|
||||
- ✅ 最快速（无下载）
|
||||
- ✅ 完全离线
|
||||
- ✅ 代码最简单
|
||||
|
||||
**缺点：**
|
||||
- ❌ 必须有完整的项目结构
|
||||
- ❌ 无法独立分发脚本
|
||||
- ❌ 需要手动更新库
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **仓库内脚本**：使用混合模式
|
||||
2. **独立分发脚本**：使用纯远程模式
|
||||
3. **测试环境**：使用 `FORCE_REMOTE=1` 测试远程加载
|
||||
4. **生产环境**：建议使用本地库（性能更好）
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 错误：无法下载远程库
|
||||
|
||||
**可能原因：**
|
||||
1. 网络连接问题
|
||||
2. Gitea 服务器不可达
|
||||
3. URL 错误
|
||||
|
||||
**解决方案：**
|
||||
```bash
|
||||
# 测试连接
|
||||
curl -I https://gitea.bcde.io/wangdefa/tools/raw/branch/main/common/remote_loader.sh
|
||||
|
||||
# 使用自定义 URL
|
||||
REMOTE_LIB_URL=https://your-mirror.com/tools ./script.sh
|
||||
```
|
||||
|
||||
### 错误：curl/wget 未找到
|
||||
|
||||
**解决方案：**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install curl
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install curl
|
||||
|
||||
# macOS
|
||||
brew install curl
|
||||
```
|
||||
|
||||
## 安全考虑
|
||||
|
||||
1. **HTTPS**：始终使用 HTTPS URL
|
||||
2. **验证**：建议验证下载文件的哈希值
|
||||
3. **审计**：定期审查远程库的变更
|
||||
4. **备份**：保留本地备份以防远程不可用
|
||||
|
||||
## 更多信息
|
||||
|
||||
- 公共库文档：[common/README.md](../common/README.md)
|
||||
- 编码规范：[llmdoc/reference/coding-conventions.md](../llmdoc/reference/coding-conventions.md)
|
||||
Reference in New Issue
Block a user