74 lines
4.2 KiB
Markdown
74 lines
4.2 KiB
Markdown
# Jenkinsfile 单体部署 nl-server 设计
|
||
|
||
- 日期：2026-07-16
|
||
- 分支：feature/20260713/task-module
|
||
- 状态：已评审通过（Docker 容器 + 构建机=运行机 + 参数化多环境）
|
||
|
||
## 1. 背景与目标
|
||
|
||
项目当前无任何 CI/CD 流水线。目标：在仓库根目录新增 `Jenkinsfile`，把 `nl-server`（单体聚合模块，内含 system/infra/lms/task 四个 server 模块）以 Docker 容器形式部署到 Jenkins 构建机本机，先跑通单服务单机部署。
|
||
|
||
## 2. 已确认的环境事实与决策
|
||
|
||
| 项 | 结论 |
|
||
|---|---|
|
||
| 部署形态 | Docker 容器（复用现有 `nl-server/Dockerfile`：temurin 21-jre、EXPOSE 48080、支持 `JAVA_OPTS`/`ARGS` 环境变量） |
|
||
| 构建机与运行机 | 同一台机器（Jenkins agent 本机 docker run） |
|
||
| Spring profile | 参数化（test/dev/prod，默认 test） |
|
||
| 构建产物 | `mvn package` 后 `nl-server/target/nl-server.jar`（pom finalName=nl-server，spring-boot repackage） |
|
||
| 前提 | 构建机已装 JDK 17+、Maven、Docker，Jenkins 任务类型为 Pipeline from SCM |
|
||
| 测试 | 构建跳过测试（`-DskipTests`，项目约定） |
|
||
|
||
## 3. Jenkinsfile 设计（声明式 Pipeline）
|
||
|
||
### 3.1 参数（parameters）
|
||
|
||
| 参数 | 类型 | 默认值 | 用途 |
|
||
|---|---|---|---|
|
||
| `PROFILE` | choice(test/dev/prod) | test | 注入 `SPRING_PROFILES_ACTIVE` |
|
||
| `NACOS_ADDR` | string | `127.0.0.1:8848` | 注入 `SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR` 与 `SPRING_CLOUD_NACOS_SERVER_ADDR`（沿用现有 docker-compose 变量名风格） |
|
||
| `NACOS_NAMESPACE` | string | 空 | 注入 `SPRING_CLOUD_NACOS_CONFIG_NAMESPACE` 与 `SPRING_CLOUD_NACOS_DISCOVERY_NAMESPACE` |
|
||
| `JAVA_OPTS` | string | `-Xms512m -Xmx512m -Djava.security.egd=file:/dev/./urandom` | 覆盖 Dockerfile 内默认 JVM 参数（默认值与 Dockerfile 保持一致，避免参数化后丢失 egd 配置） |
|
||
|
||
### 3.2 环境变量（environment）
|
||
|
||
- `IMAGE_NAME = 'nl-server'`
|
||
- `CONTAINER_NAME = 'nl-server'`
|
||
- `APP_PORT = '48080'`
|
||
|
||
### 3.3 Stages
|
||
|
||
1. **Checkout**：`checkout scm`。
|
||
2. **Maven Build**：`mvn clean package -pl nl-server -am -DskipTests`（只构建 nl-server 及依赖模块）。
|
||
3. **Docker Build**：`docker build -t nl-server:${BUILD_NUMBER} -t nl-server:latest nl-server/`（构建上下文为 nl-server 目录，Dockerfile `COPY ./target/nl-server.jar`）。
|
||
4. **Deploy**：`docker stop`/`docker rm` 旧容器（`|| true` 容错首次部署）；`docker run -d --name nl-server --restart always --network host`，挂载日志卷 `-v /docker/nl-cloud/logs:/root/logs/`（与现有 compose 一致），注入 `TZ=Asia/Shanghai`、`SPRING_PROFILES_ACTIVE`、Nacos 四个变量、`JAVA_OPTS`，镜像用 `nl-server:${BUILD_NUMBER}`。
|
||
5. **Health Check**：shell 循环最多 24 次、每次间隔 5s（约 120s）探测 `http://127.0.0.1:48080`，收到任意 HTTP 响应即通过；超时则 `docker logs --tail 200` 输出容器日志并使构建失败。
|
||
|
||
### 3.4 post 处理
|
||
|
||
- `success`：输出部署成功信息（镜像 tag、访问地址）。
|
||
- `failure`：输出失败提示。
|
||
- `always`：`docker image prune -f` 仅清理悬空镜像（历史 `nl-server:<BUILD_NUMBER>` tag 保留，用于手动回滚）。
|
||
|
||
### 3.5 网络模式说明
|
||
|
||
使用 `--network host`：与项目现有 `script/docker/docker-compose.yml` 一致；Nacos 在同机部署时容器内可直接访问 `127.0.0.1:8848`，无需端口映射（端口由应用自身监听 48080）。
|
||
|
||
## 4. 错误处理
|
||
|
||
- 任一 stage 命令非零退出即中止流水线（声明式默认行为）。
|
||
- 停删旧容器 `|| true`，首次部署无旧容器不报错。
|
||
- 健康检查失败：输出容器日志后 `exit 1`，构建标红；旧镜像 tag 仍在本机，可手动回滚。
|
||
|
||
## 5. 验证
|
||
|
||
- 本地无 Jenkins 环境，静态验证为主：Jenkinsfile 为 Groovy 声明式语法，检查括号/引号配对与 stage 结构；shell 片段用 `bash -n` 无法直接验证（内嵌），人工核对。
|
||
- 真实验证需在 Jenkins 上建 Pipeline 任务指向仓库运行（由用户执行）。
|
||
|
||
## 6. 范围外（明确不做）
|
||
|
||
- 微服务逐个部署（gateway/system/infra/task 独立容器）。
|
||
- 推送镜像仓库、SSH 远程部署、多机部署。
|
||
- 前端 nl-ui 的构建部署。
|
||
- 自动回滚、通知（钉钉等）。
|