Bruno GaoandQwen-Coder
2fd1eb59ab
- Create SECURITY.md with vulnerability disclosure policy - Create docs/README.md as documentation index page - Create docs/observability.md with metrics/logs/traces/alerting/SLO specs - Create docs/runbook.md with troubleshooting scenarios (RB-01 to RB-05) - Create docs/security.md with security design and compliance - Create docs/release.md with versioning and rollback strategies - Create docs/database.md with database design and migration strategy - Create docs/adr/0005-cache-error-handler.md for cache error handling ADR - Update README.md with documentation index section - Update docs/architecture.md to update B-7 rule and add trust boundary section - Create docs/api-guide.md with API specifications - Fix method names in OrderDao.java to match OrderMapper interface - Add Spring Boot Actuator dependency to tmpl-infrastructure - Fix Redis ping method in RedisHealthContributor.java - Fix syntax errors and method names in OrderAppService.java Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# 版本发布与回滚 (Release)
|
||
|
||
---
|
||
|
||
## 1. 版本号规范
|
||
|
||
本项目采用 **语义化版本** (Semantic Versioning 2.0.0)：`MAJOR.MINOR.PATCH`。
|
||
|
||
| 组成 | 含义 | 何时递增 |
|
||
|------|------|----------|
|
||
| MAJOR | 不兼容的 API 变更 | 删除端点、修改响应结构、删除字段 |
|
||
| MINOR | 向后兼容的功能新增 | 新增端点、新增可选字段 |
|
||
| PATCH | 向后兼容的缺陷修复 | Bug 修复、安全补丁、文档修正 |
|
||
|
||
预发布版本可附加标签，如 `1.2.0-rc.1`、`1.2.0-beta.1`。
|
||
|
||
---
|
||
|
||
## 2. 发布流程
|
||
|
||
### 2.1 完整流程
|
||
|
||
**Step 1 — 更新版本号**
|
||
|
||
```bash
|
||
# Maven 项目版本
|
||
mvn versions:set -DnewVersion=1.2.0
|
||
mvn versions:commit
|
||
```
|
||
|
||
**Step 2 — 更新 CHANGELOG.md**
|
||
|
||
在 `CHANGELOG.md` 顶部添加新版本段落，列出 Added、Changed、Fixed、Removed 各类变更。
|
||
|
||
**Step 3 — 提交并打 Tag**
|
||
|
||
```bash
|
||
git add -A
|
||
git commit -m "chore(release): v1.2.0"
|
||
git tag -a v1.2.0 -m "Release v1.2.0"
|
||
git push origin main --tags
|
||
```
|
||
|
||
**Step 4 — CI 自动构建**
|
||
|
||
Tag push 触发 CI Pipeline：运行全部测试（`mvn clean verify`）；构建 Docker 镜像并推送（`tmpl-api:1.2.0` + `tmpl-api:latest`）；生成 GitHub Release（附 CHANGELOG 摘要）。
|
||
|
||
**Step 5 — 更新 Kustomize 镜像标签**
|
||
|
||
```bash
|
||
./deploy/scripts/update-image-tag.sh <env> 1.2.0
|
||
git add deploy/overlays/<env>/kustomization.yaml
|
||
git commit -m "deploy(<env>): update image tag to 1.2.0"
|
||
git push
|
||
```
|
||
|
||
GitOps 工具（ArgoCD / Flux）检测到 overlay 变更后自动部署。
|
||
|
||
### 2.2 热修复流程 (Hotfix)
|
||
|
||
从对应版本 Tag 创建 `hotfix/1.2.1` 分支 → 修复 → 合并回 `main` → 按上述流程发布 `1.2.1`。
|
||
|
||
---
|
||
|
||
## 3. Docker 镜像标签策略
|
||
|
||
| 标签 | 来源 | 用途 |
|
||
|------|------|------|
|
||
| `1.2.0` | Git Tag `v1.2.0` | 不可变生产标签 |
|
||
| `1.2` | 最新 1.2.x | 方便 staging 滚动 |
|
||
| `latest` | 最新 main 构建 | 仅限 dev 环境 |
|
||
| `sha-abc1234` | Git commit SHA | CI 中间产物追溯 |
|
||
|
||
生产环境禁止使用 `latest` 标签。
|
||
|
||
---
|
||
|
||
## 4. 回滚策略
|
||
|
||
### 4.1 Kubernetes 回滚
|
||
|
||
```bash
|
||
# 查看历史
|
||
kubectl rollout history deployment/tmpl-api -n <ns>
|
||
|
||
# 回滚到上一版本
|
||
kubectl rollout undo deployment/tmpl-api -n <ns>
|
||
|
||
# 回滚到指定版本
|
||
kubectl rollout undo deployment/tmpl-api -n <ns> --to-revision=3
|
||
```
|
||
|
||
### 4.2 Kustomize / GitOps 回滚
|
||
|
||
通过 Git revert overlay 中的镜像标签变更，ArgoCD/Flux 会自动部署回退版本。
|
||
|
||
```bash
|
||
git revert <commit-hash>
|
||
git push
|
||
```
|
||
|
||
### 4.3 数据库回滚注意事项
|
||
|
||
Flyway 迁移是 forward-only 的，不支持自动回滚。如果新版本包含 schema 变更，回滚应用时：
|
||
|
||
若迁移仅添加了列或表（向后兼容），旧版本代码可正常运行，无需回滚 schema。若迁移删除了列或修改了类型（不兼容），必须提前准备反向迁移脚本（新版本号），在回滚应用前先执行。
|
||
|
||
**建议**：所有 schema 变更设计为向后兼容（expand-then-contract 模式），使回滚成为可能。
|
||
|
||
---
|
||
|
||
## 5. 发布检查清单
|
||
|
||
发布前确认以下项目：`mvn clean verify` 全部通过；CHANGELOG.md 已更新；版本号已在 POM 和 Tag 中同步；Docker 镜像构建成功且大小 <= 200MB；OWASP Dependency-Check 无 CVSS >= 7.0 漏洞；Kustomize overlay 中镜像标签已更新；在 staging 环境完成冒烟测试（健康检查、核心 API、Prometheus 端点）。 |