快速开始

本篇带你 5 分钟把前后端跑起来并登录系统。

端口说明（重要）

旧文档里写的「后端 8080 / 前端 5173」是过时的。实际端口以 application.yml 与 vite.config.ts 为准：

后端：52856（application.yml 中 server.port: 52856）
前端：3000（vite.config.ts 中 server.port: 3000）

环境要求

依赖	版本	说明
JDK	17	项目编译目标为 17；JDK 21 + Maven 命令行编译可能触发 Lombok TypeTag 问题，建议用 17
Maven	3.8+	后端构建
Node.js	18+	前端构建（推荐 22）
包管理器	pnpm 8+ / npm 9+	前端依赖
MySQL	8.0+	生产 / 类生产环境；快速体验可用内置 H2 免安装
Redis	6+	可选；用于缓存、接口防抖、限流（缺失时部分功能降级）

方式一：H2 内存库（最快，无需装 MySQL）

H2 profile 会在启动时自动执行 schema-h2.sql + data-h2.sql，开箱即用，适合快速体验与调试。

后端

cd backend

# 编译（跳过测试）
mvn clean install -DskipTests

# 以 H2 profile 启动
mvn spring-boot:run -Dspring-boot.run.profiles=h2

启动后访问 http://localhost:52856，H2 控制台在 http://localhost:52856/h2-console。

前端

cd frontend

# 安装依赖（pnpm 较快）
pnpm install
# 或 npm install

# 启动开发服务
pnpm dev
# 或 npm run dev

启动后访问 http://localhost:3000。

H2 数据会丢

H2 是内存库，重启后数据丢失。需要持久化请用方式二的 MySQL。

方式二：MySQL（生产 / 类生产）

默认 profile 即 mysql。

# 1. 建库
mysql -u root -p

CREATE DATABASE lowcode CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 2. 导入表结构与基础数据
#    schema-h2.sql 是最完整的建表脚本（53 张表），MySQL 下也可参考执行
#    生产推荐组合：docs/SQL_INIT.sql + docs/SQL_EXTENSION.sql + sql/mysql/*.sql
mysql -u root -p lowcode < docs/SQL_INIT.sql
mysql -u root -p lowcode < docs/SQL_EXTENSION.sql
mysql -u root -p lowcode < sql/mysql/bpm.sql
mysql -u root -p lowcode < sql/mysql/hr_employee.sql

修改 backend/src/main/resources/application-mysql.yml 中的数据源地址与密码（默认 root / Admin123.，库 lowcode）：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/lowcode?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: Admin123.

# 3. 启动后端（默认 mysql profile）
cd backend
mvn clean install -DskipTests
mvn spring-boot:run

# 4. 启动前端
cd ../frontend
pnpm install
pnpm dev

注意 schema-mysql.sql 不完整

schema-mysql.sql 仅 16 张表，远落后于 schema-h2.sql（53 张）。MySQL 初始化请用上面列出的 SQL_INIT.sql + SQL_EXTENSION.sql 组合，不要只跑 schema-mysql.sql。详见。

登录系统

前端打开 http://localhost:3000，使用默认账号 admin 登录。密码随启动 profile 不同：

Profile	默认密码	来源
`h2`（开发内存库）	`123456`	`data-h2.sql` 种子
`mysql`（首次启动）	`admin123`	`DataInitializer`（可用 `-Dapp.admin.password` 覆盖）
新建租户	`123456`	平台登录页底部也写明「新租户默认密码：123456」

别用错密码

本篇「方式一 H2」用 123456 登录；「方式二 MySQL」首次用 admin123。用错会提示账号或密码错误。

登录后可选择租户，进入工作台。

前后端联调原理

前端开发服务（Vite）通过代理把 /api 请求转发到后端：

// frontend/vite.config.ts
server: {
  host: '0.0.0.0',
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://127.0.0.1:52856',  // 指向后端
      changeOrigin: true,
      // 注意：没有 rewrite，所以 /api 前缀会原样透传给后端
    }
  }
}

后端控制器统一以 /api/xxx 为前缀（如 @RequestMapping("/api/auth")），与前端 baseURL: '/api' 对齐。前端请求路径里不要再写 /api，否则会变成 /api/api/xxx 导致 404。详见。

常见问题

后端启动报 Lombok / TypeTag 相关错误

在 JDK 21 + Maven 命令行环境下，Lombok 注解处理可能失败。解决方案：使用 JDK 17；或在 IntelliJ IDEA 中编译；或用 javac --add-opens 打开相关模块。

前端启动报依赖 / 版本错误

项目使用 pnpm-workspace.yaml，建议统一用 pnpm。若已用 npm 装过，删除 node_modules 与锁文件后用 pnpm 重装。

接口 404 / 双重 /api 前缀

确认前端 api 模块的请求路径没有额外加 /api。历史上有多个 BPM 接口因此踩坑。

下一步：阅读了解代码组织。