签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 11.11 CI/CD 流水线
+
+:::tip 概述
+CI 门禁：后端 go vet + gofmt + build + test；前端 vue-tsc + eslint + 构建。CD：镜像/产物构建 → 部署 → 健康检查 → 冒烟。本节给出流水线模板与质量门建议。
+:::
+
+## CI 门禁（每次提交）
+
+```yaml
+# 流水线示意（GitLab CI / GitHub Actions 通用）
+stages: [check, build]
+
+backend-check:
+  stage: check
+  script:
+    - go build ./...
+    - go vet ./...
+    - test -z "$(gofmt -l .)"     # 格式检查（有输出即失败）
+    - go test ./...               # sqlite 集成 + hooks MySQL 集成
+
+frontend-check:
+  stage: check
+  working_dir: ui
+  script:
+    - pnpm install --frozen-lockfile
+    - pnpm type:check             # vue-tsc
+    - pnpm lint:eslint
+```
+
+## 构建与发布（tag/主干）
+
+```yaml
+build-push:
+  stage: build
+  script:
+    # 后端镜像（多阶段 Dockerfile，位于 docker/ 目录，上下文为项目根）
+    - docker build -f docker/Dockerfile -t $REGISTRY/easygoadmin:$TAG .
+    - docker push $REGISTRY/easygoadmin:$TAG
+    # 前端产物
+    - cd ui && pnpm build && rsync -az dist/ $SERVER:/opt/ui/dist/
+  only: [main, tags]
+
+deploy:
+  stage: deploy
+  script:
+    - ssh $SERVER "docker pull $REGISTRY/easygoadmin:$TAG && cd docker && docker compose up -d easygoadmin"
+    - ssh $SERVER "curl -sf http://127.0.0.1:8000/api/health"   # 健康检查失败即中止
+    # 冒烟：登录 + 核心接口
+```
+
+## 质量门建议
+
+```text
+必过（阻断合并）：
+  go build / go vet / gofmt
+  go test（sqlite 集成 + hooks MySQL 集成）
+  vue-tsc / eslint
+
+增强（告警或分级）：
+  黄金样本回归（hack/golden 接口响应比对——录制参数带 pageSize=3 等）
+  pnpm audit / go vulncheck（依赖漏洞）
+  覆盖率报告（逐步提升）
+```
+
+## 黄金样本回归（项目内置能力）
+
+```text
+hack/golden/after*/  接口响应黄金样本（回归比对基线）
+录制规范：带录制参数（pageSize=3 等）保证响应稳定可比
+DIFF 归因三类：预期变更（更新样本）/ 非预期回归（修复）/ 环境差异（排除）
+接入 CI：接口回归 job 对比新旧响应，非零差异阻断
+```
+
+## 发布流水线完整链
+
+```text
+提交 → CI 门禁 → 合并主干 → 构建镜像/产物 → 部署测试环境
+  → 冒烟/回归 → 人工确认 → 生产发布（滚动/蓝绿）
+  → health 验证 → 观察日志 → 完成/回滚
+```
+
+## 密钥管理
+
+```text
+CI 变量（加密变量/密钥库）：
+  REGISTRY 凭据 / 部署 SSH 密钥 / GF_JWT_SECRET 等生产密钥
+原则：
+  * 密钥不进代码仓库与镜像层
+  * 生产密钥仅 deploy 阶段注入（check 阶段不可见）
+  * 轮换有流程（改密钥 → 滚动重启 → 旧值失效窗口评估）
+```
+
+## 分支策略建议
+
+```text
+main        可发布主干（保护分支，CI 必过）
+feature/*   功能分支 → MR → CI 门禁 → review 合并
+hotfix/*    紧急修复 → 双人确认 → 快速通道发布
+release/*   版本发布分支（打 tag 触发 CD）
+```
+
+## 流水线排障
+
+| 症状 | 处理 |
+|------|------|
+| gofmt 失败 | gofmt -w . 本地修复后提交 |
+| go test 失败 | 集成测试依赖 MySQL/sqlite——CI 需起测试库服务 |
+| vue-tsc 失败 | 类型错误本地 pnpm type:check 复现 |
+| 部署后 health 失败 | 流水线自动中止；查容器日志/配置注入 |
+| 镜像过大 | 多阶段构建 + alpine + .dockerignore |