tools/examples/REMOTE_LOADER_README.md

# 远程库加载器使用指南

## 概述

远程库加载器允许脚本从 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)