gavindiaz/PolyHermes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现系统动态更新功能和 Release 创建脚本

Browse Source 
主要变更：

1. 动态更新功能
   - 新增 Python 更新服务 (docker/update-service.py)
   - 添加系统更新前端页面 (frontend/src/pages/SystemUpdate.tsx)
   - 配置 Nginx 代理更新服务 API
   - 更新 Docker 启动脚本支持多进程管理
   - 修复权限验证接口 (AuthController.verify)

2. Release 创建脚本
   - 新增 create-release.sh 脚本支持快速创建 GitHub Release
   - 支持自动拼接 -beta 后缀（pre-release）
   - 支持无交互模式（--yes 参数）
   - 添加详细的使用文档

3. GitHub Actions 增强
   - 添加更新包构建和上传流程
   - 支持 Pre-release 检测和过滤

4. 文档完善
   - 添加动态更新技术方案文档
   - 添加 Docker 版本号确定流程文档
   - 添加 Release 脚本使用说明
This commit is contained in:
WrBug
2026-01-21 03:34:16 +08:00
parent 662aa47de6
commit 26dd3bb387
25 changed files with 4957 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/CHANGELOG_TEMPLATE.md
+60
View File
@@ -0,0 +1,60 @@
# Release Notes Template
## 使用方法
将 AI 生成的更新内容替换下面的模板内容，然后保存为文件（如 `release-notes-v1.0.1.md`），使用 `-f` 参数创建 Release：
```bash
./create-release.sh -t v1.0.1 -f release-notes-v1.0.1.md
```
---
## 新功能 (Features)
- 功能描述 1
- 功能描述 2
## 修复 (Bug Fixes)
- 修复了问题 1
- 修复了问题 2
## 改进 (Improvements)
- 性能优化 1
- UI 改进 2
## 变更 (Changes)
- 变更说明 1
- 变更说明 2
---
## 示例
### Release v1.0.1
## 新功能
- 添加了系统动态更新功能，支持在线更新无需重启容器
- 添加了 Pre-release 支持，支持创建测试版本
## 修复
- 修复了订单状态同步延迟问题
- 修复了账户余额显示错误
- 修复了跟单统计计算不准确的问题
## 改进
- 优化了 API 响应速度，提升约 30%
- 优化了数据库查询性能
- 改进了前端加载速度
## 变更
- 更新了依赖包版本
- 改进了错误提示信息
scripts/README_RELEASE.md
+361
View File
@@ -0,0 +1,361 @@
# Release 创建脚本使用说明
## 简介
`create-release.sh` 脚本用于快速创建 GitHub Release，包括：
- 创建本地和远程 tag
- 创建 GitHub Release 页面
- 支持 Pre-release 标记
- 自动触发 GitHub Actions 构建流程
## 前置要求
### 1. 安装 GitHub CLI
脚本依赖 GitHub CLI (`gh`) 来创建 Release。
**macOS**:
```bash
brew install gh
```
**Linux**:
```bash
# Ubuntu/Debian
sudo apt install gh
# 或从官网下载安装
# https://cli.github.com/
```
**验证安装**:
```bash
gh --version
```
### 2. 登录 GitHub
首次使用需要登录 GitHub：
```bash
gh auth login
```
按照提示完成认证。
**验证登录状态**:
```bash
gh auth status
```
### 3. 确保 Git 仓库配置正确
```bash
# 检查远程仓库
git remote -v
# 确保在正确的分支
git checkout main # 或 master
```
## 使用方法
### 基本用法
```bash
# 在项目根目录下运行脚本
# 创建正式版本
./create-release.sh -t v1.0.1 -T "Release v1.0.1" -d "## 新功能\n- 功能1\n- 功能2"
# 创建 Pre-release（自动拼接 -beta）
./create-release.sh -t v1.0.1 -T "Release v1.0.1-beta" -d "测试版本" --prerelease
```
### 参数说明
| 参数 | 简写 | 说明 | 必需 | 默认值 |
|------|------|------|------|--------|
| `--tag TAG` | `-t` | 版本号 tag（格式：v1.0.0） | ✅ 是 | - |
| `--title TITLE` | `-T` | Release 标题 | ❌ 否 | 使用 tag 值 |
| `--description DESC` | `-d` | Release 描述内容 | ❌ 否 | "Release {tag}" |
| `--description-file FILE` | `-f` | 从文件读取 Release 描述 | ❌ 否 | - |
| `--prerelease` | `-p` | 标记为 Pre-release | ❌ 否 | false |
| `--help` | `-h` | 显示帮助信息 | ❌ 否 | - |
### 版本号格式
**正式版本**:
- ✅ `v1.0.0`
- ✅ `v2.10.102`
- ✅ `v1.0.1`
**Pre-release**:
- ✅ `v1.0.1-beta`
- ✅ `v1.0.1-rc.1`
- ✅ `v1.0.1-alpha`
**错误格式**:
- ❌ `v1.0`（缺少补丁号）
- ❌ `1.0.0`（缺少 v 前缀）
- ❌ `v1.0.0.1`（版本号过多）
## 使用场景示例
### 场景 1: 创建正式版本 Release
```bash
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1" \
-d "## 新功能
- 添加了系统更新功能
- 优化了跟单性能
## 修复
- 修复了订单状态同步问题
- 修复了账户余额显示错误"
```
### 场景 2: 创建 Pre-release（测试版本）
```bash
# 使用 --prerelease 参数，会自动拼接 -beta 后缀
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1-beta (测试版)" \
-d "这是 v1.0.1 的测试版本，请勿用于生产环境" \
--prerelease
# 实际创建的 tag: v1.0.1-beta（自动拼接）
```
### 场景 3: 从文件读取 Release 描述
如果你的 Release 描述内容很长，可以保存在文件中：
```bash
# 创建描述文件
cat > release-notes.txt << 'EOF'
## 新功能
- 添加了系统更新功能
- 优化了跟单性能
## 修复
- 修复了订单状态同步问题
- 修复了账户余额显示错误
## 改进
- 提升了 API 响应速度
- 优化了数据库查询性能
EOF
# 使用文件创建 Release
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1" \
-f release-notes.txt
```
### 场景 4: 结合 AI 生成 Release 内容
你可以让 AI 对比代码差异生成 Release 描述，然后使用脚本发布：
```bash
# 1. AI 生成 Release 内容到文件
# 例如：对比 v1.0.0 和最新代码，生成 v1.0.1 的更新内容
# 保存到 CHANGELOG.md
# 2. 使用脚本创建 Release
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1" \
-f CHANGELOG.md
```
## 工作流程
脚本执行时会按以下步骤进行：
1. **验证参数**
- 检查版本号格式
- 检查必需参数
2. **检查环境**
- 检查 git 命令
- 检查 GitHub CLI
- 检查 GitHub 登录状态
- 检查未提交的更改
3. **检查 Tag**
- 检查本地是否已存在 tag
- 检查远程是否已存在 tag
- 如果存在，询问是否删除重建
4. **确认操作**
- 显示即将执行的操作信息
- 等待用户确认
5. **创建 Tag**
- 基于当前 HEAD 创建 tag
- 推送 tag 到远程
6. **创建 Release**
- 使用 GitHub CLI 创建 Release
- 设置标题和描述
- 标记是否为 Pre-release
7. **触发构建**
- GitHub Actions 自动检测到新 Release
- 开始构建 Docker 镜像和更新包
## 注意事项
### 1. Tag 和 Release 的关系
- 脚本会**先创建 tag**，然后**创建 Release**
- GitHub Release **必须关联一个 tag**
- 如果 tag 已存在，会询问是否删除重建
### 2. Pre-release 的影响
- Pre-release **不会**触发 Telegram 通知
- Pre-release **不会**推送到 `latest` Docker 标签
- Pre-release **不会**被更新服务检测（除非设置 `ALLOW_PRERELEASE=true`）
### 3. GitHub Actions 触发
- GitHub Actions 监听 `release: published` 事件
- 只有通过脚本或 GitHub 页面创建 Release 才会触发
- 直接 `git push` tag **不会**触发构建
### 4. 发布前检查清单
在创建 Release 前，建议检查：
- ✅ 代码已提交并推送
- ✅ 所有测试通过
- ✅ 版本号遵循语义化版本规范
- ✅ Release 描述内容准确完整
- ✅ 确认是否为 Pre-release
## 故障排除
### 问题 1: GitHub CLI 未安装
**错误信息**:
```
未找到 GitHub CLI (gh) 命令
```
**解决方案**:
```bash
# macOS
brew install gh
# 然后登录
gh auth login
```
### 问题 2: GitHub 未登录
**错误信息**:
```
未登录 GitHub，请先运行: gh auth login
```
**解决方案**:
```bash
gh auth login
```
### 问题 3: Tag 已存在
**错误信息**:
```
Tag v1.0.1 已存在（本地）
```
**解决方案**:
- 脚本会询问是否删除重建
- 回答 `y` 继续，或回答 `n` 取消
### 问题 4: 版本号格式错误
**错误信息**:
```
版本号格式不正确：v1.0
```
**解决方案**:
- 确保版本号格式为 `v数字.数字.数字` 或 `v数字.数字.数字-后缀`
- 例如：`v1.0.0`, `v1.0.1-beta`
### 问题 5: 未提交的更改
**错误信息**:
```
检测到未提交的更改，建议先提交或暂存
```
**解决方案**:
```bash
# 提交更改
git add .
git commit -m "准备发布 v1.0.1"
# 或暂存更改
git stash
```
## 完整示例
假设当前线上版本是 `v1.0.0`，要发布 `v1.0.1`：
```bash
# 1. 确保代码已提交
git add .
git commit -m "准备发布 v1.0.1"
git push
# 2. 使用脚本创建 Release（正式版本）
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1" \
-d "## 新功能
- 添加了动态更新功能
- 优化了跟单统计性能
## 修复
- 修复了订单状态同步延迟问题
- 修复了账户余额显示错误
## 改进
- 提升了 API 响应速度 30%
- 优化了数据库查询性能"
# 3. 等待 GitHub Actions 构建完成
# 可以在 GitHub Actions 页面查看构建进度
```
**创建 Pre-release**:
```bash
# 使用 --prerelease 参数，会自动拼接 -beta 后缀
./create-release.sh \
-t v1.0.1 \
-T "Release v1.0.1-beta (测试版)" \
-d "这是 v1.0.1 的测试版本，包含以下更新：
- 添加了动态更新功能
- 修复了订单状态同步问题
请勿用于生产环境。" \
--prerelease
# 实际创建的 tag: v1.0.1-beta
```
## 相关文档
- [版本号管理说明](../docs/zh/VERSION_MANAGEMENT.md)
- [动态更新技术方案](../docs/zh/DYNAMIC_UPDATE.md)
- [GitHub Actions 配置](../.github/workflows/docker-build.yml)
scripts/create-release.sh
+311
View File
@@ -0,0 +1,311 @@
#!/bin/bash
# PolyHermes Release 创建脚本
# 功能：创建 tag、推送 tag、创建 GitHub Release（支持 pre-release）
set -e
# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# 打印信息
info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 显示使用说明
usage() {
cat << EOF
用法: $0 [选项]
选项:
-t, --tag TAG 版本号 tag（必需，格式：v1.0.0）
-T, --title TITLE Release 标题（可选，默认使用 tag）
-d, --description DESC Release 描述内容（可选）
-f, --description-file FILE 从文件读取 Release 描述（可选）
-p, --prerelease 标记为 Pre-release（会自动拼接 -beta 后缀，默认：false）
-h, --help 显示此帮助信息
示例:
# 创建正式版本
$0 -t v1.0.1 -T "Release v1.0.1" -d "## 新功能\n- 功能1\n- 功能2"
# 创建 Pre-release（自动拼接 -beta）
$0 -t v1.0.1 -T "Release v1.0.1-beta" -d "测试版本" --prerelease
# 实际创建的 tag: v1.0.1-beta
# 从文件读取描述
$0 -t v1.0.1 -f CHANGELOG.md --prerelease
# 实际创建的 tag: v1.0.1-beta
版本号格式:
- 必须格式: v数字.数字.数字 (例如: v1.0.0, v1.10.2, v1.1.12)
- 如果指定 --prerelease，会自动拼接 -beta 后缀 (例如: v1.0.1 -> v1.0.1-beta)
EOF
}
# 验证版本号格式（只允许 v数字.数字.数字，不允许后缀）
validate_tag() {
local tag=$1
# 匹配格式：v数字.数字.数字（不允许后缀）
if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
error "版本号格式不正确：$tag"
error "应为 v数字.数字.数字 (例如: v1.0.0, v1.10.2, v1.1.12)"
error "如果创建 Pre-release，请使用 --prerelease 参数，脚本会自动拼接 -beta 后缀"
exit 1
fi
return 0
}
# 检查必要的工具
check_requirements() {
# 检查 git
if ! command -v git &> /dev/null; then
error "未找到 git 命令，请先安装 git"
exit 1
fi
# 检查 GitHub CLI
if ! command -v gh &> /dev/null; then
error "未找到 GitHub CLI (gh) 命令"
error "请先安装 GitHub CLI: https://cli.github.com/"
exit 1
fi
# 检查是否已登录 GitHub
if ! gh auth status &> /dev/null; then
error "未登录 GitHub，请先运行: gh auth login"
exit 1
fi
# 检查是否有未提交的更改
if [[ -n $(git status --porcelain) ]]; then
warn "检测到未提交的更改，建议先提交或暂存"
read -p "是否继续？(y/N): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
info "已取消"
exit 0
fi
fi
# 检查是否在正确的分支
local current_branch=$(git branch --show-current)
info "当前分支: $current_branch"
}
# 检查 tag 是否已存在
check_tag_exists() {
local tag=$1
if git rev-parse "$tag" >/dev/null 2>&1; then
error "Tag $tag 已存在（本地）"
read -p "是否删除并重新创建？(y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
git tag -d "$tag" || true
git push origin ":refs/tags/$tag" || true
info "已删除旧 tag: $tag"
else
error "已取消"
exit 1
fi
fi
# 检查远程是否存在
if git ls-remote --tags origin "$tag" | grep -q "$tag"; then
error "Tag $tag 已存在于远程仓库"
read -p "是否删除并重新创建？(y/N): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
git tag -d "$tag" || true
git push origin ":refs/tags/$tag" || true
info "已删除远程 tag: $tag"
else
error "已取消"
exit 1
fi
fi
}
# 主函数
main() {
local TAG=""
local TITLE=""
local DESCRIPTION=""
local DESCRIPTION_FILE=""
local PRERELEASE=false
# 解析参数
while [[ $# -gt 0 ]]; do
case $1 in
-t|--tag)
TAG="$2"
shift 2
;;
-T|--title)
TITLE="$2"
shift 2
;;
-d|--description)
DESCRIPTION="$2"
shift 2
;;
-f|--description-file)
DESCRIPTION_FILE="$2"
shift 2
;;
-p|--prerelease)
PRERELEASE=true
shift
;;
-h|--help)
usage
exit 0
;;
*)
error "未知参数: $1"
usage
exit 1
;;
esac
done
# 检查必需参数
if [[ -z "$TAG" ]]; then
error "缺少必需参数: --tag"
usage
exit 1
fi
# 验证版本号格式（不允许后缀）
validate_tag "$TAG"
# 如果指定了 --prerelease，自动拼接 -beta 后缀
local BASE_TAG="$TAG"
if [[ "$PRERELEASE" == "true" ]]; then
TAG="${BASE_TAG}-beta"
info "Pre-release 模式：tag 将自动拼接 -beta 后缀"
info "基础版本: $BASE_TAG -> 实际 tag: $TAG"
fi
# 检查工具和环境
check_requirements
# 检查 tag 是否已存在（使用拼接后的 tag）
check_tag_exists "$TAG"
# 设置默认标题
if [[ -z "$TITLE" ]]; then
TITLE="$TAG"
fi
# 读取描述内容
if [[ -n "$DESCRIPTION_FILE" ]]; then
if [[ ! -f "$DESCRIPTION_FILE" ]]; then
error "描述文件不存在: $DESCRIPTION_FILE"
exit 1
fi
DESCRIPTION=$(cat "$DESCRIPTION_FILE")
fi
# 如果没有描述，使用默认值
if [[ -z "$DESCRIPTION" ]]; then
if [[ "$PRERELEASE" == "true" ]]; then
DESCRIPTION="Pre-release $TAG"
else
DESCRIPTION="Release $TAG"
fi
fi
# 显示即将执行的操作
echo
info "========================================="
info " PolyHermes Release 创建"
info "========================================="
info "Tag: $TAG"
info "Title: $TITLE"
info "Pre-release: $PRERELEASE"
info "Description:"
echo "$DESCRIPTION" | sed 's/^/ /'
info "========================================="
echo
# 确认操作
read -p "确认创建 Release？(y/N): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
info "已取消"
exit 0
fi
# 1. 创建 tag（基于当前 HEAD）
info "创建 tag: $TAG"
git tag "$TAG"
success "Tag 创建成功: $TAG"
# 2. 推送 tag 到远程
info "推送 tag 到远程..."
git push origin "$TAG"
success "Tag 推送成功"
# 3. 创建 GitHub Release
info "创建 GitHub Release..."
local RELEASE_ARGS=(
"$TAG"
--title "$TITLE"
--notes "$DESCRIPTION"
)
if [[ "$PRERELEASE" == "true" ]]; then
RELEASE_ARGS+=(--prerelease)
fi
if gh release create "${RELEASE_ARGS[@]}"; then
success "GitHub Release 创建成功！"
# 获取 release URL
local RELEASE_URL=$(gh release view "$TAG" --json url -q .url)
info "Release URL: $RELEASE_URL"
echo
success "========================================="
success " Release 创建完成！"
success "========================================="
success "Tag: $TAG"
success "Pre-release: $PRERELEASE"
success "URL: $RELEASE_URL"
success "========================================="
echo
info "GitHub Actions 将自动触发构建流程"
if [[ "$PRERELEASE" == "true" ]]; then
warn "这是 Pre-release，GitHub Actions 不会发送 Telegram 通知"
fi
else
error "GitHub Release 创建失败"
error "请手动在 GitHub 上创建 Release: https://github.com/WrBug/PolyHermes/releases/new"
exit 1
fi
}
# 执行主函数
main "$@"