Files

T

Bruno GaoandQwen-Coder 2fd1eb59ab docs: Complete production-grade documentation set

- 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 <[email protected]>

2026-02-12 21:47:33 +08:00

3.4 KiB

Raw Permalink Blame History

版本发布与回滚 (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 — 更新版本号

# Maven 项目版本
mvn versions:set -DnewVersion=1.2.0
mvn versions:commit

Step 2 — 更新 CHANGELOG.md

在 CHANGELOG.md 顶部添加新版本段落，列出 Added、Changed、Fixed、Removed 各类变更。

Step 3 — 提交并打 Tag

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 镜像标签

./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 回滚

# 查看历史
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 会自动部署回退版本。

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 端点）。

3.4 KiB Raw Permalink Blame History Unescape Escape