4.8 KiB
头程单仓多服务构建部署说明
一、适用范围
当前 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/** 变化时执行：
mvn -pl order -am clean package
order 与 warehouse 同时变化时只调用一次 Maven：
mvn -pl order,warehouse -am clean package
这样可避免多个并发 Maven 任务同时改写公共模块的 target 目录。
六、镜像与部署规则
每个镜像使用 Git 提交短 SHA 作为不可变标签，例如：
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。生产回滚仍应保留人工确认和操作记录。