tools/examples/REMOTE_LOADER_README.md

远程库加载器使用指南

概述

远程库加载器允许脚本从 Gitea 仓库动态下载并加载公共库，使得脚本可以独立运行而不依赖本地的 common/ 目录。

仓库 URL

https://gitea.bcde.io/wangdefa/tools/raw/branch/main

使用方式

方式 1: 纯远程模式（推荐用于独立脚本）

适用于需要独立分发的脚本，每次运行都下载最新版本的公共库。

#!/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: 混合模式（推荐用于仓库内脚本）

优先使用本地库，本地不存在时自动使用远程库。

#!/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: 环境变量控制

通过环境变量灵活切换本地/远程模式。

#!/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

使用方法：

# 使用本地库
./script.sh

# 强制使用远程库
FORCE_REMOTE=1 ./script.sh

完整示例

示例 1: 纯远程脚本

参见 remote_example.sh

运行：

chmod +x examples/remote_example.sh
./examples/remote_example.sh

示例 2: 混合模式脚本

参见 hybrid_loader_template.sh

运行：

chmod +x examples/hybrid_loader_template.sh

# 使用本地库（如果存在）
./examples/hybrid_loader_template.sh

# 强制使用远程库
FORCE_REMOTE=1 ./examples/hybrid_loader_template.sh

更新现有脚本

步骤 1: 备份原脚本

cp linux/create_raid0_array.sh linux/create_raid0_array.sh.bak

步骤 2: 替换加载部分

原代码：

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"

新代码（纯远程）：

# 远程加载
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

新代码（混合模式）：

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

示例：

# 使用自定义仓库 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 错误

解决方案：

# 测试连接
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 未找到

解决方案：

# 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
• 编码规范：llmdoc/reference/coding-conventions.md