Files

5.7 KiB
Raw Permalink Blame History

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