# 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 实际解析验证 | --- ## 本地自检命令速查 ```bash # 前端(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` |