docs: 添加 README、Release 模板、docker-compose 编排、构建发布脚本

RELEASE_WORKFLOW.md

@@ -0,0 +1,157 @@
+# 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** — 保持镜像仓库与源码一致