gavindiaz/PolyHermes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7d752073fbad0c3e32f99a8233d55fba538f4edf
PolyHermes/docs/VERSION_MANAGEMENT.md
T
WrBug b069e54b89 feat: 添加版本号显示和自动构建/删除 Docker 镜像功能 
- 添加前端版本号显示（桌面端和移动端）
- 实现 GitHub Actions 自动构建和推送 Docker 镜像
- 实现删除 release 时自动删除对应 Docker 镜像
- 支持版本号格式：v数字.数字.数字 或 v数字.数字.数字-后缀
- 添加版本号管理文档
- 更新 Dockerfile 和部署脚本支持版本号构建参数
2025-12-07 16:46:18 +08:00

7.7 KiB
Raw Blame History

版本号管理说明

概述

本项目支持自动版本号管理和显示。当在 GitHub 创建 release tag 时，会自动触发 GitHub Actions 构建 Docker 镜像并推送到 Docker Hub，同时在前端标题后显示版本号。

功能特性

  1. 自动构建：创建 release tag 时自动触发 GitHub Actions
  2. 版本号显示：前端标题后显示版本号（小字号）
  3. 点击跳转：点击版本号跳转到对应的 GitHub tag 页面
  4. Docker 推送：自动构建并推送到 Docker Hub
  5. 自动删除：删除 release 时自动删除对应的 Docker 镜像标签
  6. 版本号验证：精准匹配版本号格式 v数字.数字.数字（例如：v1.0.0, v2.10.102）

使用方法

1. 配置 Docker Hub 凭证

在 GitHub 仓库设置中添加以下 Secrets：

  • DOCKER_USERNAME: Docker Hub 用户名（例如：wrbug）
  • DOCKER_PASSWORD: Docker Hub 密码或访问令牌

设置步骤：

  1. 访问 GitHub 仓库 → Settings → Secrets and variables → Actions
  2. 点击 "New repository secret"
  3. 添加 DOCKER_USERNAME 和 DOCKER_PASSWORD

2. 创建 Release（必须通过 GitHub Releases 页面）

重要：只有通过 GitHub Releases 页面 创建 release 时才会触发自动构建。

创建步骤：

  1. 访问 GitHub Releases 页面
  2. 点击 "Choose a tag" 下拉菜单，输入新的 tag 名称（例如：v1.0.0 或 v1.0.0-beta）
    • 如果 tag 不存在，GitHub 会自动创建
    • Tag 格式：v数字.数字.数字 或 v数字.数字.数字-后缀（例如：v1.0.0, v1.0.0-beta, v2.10.102-rc.1）
  3. 填写 Release 标题（例如：v1.0.0 或 v1.0.0-beta）
  4. 填写 Release 描述（可选，建议填写更新内容）
  5. 点击 "Publish release" 按钮

注意：

  • ⚠️ 直接通过 git push 推送 tag 不会触发构建
  • ✅ 只有通过 Releases 页面点击 "Publish release" 才会触发构建
  • 这样可以确保只有正式发布的版本才会构建 Docker 镜像

3. 自动构建流程

点击 "Publish release" 后，GitHub Actions 会自动：

  1. 提取版本号：从 tag 中提取版本号（例如：v1.0.0 → 1.0.0）
  2. 构建 Docker 镜像：使用版本号作为构建参数
  3. 注入版本号：在构建前端时注入版本号到代码中
  4. 推送镜像：推送到 Docker Hub，标签为：
    • wrbug/polyhermes:v1.0.0（具体版本）
    • wrbug/polyhermes:latest（最新版本）

4. 版本号显示

前端会在标题 "PolyHermes" 后显示版本号，格式为：PolyHermes v1.0.0

  • 显示位置：桌面端左侧导航栏标题，移动端顶部标题
  • 样式：小字号，半透明，正常展示（无下划线等特殊样式）
  • 点击行为：点击版本号跳转到对应的 GitHub tag 页面

5. 删除 Release 和 Docker 镜像

当在 GitHub Releases 页面删除 release 时，会自动删除对应的 Docker 镜像标签：

  1. 访问 GitHub Releases 页面
  2. 找到要删除的 release
  3. 点击 "Delete" 按钮
  4. GitHub Actions 会自动触发删除流程
  5. 删除对应的 Docker 镜像标签（例如：wrbug/polyhermes:v1.0.0）

注意事项：

  • ⚠️ 只有格式为 v数字.数字.数字 或 v数字.数字.数字-后缀 的版本号才会被删除（例如：v1.0.0, v1.0.0-beta, v2.10.102）
  • ⚠️ 如果镜像标签不存在，会显示警告但不会失败
  • ⚠️ latest 标签不会被删除（即使删除最新的 release）

技术实现

版本号注入流程

  1. GitHub Actions 提取 tag 中的版本号
  2. Dockerfile 接收构建参数（VERSION、GIT_TAG、GITHUB_REPO_URL）
  3. Vite 构建 通过环境变量注入版本号到 window.__VERSION__
  4. 前端代码 从 window.__VERSION__ 读取版本号并显示

文件说明

  • .github/workflows/docker-build.yml: GitHub Actions 工作流配置
  • Dockerfile: 支持版本号构建参数
  • frontend/vite.config.ts: Vite 配置，注入版本号到全局变量
  • frontend/src/utils/version.ts: 版本号工具函数
  • frontend/src/components/Layout.tsx: 显示版本号的组件

环境变量

构建时使用的环境变量：

  • VERSION: 版本号（例如：1.0.0）
  • GIT_TAG: Git tag（例如：v1.0.0）
  • GITHUB_REPO_URL: GitHub 仓库 URL（默认：https://github.com/WrBug/PolyHermes）

开发环境

在开发环境中，版本号默认为 dev，不会显示为链接。

如果需要测试版本号显示，可以在 .env 文件中设置：

VITE_APP_VERSION=1.0.0
VITE_APP_GIT_TAG=v1.0.0
VITE_APP_GITHUB_REPO_URL=https://github.com/WrBug/PolyHermes

常见问题

Q1: 创建 release 后没有触发构建？

A: 检查以下几点：

  1. 确认是通过 GitHub Releases 页面 创建的 release，而不是直接推送 tag
  2. 确认点击了 "Publish release" 按钮（不是 "Save draft"）
  3. 检查 GitHub Actions 是否已启用
  4. 查看 Actions 标签页中的工作流运行情况
  5. 确认 release 状态为 "Published"（不是 "Draft" 或 "Prerelease"）

Q2: Docker 推送失败？

A: 检查以下几点：

  1. 确认已正确配置 DOCKER_USERNAME 和 DOCKER_PASSWORD Secrets
  2. 确认 Docker Hub 账户有权限推送镜像
  3. 检查 Docker Hub 仓库名称是否正确（wrbug/polyhermes）

Q3: 前端没有显示版本号？

A: 检查以下几点：

  1. 确认构建时传递了版本号环境变量
  2. 检查浏览器控制台是否有错误
  3. 确认使用的是构建后的镜像，而不是开发环境

Q4: 版本号点击没有跳转？

A: 检查以下几点：

  1. 确认 GIT_TAG 环境变量已正确设置
  2. 确认 GitHub 仓库 URL 正确
  3. 检查浏览器是否阻止了弹窗

Q5: 删除 release 后 Docker 镜像没有被删除？

A: 检查以下几点：

  1. 确认版本号格式为 v数字.数字.数字（例如：v1.0.0）
  2. 确认 Docker Hub 凭证（DOCKER_USERNAME 和 DOCKER_PASSWORD）正确配置
  3. 确认 Docker Hub 访问令牌有删除镜像的权限
  4. 查看 GitHub Actions 日志，确认删除操作是否执行
  5. 如果镜像标签不存在，会显示警告但不会失败（这是正常的）

Q6: 版本号格式要求是什么？

A: 版本号必须严格匹配格式：v数字.数字.数字 或 v数字.数字.数字-后缀

  • ✅ 正确：v1.0.0, v2.10.102, v1.0.0-beta, v1.0.0-rc.1, v2.10.102-alpha
  • ❌ 错误：v1.0, 1.0.0, v1.0.0.1, v1.0.0_beta（下划线不支持）

示例

创建 Release 示例

步骤 1：访问 Releases 页面 访问：https://github.com/WrBug/PolyHermes/releases/new

步骤 2：创建 Release

  1. 在 "Choose a tag" 中输入 v1.0.0（如果不存在会自动创建）
  2. 填写 Release 标题：v1.0.0
  3. 填写 Release 描述（可选）
  4. 点击 "Publish release"

步骤 3：自动构建

  • GitHub Actions 会自动触发构建
  • 构建完成后，Docker 镜像会自动推送到 Docker Hub
  • 前端会显示 "PolyHermes v1.0.0"

注意：直接通过 git push 推送 tag 不会触发构建，必须通过 Releases 页面创建。

使用 Docker 镜像示例

# 拉取特定版本
docker pull wrbug/polyhermes:v1.0.0

# 拉取最新版本
docker pull wrbug/polyhermes:latest

# 运行容器
docker run -d -p 80:80 wrbug/polyhermes:v1.0.0

注意事项

  1. Tag 格式：必须使用 v* 格式（例如：v1.0.0），否则不会触发构建
  2. 版本号格式：建议使用语义化版本号（Semantic Versioning）
  3. Docker Hub：确保 Docker Hub 仓库已创建
  4. 权限：确保 GitHub Actions 有权限访问 Docker Hub
Reference in New Issue View Git Blame Copy Permalink