WrBug
60dbfbcfde
- 创建 docker-build.yml：专门负责构建和推送 Docker 镜像 - 创建 docker-delete.yml：专门负责删除 Docker 镜像标签 - 简化 docker-build.yml，移除删除逻辑 - 更新文档，说明两个独立的 workflow 文件及其职责
267 lines
11 KiB
Markdown
267 lines
11 KiB
Markdown
# 版本号管理说明
|
||
|
||
## 概述
|
||
|
||
本项目支持自动版本号管理和显示。当在 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 页面](https://github.com/WrBug/PolyHermes/releases/new) 创建 release 时才会触发自动构建。
|
||
|
||
**Workflow 说明**：
|
||
- 创建 release 时，会触发 `docker-build.yml` workflow，自动构建并推送镜像
|
||
- 删除 release 时，会触发 `docker-delete.yml` workflow，自动删除对应的镜像标签
|
||
|
||
**创建步骤**：
|
||
1. 访问 [GitHub Releases 页面](https://github.com/WrBug/PolyHermes/releases/new)
|
||
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 页面](https://github.com/WrBug/PolyHermes/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` 文件中设置：
|
||
|
||
```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 页面](https://github.com/WrBug/PolyHermes/releases/new) 创建的 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 镜像示例
|
||
|
||
```bash
|
||
# 拉取特定版本
|
||
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
|
||
|