103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# 版本号规范 (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）
|
||
|
||
每次部署严格遵守以下步骤：
|
||
|
||
```bash
|
||
# 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. 回滚流程
|
||
|
||
若发布后发现问题：
|
||
|
||
```bash
|
||
# 方案 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` 视为历史资产，新发布不再沿用该命名。
|