暂存提交
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# 头程单仓多服务构建部署说明
|
||||
|
||||
## 一、适用范围
|
||||
|
||||
当前 `baiyue-firstleg` 是一个 Git 仓库，包含 11 个可独立运行的服务和 7 个公共模块。部署时无需拆成多个仓库，Jenkins 使用 Maven `-pl ... -am` 只构建目标服务及其依赖，并为每个服务生成独立 Docker 镜像。
|
||||
|
||||
MySQL、Redis、Nacos 是外部基础设施，不包含在业务 Compose 文件中。各业务库仍使用独立数据库，往来单位数据继续归属 `baiyue_warehouse`。
|
||||
|
||||
## 二、文件说明
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --- | --- |
|
||||
| `Jenkinsfile` | 自动识别变更、测试、打包、构建镜像、推送和部署 |
|
||||
| `deploy/docker/Dockerfile` | 11 个服务共用的 Java 17 非 root 镜像模板 |
|
||||
| `deploy/service-map.yml` | 模块、JAR 和端口的唯一映射清单 |
|
||||
| `deploy/docker-compose.yml` | 11 个业务服务的统一编排文件 |
|
||||
| `deploy/env/.env.test.example` | 测试环境变量模板，不含真实密码 |
|
||||
| `deploy/scripts/deploy-services.sh` | Jenkins 节点上的增量部署脚本 |
|
||||
|
||||
## 三、Jenkins 前置条件
|
||||
|
||||
Jenkins 新建“多分支流水线”或“流水线”，脚本路径填写 `Jenkinsfile`。执行节点标签为 `docker-java17`，节点需要安装：
|
||||
|
||||
- JDK 17
|
||||
- Maven 3.8.8 以上
|
||||
- Docker Engine
|
||||
- Docker Compose V2
|
||||
- Git
|
||||
|
||||
Jenkins 执行用户必须有运行 Docker 的权限。部署脚本当前在 Jenkins 节点执行，因此该节点应位于目标服务器，或将同一标签绑定到对应环境的部署节点。
|
||||
|
||||
## 四、必须创建的 Jenkins 凭据
|
||||
|
||||
| Credentials ID | 类型 | 内容 |
|
||||
| --- | --- | --- |
|
||||
| `gitlab-registry-credentials` | Username with password | GitLab Deploy Token 用户名和令牌，至少有 `read_registry`、`write_registry` 权限 |
|
||||
| `firstleg-test-env` | Secret file | 根据 `.env.test.example` 创建的测试环境 `.env` |
|
||||
| `firstleg-staging-env` | Secret file | 预发布环境 `.env`，使用预发布基础设施地址和密钥 |
|
||||
| `firstleg-production-env` | Secret file | 生产环境 `.env`，使用生产基础设施地址和密钥 |
|
||||
|
||||
GitLab 仓库拉取如果不是由 Jenkins GitLab 集成统一授权，还需单独创建只读仓库凭据。任何 MySQL、Redis、Nacos、JWT 和第三方平台密钥都不得直接填写在 Jenkinsfile 或提交到 Git。
|
||||
|
||||
## 五、流水线参数
|
||||
|
||||
| 参数 | 推荐值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `BUILD_MODE` | `AUTO` | 自动分析上次成功构建之后的 Git 变更 |
|
||||
| `SERVICE` | 按需 | `SELECT` 时填写，如 `order,warehouse` |
|
||||
| `ENVIRONMENT` | `test` | 可选 `test`、`staging`、`production` |
|
||||
| `DEPLOY` | 测试环境勾选 | 是否在镜像推送后执行部署 |
|
||||
| `SKIP_TESTS` | 不勾选 | 临时调试才跳过测试 |
|
||||
| `IMAGE_REPOSITORY` | GitLab 项目镜像地址 | 示例 `gitlab.example.com/logistics/baiyue-firstleg` |
|
||||
|
||||
公共模块、根 POM 或 Dockerfile 变化会构建全部 11 个服务。仅 `order/**` 变化时执行：
|
||||
|
||||
```bash
|
||||
mvn -pl order -am clean package
|
||||
```
|
||||
|
||||
`order` 与 `warehouse` 同时变化时只调用一次 Maven：
|
||||
|
||||
```bash
|
||||
mvn -pl order,warehouse -am clean package
|
||||
```
|
||||
|
||||
这样可避免多个并发 Maven 任务同时改写公共模块的 `target` 目录。
|
||||
|
||||
## 六、镜像与部署规则
|
||||
|
||||
每个镜像使用 Git 提交短 SHA 作为不可变标签，例如：
|
||||
|
||||
```text
|
||||
gitlab.example.com/logistics/baiyue-firstleg/order:a1b2c3d4e5f6
|
||||
```
|
||||
|
||||
测试和预发布环境勾选 `DEPLOY` 后自动部署。生产环境会额外出现人工确认，确认内容包含服务列表和镜像标签。增量部署会自动带上 `gateway`，保证网关配置与业务服务保持可用；不会重启未选择的其他业务服务。
|
||||
|
||||
首次部署建议使用 `BUILD_MODE=ALL`。基础设施必须先可用，并已创建以下数据库：`baiyue_auth`、`baiyue_iam`、`baiyue_firstleg`、`baiyue_order`、`baiyue_warehouse`、`baiyue_file`、`baiyue_print`、`baiyue_event_bridge`、`baiyue_audit`。
|
||||
|
||||
## 七、GitLab CI 与 Jenkins 职责
|
||||
|
||||
现有 `.gitlab-ci.yml` 仍执行全量校验和打包，适合合并请求质量检查；Jenkins 负责镜像构建与部署。正式启用 Jenkins 后，建议把 GitLab CI 的“打包服务”任务限制为合并请求或删除，避免一次提交重复进行两次完整打包。
|
||||
|
||||
## 八、回滚
|
||||
|
||||
回滚不重新编译代码。在 Jenkins 用 `SELECT` 选中服务，将部署环境 `.env` 中的镜像标签临时改为已验证的历史 SHA，或在服务器执行同一 Compose 文件指定历史 `IMAGE_TAG` 后 `up -d`。生产回滚仍应保留人工确认和操作记录。
|
||||
Reference in New Issue
Block a user