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) 划分：

Checkout：拉取代码。
Quality Gate (Linter & Test)：执行静态代码扫描（Ruff/ESLint）和单元测试（Pytest）。失败则立刻中断流水线。
SonarQube Analysis：进行代码异味、漏洞分析。
Build & Push：将应用打包并构建为 Docker 镜像，打上与 Git Commit ID 绑定的 Tag，推送到镜像仓库（Harbor/阿里云 ACR）。
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 环境变量清单。

5.8 KiB Raw Blame History Unescape Escape