# 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** — 保持镜像仓库与源码一致