PolyHermes/docs/zh/VERSION_MANAGEMENT.md

版本号管理说明

📖 English Version: Version Management Guide (English)

概述

本项目支持自动版本号管理和显示。当在 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数字.数字.数字 或 v数字.数字.数字-后缀（例如：v1.0.0, v1.0.0-beta）
7. 独立脚本：构建和删除功能分离到不同的 workflow 文件，便于管理和维护

Workflow 文件说明

项目使用两个独立的 GitHub Actions workflow 文件：

• .github/workflows/docker-build.yml：负责构建和推送 Docker 镜像

  • 触发条件：release: published（创建 release 时）
  • 功能：提取版本号、构建多架构镜像、推送到 Docker Hub

• .github/workflows/docker-delete.yml：负责删除 Docker 镜像

  • 触发条件：release: deleted（删除 release 时）
  • 功能：验证版本号格式、删除对应的 Docker 镜像标签

使用方法

1. 配置 Docker Hub 凭证

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

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

设置步骤：

1. 创建 Docker Hub Access Token（推荐）：

   • 访问：https://hub.docker.com/settings/security
   • 点击 "New Access Token"
   • 填写描述（如：GitHub Actions PolyHermes）
   • 重要：勾选以下权限：
     • ✅ Read & Write（用于推送镜像）
     • ✅ Delete repository tags（用于删除镜像）
   • 点击 "Generate"
   • 立即复制令牌（只显示一次）

2. 在 GitHub 中添加 Secrets：

   • 访问 GitHub 仓库 → Settings → Secrets and variables → Actions
   • 点击 "New repository secret"
   • 添加 DOCKER_USERNAME：你的 Docker Hub 用户名
   • 添加 DOCKER_PASSWORD：刚才创建的 Access Token（不是密码）

注意：

• ⚠️ 如果使用密码而不是 Access Token，删除镜像功能可能无法正常工作
• ✅ 推荐使用 Access Token，并确保有 Delete repository tags 权限

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

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

Workflow 说明：

• 创建 release 时，会触发 docker-build.yml workflow，自动构建并推送镜像
• 删除 release 时，会触发 docker-delete.yml workflow，自动删除对应的镜像标签

创建步骤：

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数字.数字.数字 或 v数字.数字.数字-后缀（例如：v1.0.0, v1.0.0-beta）
2. 确认 Docker Hub 凭证（DOCKER_USERNAME 和 DOCKER_PASSWORD）正确配置
3. 确认 Docker Hub 访问令牌有删除镜像的权限：
   • 如果使用 Access Token，需要确保有 Delete repository tags 权限
   • 访问 Docker Hub → Account Settings → Security → Access Tokens
   • 创建或编辑访问令牌，确保勾选 Delete repository tags 权限
4. 如果遇到 401 错误，可能是：
   • 访问令牌过期，需要重新生成
   • 访问令牌权限不足，需要添加删除权限
   • 用户名或密码/令牌错误
5. 查看 GitHub Actions 日志，确认删除操作是否执行
6. 如果镜像标签不存在，会显示警告但不会失败（这是正常的）

Q7: 删除镜像时遇到 401 未授权错误？

A: 这通常是因为认证失败，请检查：

1. 如果使用 Access Token：

   • 确保访问令牌未过期
   • 确保访问令牌有 Delete repository tags 权限
   • 在 Docker Hub → Account Settings → Security → Access Tokens 中检查权限

2. 如果使用密码：

   • 确保用户名和密码正确
   • 如果启用了 2FA，需要使用 Access Token 而不是密码

3. 创建新的 Access Token：

   • 访问：https://hub.docker.com/settings/security
   • 点击 "New Access Token"
   • 填写描述（如：GitHub Actions Delete Images）
   • 重要：勾选 Delete repository tags 权限
   • 复制生成的令牌，更新 GitHub Secrets 中的 DOCKER_PASSWORD

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