桌面应用

本文档介绍 MateClaw 桌面应用（mateclaw-desktop）的架构、构建与使用。

概述

mateclaw-desktop 基于 Electron 框架，将 Vue 3 前端嵌入 Chromium 窗口，同时管理内嵌的 Spring Boot 后端进程（含捆绑 JRE）。用户无需安装 Java 或打开浏览器，启动应用后即可使用完整的 MateClaw 功能。

架构

┌──────────────────────────────────────────┐
│            Electron 外壳                  │
│  ┌────────────────────────────────────┐  │
│  │      BrowserWindow (Chromium)      │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │     Vue 3 前端 (dist/)       │  │  │
│  │  │   Element Plus + Tailwind    │  │  │
│  │  └────────────┬─────────────────┘  │  │
│  └───────────────┼────────────────────┘  │
│                  │ HTTP / SSE             │
│  ┌───────────────▼────────────────────┐  │
│  │   Spring Boot 后端 (子进程)         │  │
│  │   localhost:18088                   │  │
│  │   捆绑 JRE + H2 文件数据库          │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │   electron-updater 自动更新         │  │
│  │   GitHub Releases 检查 + 下载       │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

核心特性：

原生窗口体验，无需浏览器
系统托盘集成，后台常驻
捆绑 JRE，用户无需单独安装 Java
自动更新：通过 electron-updater 检查 GitHub Releases 并下载安装
本地优先，数据存储在用户目录
跨平台支持（macOS、Windows、Linux）

平台支持

平台	架构	状态
macOS	Intel (x64)	支持
macOS	Apple Silicon (ARM64)	支持
Windows	x64	支持
Linux	x64	支持

前置条件

依赖	版本要求	说明
Node.js	18+	前端构建和 Electron 开发
pnpm / npm	8+ / 9+	包管理器
Java	21+（推荐）	后端编译和开发模式运行（生产包已捆绑 JRE）
Maven	3.8+	后端构建

模块结构

mateclaw-desktop/
├── electron/
│   ├── main/
│   │   └── index.ts             # Electron 主进程（后端管理、自动更新）
│   └── preload/
│       └── index.ts             # 预加载脚本（IPC 桥接）
├── src/                         # Vue 3 前端源码（渲染进程）
│   └── App.vue
├── resources/
│   ├── jre/                     # 捆绑的 JRE（按平台/架构）
│   └── app.jar                  # Spring Boot 后端 JAR
├── build/                       # 应用图标（各平台格式）
├── electron-builder.json        # electron-builder 打包配置
├── package.json                 # 含 dev / build / package 脚本
└── vite.config.ts               # Vite + vite-plugin-electron 配置

开发模式

bash

cd mateclaw-desktop
npm install
npm run dev

开发模式下：

Vite 启动前端开发服务器（热更新生效）
Electron 主进程启动，打开 BrowserWindow 加载 Vite 开发地址
主进程以子进程方式启动 Spring Boot JAR，监听 localhost:18088
前端通过 HTTP/SSE 与后端通信

修改前端代码会自动热更新（HMR）；修改 Electron 主进程代码会自动重启。

生产构建

bash

cd mateclaw-desktop
npm run build && npx electron-builder --mac   # macOS
npm run build && npx electron-builder --win   # Windows
npm run build && npx electron-builder --linux # Linux

构建产物位于 release/ 目录：

平台	产物	说明
macOS	`.dmg` 安装包 + `.zip`	双击 .dmg 拖入 Applications 安装
Windows	`.exe` 安装包 (NSIS)	标准 Windows 安装流程，支持自定义安装目录
Linux	`.AppImage`	添加执行权限后直接运行，无需安装

构建前提

生产构建前，需要先准备后端 JAR 和 JRE：

bash

# 1. 构建前端静态资源
cd mateclaw-ui
pnpm install && pnpm build

# 2. 构建后端 JAR（含前端静态资源）
cd mateclaw-server
mvn clean package -DskipTests

# 3. 复制 JAR 到桌面项目资源目录
cp target/mateclaw-server.jar ../mateclaw-desktop/resources/app.jar

# 4. 下载对应平台的 JRE（脚本会自动下载并解压到 resources/jre/）
cd ../mateclaw-desktop
bash scripts/download-jre.sh

# 5. 构建桌面安装包
npm run build && npx electron-builder

Java 后端生命周期管理

Electron 主进程通过 Node.js child_process 管理 Java 后端的完整生命周期：

启动阶段：应用启动时，主进程使用捆绑的 JRE 以子进程方式启动 Spring Boot JAR，并等待后端端口就绪
就绪检测：轮询 http://localhost:18088 直到后端响应，随后加载前端页面
运行阶段：前端通过 localhost:18088 与后端通信，包括 REST API 和 SSE 流式连接
关闭阶段：用户退出应用时，主进程向后端发送优雅关闭信号（SIGTERM / taskkill），等待进程退出后再关闭窗口

自动更新

MateClaw 桌面版集成了 electron-updater，支持从 GitHub Releases 自动检测和下载新版本。

更新流程

应用启动后自动检查 GitHub Releases 是否有新版本
发现新版本时，在前端界面显示更新通知（版本号和更新日志）
用户确认后开始下载更新包，实时显示下载进度
下载完成后，用户可选择「立即安装」或「下次启动时安装」
安装时自动退出应用、替换文件并重启

配置

更新源配置在 electron-builder.json 的 publish 字段中：

json

{
  "publish": [
    {
      "provider": "github",
      "owner": "matevip",
      "repo": "mateclaw"
    }
  ]
}

开发模式测试

开发模式下，如果项目根目录存在 dev-app-update.yml 文件，electron-updater 仍可工作。否则会跳过自动更新。

数据存储

桌面版使用 H2 文件数据库，数据存储在用户目录下：

macOS：~/Library/Application Support/MateClaw/data/
Windows：%APPDATA%/MateClaw/data/
Linux：~/.local/share/MateClaw/data/

electron-builder.json 配置

打包配置位于 electron-builder.json，控制安装包的生成方式：

配置	说明
`appId`	应用唯一标识符（`vip.mate.mateclaw`），用于系统注册和代码签名
`productName`	应用名称，显示在标题栏和安装程序中
`publish`	自动更新源配置（GitHub Releases）
`extraResources`	需要捆绑的额外资源（JRE 和 app.jar）
`mac.target`	macOS 构建目标：dmg + zip，支持 arm64 和 x64
`win.target`	Windows 构建目标：NSIS 安装程序
`linux.target`	Linux 构建目标：AppImage
`mac.hardenedRuntime`	macOS 强化运行时（代码签名和公证必需）
`nsis.oneClick`	设为 false，允许用户选择安装目录

环境变量

桌面版需要配置 API Key 才能正常使用 AI 功能：

bash

# macOS / Linux - 写入 shell 配置文件
echo 'export DASHSCOPE_API_KEY=sk-your-key' >> ~/.zshrc
source ~/.zshrc

# Windows - 在系统环境变量中添加
setx DASHSCOPE_API_KEY sk-your-key

也可以在应用启动后，进入「设置」页面配置 API Key。

故障排除

窗口空白

症状： 应用启动后窗口显示空白页面。

可能原因及解决方案：

后端未成功启动 -- 检查系统进程中是否存在 Java 进程监听 18088 端口

bash

lsof -i :18088         # macOS / Linux
netstat -ano | findstr 18088  # Windows

端口被占用 -- 关闭占用 18088 端口的其他进程后重试
捆绑的 JRE 损坏 -- 尝试重新安装应用
查看应用日志定位具体错误

代码签名

未签名的应用在 macOS 和 Windows 上会触发安全警告：

macOS：首次打开时右键点击应用，选择「打开」以绕过 Gatekeeper 检查。生产分发建议配置 Apple Developer 证书进行签名和公证。详见 mateclaw-desktop/CODESIGNING.md。
Windows：用户可能看到 SmartScreen 警告，点击「更多信息」后选择「仍要运行」。生产分发建议购买 EV 代码签名证书。

桌面应用无法启动

症状： 双击应用图标后无反应或闪退。

排查步骤：

安装版已捆绑 JRE，通常无需单独安装 Java。如果从源码构建的开发版，需确认 java -version 输出 21 或更高
查看应用日志：
- macOS：~/Library/Logs/MateClaw/
- Windows：%APPDATA%/MateClaw/logs/
- Linux：~/.local/share/MateClaw/logs/
尝试从终端启动应用以查看控制台输出
确认端口 18088 未被其他进程占用

企业微信扫码授权弹窗

桌面端中企业微信扫码授权需要在应用内打开弹窗（而非系统浏览器），以确保 postMessage 回调正常工作。MateClaw 已在 setWindowOpenHandler 中对 work.weixin.qq.com 域名做了特殊处理，自动以应用内弹窗方式打开。

注意事项

桌面版默认使用端口 18088，确保该端口未被占用
首次启动需要较长时间初始化数据库
关闭窗口不会停止后台服务，需通过系统托盘退出
数据存储在本地文件系统，建议定期备份

下一步

快速开始 -- 本地开发环境搭建
配置说明 -- 应用配置详解
控制台 -- 前端功能介绍

桌面应用 ​

概述 ​

架构 ​

平台支持 ​

前置条件 ​

模块结构 ​

开发模式 ​

生产构建 ​

构建前提 ​

Java 后端生命周期管理 ​

自动更新 ​

更新流程 ​

配置 ​

开发模式测试 ​

数据存储 ​

electron-builder.json 配置 ​

环境变量 ​

故障排除 ​

窗口空白 ​

代码签名 ​

桌面应用无法启动 ​

企业微信扫码授权弹窗 ​

注意事项 ​

下一步 ​

桌面应用

概述

架构

平台支持

前置条件

模块结构

开发模式

生产构建

构建前提

Java 后端生命周期管理

自动更新

更新流程

配置

开发模式测试

数据存储

electron-builder.json 配置

环境变量

故障排除

窗口空白

代码签名

桌面应用无法启动

企业微信扫码授权弹窗

注意事项

下一步