feat(release): ship integrated desktop runtime bundle

FallingAKS · FallingAKS · commit 04756a54bb6c · 2026-02-20T18:02:19.000+08:00
diff --git a/.github/workflows/release-on-tag.yml b/.github/workflows/release-on-tag.yml
@@ -25,6 +25,15 @@ jobs:
           cache: npm
           cache-dependency-path: frontend/package-lock.json
 
+      - name: Setup Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Stage desktop runtime payload
+        run: node scripts/stage-desktop-runtime.js --project-root . --frontend-dir frontend --include-jre
+
       - name: Install frontend dependencies
         working-directory: frontend
         run: npm ci
diff --git a/.gitignore b/.gitignore
@@ -15,11 +15,13 @@ backend/moqui_logs/
 backend/app/moqui_logs/
 moqui_logs/
 backend/app/target/
+backend/framework/target/
 
 # frontend build artifacts
 frontend/dist/
 frontend/dist-electron/
 frontend/node_modules/
+frontend/resources/
 
 # local editor/system files
 *.tmp
diff --git a/backend/dist/README.md b/backend/dist/README.md
@@ -0,0 +1,12 @@
+# Backend Runtime Artifact
+
+- `app.jar` is the backend runtime artifact used by desktop release packaging.
+- Desktop packaging script priority:
+  1. `backend/dist/app.jar`
+  2. `backend/app/target/app.jar` (local fallback)
+
+When backend implementation changes, refresh this artifact before tagging release:
+
+```powershell
+Copy-Item -Force backend\app\target\app.jar backend\dist\app.jar
+```
diff --git a/backend/dist/app.jar b/backend/dist/app.jar
diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -139,6 +139,7 @@ Run in order:
    - `v3.0.4` exists in Releases
    - Title/tag/target branch/release notes are correct
    - Windows downloadable assets are attached (portable `exe`, and optional `zip`)
+   - Downloaded package can run without source checkout (Electron + embedded backend runtime + bundled JRE)
 6. **Verify runtime surface health**
    - `http://localhost:8080/docs` returns `200`
    - `http://localhost:8080/redoc` returns `200`
diff --git a/docs/release-tagging.md b/docs/release-tagging.md
@@ -37,6 +37,11 @@ npm run release:tag -- -Version v3.0.4 -Push -CreateRelease
 - 工作流：`.github/workflows/release-on-tag.yml`
 - 触发条件：push `v*` tag
 - 行为：自动创建 GitHub Release，并开启自动 Release Notes；同时自动构建并挂载 Windows 下载包（优先 `portable exe`，按目标可能附带 `zip`）
+- 桌面安装包包含：
+  - Electron 客户端
+  - 内置后端 `app.jar`
+  - 后端运行时模板（runtime/component/db）
+  - 内置 JRE（优先使用包内 Java，无包内时回退系统 Java）
 - 若 tag 名含 `-rc/-beta/-alpha`，自动标记为 pre-release
 
 ## 5. 失败处理
diff --git a/docs/releases/README.md b/docs/releases/README.md
@@ -14,3 +14,4 @@ This directory stores release-facing documents:
 - [v3.0.4 release notes](./v3.0.4.md)
 - [v3.0.5 release notes](./v3.0.5.md)
 - [v3.0.6 release notes](./v3.0.6.md)
+- [v3.0.7 release notes](./v3.0.7.md)
diff --git a/docs/releases/v3.0.7.md b/docs/releases/v3.0.7.md
@@ -0,0 +1,34 @@
+# Release Notes: v3.0.7
+
+Release date: 2026-02-20
+
+## Highlights
+
+- Delivered integrated desktop runtime packaging:
+  - Electron desktop app now starts/stops embedded backend automatically.
+  - Packaged app resolves API requests to local embedded backend endpoint.
+- Added runtime staging pipeline:
+  - New staging script assembles backend `app.jar`, runtime template, Moqui components, and optional bundled JRE.
+  - `dist:win` now runs runtime staging before Electron build.
+- Upgraded tag release workflow:
+  - Added Java 21 setup.
+  - Added desktop runtime staging before Windows artifact build.
+
+## Why This Release Matters
+
+- End users can run desktop package without source checkout.
+- Release pipeline now consistently produces integrated runtime artifacts.
+- Desktop packaged mode no longer depends on dev-only `/api` relative routing.
+
+## Verification Snapshot
+
+- Local validation passed:
+  - `npm --prefix frontend run prepare:runtime -- --include-jre`
+  - `npm --prefix frontend run build`
+  - `npm --prefix frontend run dist:win -- --dir`
+
+## Included Changes
+
+- Electron backend process management and runtime bridge.
+- API base URL runtime adaptation for packaged mode.
+- CI/runtime staging integration for tag releases.
diff --git a/docs/zh/release-checklist.md b/docs/zh/release-checklist.md
@@ -139,6 +139,7 @@ git log --oneline -n 15
    - `Releases` 页面存在 `v3.0.4`
    - 标题、Tag、目标分支、发布说明内容一致
    - 已附带 Windows 下载包（优先 portable `exe`，按目标可能含 `zip`）
+   - 下载包可脱离源码直接运行（Electron + 内置后端运行时 + 内置 JRE）
 6. **确认核心访问面健康**
    - `http://localhost:8080/docs` 返回 `200`
    - `http://localhost:8080/redoc` 返回 `200`
diff --git a/docs/zh/releases/README.md b/docs/zh/releases/README.md
@@ -14,3 +14,4 @@
 - [v3.0.4 发布说明](./v3.0.4.md)
 - [v3.0.5 发布说明](./v3.0.5.md)
 - [v3.0.6 发布说明](./v3.0.6.md)
+- [v3.0.7 发布说明](./v3.0.7.md)
diff --git a/docs/zh/releases/v3.0.7.md b/docs/zh/releases/v3.0.7.md
@@ -0,0 +1,34 @@
+# 发布说明：v3.0.7
+
+发布日期：2026-02-20
+
+## 核心更新
+
+- 实现桌面一体化运行时发布：
+  - Electron 应用可自动拉起并关闭内置后端。
+  - 打包态前端 API 自动指向本地内置后端地址。
+- 新增运行时编排流程：
+  - 新脚本统一组装后端 `app.jar`、runtime 模板、Moqui 组件与可选内置 JRE。
+  - `dist:win` 在 Electron 打包前自动执行运行时编排。
+- 升级 Tag 发版工作流：
+  - 增加 Java 21 环境准备。
+  - 增加 Windows 构建前运行时编排步骤。
+
+## 价值说明
+
+- 用户无需源码环境即可运行桌面安装包。
+- 发布链路可稳定产出“客户端 + 后端”一体包。
+- 解决打包态依赖开发代理路径的问题。
+
+## 验证摘要
+
+- 本地验证通过：
+  - `npm --prefix frontend run prepare:runtime -- --include-jre`
+  - `npm --prefix frontend run build`
+  - `npm --prefix frontend run dist:win -- --dir`
+
+## 包含改动
+
+- Electron 内嵌后端进程托管与运行时桥接。
+- 打包态 API 基址自适配。
+- CI/Tag 发布链路接入运行时编排。
diff --git a/frontend/package.json b/frontend/package.json
@@ -7,12 +7,13 @@
     "dev": "concurrently \"npm run dev:main\" \"npm run dev:renderer\"",
     "dev:main": "electron src/main/main.js",
     "dev:renderer": "vite",
+    "prepare:runtime": "node ../scripts/stage-desktop-runtime.js --project-root .. --frontend-dir .",
     "build": "npm run build:renderer && npm run build:main",
     "build:main": "echo 'Main process ready'",
     "build:renderer": "vite build",
     "dist": "npm run build && electron-builder",
     "dist:mac": "npm run build && electron-builder --mac",
-    "dist:win": "npm run build && electron-builder --win",
+    "dist:win": "npm run prepare:runtime -- --include-jre && npm run build && electron-builder --win",
     "dist:linux": "npm run build && electron-builder --linux",
     "dist:all": "npm run build && electron-builder -mwl",
     "pack": "npm run build && electron-builder --dir",
diff --git a/frontend/src/main/main.js b/frontend/src/main/main.js
@@ -2,15 +2,197 @@ const { app, BrowserWindow, Menu, dialog, ipcMain } = require('electron')
 const path = require('path')
 const os = require('os')
 const fs = require('fs')
+const http = require('http')
+const { spawn } = require('child_process')
 
 const fsPromises = fs.promises
 const isDev = !app.isPackaged
 const LOCAL_CONFIG_FILE_NAME = 'local-agent-config.json'
+const BACKEND_HOST = process.env.MOQUI_BACKEND_HOST || '127.0.0.1'
+const BACKEND_PORT = Number(process.env.MOQUI_BACKEND_PORT || 8080)
+const BACKEND_BASE_URL = `http://${BACKEND_HOST}:${BACKEND_PORT}`
+const BACKEND_API_BASE_URL = `${BACKEND_BASE_URL}/api/v1`
+
+let backendProcess = null
+let backendSpawnedByApp = false
 
 function normalizePathInput(value) {
   return typeof value === 'string' ? value.trim() : ''
 }
 
+function isWindows() {
+  return process.platform === 'win32'
+}
+
+function ensureDir(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true })
+}
+
+function copyDirectory(sourceDir, targetDir) {
+  fs.cpSync(sourceDir, targetDir, {
+    recursive: true,
+    force: true,
+    errorOnExist: false,
+  })
+}
+
+function getProjectRootFromDevMain() {
+  return path.resolve(__dirname, '../../..')
+}
+
+function resolveBackendJarPath(projectRoot) {
+  const candidates = [
+    path.join(projectRoot, 'backend', 'dist', 'app.jar'),
+    path.join(projectRoot, 'backend', 'app', 'target', 'app.jar'),
+  ]
+  return candidates.find((filePath) => fs.existsSync(filePath)) || null
+}
+
+function resolveBundledRuntimeRoot() {
+  return path.join(process.resourcesPath, 'resources', 'backend-runtime')
+}
+
+function resolveBundledJavaCommand(runtimeRoot) {
+  const javaExecutable = isWindows() ? 'java.exe' : 'java'
+  const bundledJava = path.join(runtimeRoot, 'jre', 'bin', javaExecutable)
+  return fs.existsSync(bundledJava) ? bundledJava : null
+}
+
+function resolveSystemJavaCommand() {
+  const javaExecutable = isWindows() ? 'java.exe' : 'java'
+  if (process.env.JAVA_HOME) {
+    const javaFromEnv = path.join(process.env.JAVA_HOME, 'bin', javaExecutable)
+    if (fs.existsSync(javaFromEnv)) return javaFromEnv
+  }
+  return 'java'
+}
+
+function waitForBackendReady(url, timeoutMs = 120000) {
+  const startedAt = Date.now()
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const request = http.get(url, (response) => {
+        response.resume()
+        if (response.statusCode === 200) {
+          resolve(true)
+          return
+        }
+        retry()
+      })
+      request.on('error', retry)
+      request.setTimeout(3000, () => {
+        request.destroy()
+      })
+    }
+
+    const retry = () => {
+      if (Date.now() - startedAt >= timeoutMs) {
+        resolve(false)
+        return
+      }
+      setTimeout(attempt, 1000)
+    }
+
+    attempt()
+  })
+}
+
+function ensurePackagedRuntimeData(runtimeRoot) {
+  const runtimeTemplate = path.join(runtimeRoot, 'runtime-template')
+  if (!fs.existsSync(runtimeTemplate)) {
+    throw new Error(`Missing runtime template: ${runtimeTemplate}`)
+  }
+
+  const userRuntimeRoot = path.join(app.getPath('userData'), 'backend-runtime')
+  const runtimeConf = path.join(userRuntimeRoot, 'conf', 'MoquiDevConf.xml')
+  if (!fs.existsSync(runtimeConf)) {
+    copyDirectory(runtimeTemplate, userRuntimeRoot)
+  }
+  return userRuntimeRoot
+}
+
+async function startBackendProcess() {
+  process.env.MOQUI_BACKEND_BASE_URL = BACKEND_API_BASE_URL
+
+  const alreadyUp = await waitForBackendReady(`${BACKEND_BASE_URL}/docs`, 2500)
+  if (alreadyUp) return
+
+  let javaCommand = null
+  let appJar = null
+  let runtimeDir = null
+  let workingDirectory = null
+
+  if (isDev) {
+    const projectRoot = getProjectRootFromDevMain()
+    appJar = resolveBackendJarPath(projectRoot)
+    runtimeDir = path.join(projectRoot, 'backend', 'runtime')
+    workingDirectory = path.join(projectRoot, 'backend')
+    javaCommand = resolveSystemJavaCommand()
+  } else {
+    const runtimeRoot = resolveBundledRuntimeRoot()
+    appJar = path.join(runtimeRoot, 'app.jar')
+    runtimeDir = ensurePackagedRuntimeData(runtimeRoot)
+    workingDirectory = runtimeDir
+    javaCommand = resolveBundledJavaCommand(runtimeRoot) || resolveSystemJavaCommand()
+  }
+
+  if (!appJar || !fs.existsSync(appJar)) {
+    throw new Error(`Backend jar not found: ${appJar || '<empty>'}`)
+  }
+  if (!fs.existsSync(runtimeDir)) {
+    throw new Error(`Backend runtime not found: ${runtimeDir}`)
+  }
+
+  const backendLogDir = path.join(app.getPath('userData'), 'logs')
+  ensureDir(backendLogDir)
+  const stdoutPath = path.join(backendLogDir, 'backend.stdout.log')
+  const stderrPath = path.join(backendLogDir, 'backend.stderr.log')
+  const stdoutStream = fs.createWriteStream(stdoutPath, { flags: 'a' })
+  const stderrStream = fs.createWriteStream(stderrPath, { flags: 'a' })
+
+  const args = [
+    `-Dmoqui.runtime=${runtimeDir}`,
+    '-Dmoqui.conf=conf/MoquiDevConf.xml',
+    `-Dmoqui.port=${BACKEND_PORT}`,
+    '-jar',
+    appJar,
+  ]
+
+  backendProcess = spawn(javaCommand, args, {
+    cwd: workingDirectory,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      MOQUI_RUNTIME: runtimeDir,
+      MOQUI_CONF: 'conf/MoquiDevConf.xml',
+    },
+  })
+  backendSpawnedByApp = true
+
+  backendProcess.stdout?.pipe(stdoutStream)
+  backendProcess.stderr?.pipe(stderrStream)
+  backendProcess.on('exit', () => {
+    stdoutStream.end()
+    stderrStream.end()
+    backendProcess = null
+    backendSpawnedByApp = false
+  })
+
+  const ready = await waitForBackendReady(`${BACKEND_BASE_URL}/docs`, 120000)
+  if (!ready) {
+    throw new Error(`Backend startup timeout. Check logs: ${stderrPath}`)
+  }
+}
+
+function stopBackendProcess() {
+  if (!backendProcess || !backendSpawnedByApp || backendProcess.killed) return
+  try {
+    backendProcess.kill()
+  } catch {
+  }
+}
+
 function createDefaultLocalConfig() {
   const homeDir = os.homedir()
   return {
@@ -130,9 +312,19 @@ function createWindow() {
 }
 
 app.whenReady().then(() => {
-  Menu.setApplicationMenu(null)
-  registerIpcHandlers()
-  createWindow()
+  startBackendProcess()
+    .then(() => {
+      Menu.setApplicationMenu(null)
+      registerIpcHandlers()
+      createWindow()
+    })
+    .catch((error) => {
+      dialog.showErrorBox(
+        'Backend Startup Failed',
+        `${error?.message || error}\n\nPlease verify runtime files and Java environment.`
+      )
+      app.quit()
+    })
 
   app.on('activate', () => {
     if (BrowserWindow.getAllWindows().length === 0) {
@@ -141,6 +333,10 @@ app.whenReady().then(() => {
   })
 })
 
+app.on('before-quit', () => {
+  stopBackendProcess()
+})
+
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {
     app.quit()
diff --git a/frontend/src/preload/preload.js b/frontend/src/preload/preload.js
diff --git a/frontend/src/renderer/services/apiV1Client.ts b/frontend/src/renderer/services/apiV1Client.ts
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
diff --git a/scripts/stage-desktop-runtime.js b/scripts/stage-desktop-runtime.js
