147 lines
8.2 KiB
Markdown
147 lines
8.2 KiB
Markdown
# PERLER LAB 发布流水线(Release Pipeline)
|
||
|
||
> 版本: v1.0 · 文档编号: RELEASE-PIPELINE · 关联任务: T-080
|
||
> 流水线目标:**验收通过 → 自动提交 → 手动推送 → CI 构建部署**,全程可追溯、可监控、可回滚。
|
||
|
||
---
|
||
|
||
## 1. 流水线总览
|
||
|
||
```
|
||
┌──────────┐ taskboard.js test --pass ┌──────────────┐ 轮询检测新验收任务 ┌────────────────┐
|
||
│ QA 测试 │ ───────────────────────────▶ │ 任务状态: │ ──────────────────▶ │ auto-commit │
|
||
│ Agent │ 状态: review → approved │ approved │ (AUTO_COMMIT_INTERVAL│ 自动提交管道 │
|
||
└──────────┘ └──────────────┘ 默认 60 秒) └───────┬────────┘
|
||
│ git add -A + commit
|
||
│ "[验收通过] T-xxx 标题"
|
||
▼
|
||
┌──────────┐ 人工执行(不自动推送!) ┌────────────────┐ GitHub Actions ┌───────────────┐
|
||
│ GitOps │ ───────────────────────────▶ │ git push │ ──────────────────▶ │ CI/CD │
|
||
│ 工程师 │ node gitflow.js push │ origin/master │ 触发 .github/workflows│ 构建+测试+部署 │
|
||
└──────────┘ └────────────────┘ └───────────────┘
|
||
```
|
||
|
||
**核心原则:**
|
||
- 任务状态机(`pending → in_progress → review → approved`)由 taskboard.js 管理,本管道只**读取**任务文件、**不修改**任务状态。
|
||
- 验收通过后的提交由 auto-commit.js **自动**完成;**推送是独立步骤**,由 GitOps 工程师手动执行,两者解耦。
|
||
- CI/CD(GitHub Actions)由 push 触发,属于发布环节的最后一道自动化闸门。
|
||
|
||
---
|
||
|
||
## 2. 各角色职责(谁跑什么)
|
||
|
||
| 环节 | 负责人 | 执行方式 | 产物 / 记录 |
|
||
|---|---|---|---|
|
||
| 开发 | 实施 Agent | `taskboard.js submit <id>` | 任务进入 `review`(待验收) |
|
||
| 验收 | QA 测试 Agent | `taskboard.js test <id> --pass/--fail` | 状态 → `approved`(通过)/ `rejected` + 自动生成 Bug |
|
||
| **自动提交** | **Release-Manager(本管道)** | `auto-commit.bat` 常驻 或 `node auto-commit.js --once` | `auto-commit.log`(提交 hash、结果) |
|
||
| 推送 | GitOps 工程师 | `node gitflow.js push` 或 `git push` | 远端提交记录 |
|
||
| 构建/部署 | CI(GitHub Actions) | push 自动触发 `.github/workflows/deploy.yml` | Actions 运行记录 |
|
||
| 监控 | 主代理 / 全体 | 看板 `node taskboard.js serve` + `auto-commit.log` | 实时状态 |
|
||
|
||
---
|
||
|
||
## 3. 自动提交管道(auto-commit.js)
|
||
|
||
### 3.1 工作方式
|
||
|
||
- 轮询读取 `taskboard/tasks.json`,间隔由环境变量 `AUTO_COMMIT_INTERVAL` 控制(默认 **60 秒**)。
|
||
- 对比状态文件 `auto-commit-state.json` 中记录的「上次见到的状态」:
|
||
- 任务当前为 `approved` **且** 上次记录不是 `approved` → 判定为「新验收通过」→ 触发提交。
|
||
- 提交逻辑与 `node gitflow.js approve <id>` 等价:`git add -A` + `git commit -m "[验收通过] <id> <标题>"`。
|
||
- ⚠️ 与 gitflow.js 的区别:**本管道不推送**。gitflow.js 的 approve 在配置了 origin 时会顺带推送,本管道刻意省略推送,保持「提交 / 推送」分离。
|
||
- 提交前检查工作区:`git status --porcelain` 为空 → 记录「跳过(无改动)」,不产生空提交。
|
||
- 提交信息通过临时文件传给 `git commit -F`,避免中文标题/引号在 shell 中出错。
|
||
|
||
### 3.2 幂等性(重复运行不会重复提交)
|
||
|
||
- `auto-commit-state.json` 记录每个任务最近一次状态;提交成功或「无改动跳过」后,该任务被标记为 `approved`,后续轮询不再触发。
|
||
- **首次运行只记录基线**:不追溯提交已存在的验收通过任务(避免启动管道时一次性提交全部历史任务)。
|
||
- 提交失败(如 git 异常)会**保留旧状态,下轮自动重试**,不会静默丢失。
|
||
|
||
### 3.3 文件清单
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `auto-commit.js` | 管道主程序(Node,零依赖) |
|
||
| `auto-commit.bat` | Windows 后台启动脚本(最小化窗口运行,窗口标题 `PERLER LAB Auto-Commit`) |
|
||
| `auto-commit-state.json` | 运行状态(每个任务最近状态),已加入 `.gitignore`,不进入提交 |
|
||
| `auto-commit.log` | 运行日志(时间戳 / 任务 id / commit hash / 结果) |
|
||
|
||
### 3.4 启动 / 停止
|
||
|
||
```bat
|
||
:: 后台常驻(最小化窗口)
|
||
auto-commit.bat
|
||
|
||
:: 或前台运行,Ctrl+C 停止
|
||
node auto-commit.js
|
||
|
||
:: 环境变量示例(管理员/命令行先 set 再启动)
|
||
set AUTO_COMMIT_INTERVAL=30
|
||
auto-commit.bat
|
||
```
|
||
|
||
停止后台任务:任务管理器结束 `node.exe`(标题为 `PERLER LAB Auto-Commit` 的窗口),或 `taskkill /F /FI "WINDOWTITLE eq PERLER LAB Auto-Commit*"`。
|
||
|
||
### 3.5 演练模式(干跑)
|
||
|
||
```bat
|
||
node auto-commit.js --dry-run --once
|
||
```
|
||
|
||
只打印「将要提交哪些任务、提交信息是什么、工作区是否有改动」,**不提交、不改状态文件**,可在正式接入前安全验证。
|
||
|
||
### 3.6 日志格式(auto-commit.log)
|
||
|
||
```
|
||
[2026-08-14 09:00:00+08:00] [启动] 验收自动提交管道 v1.0
|
||
[2026-08-14 09:00:00+08:00] [初始化] 首次运行:已记录 81 个任务的当前状态为基线(其中验收通过 43 个,不追溯提交)
|
||
[2026-08-14 09:01:00+08:00] [检测] 发现 1 个新验收通过任务: T-082
|
||
[2026-08-14 09:01:00+08:00] [提交成功] 任务 T-082「xxx」→ commit a1b2c3d4...
|
||
[2026-08-14 09:02:00+08:00] [巡检] 无新验收通过任务(任务总数 82,验收通过 44)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 推送(手动、独立步骤)
|
||
|
||
自动提交只生成**本地** commit。发布到远端由 GitOps 工程师执行:
|
||
|
||
```bash
|
||
node gitflow.js push # 推当前分支到 origin
|
||
# 等价: git push -u origin master
|
||
```
|
||
|
||
> 为什么推送不自动化:push 是**对外发布动作**,涉及远端仓库与 CI 触发,必须由人确认后执行(验收 → 提交已自动,发布 → 人工闸门)。
|
||
|
||
---
|
||
|
||
## 5. CI(push 触发)
|
||
|
||
- push 到远端后,GitHub Actions(`.github/workflows/deploy.yml`)自动执行:测试 → 构建 → 部署(详见 `docs/DEPLOY.md`)。
|
||
- CI 失败处理:GitOps/DevOps 工程师查看 Actions 日志 → 修复 → 重新 push(或 revert 问题提交后重新推送)。
|
||
|
||
---
|
||
|
||
## 6. 监控
|
||
|
||
| 监控点 | 方法 |
|
||
|---|---|
|
||
| 任务状态 | `node taskboard.js serve` 打开实时看板(默认 http://localhost:8787,2 秒刷新) |
|
||
| 提交结果 | 查看 `auto-commit.log` 尾部:`Get-Content auto-commit.log -Tail 20` |
|
||
| 管道是否在跑 | 任务管理器找标题 `PERLER LAB Auto-Commit` 的窗口;或 `tasklist | findstr node` |
|
||
| 本地提交/远端 | `node gitflow.js status`;`git log --oneline -10` |
|
||
|
||
---
|
||
|
||
## 7. 故障排查
|
||
|
||
| 现象 | 原因 | 处理 |
|
||
|---|---|---|
|
||
| 日志无新提交,任务已是 approved | 该任务在管道启动前就已通过验收(基线任务) | 手动 `node gitflow.js approve <id>` 提交;管道此后只处理新增 |
|
||
| `[提交失败] ... 下轮自动重试` | git 异常/冲突 | 查看日志详情,修复后无需操作,下轮自动重试 |
|
||
| 状态文件损坏 | 异常写入 | 管道自动按全新状态处理(重新记基线);也可删除 `auto-commit-state.json` 重置 |
|
||
| 提交未触发 | 工作区无改动 | 正常:管道记录「跳过(无改动)」,不产生空提交 |
|
||
| 想重新触发某任务提交 | 状态文件把该任务记为 approved | 手动执行 `node gitflow.js approve <id>`(或改状态文件后重启管道) |
|