JManus 项目编译与启动完整指南

📋 前置要求

在开始之前，请确保您的系统满足以下要求：

1. 系统环境要求

• 操作系统：Windows 10/11、macOS 10.15+ 或 Linux (Ubuntu 18.04+)
• 内存：至少 8GB RAM（推荐 16GB）
• 磁盘空间：至少 5GB 可用空间

2. 软件依赖

#### Java 环境

• Java JDK：17 或更高版本
• Maven：3.8+（项目已包含 Maven Wrapper）

• Node.js：18.x 或更高版本
• pnpm：包管理器（推荐）

• Git：用于克隆代码仓库
• Docker：用于容器化部署（可选）

🚀 快速启动方法（推荐）

方法 1：使用预编译 JAR 文件（最简单）

# 1. 下载最新版本的 JAR 文件
wget https://github.com/spring-ai-alibaba/JManus/releases/latest/download/jmanus.jar
# 或者使用 curl
curl -L -o jmanus.jar https://github.com/spring-ai-alibaba/JManus/releases/latest/download/jmanus.jar

# 2. 直接运行
java -jar jmanus.jar

# 3. 访问应用
# 打开浏览器访问 http://localhost:18080

方法 2：使用 Docker（推荐）

# 1. 确保已安装 Docker
docker --version

# 2. 运行容器（自动下载镜像）
docker run -d -p 18080:18080 --name jmanus springai/jmanus:latest

# 3. 访问应用
# 打开浏览器访问 http://localhost:18080

🔧 从源码编译启动

步骤 1：环境准备

#### 安装 Java 17+

# 检查 Java 版本
java -version

# 如果未安装，请下载安装：
# Windows: https://adoptium.net/
# macOS: brew install openjdk@17
# Linux: sudo apt install openjdk-17-jdk

#### 安装 Node.js 18+

# 检查 Node.js 版本
node --version

# 如果未安装，请下载安装：
# https://nodejs.org/ 下载 18.x 版本

# 安装 pnpm（推荐）
npm install -g pnpm
# 或者使用 npm
npm install -g npm@latest

步骤 2：获取源码

# 克隆代码仓库
git clone https://github.com/spring-ai-alibaba/JManus.git
cd JManus

# 或者下载 ZIP 包并解压
# wget https://github.com/spring-ai-alibaba/JManus/archive/refs/heads/main.zip
# unzip main.zip
# cd JManus-main

步骤 3：编译后端（Java）

#### 选项 A：使用 Maven Wrapper（推荐）

# 进入项目目录
cd JManus

# 编译项目（跳过测试以加快速度）
./mvnw clean package -DskipTests

# 或者使用 Maven（如果已安装）
mvn clean package -DskipTests

#### 选项 B：使用 Makefile

# 编译 Java 后端
make build

# 或者分别执行
make java-build

步骤 4：编译前端（Vue3）

#### 进入前端目录

cd ui-vue3

#### 安装依赖

# 使用 pnpm（推荐）
pnpm install

# 或者使用 npm
npm install

# 或者使用 yarn
yarn install

#### 编译前端

# 构建生产版本
pnpm run build

# 或者使用 Makefile
cd .. && make ui-build

步骤 5：启动应用

#### 选项 A：直接启动 JAR 文件

# 进入项目根目录
cd ..

# 运行编译好的 JAR 文件
java -jar target/jmanus.jar

# 或者使用 Maven 运行
./mvnw spring-boot:run

#### 选项 B：使用 Makefile 启动

# 启动后端服务
make run

# 或者分别启动
make java-run

#### 选项 C：开发模式（前后端分离）

后端开发模式：

# 在项目根目录启动后端
./mvnw spring-boot:run

# 后端将在 http://localhost:18080 运行

前端开发模式：

# 在 ui-vue3 目录启动前端开发服务器
cd ui-vue3
pnpm run dev

# 前端将在 http://localhost:5173 运行
# 会自动代理 API 请求到 http://localhost:18080

🛠️ 高级配置

数据库配置（可选）

默认使用 H2 内存数据库，如需使用 MySQL/PostgreSQL：

1. 修改配置文件 src/main/resources/application.yml：

spring:
  profiles:
    active: mysql  # 或 postgres

2. 配置数据库连接 src/main/resources/application-mysql.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/jmanus
    username: your_username
    password: your_password
  jpa:
    database-platform: org.hibernate.dialect.MySQLDialect

API 密钥配置

1. 启动后配置：访问 http://localhost:18080 按向导配置 2. 手动配置：修改配置文件或设置环境变量

📊 验证启动

1. 检查服务状态

# 检查端口是否监听
netstat -an | grep 18080

# 或者使用 curl
curl http://localhost:18080/api/init/status

2. 访问应用

• Web 界面：http://localhost:18080
• API 文档：http://localhost:18080/swagger-ui.html
• 健康检查：http://localhost:18080/actuator/health

3. 测试 API

# 测试初始化状态
curl http://localhost:18080/api/init/status

# 测试基本功能
curl -X POST http://localhost:18080/api/executor/executeByToolNameSync/test \
  -H "Content-Type: application/json" \
  -d '{"toolName":"test"}'

🐛 常见问题解决

问题 1：端口被占用

# 查找占用 18080 端口的进程
lsof -i :18080
# 或
netstat -ano | findstr 18080

# 终止进程（Linux/macOS）
kill -9 <PID>

# 或修改端口
java -jar jmanus.jar --server.port=8080

问题 2：内存不足

# 增加 JVM 内存
java -Xmx4g -Xms2g -jar jmanus.jar

# 或者设置环境变量
export JAVA_OPTS="-Xmx4g -Xms2g"
java -jar jmanus.jar

问题 3：前端构建失败

# 清除缓存重新安装
cd ui-vue3
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 检查 Node.js 版本
node --version  # 需要 18+

问题 4：Maven 构建失败

# 清除 Maven 缓存
./mvnw clean

# 强制更新依赖
./mvnw dependency:purge-local-repository

# 跳过测试构建
./mvnw package -DskipTests -Dmaven.test.skip=true

🚀 生产环境部署

Docker 部署

# 构建 Docker 镜像
docker build -t jmanus:latest .

# 运行容器
docker run -d \
  --name jmanus \
  -p 18080:18080 \
  -e JAVA_OPTS="-Xmx2g -Xms1g" \
  jmanus:latest

系统服务（Linux）

# 创建 systemd 服务文件
sudo nano /etc/systemd/system/jmanus.service

# 添加以下内容
[Unit]
Description=JManus AI System
After=network.target

[Service]
Type=simple
User=jmanus
WorkingDirectory=/opt/jmanus
ExecStart=/usr/bin/java -jar jmanus.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# 启动服务
sudo systemctl enable jmanus
sudo systemctl start jmanus
sudo systemctl status jmanus

📋 开发环境设置

IDE 配置

• 导入为 Maven 项目
• 配置 Java 17 SDK
• 启用 Spring Boot 支持

• 安装 Java Extension Pack
• 安装 Spring Boot Extension Pack
• 配置调试环境

调试模式

# 启用调试模式
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar jmanus.jar

# 前端开发模式（热重载）
cd ui-vue3
pnpm run dev

🔧 常用命令速查

后端命令

# 编译
./mvnw clean package

# 运行测试
./mvnw test

# 代码格式化
./mvnw spotless:apply

# 启动应用
./mvnw spring-boot:run

前端命令

# 安装依赖
pnpm install

# 开发模式
pnpm run dev

# 构建生产版本
pnpm run build

# 运行测试
pnpm run test:unit

# 代码检查
pnpm run lint

Makefile 命令

# 查看所有可用命令
make help

# 编译项目
make build

# 运行测试
make test

# 构建 UI
make ui-build

# 运行 UI 开发服务器
make ui-run

# 完整构建（后端+前端）
make build && make ui-build

📚 下一步

启动成功后，您可以：

1. 访问 Web 界面：http://localhost:18080 2. 配置 API 密钥：按照向导配置您的 AI 模型 API 密钥 3. 查看文档：访问 API 文档了解可用接口 4. 运行示例：尝试内置的示例任务 5. 自定义配置：根据需求调整系统配置