fix: ACS、PC对任务状态的变化

2026-07-16 14:11:30 +08:00
parent f24e01c7dd
commit be46cf49c5
37 changed files with 2349 additions and 268 deletions
--- a/docs/superpowers/plans/2026-07-16-jenkinsfile-monolith-deploy.md
+++ b/docs/superpowers/plans/2026-07-16-jenkinsfile-monolith-deploy.md
@@ -0,0 +1,170 @@
+# 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 未就绪，健康检查会超时失败并打印容器日志。