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

# 开发环境要求

• 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
# 注意：不要放到中文或带空格的目录下。

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;

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

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

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

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

## 您的产品或项目迭代版本、版权年份
productVersion: V5.x
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

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

# 启动 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、恭喜您已经部署完成，开启您的开发之旅吧

# 减少 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=

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

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

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

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

旧版 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、进入菜单：系统管理 -> 系统设置 -> 模块管理，新建一个模块，填写：

• 模块名称：测试模块
• 模块编码：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>

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

5、模块创建完成。

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>

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、确保正式服务器，已经具备与您的项目要求的 JDK 和 数据库 版本

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

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

4、配置系统环境变量 JAVA_HOME 指定 JDK 路径，注意不要包含中文或空格（如果服务器上有多个 JDK 版本，可以修改 startup.bat(sh) 脚本，在文件中局部设置 JAVA_HOME 即可）

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

6、若需自定义加载配置文件，可以在 JVM 参数中增加 -Dspring.config.location=x:/app.yml

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

8、在您加载的 application.yml 配置文件中修改对应环境的参数，如：连接数据库、缓存库、文件库 等等

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

10、前端 Vue 部署方法：部署到正式服务器

# 部署到外部 Web 容器

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

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

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

# 部署到 Docker

1、打开 parent/pom.xml 修改容器地址 docker.dockerHost 为您的 Docker 的 2375 地址

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

3、打开 web/pom.xml 修改 docker.run.port 运行端口，与 application.yml 里的服务端口一致
   （运行端口参数，只对 mvn docker:run 命令有效，如果不需要本地运行，可以不用修改）

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

5、JAVA_OPTS 参数，支持通过 Docker 环境变量设置 -e 或 docker-compose 的 environment 参数设置

6、Dockfile 默认会激活 prod 环境，请修改 application-prod.yml 或 取消默认激活环境配置

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

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

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