ICEJZ
获取项目

Documentation

使用指南

按子项目给出独立启动教程。当前版本 1.0.6。 本地联调时请记住：后端 + 前端都要启动；后端有多套实现，同一时间只启动一套。

还没有源码？请先到 获取项目 克隆完整仓库或单独拉取子项目，再按本文启动。

概述

ICEJZ 是带国密安全、RBAC 与多端客户端的低代码底座，以 monorepo 组织。 后端提供 Java / PHP 单体与可选微服务；前端有管理端与多端 App。各子项目可单独启动，但业务联调需要「一个后端 + 至少一个前端」同时运行。

目录 角色 类型
icejz-boot Java 单体后端（原版，推荐） 后端 · 三选一
icejz-php PHP 单体后端（接口对齐 boot） 后端 · 三选一
icejz-cloud 微服务后端（可选进阶） 后端 · 三选一
icejz-admin Vue3 管理后台 前端
icejz-app-uniapp-vue3 UniApp 移动端 前端
icejz-android 原生 Android 前端
icejz-flutter Flutter 客户端 前端

联调必读：前后端都要启动

最常见的踩坑

只启动管理端 / App，而没有启动任何后端，登录、验证码、菜单都会失败。 反过来，只启动后端、不打开前端，也无法完成界面联调。

后端（必选 1 个）

API 服务

从 icejz-boot、icejz-php、icejz-cloud 中只选一套启动。 日常联调优先 boot 或 php，默认端口 8080。

前端（至少 1 个）

界面客户端

再启动 icejz-admin 和/或移动端。前端通过 API 地址访问后端，两边要同时保持运行。

  • 必须：MySQL + Redis 已启动
  • 必须：后端三选一，已在 8080（或你配置的端口）监听
  • 必须：至少一个前端已启动，并指向该后端
  • 不要：同时启动 boot 与 php（端口冲突）

公共依赖

开始前请确认本机已安装下列依赖。数据库与 Redis 建议先于后端启动。

依赖 用途 默认
JDK 17+icejz-boot / cloud—
Maven 3.8+Java 构建—
MySQL 8业务库icejz_boot / root / 123456
RedisToken / 验证码6379 · DB 1
Node.js 18+admin / UniApp—
PHP 8.2+ · Composericejz-phpD:\php
Android Studio / Flutter原生客户端—

PHP 需开启扩展：pdo_mysql、openssl、mbstring、gmp、gd、curl。

数据库初始化

所有后端（boot / php / cloud）共用同一套业务库。首次只需导入一次。

  1. 创建库，建议名称 icejz_boot
  2. 导入 icejz-boot/db/mysql/icejz.sql（一份全量库即可）
  3. 确认 Redis 可连接，开发环境常用 DB 1

演示账号：超级管理员 admin / 123456。 用户表中所有演示用户的密码均为 123456（含 chenkai、linyue 等），仅用于本地开发，上线前请修改。

若全量 SQL 尚未包含较新能力，可按需执行增量脚本，例如 upgrade_menu_client_type.sql、upgrade_sys_chat.sql、upgrade_sys_chat_acl.sql （见 icejz-boot/db/mysql/）。

推荐联调顺序

  1. 启动 MySQL + Redis
  2. 启动一个后端（boot / php / cloud）→ http://localhost:8080
  3. 启动管理端 icejz-admin（前后端同时保持运行）
  4. 按需再启动 UniApp / Android / Flutter

boot 与 php 默认都监听 8080，同时只能运行一个。切换后端前请先停掉另一个进程。

后端怎么选（启动一个即可）

仓库里有三套后端实现，接口面向同一套前端。本地开发只需启动其中一套，不要同时开多套占用同一端口。

推荐

icejz-boot

Java Spring Boot 单体，能力最全，默认联调首选。

 备选

icejz-php

PHP 复刻实现，接口对齐 boot，适合 PHP 技术栈。

 可选

icejz-cloud

微服务形态，需注册中心 / 网关，日常联调一般不用。

选定后端后，再启动前端。管理端默认请求 http://localhost:8080；移动端同理。

后端 · 三选一

icejz-boot 启动教程

原版 Java 单体服务，能力最完整，适合作为默认联调后端。

启动前准备

  • 已安装 JDK 17+、Maven 3.8+
  • MySQL、Redis 已启动，库已导入
  • 确认 8080 端口空闲（未运行 icejz-php）

启动方式

方式 A · Maven 命令行：

cd icejz-boot
mvn -pl icejz-server -am spring-boot:run

方式 B · IDE：打开工程后直接运行 icejz-server 主类。

开发配置：icejz-server/src/main/resources/application-dev.yml

启动后自检

后端起来后，请继续启动 icejz-admin 或移动端，前后端同时运行才能登录联调。

后端 · 三选一

icejz-php 启动教程

对 icejz-boot 的接口复刻实现，复用同一套 MySQL / Redis，适合 PHP 技术栈团队。

启动前准备

  • PHP ≥ 8.2 + Composer 2，扩展齐全
  • MySQL、Redis 已启动，库已导入
  • 若本机已有 Java boot 占用 8080，请先停掉

首次安装

cd icejz-php
copy .env.example .env
composer install

按需编辑 .env（库名、账号、Redis 等）。

启动

方式 A · 内置服务器：

cd icejz-php
php -S 0.0.0.0:8080 -t public public/index.php

方式 B · Windows 脚本：icejz-php\bin\serve.bat（默认指向 D:\php\php.exe）。

自检

  • 欢迎页
  • GET /sys/app/version
  • GET /sys/auth/public-key
  • php bin/smoke_login.php（需服务已启动）

PHP 后端就绪后，同样需要启动前端（如 icejz-admin），不要只开后端。

后端 · 三选一

icejz-cloud 启动教程（可选）

与单体 boot 对应的云版本，通常需要注册中心、网关等额外组件。 日常前端联调请优先使用 boot 或 php 单体；只有验证微服务拆分时再启动 cloud。

建议步骤

  1. 阅读 icejz-cloud 各模块 README 与 deploy 配置
  2. 先拉起注册中心 / 网关等基础设施
  3. 按模块顺序启动业务服务，确认网关入口可访问
  4. 把前端 API 地址改到网关地址后再开管理端 / App

不要与 boot / php 同时抢占同一 API 端口；cloud 更重，不适合作为第一次本地联调入口。

前端

icejz-admin 启动教程

Vue3 管理后台，承载用户、角色、菜单、机构、字典、日志、即时通讯与系统配置等能力。

依赖后端

启动 admin 前，请先让 icejz-boot 或 icejz-php 在 8080 运行。 只开前端无法登录。

启动步骤

cd icejz-admin
npm install
npm run dev

开发配置 .env.development 中设置 VITE_API_URL=http://localhost:8080。 浏览器按终端提示访问（常见端口 5173）。

验证

  1. 浏览器打开管理端地址，能看到登录页
  2. 使用 admin / 123456 登录
  3. 若验证码或登录失败，先检查后端 8080 与 Redis

前端

icejz-app-uniapp-vue3 启动教程

UniApp Vue3 移动端，支持 H5 与微信小程序。接口契约与管理端共用同一后端。

依赖后端

请先启动 boot 或 php（8080），再启动本项目；前后端需同时运行。

H5

cd icejz-app-uniapp-vue3
npm install
npm run dev:h5

微信小程序

npm run dev:mp-weixin

再用微信开发者工具打开输出目录，确认 API 指向本机后端。

前端

icejz-android 启动教程

原生 Android（Compose）客户端。同样依赖已启动的后端 API。

  1. 用 Android Studio 打开 icejz-android
  2. 同步 Gradle 后 Run
  3. 确认后端已在电脑 8080 运行
  4. 模拟器 API 使用 http://10.0.2.2:8080
  5. 真机请将 BASE_URL 改为电脑局域网 IP

前端

icejz-flutter 启动教程

Flutter 客户端。启动前同样需要后端已就绪。

cd icejz-flutter
flutter pub get
flutter run

真机示例：

flutter run --dart-define=BASE_URL=http://192.168.1.8:8080

模拟器默认可使用 http://10.0.2.2:8080，不要用 127.0.0.1。

端口一览

服务 端口 说明
icejz-boot / icejz-php8080API（同一时间只开一个）
MySQL3306业务库
Redis6379缓存 / Token
icejz-admin5173管理端 Vite
UniApp H5Vite移动端 H5

常见问题

为什么登录一直失败？

先确认后端是否在跑：浏览器访问 http://localhost:8080/。 再确认前端 API 地址指向该后端，且 Redis 可用。前后端缺一不可。

8080 被占用

多半是 boot 与 php 同时开了。关掉其中一个，或改端口后同步前端 VITE_API_URL / 客户端 BASE_URL。

验证码 / 密码解密失败

确认 Redis 可用；PHP 开启 gmp；检查 /sys/auth/public-key 是否正常返回。

模拟器访问不到后端

Android / Flutter 模拟器请使用 10.0.2.2:8080，不要用 127.0.0.1。

PHP 命令找不到

确认已安装并加入 PATH（示例目录 D:\php），新开终端执行 php -v / composer -V。

管理端能开但登录失败

先确认后端 8080 可访问；核对 admin 的 API 地址；看浏览器网络面板中的 captcha / login 响应。

更完整说明见仓库根目录 START.md，各子项目细节见对应 README.md。 返回首页