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

# 开发环境要求

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

# 导入到 IDE 工具

1、获取 JeeSite 源代码：

git clone https://gitee.com/thinkgem/jeesite5.git jeesite
cd jeesite

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

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

4、此时 Eclipse 或 IDEA 会根据 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.7
copyrightYear: 2024

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

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

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

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

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

（注意：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 一套后端代码同时支持两种前端技术栈下面，根据您的需求进行选择启动方式

# 全栈经典版

前端技术栈：Bootstrap + Beetl。

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

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

# Vue 分离版

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

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

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

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

# 专业版用户

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

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

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

# 部署完成后访问

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、确保正式服务器 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 属性文件

# 部署到外部 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

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