快速开始

本文档帮助你在本地快速运行 Molan Cloud 单体模式，开始开发。

面向对象

本文档面向本地开发，不是生产部署。建议使用 IntelliJ IDEA。

环境准备

软件	版本要求	说明
JDK	21+	后端运行环境
Maven	3.9+	后端构建工具
IntelliJ IDEA	2023+	开发 IDE（社区版即可）
Docker Desktop	Latest	推荐：一键启动中间件

推荐使用 Docker

项目在 deploy/docker/ 下准备了各中间件的 docker-compose，一条命令即可启动。 如果不用 Docker，需手动安装数据库和 Redis。

验证环境：

java -version          # 21+
mvn -version           # 3.9+
docker -v              # Docker 20+
docker compose version # Compose V2

第一步：获取代码

git clone https://gitee.com/pangui0/molan-cloud.git

用 IDEA 打开 backend/ 目录，等待 Maven 依赖下载和索引建立完成（首次约 5-10 分钟）。

第二步：启动中间件

方式一：Docker 启动（推荐）

项目支持 PostgreSQL 和 MySQL 两种数据库，按需选择：

MySQL + Milvus + Elasticsearch（推荐）

项目在 backend/deploy/docker/ 下准备了各中间件的 docker-compose，按需启动：

# 最小必需：MySQL + Redis
cd backend/deploy/docker/mysql && docker compose up -d && cd ../../
cd backend/deploy/docker/redis && docker compose up -d && cd ../../

还有 Nacos、MinIO、Elasticsearch、Milvus、RabbitMQ 等，用到时再启动。

PostgreSQL + pgvector（最小配置）

# 启动 PostgreSQL（内置 pgvector，兼具向量库功能）
cd backend/deploy/docker/postgres && docker compose up -d && cd ../../

# 启动 Redis
cd backend/deploy/docker/redis && docker compose up -d && cd ../../

默认密码

• MySQL root: 123456
• PostgreSQL: postgres / postgres
• Redis: 123456
• MinIO: molandev / molandev

方式二：手动安装

点击展开

需要安装：

• MySQL 8.0+ 或 PostgreSQL 14+
• Redis 6.0+

验证：

# MySQL
mysql -u root -p

# PostgreSQL
psql -U postgres

# Redis
redis-cli -a 123456 ping  # 应返回 PONG

第三步：初始化数据库

项目使用多数据源，需创建 3 个数据库：

MySQL

# 创建数据库
mysql -u root -p123456 < backend/deploy/sql/mysql/01_schema.sql

# 导入表结构
mysql -u root -p123456 molandev_base < backend/deploy/sql/mysql/02_molandev_base.sql
mysql -u root -p123456 molandev_kl < backend/deploy/sql/mysql/03_molandev_kl.sql
mysql -u root -p123456 molandev_xiuxian < backend/deploy/sql/mysql/04_molandev_xiuxian.sql
mysql -u root -p123456 nacos < backend/deploy/sql/mysql/05_molandev_nacos.sql

PostgreSQL

# 创建数据库
psql -U postgres -f backend/deploy/sql/postgres/01_schema.sql

# 导入表结构
psql -U postgres -d molandev_base -f backend/deploy/sql/postgres/02_molandev_base.sql
psql -U postgres -d molandev_kl -f backend/deploy/sql/postgres/03_molandev_kl.sql
psql -U postgres -d molandev_xiuxian -f backend/deploy/sql/postgres/04_molandev_xiuxian.sql

数据库	用途
molandev_base	RBAC 权限、文件、消息、任务
molandev_kl	RAG 知识库
molandev_xiuxian	AI Agent 示例
nacos	Nacos 配置中心数据（含 molandev_cloud 命名空间）

第四步：配置并运行

4.1 选择数据库 Profile

项目通过 Spring Profile 切换数据库和向量存储组合：

Profile	数据库	向量存储	全文检索	需要启动的中间件
mysql	MySQL	Milvus	Elasticsearch	MySQL + Redis + Milvus + ES
pg	PostgreSQL	pgvector	Lucene（内置）	PostgreSQL + Redis

默认激活 mysql profile。如需 PostgreSQL，修改 application.yml：

spring:
  profiles:
    active: pg   # 改为 pg

4.2 核心配置

配置文件位于 backend/molandev-standalone-service/src/main/resources/application.yml，按需修改：

数据库连接（在 application-mysql.yml 或 application-pg.yml 中）：

molandev:
  datasource:
    sys:
      url: jdbc:mysql://localhost:3306/molandev_base?...
      username: root
      password: 123456    # 修改为你的密码

Redis 连接（在 application.yml 中）：

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: 123456    # 修改为你的密码

文件存储（在 application.yml 中）：

molandev:
  file:
    type: local
    local:
      base-path: /home/app/files/   # 修改为你的路径

AI API Key（用于知识库向量化和 AI 对话）：

spring:
  ai:
    openai:
      api-key: ${DASHSCOPE_API_KEY:123456}

可通过环境变量注入：export DASHSCOPE_API_KEY=sk-xxx

4.3 启动

IDEA 启动（推荐）

1. 打开 backend/molandev-standalone-service/src/main/java/com/molandev/standalone/StandaloneApp.java
2. 点击 main 方法旁的绿色三角 ▶️ 运行

Maven 命令启动

# MySQL 模式（默认）
mvn spring-boot:run -pl molandev-standalone-service -f backend/pom.xml

# PostgreSQL 模式
mvn spring-boot:run -pl molandev-standalone-service -f backend/pom.xml \
  -Dspring-boot.run.arguments="--spring.profiles.active=pg"

4.4 验证

启动成功后看到：

Started StandaloneApp in x.xxx seconds

• 后端地址：http://localhost:9099
• 接口文档：http://localhost:9099/doc.html

访问 doc.html 能看到 Knife4j 接口文档页面，说明运行正常。

第五步：启动前端

前端代码位于 frontend/ 目录。

启动后端后，前端通过 Vite 代理将 /api 请求转发到 http://localhost:9099。

常见问题

数据库连接失败

Communications link failure

1. 检查数据库是否启动
2. 检查用户名密码是否与配置一致
3. 检查数据库是否已创建：SHOW DATABASES;

Redis 连接失败

Unable to connect to Redis

1. 检查 Redis 是否启动：redis-cli -a 123456 ping
2. 检查密码配置是否正确

端口占用

Port 9099 was already in use

# 查找占用进程
lsof -i :9099        # macOS/Linux
netstat -ano | findstr :9099  # Windows

Milvus / Elasticsearch 连接失败

如果使用 mysql profile，需要 Milvus 和 Elasticsearch 也在运行。如果不想启动它们，改用 pg profile，向量存储用 pgvector，全文检索用内置 Lucene，只需 PostgreSQL + Redis。

下一步

• 架构概览 - 理解系统设计
• 项目结构 - 熟悉代码结构
• 知识库 - RAG 检索增强生成
• AI 集成 - AI Agent 示例