快速开始、环境搭建、修改包名、新建模块、正式部署

# 开发环境要求

Spring Boot 3 版本请下载 JDK 17、21 下载1 (opens new window) 下载2 (opens new window) 下载3 (opens new window) (推荐JDK17)
Spring Boot 2 版本请下载 JDK 1.8、11、17 下载1 (opens new window) 下载2 (opens new window) 下载3 (opens new window) (推荐JDK11)
Apache Maven 3.6+ 以上版本下载 (opens new window)（请删除 settings.xml 里的 mirror 配置）
IntelliJ IDEA 下载 (opens new window) 或 Spring Tools 下载 (opens new window) 或 Eclipse for Java EE 下载 (opens new window)（根据个人喜好选择）
MySql 8.x 下载 (opens new window) 或 5.7.11+ 以上版本下载 (opens new window) 或 Oracle、PostgreSQL、Sql Server
Git 下载 (opens new window)，可选下载：TortoiseGit (opens new window) 或其它 (opens new window)、DBeaver Community (opens new window)
提示：一般 IDE 中会自带部分工具，如果已经具备，可免下载（^_^）。

# 导入到 IDE 工具

1、获取 JeeSite 源代码：

git clone https://gitee.com/thinkgem/jeesite5.git jeesite
cd jeesite
# 注意：不要放到中文或带空格的目录下。

1
2
3

2、IDEA：菜单中点击 File -> Open，然后选择刚下载的 jeesite 文件夹，点击 Open as Project 按钮。

3、Eclipse：菜单中点击 File -> Import，然后选择 Maven -> Existing Maven Projects，点击 Next> 按钮，选择刚下载的 jeesite 文件夹，点击 Finish 按钮。

4、此时 IDEA 或 Eclipse 会根据 JeeSite 工程配置，自动下载 Maven 依赖并编译项目。初次加载可能会较慢（根据自身网络情况而定）若工程上有小叉号，请打开 Problems 窗口，查看具体错误内容，直到无错误为止。

提示

如果在编译过程中遇见问题，请在 “常见问题” 中找找，看看有没有和您相同的问题

5、下载依赖和编译过程中，您可先进行下一步，准备数据库环境

# 初始化数据库

JeeSite 采用自动数据库初始化程序，根据用户创建的数据库账号自动完成表结构和初始数据。无需自行执行 SQL 文件进行初始化，此举为了更方便的导入不同类型的数据库，如 MySQL、Oracle、SqlServer、PostgreSQL 等，不用维护多种类型数据库的 SQL 初始数据的语句。减少出错率，也提供了更方便的，按需导入 JeeSite 扩展模块的数据表和基础数据功能。

1、创建用户和授权（以 MySql 为例）

set global read_only=0;
set global optimizer_switch='derived_merge=off';
create user 'jeesite'@'%' identified by 'jeesite';
create database jeesite DEFAULT CHARSET 'utf8mb4' COLLATE 'utf8mb4_unicode_ci';
-- MySql 5.x
-- grant all privileges on jeesite.* to 'jeesite'@'%' identified by 'jeesite';
-- MySql 8.x
grant all privileges on jeesite.* to 'jeesite'@'%';
flush privileges;

1
2
3
4
5
6
7
8
9

官方也提供了 MySql 的初始化库，直接导入即可，省去执行 init-data.bat(sh)，点击下载 (opens new window)（社区版用）

2、打开 /web(-api)/src/main/resources/config/application.yml（v4.0：jeesite.yml）文件

`/web(-api)` 代表 `/web`、`/web-api` 或 `/web-pro`、`/web-pro-api`

全栈经典版，前端技术栈：Bootstrap + Beetl，选用 /web 或 /web-pro
Vue 分离版，前端技术栈：TS + Vue3 + Vite，选用 /web-api 或 /web-pro-api

配置您的产品名称、公司名称、产品版本和 JDBC 连接，例如：

## 您的产品或项目名称、软件开发公司名称
productName: 某某信息化管理系统
companyName: 某某信息技术有限公司

## 您的产品或项目迭代版本、版权年份
productVersion: V5.11
copyrightYear: 2025

## 数据库连接
jdbc: 

  # MySql 数据库配置（提示：MySql 8.x 驱动类的配置方法，默认在 v4.2 及之后版本 ）
  type: mysql
  driver: com.mysql.cj.jdbc.Driver
  # 如果需要提供公钥进行身份验证，MySql 8.2 可添加选项：&allowPublicKeyRetrieval=true
  url: jdbc:mysql://127.0.0.1:3306/jeesite?useSSL=false&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=CONVERT_TO_NULL&serverTimezone=Asia/Shanghai
  username: root
  password: 123456
  testSql: SELECT 1

  ## MySql 数据库配置（提示：MySql 5.x 驱动类的配置方法，默认在 v4.1 及之前版本 ）
  type: mysql
  driver: com.mysql.jdbc.Driver
  url: jdbc:mysql://127.0.0.1:3306/jeesite?useSSL=false&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
  username: jeesite
  password: jeesite
  testSql: SELECT 1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

3、若刚才导入到的 IDEA 或 Eclipse 的项目，Maven 依赖已经完成编译并无错误，这时您就可以执行 /bin/init-data.bat(sh) 脚本初始化数据库了，按提示操作。

（注意：v4.2.x 之后版本的初始化数据不会清空数据，如果已经初始化，将会自动忽略。如果执行过程不小心中断了，请手动删除 jeesite 库中已经创建的 table，再次执行 init-data 脚本）

4、如果因您的环境原因 /bin/init-data.bat(sh) 脚本无法运行，您可以在 IDEA 或 Eclipse 里找到 com.jeesite.test.InitData.java 文件并打开。

1）IDEA 在 java 文件空白处右键，点击 Run 'InitData' 运行单元测试，进行初始化数据库脚本。

2）Eclipse 在 java 文件空白处右键，点击 Run As -> JUnit Test 运行单元测试，进行初始化数据库脚本。

（注意：v4.1.8 之前版本找 com.jeesite.test.InitCoreData.java 文件；v4.2.0 之前版本可能会提示您：为了防止误操作，您还需要：打开 Run Configurations 找到 Arguments 选项卡，在 VM arguments 里增加 “-Djeesite.initdata=true” 参数，点击Run运行，执行完成后建议将该单元测试 Run Configuration 删除掉，防止误操作，不小心再把您的有用数据清理掉）

提示

如果在初始化数据库遇见问题，请在 “常见问题” 中找找，看看有没有和您相同的问题

# 配置服务端口

1、当前是 Spring Boot 工程，内部已经集成 Web 容器，您无需另外再下载 Tomcat 进行部署，只需按照以下方式进行即可。

2、打开 /web(-api)/src/main/resources/config/application.yml 文件，

配置您的服务端口 port、部署路径 context-path 例如:

server:
  port: 8980
  servlet:
    context-path: /js
  tomcat:
    uri-encoding: UTF-8

# 提示：v4.0.x 及之前版本，配置方法：
server:
  port: 8980
  context-path: /js
  tomcat:
    uri-encoding: UTF-8

1
2
3
4
5
6
7
8
9
10
11
12
13

# 启动 Web 服务

注意：JeeSite 一套后端代码同时支持两种前端技术栈下面，根据您的需求进行选择启动方式

# Vue 分离版

前端技术栈：TS + Vue3 + Vite。

1、IDEA：右上角运行调试配置下拉框，选择 ApiApplication 运行配置，点击 Debug 图标，启动服务。

2、Eclipse：打开 ApiApplication.java 启动文件，在空白处右键，点击 Debug As -> Java Application 即可启动服务。

3、分离前端需要单独部署 Vue 项目，部署方法详见：https://jeesite.com/docs/vue-install-deploy/

# 经典版

前端技术栈：Bootstrap + Beetl。

1、IDEA：右上角运行调试配置下拉框，选择 Application 运行配置，点击 Debug 图标，启动服务。

2、Eclipse：打开 Application.java 启动文件，在空白处右键，点击 Debug As -> Java Application 即可启动服务。

# 专业版用户

1、若想分离版，请先打开 application.yml 设置 apiMode 为 true，否则请忽略本步。

2、IDEA：右上角运行调试配置下拉框，选择 ProApplication 运行配置，点击 Debug 图标，启动服务。

3、Eclipse：打开 ProApplication.java 启动文件，在空白处右键，点击 Debug As -> Java Application 即可启动服务。

# 部署完成后访问

1、浏览器访问：http://127.0.0.1:8980/js (opens new window) 分离版：http://127.0.0.1:3100 (opens new window)

2、默认最高管理员账号：system 密码：admin

3、恭喜您已经部署完成，开启您的开发之旅吧

提示

如果启动的时候提示 NoClassDefFoundError: javax/servlet/ServletOutputStream 错误，请修改 web 项目下的 pom.xml，注释掉 spring-boot-starter-tomcat 的 <scope>provided</scope> 即可
使用 Debug 运行，有助于您调试程序和提升开发效率，如：修改方法内的代码，修改视图代码，修改 mapper 代码，是不需要重启 Web 服务的。如果改变 java类的结构，如果增删属性、方法、参数等，新增文件，这时才需要重启服务。

# 减少 IDE 语法错误提示

配置 Beetl 第二个占位符和定界符，让 html 和 js 语法编写不同的占位符（5.5.0+默认配置）

这样就可以不用配置 IDE 的 HTML 语法验证，IDE 也不会报红。

beetl-core.properties

DELIMITER_PLACEHOLDER_START2="#{
DELIMITER_PLACEHOLDER_END2=}"
DELIMITER_STATEMENT_START2=//#
DELIMITER_STATEMENT_END2=

1
2
3
4

正则表达式全局查找替换：

查找：\$\{@DictUtils\.getDictListJson\(\'(.+?)\'\)\}
替换："#\{@DictUtils\.getDictListJson\(\'$1\'\)\}"

1
2

查找：\$\{toJson\((.+?)\)\}
替换："#\{toJson\($1\)\}"

1
2

查找：\/\/\<\% (.+?) \%\>
替换：//# $1

1
2

旧版 Eclipse 推荐设置参数

5.4.2 之前版本，打开项目您可能会发现 html 文件多处报错，是因为 Beetl 语法和 JS 语法混用的时候语法错误误报问题。

设置如下，可关闭 IDE HTML 语法检查，菜单：Window -> Preferences ->

Validation -> JSON Validator -> 去掉对勾
Validation -> JavaScript Validator -> 去掉对勾
Validation -> HTML Syntax Validator -> 去掉对勾
Web -> HTML Files - Unknown tag name -> Ignore
Web -> HTML Files - Start-tag uses invalid case -> Ignore
Web -> HTML Files - Undefined attribute name -> Ignore
Web -> HTML Files - Invalid characters used in text string -> Ignore

哇，界面瞬间干净了。

# 清理 Demo 数据

为了演示方法，初始化数据库后会载入一些演示数据，执行以下脚本即可清理

DELETE FROM js_sys_post;
DELETE FROM js_sys_office;
DELETE FROM js_sys_company;
DELETE FROM js_sys_employee;
DELETE FROM js_sys_employee_post;
DELETE FROM js_sys_role WHERE role_code NOT IN ('corpAdmin','default');
DELETE FROM js_sys_role_data_scope;
DELETE FROM js_sys_user WHERE user_code NOT IN ('system','admin');
DELETE FROM js_sys_user_data_scope;
DELETE FROM js_sys_user_role;
DELETE FROM js_sys_log;

1
2
3
4
5
6
7
8
9
10
11

# 新建一个模块工程

1、进入菜单：系统管理 -> 系统设置 -> 模块管理，新建一个模块，填写：

模块名称：测试模块
模块编码：test
生成基础路径：填写新建模块的根目录
代码生成模板：生成模块代码

点击 “保存并生成代码” 按钮，即可完成业务模块的工程代码新建（自动化生成模块工程源码）

2、打开 /modules/pom.xml 文件，拷贝 <module>core</module> 到新一行，修改为您的模块名，如：<module>test</module>

v5.3.1 之前版本打开 /root/pom.xml 文件，拷贝 <module>../modules/core</module> 到新一行，修改为您的模块名，如：<module>../modules/test</module>

3、在您需要用到的项目引入您的新模块，如，在 web 项目下用，则打开 /web/pom.xml 文件，加入：

<dependency>
	<groupId>com.jeesite</groupId>
	<artifactId>jeesite-module-test</artifactId>
	<version>${project.parent.version}</version>
</dependency>

1
2
3
4
5

4、若您使用的 Eclipse ，将该模块导入即可。若 IDEA 点击 Maven Update，则会自动检测 root 模块的依赖，并自动导入。

5、模块创建完成。

提示

模块下新增代码后，请返回模块管理菜单，编辑模块的 “主类全名”，如下：

主类全名：com.jeesite.modules.test.TestController

解释：类名为该模块的状态验证类，如果该类检测不存在，则该模块状态提示 “未安装”

验证原理：Class.forName("com.jeesite.modules.sys.web.LoginController")

v4.2.2之前版本创建模块方法：

1、举例创建 jeesite-module-test 模块功能，拷贝模块目录下的 /modules/template 模板项目文件夹

2、然后在相同文件夹 /modules/ 下粘贴，并重命名为您的模块名，如：/modules/test

3、打开 /modules/test/pom.xml 文件，找到 jeesite-module-template 的 artifactId 元素，修改为您的模块名，如：jeesite-module-test

4、打开 /root/pom.xml 文件，拷贝 <module>../modules/core</module> 到新一行，修改为您的模块名，如：<module>../modules/test</module>

5、在您需要用到的项目引入您的新模块，如，在 web 项目下用，则打开 /web/pom.xml 文件，加入：

<dependency>
	<groupId>com.jeesite</groupId>
	<artifactId>jeesite-module-test</artifactId>
	<version>${project.parent.version}</version>
</dependency>

1
2
3
4
5

6、若您使用的 Eclipse ，将该模块导入即可。若 IDEA 会自动检测 root 模块的依赖，并自动导入。

7、启动项目，打开 “系统管理 -> 系统设置 -> 模块管理” 菜单，新建一个模块，数据如下：

模块名称：测试模块
模块编码：test

点击 “保存” 按钮。

8、模块创建完成。

# 数据库脚本自动升级

非常好的功能，当升级模块代码时，同时自动更新对应模块的数据库升级 SQL 脚本，无需运维人员手动去执行脚本。

1、每个主要模块下都有一个 versions 文件，该文件为数据库版本检测的关键文件

2、例如 core 模块的版本检测文件为：/modules/core/src/main/resources/db/upgrade/core/versions

3、系统启动时，遍历模块表里的所有模块，检测 versions 文件的版本列表，与其当前模块版本进行对应

4、找到对应版本，则依次往下进行匹配执行升级。若匹配的版本没有 sql 脚本，则忽略，只更新模块版本

5、若 versions 文件的版本列表中没有匹配的版本，则提示：升级失败，数据库的版本可能比代码版本新

6、自己的模块实现，可参考官方 CMS 模块的 InitCmsData 相关代码（含初始化表、菜单、字典等基础数据）

# 使用自己的包路径

自己新建的业务模块，可以自定义为自己公司的包名，如：com.mycompany.modules.xxx

1、Application.java 的 @SpringBootApplication(scanBasePackages="包路径") 增加您的包路径

2、application.yml 中找到 mybatis: scanBasePackage: 增加您的包路径，用逗号隔开

3、默认代码生成包路径修改：菜单系统设置->参数设置的gen.defaultPackageName为您的包名

4、打开 logback-spring.xml，配置日志级别 <logger name="包路径" level="DEBUG" />

5、修改完成

# 部署到正式服务器

1、确保正式服务器 jdk1.8、11 or 17 及 数据库 环境已经具备

2、配置系统环境变量 JAVA_HOME 指定 jdk 路径，注意不要包含中文或空格

3、执行 bin/package.bat(sh) 打包项目，在 target 目录下找到 war 包文件，并拷贝到服务器上
（根据自身需要，可以修改为 jar 包，打开 web/pom.xml，吧 packaging 修改为 jar 即可）

4、进行解压war包，配置yml相关参数，运行/WEB-INF/startup.bat(sh)脚本，即可启动 Web 服务
（注意：一定要解压，否则影响性能，当后面发布更新的时候，可以部分升级某个依赖，不用整包上传）
（解压后请删除war包，war 可以独立运行，也可以直接放到 tomcat 或其它容器下运行）

5、若需修改 jvm 参数，编辑 startup.bat(sh) 修改 JAVA_OPTS 参数优化 jvm 环境

6、支持启动参数增加 -Dspring.config.location=x:/app.yml 加载指定配置文件

7、若需要配置环境，则指定 -Dspring.profiles.active=prod，则加载 application-prod.yml 属性文件

8、系统默认开启了百度统计，可在 application.yml 中添加 hmt: 0 参数，即关闭统计。

# 部署到外部 Web 容器

1、修改 application.yml 中的 server.servlet.context-path 值，除了前面多一个 / 外，后面与 web/pom.xml 中的 finalName 一致。如果部署路径设置不一致，可能会出现 cookie 无法存储，不能登录问题

2、执行 bin/package.bat(sh) 打包项目，在 target 目录下找到 war 包文件

3、如果为 Tomcat，可将 war 文件拷贝到 webapps 目录，并启动 Tomcat 即可；其它 Web 服务，如 WebLogic、TongWeb、JBoss、WebSphere 等，可根据对应部署方法进行操作（注意：必须支持 Servlet 3.1+）

# 部署到 Docker

1、打开 parent/pom.xml 修改容器地址 docker.dockerHost 为您的Docker地址，镜像名称默认为 ${project.groupId}/${project.artifactId}:4.3 规则

2、执行 parent/bin/package.bat(sh) 对，上一步的修改进行编译到本地 Maven 仓库

3、打开 web/pom.xml 修改 docker.run.port 运行端口，与 application.yml 里的服务端口一致

4、Dockfile 会激活了 prod 环境，请修改 application-prod.yml 中的 jdbc 数据库连接配置和 file 文件存储根路径

5、修改 web/bin/docker/Dockerfile 中的配置，根据您的项目环境情况进行配置和修改

6、执行 web/bin/docker-build.bat(sh) 进行编译打包镜像文件并上传至 Docker

7、进入 Docker 服务器，启动镜像，举例： docker run -p 8980:8980 com.jeesite/jeesite-web:5.5

【使用过程中的常见问题汇总】

进入 JeeSite 源码仓库页面，点击右上角 ⭐ Star 加星关注。

← 平台更新日志 🚀 代码生成、表结构 ER 图→