# 头程单仓多服务构建部署说明

## 一、适用范围

当前 `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/maven/settings-cn.xml` | Jenkins 构建使用的阿里云 Maven 公共仓库配置 |
| `deploy/service-map.yml` | 模块、JAR 和端口的唯一映射清单 |
| `deploy/docker-compose.yml` | 11 个业务服务的统一编排文件 |
| `deploy/env/.env.test.example` | 测试环境变量模板，不含真实密码 |
| `deploy/scripts/deploy-services.sh` | Jenkins 节点上的增量部署脚本 |

测试环境服务器准备步骤详见 `docs/test-environment-deployment.md`。

## 三、Jenkins 前置条件

Jenkins 新建“多分支流水线”或“流水线”，脚本路径填写 `Jenkinsfile`。执行节点标签为 `docker-java17`，节点需要安装：

- JDK 17
- Maven 3.8.8 以上
- Docker Engine
- Docker Compose V2
- Git

Jenkins 执行用户必须有运行 Docker 的权限。部署脚本当前在 Jenkins 节点执行，因此该节点应位于目标服务器，或将同一标签绑定到对应环境的部署节点。

## 四、必须创建的 Jenkins 凭据

| Credentials ID | 类型 | 内容 |
| --- | --- | --- |
| `gitea-test-token` | Username with password | Gitea 用户名和访问令牌，令牌需要代码读取及容器包读写权限 |
| `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` 时勾选一个或多个服务，如订单和仓库 |
| `ENVIRONMENT` | `test` | 可选 `test`、`staging`、`production` |
| `DEPLOY` | 测试环境勾选 | 是否在镜像推送后执行部署 |
| `SKIP_TESTS` | 不勾选 | 临时调试才跳过测试 |
| `IMAGE_REPOSITORY` | Gitea 容器镜像地址 | 当前测试环境为 `8.163.30.128:10082/java-project/baiyue-firstleg` |
| `DOCKER_BASE_IMAGE` | 保持默认 | 默认通过国内镜像代理拉取 Java 17 运行时，也可替换为企业内部镜像地址 |

公共模块、根 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`。生产回滚仍应保留人工确认和操作记录。