qihuaiflow/docs/VERSIONING.md

版本号规范 (Versioning)

适用：七虎AI PaaS 平台 (qihuaiflow) 全部发布物（源码、Docker 镜像、线上环境）。 生效版本：v2026.07.18.1（取代旧 -recover 标签体系）。

---

1. 版本号格式

vYYYY.MM.DD.N

段	含义	示例
YYYY	年（4 位）	2026
MM	月（2 位，补零）	07
DD	日（2 位，补零）	18
N	当日递增序号，从 1 开始，同日多次发布顺延	1, 2, 3 …

• 同一天第 1 次发布 = v2026.07.18.1，第 2 次 = v2026.07.18.2。
• 跨天序号重置：次日第 1 次发布 = v2026.07.19.1。
• 序号不与全局总发布数绑定，只跟"当天第几次"有关，便于人类快速判断发布日期与顺序。

2. 环境标签 (prod / test)

每个版本必须标注环境，用于正式版与测试版的环境切割：

• prod — 正式版，面向最终用户，质量门禁（测试全绿 + 备份完成）必须达标。
• test — 测试版 / 灰度 / 预发布，允许未完全冻结，但同样需要镜像备份。

环境信息记录在 VERSION 文件的 ENV= 字段，并写入 git tag 注解与镜像 metadata。

3. 三类发布物的对应关系

一次发布同时产生三个相互关联的制品：

制品	命名	工具
Git 标签	v2026.07.18.1（注解含 env=prod）	git tag -a
Docker 镜像	qihu-aiflow:v2026.07.18.1	docker tag / docker commit
运行态快照（回滚点）	qihu-aiflow:backup-YYYYMMDD-NNN	scripts/backup_before_deploy.py

关键纪律：backup-* 是部署前对当前健康运行态的快照（防线）；v* 镜像/标签是部署后的发布物（成果）。两者不是一个东西。

4. 发布流程（SOP）

每次部署严格遵守以下步骤：

# 0. 在改任何代码之前，先打部署前镜像备份（强制）
python scripts/backup_before_deploy.py --env prod --note "发布 v2026.07.18.1 前快照"

# 1. 在容器中完成代码修改
#    （编辑 /app/... → 必要时 npm run build → docker restart）

# 2. 把容器内最新源码 docker cp 回宿主仓库
docker cp qihu-aiflow:/app /www/wwwroot/qihuaiflow   # 仅后端；前端 dist 同理

# 3. 更新 VERSION 文件（VERSION / ENV / DATE / BACKUP_IMAGE）

# 4. 提交并打标签
cd /www/wwwroot/qihuaiflow
git add -A
git commit -m "release: v2026.07.18.1 (prod) — <一句话变更摘要>"
git tag -a v2026.07.18.1 -m "prod | Phase0 工程纪律止血：备份SOP + 版本规范 + 测试基建"
git push origin main
git push origin v2026.07.18.1

# 5. 固化发布镜像（可选但推荐，便于回滚到有版本号的镜像）
docker commit qihu-aiflow qihu-aiflow:v2026.07.18.1

5. 回滚流程

若发布后发现问题：

# 方案 A：回滚到部署前快照（最快，不依赖源码）
docker tag qihu-aiflow:backup-20260718-001 qihu-aiflow:with-deps
docker restart qihu-aiflow

# 方案 B：回滚到某个历史发布镜像
docker tag qihu-aiflow:v2026.07.18.1 qihu-aiflow:with-deps
docker restart qihu-aiflow

# 方案 C：源码回滚
git checkout v2026.07.18.1
docker cp /www/wwwroot/qihuaiflow/app qihu-aiflow:/app
docker restart qihu-aiflow

6. VERSION 文件维护

• 仓库根目录 VERSION 为机器 + 人共读的清单，必须包含 VERSION= / ENV= / DATE= / BASE_IMAGE= / BACKUP_IMAGE= 五个字段。
• 每次发布更新 VERSION 与 DATE，并在"本版本变更"小节追加一行摘要。
• BACKUP_IMAGE 必须填写本次发布前实际生成的 backup-* 标签，作为可审计的回滚点。

7. 旧标签处理

• 旧 -recover 系列标签（v2026.07.12-recover 等）保留不删，仅停止使用，避免丢失历史快照索引。
• 旧镜像标签 AIFlow v2.0.1 / v2026.07.14 / v2026.07.14-nav 视为历史资产，新发布不再沿用该命名。