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：一键脚本（推荐）

# 1. 登录私有仓库
docker login gitea.timxx.cn

# 2. 执行发布（自动读取 VERSION 或手动指定）
chmod +x scripts/build-and-push.sh
./scripts/build-and-push.sh v0.3.32

方式 B：分步执行

# 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 模板，填写以下段落：

版本号与发布日期
新增功能 — 列出新加的特性
问题修复 — 列出修复的 bug
破坏性变更 — 标注不兼容的 API/配置变更
升级注意事项 — .env 变更、数据库迁移 SQL
Docker 镜像地址 — 本次发布的完整 tag

快速生成 Changelog

# 从上次发布到现在的提交记录
git log v0.3.31..v0.3.32 --oneline --no-merges

🤖 CI 自动化思路（可选参考）

Gitea Actions 示例

# .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 }}

🔧 生产部署触发

镜像推送成功后，生产环境执行：

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

4.4 KiB Raw Permalink Blame History Unescape Escape