Wang Defa
1be07db276
## 问题描述
当脚本使用远程加载时，出现警告：
```
/tmp/tmp.xxx: line 10: REMOTE_BASE_URL: readonly variable
```
## 根本原因
`REMOTE_BASE_URL` 被重复定义为 readonly 变量：
1. 调用脚本中定义（如 oci/create_instance.sh:16）：
```bash
readonly REMOTE_BASE_URL="..."
```
2. remote_loader.sh:10 中再次定义：
```bash
readonly REMOTE_BASE_URL="..."
```
Bash 不允许重新赋值 readonly 变量，即使值相同也会产生警告。
## 修复方案
在 remote_loader.sh 中添加检查，只有在变量未定义时才设置：
```bash
# 旧代码
readonly REMOTE_BASE_URL="..."
# 新代码
if [[ -z "${REMOTE_BASE_URL:-}" ]]; then
readonly REMOTE_BASE_URL="..."
fi
```
## 影响
- ✅ 消除警告信息
- ✅ 保持向后兼容
- ✅ 允许调用者自定义 REMOTE_BASE_URL
- ✅ 如果未定义则使用默认值
公共函数库
本目录包含可复用的 Bash 函数库，用于标准化所有脚本的日志输出和错误处理。
📦 包含的库
1. logging.sh - 日志输出库
提供统一的日志输出函数，支持多个日志级别和彩色输出。
功能特性:
- 5个日志级别：DEBUG, INFO, WARNING, ERROR, SUCCESS
- 彩色控制台输出
- 可选的时间戳
- 支持输出到文件
- 灵活的日志级别控制
使用示例:
#!/bin/bash
source common/logging.sh
# 基本使用
log_info "程序启动"
log_success "操作完成"
log_warning "磁盘空间不足"
log_error "连接失败"
log_debug "调试信息"
# 设置日志级别
log_set_level "DEBUG" # 显示所有日志
# 输出到文件
log_set_file "/var/log/myapp.log"
# 禁用时间戳
log_disable_timestamp
2. error_handler.sh - 错误处理库
提供统一的错误处理和检查机制。
功能特性:
- 命令存在性检查
- 文件/目录检查
- 变量非空检查
- Root 权限检查
- 命令返回值检查
- 带重试的命令执行
- 调用栈跟踪
使用示例:
#!/bin/bash
source common/error_handler.sh
# 启用严格错误处理
enable_exit_on_error
# 检查命令是否存在
check_command "git" || error_exit "git 未安装"
# 检查文件
check_file "/etc/config" || error_exit "配置文件不存在"
# 检查 root 权限
check_root || error_exit "需要 root 权限"
# 执行命令并检查结果
run_command "安装失败" apt-get install -y package
# 带重试的命令执行
retry_command 3 5 "下载失败" curl -O https://example.com/file
# 检查变量非空
check_not_empty "$PROJECT_ID" "PROJECT_ID" || error_exit "项目ID不能为空"
🚀 完整示例脚本
#!/bin/bash
# ============================================================================
# 示例脚本：展示如何使用公共函数库
# ============================================================================
# 获取脚本目录
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# 加载公共库
source "${SCRIPT_DIR}/../common/logging.sh"
source "${SCRIPT_DIR}/../common/error_handler.sh"
# 配置日志
log_set_level "INFO"
log_set_file "/tmp/example.log"
# 启用错误处理
enable_exit_on_error
#
# 主函数
#
main() {
log_info "脚本开始执行"
# 检查必要的命令
check_command "git" || error_exit "请先安装 git"
# 检查参数
local project_name="$1"
check_not_empty "$project_name" "project_name" || {
log_error "用法: $0 <project_name>"
exit 1
}
# 执行操作
log_info "正在处理项目: $project_name"
# 带重试的网络操作
retry_command 3 2 "网络请求失败" curl -f "https://example.com/api"
log_success "脚本执行完成"
}
# 执行主函数
main "$@"
📖 最佳实践
1. 脚本模板
每个脚本都应遵循以下模板结构：
#!/bin/bash
set -euo pipefail # 启用严格模式
# 脚本信息
# ============================================================================
# 文件名: script_name.sh
# 描述: 脚本功能描述
# 作者: 作者名
# 版本: 1.0.0
# ============================================================================
# 常量定义
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "$0")"
# 加载公共库
source "${SCRIPT_DIR}/../common/logging.sh"
source "${SCRIPT_DIR}/../common/error_handler.sh"
# 全局变量
GLOBAL_VAR=""
#
# 显示使用帮助
#
show_usage() {
cat << EOF
使用方法: $SCRIPT_NAME [选项]
选项:
-h, --help 显示此帮助信息
-v, --verbose 启用详细输出
示例:
$SCRIPT_NAME --verbose
EOF
}
#
# 主函数
#
main() {
log_info "脚本开始执行"
# 你的代码逻辑
log_success "脚本执行完成"
}
# 执行主函数
main "$@"
2. 错误处理建议
- 总是检查命令返回值
- 使用
check_*函数进行前置条件检查 - 对网络操作使用
retry_command - 提供有意义的错误消息
3. 日志使用建议
- INFO: 正常流程信息
- SUCCESS: 操作成功完成
- WARNING: 需要注意但不影响执行的情况
- ERROR: 错误但可以继续的情况
- DEBUG: 调试信息（默认不显示）
🔧 环境变量配置
logging.sh 环境变量
# 设置日志级别 (DEBUG=0, INFO=1, WARNING=2, ERROR=3, SUCCESS=4)
export LOG_CURRENT_LEVEL=1
# 设置日志文件路径
export LOG_FILE_PATH="/var/log/myapp.log"
# 启用/禁用时间戳
export LOG_ENABLE_TIMESTAMP=true
error_handler.sh 环境变量
# 错误时是否退出 (true/false)
export ERROR_EXIT_ON_FAIL=true
# 是否显示调用栈 (true/false)
export ERROR_STACK_TRACE=false
📝 维护说明
- 版本: 1.0.0
- 最后更新: 2025-12-26
- 维护者: Cloud Tools Project
🤝 贡献
如需添加新功能或修复 bug，请：
- 保持向后兼容性
- 添加完整的函数文档注释
- 提供使用示例
- 更新此 README