若依 B 端从浏览器访问升级为 Windows 安装包交付流程

若依 B 端从浏览器访问升级为 Windows 安装包交付流程1. 文档目的本文记录本项目将开源若依 B 端从默认的“浏览器访问 Vue 管理后台”方式升级为“Windows 桌面安装包交付”方式的完整流程。当前已验证通过的目标效果是测试人员下载一个 Windows 安装器.exe。双击安装后桌面出现Appliance Desktop应用图标。用户点击桌面图标后打开独立应用窗口。应用窗口内加载若依 Vue 前端界面。前端直接访问一体机或测试服务器上的 Java 后端 API。用户全程不需要手动打开浏览器。应用可以从 Windows 应用列表正常卸载。绿色 zip 包曾作为中间验证环节使用但当前正式测试交付方案以 Windows 安装包为准。2. 方案背景开源若依 Vue 管理后台的常见使用方式是后端 Java 服务部署到服务器。Vue 前端构建后部署到 Nginx 或 Web 容器。用户通过浏览器访问后台地址。这种方式适合通用 Web 管理后台但在一体机或客户现场交付场景里会遇到一些体验和运维问题用户需要记住浏览器访问地址。不同测试人员的浏览器环境不一致。地址栏、浏览器缓存、下载策略等会影响体验。客户更容易理解“安装一个应用然后从桌面打开”。售后分发时希望只给测试人员一个明确的安装包。因此本项目采用 Electron 将若依 Vue 前端包装成 Windows 桌面应用再使用 electron-builder 生成 NSIS 安装包。3. 最终使用方式后端部署方式保持不变Java 后端 MySQL/MariaDB Redis后端需要能被测试电脑访问例如http://测试服务器IP:8080/captchaImage桌面端交付方式变为Appliance Desktop Setup-YYYYMMDD.exe测试人员操作双击安装包。安装完成后桌面出现Appliance Desktop图标。双击桌面图标打开客户端。首次启动填写后端地址http://测试服务器IP:8080使用测试账号登录admin / admin123注意测试人员电脑必须能访问测试服务器的8080端口。防火墙、安全组、局域网策略需要放开对应访问。桌面安装包只包含前端桌面客户端不包含 Java 后端、MySQL/MariaDB、Redis。4. 技术架构整体结构如下Windows 桌面应用 └─ Electron 主进程 └─ BrowserWindow └─ 若依 Vue 前端 dist └─ Axios 请求一体机后端 API 测试服务器 / 一体机 ├─ Java 后端 ├─ MySQL 或 MariaDB └─ Redis关键点Electron 不替代后端只负责提供独立桌面窗口和本地配置能力。Vue 前端仍然是原有若依 B 端界面。API 地址由用户首次启动时填写并保存到 Electron 的userData目录。后续启动时客户端会自动读取本地保存的后端地址并探测/captchaImage。5. 项目目录本文涉及的主要目录如下C:\Users\WD\Desktop\test-project\test-project\Project ├─ web\RuoYi-Vue3 # 若依 Vue3 前端 Electron 桌面端 ├─ sever\RuoYi-Vue # 若依 Java 后端 └─ deploy\packages # 桌面端安装包交付目录前端工程目录C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3安装包输出目录C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages6. Electron 入口当前项目已在前端工程中配置 Electronweb/RuoYi-Vue3/electron/main.cjs web/RuoYi-Vue3/electron/preload.cjsmain.cjs负责创建独立桌面窗口。加载开发环境地址或生产环境dist/index.html。读取和写入一体机后端地址配置。控制外部链接不要直接在桌面窗口内乱跳转。preload.cjs负责通过contextBridge暴露安全的配置读写接口。让 Vue 前端可以读取和保存后端 API 地址。7. package.json 关键配置前端工程的package.json中关键脚本如下{scripts:{build:web:vite build,build:desktop:npm run build:web electron-builder --win nsis node scripts/stage-desktop-installer.cjs,build:installer:npm run build:web electron-builder --win nsis node scripts/stage-desktop-installer.cjs,pack:win:npm run build:web electron-builder --win --dir}}推荐日常打安装包使用npm.cmd run build:installer说明build:web先构建 Vue 前端生成dist。electron-builder --win nsis再构建 Windows NSIS 安装包。stage-desktop-installer.cjs最后把安装器复制到deploy/packages并加上日期。Windows PowerShell 下建议使用npm.cmd不要直接使用npm。某些机器会因为执行策略禁止加载npm.ps1导致命令被拦截。8. electron-builder 配置当前安装包使用 electron-builder 的 NSIS target{build:{appId:com.appliance.desktop,productName:Appliance Desktop,directories:{output:release},files:[dist/**/*,electron/**/*,package.json],win:{target:[{target:nsis,arch:[x64]}],artifactName:${productName} Setup ${version}.${ext}},nsis:{oneClick:true,perMachine:false,allowElevation:false,createDesktopShortcut:true,createStartMenuShortcut:true,shortcutName:Appliance Desktop,runAfterFinish:true,deleteAppDataOnUninstall:false}}}配置含义target: nsis生成 Windows 安装器。arch: x64构建 64 位 Windows 客户端。oneClick: true一键安装减少测试人员操作。perMachine: false用户级安装不要求管理员权限。allowElevation: false不主动申请提权。createDesktopShortcut: true安装后创建桌面快捷方式。createStartMenuShortcut: true安装后创建开始菜单快捷方式。runAfterFinish: true安装完成后可直接启动应用。deleteAppDataOnUninstall: false卸载时不主动删除用户配置避免误删后端地址等本地配置。9. 安装包归档脚本脚本位置web/RuoYi-Vue3/scripts/stage-desktop-installer.cjs作用从release目录查找 electron-builder 生成的安装器。复制到项目统一交付目录deploy/packages。按日期命名为Appliance Desktop Setup-YYYYMMDD.exe例如本次测试通过的产物C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-20260805.exe10. 打包流程进入前端工程目录cd C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3执行安装包构建npm.cmd run build:installer成功后应看到类似输出vite build built in xx.xx s electron-builder building targetnsis filerelease\Appliance Desktop Setup 3.9.2.exe Staged installer: C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe最终交付文件C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe11. 分发给同事测试当前正式测试方案只需要发送安装器.exeAppliance Desktop Setup-YYYYMMDD.exe可以通过以下方式分发企业微信或钉钉直接发送。如果聊天工具拦截.exe可以压缩成 zip 再发送。如果仍然拦截可以上传到内网共享盘、NAS、网盘或测试服务器下载目录。发给测试人员时建议附带说明测试客户端安装方式 1. 双击 Appliance Desktop Setup-YYYYMMDD.exe 安装。 2. 安装完成后桌面会出现 Appliance Desktop 图标。 3. 双击桌面图标打开客户端。 4. 首次启动填写后端地址 http://测试服务器IP:8080 5. 登录账号 admin / admin123 注意 - 测试电脑必须能访问测试服务器的 8080 端口。 - 如果 Windows 提示未知发布者选择“更多信息” - “仍要运行”。 - 这个安装包只包含桌面客户端不包含后端、数据库、Redis。 - 后端必须已经部署好并能访问 http://测试服务器IP:8080/captchaImage12. 测试验收流程12.1 后端连通性测试在测试电脑浏览器或命令行确认后端可访问http://测试服务器IP:8080/captchaImage如果不能访问先检查Java 后端是否启动。服务器防火墙是否放开8080。云服务器安全组是否放开8080。测试电脑和服务器是否处在可互通网络中。12.2 安装测试测试步骤双击安装器。等待安装完成。检查桌面是否出现Appliance Desktop图标。检查开始菜单是否出现Appliance Desktop。验收标准安装过程无报错。无需手动解压文件。无需管理员权限即可完成用户级安装。12.3 启动测试测试步骤双击桌面Appliance Desktop。确认打开独立桌面窗口。首次启动时填写后端地址。点击连接。验收标准应用窗口正常打开。不需要手动打开浏览器。后端地址保存成功。可进入登录页。12.4 登录测试测试账号admin / admin123验收标准验证码可以加载。登录请求正常发送到测试后端。登录成功后进入若依 B 端首页。12.5 卸载测试测试步骤打开 Windows 应用列表。找到Appliance Desktop。点击卸载。验收标准应用可以正常卸载。主程序文件被移除。Windows 应用列表中不再显示该应用。本项目当前测试结果下载、安装、启动、卸载均已验证通过。13. 常见问题13.1 npm 命令被 PowerShell 拦截现象无法加载文件 npm.ps1因为在此系统上禁止运行脚本处理方式使用npm.cmd run build:installer不要直接使用npm run build:installer13.2 electron-builder 下载超时现象connect ETIMEDOUT 20.205.243.166:443原因electron-builder在构建安装包时可能需要下载 Electron、NSIS 或相关构建资源。该错误通常是访问 GitHub 资源超时不是 Vue 构建失败。处理方式直接重试构建。更换网络。配置代理。复用已经成功下载过的本地缓存。判断标准如果只看到vite build built但后面electron-builder报ETIMEDOUT说明前端构建成功安装包没有成功生成。如果最后看到Staged installer: ...Appliance Desktop Setup-YYYYMMDD.exe说明安装包生成成功。13.3 npm 和 pnpm 如何选择当前项目使用package-lock.json说明依赖主要由 npm 管理。本次安装包链路已经验证通过的命令是npm.cmd run build:installer如果仅为解决electron-builder下载超时不建议切换 pnpm因为超时发生在electron-builder下载资源阶段换包管理器通常不能解决网络问题。如后续团队决定切换 pnpm需要统一执行pnpm install pnpm run build:installer并统一提交pnpm-lock.yaml避免 npm 和 pnpm 混用导致依赖锁文件混乱。13.4 Windows 提示未知发布者原因当前第一版安装包未配置企业代码签名证书。测试阶段处理方式更多信息 - 仍要运行正式客户交付建议申请或购买代码签名证书。在 electron-builder 中配置 Windows 签名。避免客户电脑频繁出现安全提示。13.5 安装后连接不上后端优先检查填写地址是否正确例如http://测试服务器IP:8080测试电脑是否能访问http://测试服务器IP:8080/captchaImage后端服务是否启动。服务器防火墙或安全组是否放开8080。后端是否允许当前桌面端访问接口。14. 当前方案边界当前安装包方案包含Windows 桌面客户端。Electron 运行壳。若依 Vue 前端静态资源。本地保存后端 API 地址的能力。当前安装包方案不包含Java 后端。MySQL 或 MariaDB。Redis。OCR、模型、算法服务。自动更新。代码签名证书。后端仍需要单独部署到测试服务器或一体机。15. 后续优化建议建议后续按优先级优化配置正式应用图标替换 Electron 默认图标。增加代码签名减少 Windows 安全提示。增加安装包版本号和构建日期展示。增加内网下载页统一分发安装包。增加自动更新能力但需要先明确客户现场网络策略。增加安装包哈希校验方便确认安装包未损坏或被替换。16. 技术博客提纲后续可将本文改写为技术博客标题可以是如何把若依 Vue 管理后台包装成 Windows 桌面安装包建议博客结构背景为什么 B 端后台不再只通过浏览器访问。目标安装后桌面打开不依赖用户手动打开浏览器。技术选型Electron Vue electron-builder。改造步骤添加 Electron 主进程和 preload。API 地址处理首次启动填写后端地址并本地保存。打包配置NSIS 用户级安装包配置。构建命令和产物归档。测试流程安装、启动、连接后端、登录、卸载。踩坑记录npm.ps1、GitHub 下载超时、未知发布者。总结这种方式适合一体机、局域网和客户现场测试交付。17. 快速命令汇总进入前端工程cd C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3构建 Windows 安装包npm.cmd run build:installer安装包输出位置C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe验证后端http://测试服务器IP:8080/captchaImage测试账号admin / admin123效果视频