ci: 新增 Playground 静态发布流水线

Jenkinsfile

@@ -0,0 +1,174 @@
+def runCmd(String unixScript, String windowsScript = null) {
+  if (isUnix()) {
+    sh unixScript
+  } else {
+    bat(windowsScript ?: unixScript)
+  }
+}
+
+def isPublishBranch(String branchName, String pattern) {
+  return branchName ==~ pattern
+}
+
+pipeline {
+  agent { label 'kt-node-agent' }
+
+  options {
+    skipDefaultCheckout(true)
+    timestamps()
+    disableConcurrentBuilds()
+    buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '10'))
+  }
+
+  parameters {
+    booleanParam(name: 'DEPLOY_STATIC_FILES', defaultValue: true, description: '构建成功后是否发布 dist 到 Nginx 静态目录；仅发布分支生效')
+    string(name: 'PUBLISH_BRANCH_PATTERN', defaultValue: '^(main|master|release/.+)$', description: '允许发布静态文件的分支正则')
+    string(name: 'DEPLOY_TARGET_DIR', defaultValue: '/home/jenkins/agent/frontends/html/playground', description: 'Nginx 挂载目录中 playground 项目的静态文件目录')
+    string(name: 'VITE_APP_API_BASE', defaultValue: '/api', description: '构建进 Playground 页面里的 API 前缀')
+  }
+
+  environment {
+    CI = 'true'
+    PNPM_VERSION = '10.14.0'
+  }
+
+  stages {
+    stage('Checkout') {
+      steps {
+        checkout scm
+      }
+    }
+
+    stage('Prepare') {
+      steps {
+        script {
+          env.IS_CHANGE_REQUEST = env.CHANGE_ID ? 'true' : 'false'
+          def publishPattern = params.PUBLISH_BRANCH_PATTERN?.trim() ?: '^(main|master|release/.+)$'
+          env.IS_PUBLISH_BRANCH = (!env.CHANGE_ID && isPublishBranch(env.BRANCH_NAME ?: '', publishPattern)) ? 'true' : 'false'
+
+          if (isUnix()) {
+            runCmd("""
+              node --version
+              if command -v corepack >/dev/null 2>&1; then
+                corepack enable
+                corepack prepare pnpm@${env.PNPM_VERSION} --activate
+              fi
+              if ! command -v pnpm >/dev/null 2>&1; then
+                echo "pnpm or corepack is required on the Jenkins Agent."
+                exit 1
+              fi
+              pnpm --version
+            """.stripIndent())
+          } else {
+            runCmd('', """
+              node --version
+              where corepack >nul 2>nul
+              if not errorlevel 1 (
+                corepack enable
+                corepack prepare pnpm@${env.PNPM_VERSION} --activate
+              )
+              where pnpm >nul 2>nul
+              if errorlevel 1 exit /b 1
+              pnpm --version
+            """.stripIndent())
+          }
+
+          echo """
+            Branch: ${env.BRANCH_NAME ?: '-'}
+            Change request: ${env.CHANGE_ID ?: '-'}
+            Publish branch: ${env.IS_PUBLISH_BRANCH}
+            Deploy static files: ${params.DEPLOY_STATIC_FILES}
+            Deploy target: ${params.DEPLOY_TARGET_DIR}
+            API base: ${params.VITE_APP_API_BASE}
+          """.stripIndent()
+        }
+      }
+    }
+
+    stage('Install') {
+      steps {
+        script {
+          runCmd('pnpm install --frozen-lockfile')
+        }
+      }
+    }
+
+    stage('Type Check') {
+      steps {
+        script {
+          runCmd('pnpm typecheck')
+        }
+      }
+    }
+
+    stage('Build') {
+      steps {
+        script {
+          withEnv(["VITE_APP_API_BASE=${params.VITE_APP_API_BASE}"]) {
+            runCmd('pnpm run build-preview')
+          }
+        }
+      }
+    }
+
+    stage('Deploy Static') {
+      when {
+        allOf {
+          expression { return params.DEPLOY_STATIC_FILES }
+          expression { return env.IS_CHANGE_REQUEST != 'true' }
+          expression { return env.IS_PUBLISH_BRANCH == 'true' }
+        }
+      }
+      steps {
+        script {
+          if (!isUnix()) {
+            error('Deploy Static stage requires a Linux/NAS Jenkins Agent.')
+          }
+
+          def targetDir = params.DEPLOY_TARGET_DIR?.trim()
+          if (!targetDir) {
+            error('DEPLOY_TARGET_DIR is required when DEPLOY_STATIC_FILES is enabled.')
+          }
+
+          // 先发布到临时目录再替换目标目录，避免 Nginx 读到半复制状态。
+          withEnv(["TARGET_DIR=${targetDir}"]) {
+            runCmd("""
+              set -e
+              test -f dist/index.html
+
+              case "\${TARGET_DIR}" in
+                ""|"/"|"/home"|"/home/jenkins"|"/home/jenkins/agent"|"/usr"|"/usr/share"|"/usr/share/nginx"|"/usr/share/nginx/html")
+                  echo "Unsafe DEPLOY_TARGET_DIR: \${TARGET_DIR}"
+                  exit 1
+                  ;;
+              esac
+
+              parent_dir=\$(dirname "\${TARGET_DIR}")
+              release_dir="\${TARGET_DIR}.release-${env.BUILD_NUMBER}"
+              previous_dir="\${TARGET_DIR}.previous"
+
+              mkdir -p "\${parent_dir}"
+              rm -rf "\${release_dir}" "\${previous_dir}"
+              mkdir -p "\${release_dir}"
+              cp -a dist/. "\${release_dir}/"
+
+              if [ -d "\${TARGET_DIR}" ]; then
+                mv "\${TARGET_DIR}" "\${previous_dir}"
+              fi
+              mv "\${release_dir}" "\${TARGET_DIR}"
+              rm -rf "\${previous_dir}"
+
+              find "\${TARGET_DIR}" -maxdepth 2 -type f | head
+            """.stripIndent())
+          }
+        }
+      }
+    }
+  }
+
+  post {
+    success {
+      archiveArtifacts artifacts: 'dist/**,package.json,pnpm-lock.yaml,Jenkinsfile', fingerprint: true, allowEmptyArchive: true
+    }
+  }
+}

README.md

@@ -66,7 +66,7 @@ pnpm dev
 常用命令：
 
 ```bash
-pnpm dev          # 本地 Playground 页面
+pnpm dev          # 本地 Playground 页面，默认端口 48090
 pnpm typecheck    # 类型检查
 pnpm build        # 构建库产物
 pnpm build-preview
@@ -84,7 +84,7 @@ Playground 同时使用 query 和 hash：
 前台跳转示例：
 
 ```text
-http://localhost:5173/?id=xxx&name=基础折线图&type=1&componentType=1#...
+http://localhost:48090/?id=xxx&name=基础折线图&type=1&componentType=1#...
 ```
 
 ## 保存流程

vite.preview.config.ts

@@ -4,6 +4,9 @@ import replace from '@rollup/plugin-replace'
 
 export default defineConfig({
   plugins: [vue()],
+  server: {
+    port: 48090,
+  },
   resolve: {
     alias: {
       '@vue/compiler-dom': '@vue/compiler-dom/dist/compiler-dom.cjs.js',