5.7 KiB
5.7 KiB
PERLER LAB CI 质量门禁清单(CI-GATES)
维护者:DevOps-Engineer(T-081) 关联文件:
.github/workflows/deploy.yml更新日期:2026-08-14
本清单定义 PERLER LAB 的 CI/CD 质量门禁。任一门禁失败即阻塞构建与部署。
本地开发可执行同样的命令提前自检,确保推送到 main 后流水线绿。
流水线结构
push main / workflow_dispatch
│
▼
┌─── test(矩阵并行)───┐
│ perler-lab │
│ perler-lab-server │
└──────────┬─────────────┘
▼
build(Docker 镜像构建)
▼
deploy(SSH 部署,需配置 Secrets)
门禁依赖关系:build 依赖 test,deploy 依赖 build。测试不通过则不会构建/部署。
质量门禁清单
G1 前端单元测试
| 项目 | 值 |
|---|---|
| 命令 | npm test(perler-lab 工作目录,即 npx vitest run) |
| 通过标准 | 所有测试文件通过,退出码 0;当前基线:11 个文件 / 147 个用例 |
| 流水线步骤 | test job → Install & Test |
| 失败后果 | 流水线终止,不进入 build |
G2 后端单元测试
| 项目 | 值 |
|---|---|
| 命令 | npm test(perler-lab-server 工作目录,即 npx vitest run) |
| 通过标准 | 所有测试文件通过,退出码 0;当前基线:9 个文件 / 121 个用例 |
| 流水线步骤 | test job → Install & Test(矩阵分支) |
| 失败后果 | 流水线终止,不进入 build |
G3 TypeScript 严格模式类型检查(前后端)
| 项目 | 值 |
|---|---|
| 命令 | npm run typecheck(前后端各自执行,即 npx tsc --noEmit) |
| 通过标准 | 无任何 TS 错误,退出码 0 |
| 严格性 | 两端 tsconfig.json 均开启 "strict": true |
| 流水线步骤 | test job → Typecheck(矩阵两项目均执行) |
| 失败后果 | 流水线终止;vite build 前本地自检必须通过 |
| 备注 | perler-lab-server 的 typecheck 脚本由 T-081 补齐;src/i18n/index.tsx 必须保持 .tsx 后缀(含 JSX) |
G4 前端生产构建
| 项目 | 值 |
|---|---|
| 命令 | npm run build(perler-lab 工作目录,即 npx vite build) |
| 通过标准 | 构建成功,产出 dist/,退出码 0 |
| 流水线步骤 | test job → Frontend production build(仅 perler-lab) |
| 失败后果 | 流水线终止 |
| 备注 | build job 中的 docker build 亦会编译前端,但 G4 在前一阶段显式验证 |
G5 依赖安装策略(矩阵)
| 项目 | 值 |
|---|---|
| 规则 | 存在 package-lock.json 用 npm ci;不存在则 npm install |
| 当前状态 | perler-lab ✅ 有锁文件 → npm ci;perler-lab-server ✅ 有锁文件 → npm ci |
| 命令 | npm ci --no-audit --no-fund |
| 流水线步骤 | test job → Install & Test |
| 备注 | 若新增子项目无锁文件,需在矩阵中改为 npm install |
G6 密钥安全(无硬编码)
| 项目 | 值 |
|---|---|
| 规则 | 所有敏感信息必须通过 ${{ secrets.X }} 引用,禁止硬编码 |
| 当前引用 | DEPLOY_HOST、DEPLOY_USER、DEPLOY_SSH_KEY(部署);DEPLOY_PATH(带默认值 /opt/perler-lab) |
| 仓库配置 | 需在 GitHub → Settings → Secrets 中配置,未配置时 deploy 自动跳过(if: ${{ secrets.DEPLOY_HOST != '' }}) |
G7 并发保护(防并行部署)
| 项目 | 值 |
|---|---|
| 配置 | 工作流级 concurrency.group: ${{ github.workflow }}-${{ github.ref }} |
| 行为 | 同一分支同时触发多次时串行执行;cancel-in-progress: false(排队等待,不中断进行中的部署) |
| 目的 | 防止两次部署同时 git pull + docker compose up 造成生产冲突 |
| 备注 | 由 T-081 新增 |
G8 超时保护
| 项目 | 值 |
|---|---|
| test | timeout-minutes: 15 |
| build | timeout-minutes: 20 |
| deploy | timeout-minutes: 30 |
| 目的 | 防止挂起的 job 无限占用 Actions 时长配额 |
| 备注 | 由 T-081 新增 |
G9 YAML 结构有效性
| 项目 | 值 |
|---|---|
| 验证命令 | python -c "import yaml; yaml.safe_load(open('.github/workflows/deploy.yml'))" |
| 通过标准 | 无解析异常 |
| 备注 | T-081 已通过 pyyaml 实际解析验证 |
本地自检命令速查
# 前端(perler-lab/)
npm ci
npm test # G1
npm run typecheck # G3
npm run build # G4
# 后端(perler-lab-server/)
npm ci
npm test # G2
npm run typecheck # G3
注意:不要直接改
src/i18n/index.tsx的后缀或把含 JSX 的代码放回.ts—— 会同时击穿 G3 与 G4。
修改记录(T-081)
| 变更 | 文件 |
|---|---|
修复矩阵安装命令:perler-lab 改用 npm ci(有锁文件)并更新过期注释 |
.github/workflows/deploy.yml |
新增工作流级 concurrency 并发保护 |
.github/workflows/deploy.yml |
新增 timeout-minutes:test 15 / build 20 / deploy 30 |
.github/workflows/deploy.yml |
| 类型检查扩展到前后端两项目(移除 perler-lab 专属条件) | .github/workflows/deploy.yml |
新增前端生产构建步骤(npm run build) |
.github/workflows/deploy.yml |
新增 typecheck 脚本 |
perler-lab-server/package.json |
修复含 JSX 的 i18n 运行时文件后缀(.ts → .tsx) |
perler-lab/src/i18n/index.tsx |
放宽 Messages 类型为值类型 string(保留键全等约束) |
perler-lab/src/i18n/messages/zh-CN.ts |
修复 DEFAULT_PLAN 与新版 Plan 接口字段不一致 |
perler-lab/src/App.tsx |