158 lines
4.4 KiB
Markdown
158 lines
4.4 KiB
Markdown
# CloudSearch · 版本发布操作流程
|
||
|
||
## 🗺️ 概述
|
||
|
||
CloudSearch 使用 **VERSION 文件** 作为版本号的唯一真相来源。每次发布包含三个步骤：构建镜像 → 推送仓库 → 创建 Release。
|
||
|
||
---
|
||
|
||
## 🔢 版本规则
|
||
|
||
| 类型 | 增量 | 触发条件 |
|
||
|------|------|---------|
|
||
| **Patch** | `+0.0.1` | 每次完成任务组后 |
|
||
| **Minor** | `+0.1.0` | 用户说"测试没问题可以上线了" |
|
||
| **Major** | `1.0.0` | 完整流程验证接近完美（需先确认） |
|
||
|
||
示例：`0.3.31 → 0.3.32` (patch) · `0.3.x → 0.4.0` (minor)
|
||
|
||
---
|
||
|
||
## 📋 手动发布流程
|
||
|
||
### 方式 A：一键脚本（推荐）
|
||
|
||
```bash
|
||
# 1. 登录私有仓库
|
||
docker login gitea.timxx.cn
|
||
|
||
# 2. 执行发布（自动读取 VERSION 或手动指定）
|
||
chmod +x scripts/build-and-push.sh
|
||
./scripts/build-and-push.sh v0.3.32
|
||
```
|
||
|
||
### 方式 B：分步执行
|
||
|
||
```bash
|
||
# 1. 更新版本号
|
||
echo "0.3.32" > VERSION
|
||
|
||
# 2. 构建镜像
|
||
cd source_clean
|
||
docker build -t cloudsearch-app:v0.3.32 -t cloudsearch-app:latest .
|
||
|
||
# 3. 标记并推送
|
||
docker tag cloudsearch-app:latest gitea.timxx.cn/admin/cloudsearch:v0.3.32
|
||
docker tag cloudsearch-app:latest gitea.timxx.cn/admin/cloudsearch:latest
|
||
docker push gitea.timxx.cn/admin/cloudsearch:v0.3.32
|
||
docker push gitea.timxx.cn/admin/cloudsearch:latest
|
||
|
||
# 4. Git 标签
|
||
git add VERSION && git commit -m "release: v0.3.32"
|
||
git tag -a v0.3.32 -m "Release v0.3.32"
|
||
git push origin master --tags
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 Release 说明编写
|
||
|
||
每次发布在 Gitea 上创建 Release，使用 `RELEASE_TEMPLATE.md` 模板，填写以下段落：
|
||
|
||
1. **版本号与发布日期**
|
||
2. **新增功能** — 列出新加的特性
|
||
3. **问题修复** — 列出修复的 bug
|
||
4. **破坏性变更** — 标注不兼容的 API/配置变更
|
||
5. **升级注意事项** — `.env` 变更、数据库迁移 SQL
|
||
6. **Docker 镜像地址** — 本次发布的完整 tag
|
||
|
||
### 快速生成 Changelog
|
||
|
||
```bash
|
||
# 从上次发布到现在的提交记录
|
||
git log v0.3.31..v0.3.32 --oneline --no-merges
|
||
```
|
||
|
||
---
|
||
|
||
## 🤖 CI 自动化思路（可选参考）
|
||
|
||
### Gitea Actions 示例
|
||
|
||
```yaml
|
||
# .gitea/workflows/release.yml
|
||
name: Build and Release
|
||
|
||
on:
|
||
push:
|
||
tags:
|
||
- 'v*'
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: 获取版本号
|
||
id: version
|
||
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
|
||
|
||
- name: 构建镜像
|
||
run: |
|
||
docker build -t cloudsearch-app:${{ steps.version.outputs.VERSION }} \
|
||
-f source_clean/Dockerfile source_clean/
|
||
|
||
- name: 登录私有仓库
|
||
run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login gitea.timxx.cn -u admin --password-stdin
|
||
|
||
- name: 推送镜像
|
||
run: |
|
||
docker tag cloudsearch-app:${{ steps.version.outputs.VERSION }} \
|
||
gitea.timxx.cn/admin/cloudsearch:v${{ steps.version.outputs.VERSION }}
|
||
docker tag cloudsearch-app:${{ steps.version.outputs.VERSION }} \
|
||
gitea.timxx.cn/admin/cloudsearch:latest
|
||
docker push gitea.timxx.cn/admin/cloudsearch:v${{ steps.version.outputs.VERSION }}
|
||
docker push gitea.timxx.cn/admin/cloudsearch:latest
|
||
|
||
- name: 创建 Release
|
||
uses: actions/gitea-release@v1
|
||
with:
|
||
tag: v${{ steps.version.outputs.VERSION }}
|
||
title: v${{ steps.version.outputs.VERSION }}
|
||
body: |
|
||
查看 RELEASE_NOTES.md 了解完整变更。
|
||
token: ${{ secrets.GITEA_TOKEN }}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 生产部署触发
|
||
|
||
镜像推送成功后，生产环境执行：
|
||
|
||
```bash
|
||
# 方式1：拉取新镜像并重建
|
||
docker pull gitea.timxx.cn/admin/cloudsearch:latest
|
||
docker compose up -d app
|
||
|
||
# 方式2：指定版本
|
||
docker pull gitea.timxx.cn/admin/cloudsearch:v0.3.32
|
||
# 修改 docker-compose.yml 中的 image 标签为 :v0.3.32
|
||
docker compose up -d app
|
||
|
||
# 验证
|
||
curl -s http://localhost:9527/health | jq .version
|
||
# → "0.3.32"
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
- **VERSION 文件是唯一真相来源** — 所有工具（build.sh、health check、前端）都从它读取
|
||
- **不要手动修改 `/app/dist/version.js`** — 它是编译产物，重启后丢失
|
||
- **`docker restart` 不会拉取新镜像** — 必须 `docker compose up -d` 重建容器
|
||
- **推送前先 pull --rebase** — 避免 force push 覆盖历史
|
||
- **每 5 次 patch 迭代同步到 Gitea** — 保持镜像仓库与源码一致
|