自动版本发布指南
📋 概述
本项目配置了自动版本发布功能，每次推送到 main 分支时会自动递增版本号并创建 GitHub Release。
🚀 工作原理
自动版本递增规则
- 版本格式:
v<major>.<minor>.<patch>（例如: v1.0.2） - 递增规则: 每次推送到 main 分支，自动递增 patch 版本号
- v1.0.1 → v1.0.2
- v1.0.9 → v1.0.10
- v1.0.99 → v1.0.100
触发条件
当满足以下条件时，会自动创建新版本：
- 推送到
main分支 - 有实际的代码变更（不包括纯文档更新）
- 自上次发布以来有新的提交
📝 使用方法
1. 常规开发流程
# 在 dev 分支开发
git checkout dev
# ... 进行开发 ...
git add .
git commit -m "feat: 添加新功能"
git push origin dev
# 合并到 main 分支
git checkout main
git merge dev
git push origin main # 这会触发自动发布
2. 跳过自动发布
如果你的提交不想触发自动发布，在 commit 消息中添加 [skip ci]：
git commit -m "docs: 更新文档 [skip ci]"
3. 手动控制版本号
如果需要发布大版本或中版本更新：
# 大版本更新 (1.0.x → 2.0.0)
git tag -a v2.0.0 -m "Major release v2.0.0"
git push origin v2.0.0
# 中版本更新 (1.0.x → 1.1.0)
git tag -a v1.1.0 -m "Minor release v1.1.0"
git push origin v1.1.0
🔧 配置说明
工作流文件
- 位置:
.github/workflows/auto-release.yml - 功能:
- 获取最新版本标签
- 计算下一个版本号
- 生成 changelog
- 创建 GitHub Release
- 更新 CHANGELOG.md 文件
- 发送 Telegram 通知（可选）
Changelog 生成
使用 git-cliff 自动生成更新日志：
- 配置文件:
.github/cliff.toml - 提交规范: 遵循 Conventional Commits
feat:新功能fix:Bug 修复docs:文档更新chore:其他变更refactor:代码重构perf:性能优化
📊 查看发布历史
GitHub Releases 页面:
- 访问
https://github.com/<owner>/<repo>/releases - 查看所有发布版本和更新内容
- 访问
CHANGELOG.md:
- 项目根目录的
CHANGELOG.md文件 - 包含完整的版本历史
- 项目根目录的
❓ 常见问题
Q: 如何查看当前版本？
# 查看最新标签
git describe --tags --abbrev=0
# 查看所有标签
git tag -l
Q: 自动发布失败怎么办？
- 检查 GitHub Actions 日志
- 确认是否有权限创建标签和发布
- 检查是否有语法错误
Q: 如何回滚版本？
自动发布只是创建标签和 Release，不会影响代码：
# 回滚到特定版本
git checkout v1.0.1
# 或者使用 Docker 镜像的特定版本
docker pull weishaw/claude-relay-service:v1.0.1
Q: 如何修改版本递增规则？
编辑 .github/workflows/auto-release.yml 中的版本计算逻辑：
# 当前是递增 patch 版本
NEW_PATCH=$((PATCH + 1))
# 可以改为递增 minor 版本
NEW_MINOR=$((MINOR + 1))
NEW_PATCH=0
📱 Telegram 通知（可选）
自动发布系统支持发送通知到 Telegram 频道。配置后，每次发布新版本都会自动发送通知。
快速设置
- 创建 Telegram Bot（通过 @BotFather）
- 将 Bot 添加到频道作为管理员
- 获取频道的 Chat ID
- 在 GitHub 仓库添加 Secrets：
TELEGRAM_BOT_TOKENTELEGRAM_CHAT_ID
详细设置步骤请参考 Telegram 通知设置指南