ChaosBlade 版本同步指南

概述

ChaosBlade 现已支持自动将 Makefile 中的分支配置同步到 go.mod 文件中的依赖版本。这确保了构建过程中使用的依赖版本与 Makefile 中配置的分支保持一致。

功能特性

• 自动版本同步：根据 Makefile 中的分支配置自动更新 go.mod 中的依赖版本
• 智能版本生成：
  • 对于 master/main 分支，使用基础版本号（如 v1.7.4）
  • 对于其他分支，生成带时间戳的版本号（如 v1.7.4-0.20241208094701-dev-1-7-5）
• 跨平台兼容：支持 macOS 和 Linux 系统
• 安全备份：自动备份原始 go.mod 文件
• 语法校验：更新后自动验证 go.mod 语法

使用方法

1. 手动版本同步

# 同步版本并清理备份文件
make sync_go_mod

# 或直接运行脚本
./scripts/sync_go_mod.sh

# 保留备份文件
./scripts/sync_go_mod.sh --keep-backup

2. 自动同步（推荐）

版本同步已集成到构建流程中，执行以下命令时会自动同步：

# 构建当前平台
make build
make build_all

# 构建指定平台
make linux_amd64
make darwin_amd64
# ... 其他平台

3. 查看帮助信息

# 查看 Makefile 帮助
make help

# 查看脚本帮助
./scripts/sync_go_mod.sh --help

配置说明

Makefile 中的分支配置

以下变量控制各项目的分支：

# chaosblade-exec-os
BLADE_EXEC_OS_BRANCH=master

# chaosblade-exec-middleware
BLADE_EXEC_MIDDLEWARE_BRANCH=main

# chaosblade-exec-cloud
BLADE_EXEC_CLOUD_BRANCH=main

# chaosblade-exec-cri
BLADE_EXEC_CRI_BRANCH=main

# chaosblade-exec-kubernetes
BLADE_OPERATOR_BRANCH=master

# chaosblade-exec-jvm
BLADE_EXEC_JVM_BRANCH=master

# chaosblade-exec-cplus
BLADE_EXEC_CPLUS_BRANCH=master

# chaosblade-spec-go
BLADE_SPEC_GO_BRANCH=master

版本号生成规则

1. 基础版本号：从 BLADE_VERSION 变量获取（默认自动从 Git Tag 提取）
2. 分支版本号：所有分支直接使用分支名
   • master 分支：使用 master
   • main 分支：使用 main
   • 其他分支：直接使用分支名（如 dev-1.7.5）

示例

假设当前配置：

• BLADE_VERSION=1.7.4
• BLADE_EXEC_OS_BRANCH=dev-1.7.5
• BLADE_EXEC_CLOUD_BRANCH=main

生成的版本号：

• chaosblade-exec-os: dev-1.7.5（Go 会将其解析为特定 commit，如 v1.7.5-0.20241208094701-b2d815847b22）
• chaosblade-exec-cloud: main（Go 会将其解析为特定 commit，如 v1.7.5-0.20250902042623-6caabb19d8c5）

工作流程

1. 提取配置：从 Makefile 中提取分支配置和版本信息
2. 生成版本：根据分支类型生成对应的版本号
3. 备份文件：自动备份原始 go.mod 文件
4. 更新依赖：使用 sed 命令更新 go.mod 中的依赖版本
5. 验证语法：运行 go mod tidy 验证语法正确性
6. 清理备份：验证成功后清理备份文件

故障排查

常见问题

1. 权限错误：确保脚本有执行权限

   chmod +x scripts/sync_go_mod.sh
   

2. sed 命令错误：脚本已自动处理 macOS 和 Linux 之间的差异

3. go.mod 语法错误：脚本会自动恢复备份文件

恢复原始文件

如果更新后出现问题，可以手动恢复：

# 如果备份文件存在
mv go.mod.backup go.mod

# 或重新同步
make sync_go_mod

注意事项

1. 版本一致性：确保 Makefile 中的分支配置与实际使用的分支一致
2. 依赖可用性：生成的版本号对应的依赖必须存在于相应的仓库中
3. 构建顺序：版本同步在 pre_build 阶段执行，确保在构建前完成
4. 备份管理：建议在重要操作前手动备份 go.mod 文件

技术实现

• 脚本语言：Bash
• 依赖工具：git, go, sed
• 兼容性：macOS, Linux
• 集成方式：Makefile target 依赖

相关文件

• scripts/sync_go_mod.sh：版本同步脚本
• Makefile：构建配置和分支定义
• go.mod：Go 模块依赖文件
• docs/version_sync_guide.md：本文档