89 lines
5.8 KiB
Markdown
89 lines
5.8 KiB
Markdown
# **5.2 CI/CD 与环境部署规范**
|
||
|
||
持续集成与持续部署（CI/CD）是连接代码与生产环境的高速公路。我们追求的目标是：**一次构建，随处运行；一切即代码（Pipeline as Code）；消除环境差异带来的人为故障。**
|
||
|
||
团队统一采用 **Jenkins** 作为核心的 CI/CD 引擎。
|
||
|
||
### **5.2.1 多环境定义与资源流转 (Environments)**
|
||
|
||
系统从开发到上线，必须经历严格的环境隔离与流转。严禁跨环境调用（如 Dev 环境连接 Prod 数据库）。
|
||
|
||
* **1\. Local (本地开发环境)**
|
||
* **使用者**：开发人员。
|
||
* **形态**：研发个人的笔记本电脑，依赖的数据库、Redis 推荐通过本地 Docker Compose 快速拉起。
|
||
* **目的**：日常编码、单步调试、执行本地单元测试。
|
||
* **2\. Dev (开发集成环境)**
|
||
* **对应分支**：dev (或 develop)
|
||
* **使用者**：开发人员、前端/客户端联调人员。
|
||
* **形态**：自动拉取 dev 分支最新代码部署。允许存在一定的不稳定性，日志级别通常设为 DEBUG。
|
||
* **目的**：验证微服务间的连通性、前后端接口联调。
|
||
* **3\. Test (系统测试环境)**
|
||
* **对应分支**：test (或 release)
|
||
* **使用者**：QA 测试工程师。
|
||
* **形态**：由专门的合并操作触发部署。数据库通常会定期从线上脱敏同步部分数据以模拟真实场景。
|
||
* **目的**：功能验收测试、自动化接口回归测试、性能压测基准测试。
|
||
* **4\. UAT (用户验收测试 / 预发环境)**
|
||
* **对应分支**：main (打 Tag 前的最终验证)
|
||
* **使用者**：产品经理、业务方验收人员。
|
||
* **形态**：**基础架构、配置规格必须与 Prod 生产环境 100% 保持一致**。甚至可以连接生产环境的只读库或独立的预发库。
|
||
* **目的**：上线前的最后一次演练，验证部署脚本本身是否正确，业务逻辑是否符合预期。
|
||
* **5\. Prod (生产环境)**
|
||
* **对应分支**：main (基于发布 Tag，如 v1.2.0)
|
||
* **使用者**：真实的外部用户。
|
||
* **形态**：极度稳定、高可用、严控权限。
|
||
* **目的**：承载真实业务。
|
||
|
||
### **5.2.2 配置隔离与凭证安全**
|
||
|
||
为了实现“同一份代码（或镜像）在不同环境无缝切换”，必须做到代码与配置的彻底分离。
|
||
|
||
* **配置文件解耦**：
|
||
* 遵循《3.2 框架实施规范》，代码中必须拆分不同环境的配置文件（如 settings/dev.py, settings/prod.py）。
|
||
* 运行时通过环境变量（如 export APP\_ENV=prod）来决定加载哪份配置。
|
||
* **密码与密钥红线 (Secret Management)**：
|
||
* **绝对禁止**将数据库密码、API 秘钥、云服务 AccessKey 写死在代码库（包括 .env 文件也不允许提交到 Git）。
|
||
* Jenkins 注入：在 CI/CD 阶段，通过 Jenkins 的凭据管理（Credentials Binding）或 HashiCorp Vault、云厂商配置中心（如 Nacos/Apollo）在容器启动时动态注入环境变量。
|
||
|
||
### **5.2.3 持续集成流水线规范 (Jenkins Pipeline)**
|
||
|
||
**核心理念：Pipeline as Code (流水线即代码)。**
|
||
|
||
* **严禁手动配置 Job**：禁止在 Jenkins UI 页面上手工拼凑 Shell 脚本构建步骤。
|
||
* **强制使用 Jenkinsfile**：
|
||
* 每个代码仓库的根目录必须包含一个使用声明式语法（Declarative Pipeline）编写的 Jenkinsfile。
|
||
* 流水线的版本控制与业务代码同源，谁修改了部署逻辑，Git 历史一目了然。
|
||
|
||
**标准 Jenkinsfile 阶段 (Stages) 划分：**
|
||
|
||
1. Checkout：拉取代码。
|
||
2. Quality Gate (Linter & Test)：执行静态代码扫描（Ruff/ESLint）和单元测试（Pytest）。**失败则立刻中断流水线**。
|
||
3. SonarQube Analysis：进行代码异味、漏洞分析。
|
||
4. Build & Push：将应用打包并构建为 Docker 镜像，打上与 Git Commit ID 绑定的 Tag，推送到镜像仓库（Harbor/阿里云 ACR）。
|
||
5. Deploy to XXX：触发 Kubernetes (K8s) 或目标服务器拉取新镜像并滚动更新。
|
||
|
||
### **5.2.4 流水线触发规则与门禁策略 (Trigger Rules)**
|
||
|
||
为了平衡开发效率与质量控制，Jenkins 流水线必须配合 Webhook 实现自动化触发，并设置严格的卡点（Quality Gates）：
|
||
|
||
#### **1\. PR/MR 提交阶段 (Merge Request to Dev/Main)**
|
||
|
||
* **触发方式**：开发人员在 Gitlab/Github 提交 Pull Request。
|
||
* **执行流水线**：仅执行 Lint \-\> Unit Test \-\> Sonar。**不进行部署**。
|
||
* **门禁规则**：如果 Jenkins 反馈测试失败、覆盖率低于 80% 或存在高危漏洞，代码托管平台必须**锁定合并按钮（Block Merge）**，强迫开发者修复。
|
||
|
||
#### **2\. 代码合并阶段 (Push to Dev/Test)**
|
||
|
||
* **触发方式**：PR 合并到 dev 或 test 分支。
|
||
* **执行流水线**：完整走完上述五个 Stage，最终自动部署到对应的 Dev 或 Test 服务器。
|
||
* **验证测试**：部署完成后，流水线应触发自动化接口测试（API E2E Tests），一旦测试不通过，立即发送飞书/钉钉告警通知团队。
|
||
|
||
#### **3\. 生产发布阶段 (Deploy to Prod)**
|
||
|
||
* **触发方式**：在 main 分支打上符合 SemVer 规范的 Tag（如 v2.1.0）。
|
||
* **门禁规则 (人工卡点)**：
|
||
* 生产环境的部署**绝对禁止全自动触发**。
|
||
* 在 Jenkins 流水线的 Deploy to Prod 阶段前，必须设置一个 input() 审批节点。只有具备 Release 权限的运维工程师或技术 TL 在 Jenkins 界面点击“同意确认”后，才会真正触发生产环境的镜像替换。
|
||
|
||
## 🤖 [附加] AI 助手执行协议 (AI Output Schema)
|
||
|
||
**绝对红线**：生成的 Dockerfile 必须采用多阶段构建 (Multi-stage Build) 并锁定基础镜像版本；必须配套输出标准的 `.env.example` 环境变量清单。 |