huachuang/docs/superpowers/plans/2026-07-16-jenkinsfile-monolith-deploy.md

# Jenkinsfile 单体部署 nl-server 实现计划

> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。

**目标：** 在仓库根目录新增 `Jenkinsfile`，以 Docker 容器形式在 Jenkins 构建机本机部署 `nl-server` 单体。

**架构：** 声明式 Pipeline：参数化（PROFILE/NACOS_ADDR/NACOS_NAMESPACE/JAVA_OPTS）→ Checkout → `mvn package -pl nl-server -am -DskipTests` → 复用 `nl-server/Dockerfile` 构建镜像（BUILD_NUMBER + latest 双 tag）→ 停删旧容器后 host 网络 `docker run` → curl 循环健康检查；post 清理悬空镜像。

**技术栈：** Jenkins 声明式 Pipeline（Groovy）/ Maven / Docker（Linux 构建机）

**规格：** `docs/superpowers/specs/2026-07-16-jenkinsfile-monolith-deploy-design.md`

---

## 文件结构

| 文件 | 操作 | 职责 |
|---|---|---|
| `Jenkinsfile`（仓库根目录） | 创建 | 单体部署流水线全部逻辑 |

---

### 任务 1：创建根目录 `Jenkinsfile`

**文件：**
- 创建：`Jenkinsfile`

- [ ] **步骤 1：创建文件，内容如下**

```groovy
// nl-server 单体部署流水线（构建机 = 运行机，Linux + JDK17+ + Maven + Docker）
pipeline {
    agent any

    parameters {
        choice(name: 'PROFILE', choices: ['test', 'dev', 'prod'], description: '运行环境（注入 SPRING_PROFILES_ACTIVE）')
        string(name: 'NACOS_ADDR', defaultValue: '127.0.0.1:8848', description: 'Nacos 配置/注册中心地址')
        string(name: 'NACOS_NAMESPACE', defaultValue: '', description: 'Nacos 命名空间（public 留空）')
        string(name: 'JAVA_OPTS', defaultValue: '-Xms512m -Xmx512m -Djava.security.egd=file:/dev/./urandom', description: 'JVM 启动参数')
    }

    environment {
        IMAGE_NAME     = 'nl-server'
        CONTAINER_NAME = 'nl-server'
        APP_PORT       = '48080'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Maven Build') {
            steps {
                // 只构建 nl-server 及其依赖模块，跳过测试
                sh 'mvn clean package -pl nl-server -am -DskipTests'
            }
        }

        stage('Docker Build') {
            steps {
                // 构建上下文为 nl-server 目录，复用其现有 Dockerfile
                sh "docker build -t ${IMAGE_NAME}:${BUILD_NUMBER} -t ${IMAGE_NAME}:latest nl-server/"
            }
        }

        stage('Deploy') {
            steps {
                // 停删旧容器（首次部署无旧容器，容错处理），host 网络启动新容器
                sh """
                    docker stop ${CONTAINER_NAME} || true
                    docker rm ${CONTAINER_NAME} || true
                    docker run -d --name ${CONTAINER_NAME} \\
                        --restart always \\
                        --network host \\
                        -v /docker/nl-cloud/logs:/root/logs/ \\
                        -e TZ=Asia/Shanghai \\
                        -e SPRING_PROFILES_ACTIVE=${params.PROFILE} \\
                        -e SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR=${params.NACOS_ADDR} \\
                        -e SPRING_CLOUD_NACOS_SERVER_ADDR=${params.NACOS_ADDR} \\
                        -e SPRING_CLOUD_NACOS_CONFIG_NAMESPACE=${params.NACOS_NAMESPACE} \\
                        -e SPRING_CLOUD_NACOS_DISCOVERY_NAMESPACE=${params.NACOS_NAMESPACE} \\
                        -e "JAVA_OPTS=${params.JAVA_OPTS}" \\
                        ${IMAGE_NAME}:${BUILD_NUMBER}
                """
            }
        }

        stage('Health Check') {
            steps {
                // 最多等待 24 次 x 5s ≈ 120s，收到任意 HTTP 响应（含 404）即视为启动成功
                sh """
                    echo "等待 nl-server 启动..."
                    for i in \$(seq 1 24); do
                        if curl -s -o /dev/null http://127.0.0.1:${APP_PORT}; then
                            echo "nl-server 启动成功"
                            exit 0
                        fi
                        sleep 5
                    done
                    echo "健康检查超时，输出容器日志："
                    docker logs --tail 200 ${CONTAINER_NAME}
                    exit 1
                """
            }
        }
    }

    post {
        success {
            echo "部署成功：${IMAGE_NAME}:${BUILD_NUMBER}，服务端口 ${APP_PORT}（历史镜像 tag 保留，可用于手动回滚）"
        }
        failure {
            echo '部署失败，请检查上方日志'
        }
        always {
            // 仅清理悬空镜像，保留历史 BUILD_NUMBER tag
            sh 'docker image prune -f || true'
        }
    }
}
```

---

### 任务 2：静态验证

本地无 Jenkins/Groovy 环境，做结构性静态检查：

- [ ] **步骤 1：花括号配对计数**

运行（仓库根目录）：

```bash
grep -o '{' Jenkinsfile | wc -l && grep -o '}' Jenkinsfile | wc -l
```

预期：两个数字相等（60 上下，以实际为准）。

- [ ] **步骤 2：结构核对清单（人工比对文件内容）**

- [ ] `pipeline { agent any; parameters; environment; stages; post }` 五段齐全
- [ ] 4 个参数名与规格一致：PROFILE / NACOS_ADDR / NACOS_NAMESPACE / JAVA_OPTS
- [ ] 5 个 stage：Checkout / Maven Build / Docker Build / Deploy / Health Check
- [ ] Deploy 中 6 个 `-e` 环境变量 + TZ + 日志卷挂载 + `--network host` + `--restart always`
- [ ] shell 中 `$(seq ...)` 已转义为 `\$(seq ...)`（避免被 Groovy 插值）
- [ ] `JAVA_OPTS` 注入带引号（值含空格）

---

### 任务 3：统一提交（可选，需用户同意）

- [ ] **步骤 1：确认用户同意后提交**

```bash
git add Jenkinsfile \
        docs/superpowers/specs/2026-07-16-jenkinsfile-monolith-deploy-design.md \
        docs/superpowers/plans/2026-07-16-jenkinsfile-monolith-deploy.md
git commit -m "build：新增 Jenkinsfile 单体部署 nl-server"
```

---

## 风险与注意事项

1. **构建机前提**：Linux、JDK 17+、Maven、Docker、curl 已装且 Jenkins 用户有 docker 权限（在 docker 用户组）。
2. **真实验证需在 Jenkins 执行**：建 Pipeline 任务指向本仓库运行；首次运行参数页尚未生成，会用默认参数跑一次。
3. **Nacos 前置**：nl-server 为 Spring Cloud 应用，启动依赖 Nacos 可达；若 Nacos 未就绪，健康检查会超时失败并打印容器日志。