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

# 开发环境要求

1、Java SDK 1.8 或 11、17  下载1 (opens new window) 下载2 (opens new window) 下载3 (opens new window)
2、Apache Maven 3.6+ 下载 (opens new window)（Maven 3.8+ 请删除 settings.xml 里的 mirror 配置）
3、Eclipse for Java EE 下载 (opens new window) 或 Spring Tools 下载 (opens new window) 或 IntelliJ IDEA 下载 (opens new window)（根据个人喜好选择）
4、MySql 8.0 下载 (opens new window) 或 5.7.11+ 下载 (opens new window)（Oracle、PostgreSQL、Sql Server 操作类似）
5、Git 下载 (opens new window)、TortoiseGit 下载 (opens new window)

# 导入到 Eclipse 或 IDEA

1、获取 JeeSite 源代码：

• 检出源代码：

git clone https://gitee.com/thinkgem/jeesite4.git
cd jeesite4

• 查看本地分支：

git branch

• 根据需要切换分支：

# 使用 4.x 版本
git checkout -b v4.6 origin/v4.6
# 使用 5.x 版本（Vue分离版的后端）
git checkout -b v5.2 origin/v5.2

2、拷贝 web 文件夹，到你的工作目录（不包含中文和空格的目录）下，重命名为你的工程名，如：jeesite-test

3、打开 pom.xml 文件，找到 jeesite-web 的 artifactId 元素，修改为你的工程名，如：jeesite-test

4、Eclipse：菜单 File -> Import，然后选择 Maven -> Existing Maven Projects，点击 Next> 按钮，选择第2步的 jeesite-test 文件夹，然后点击 Finish 按钮。

5、IDEA：点击 File 或菜单 File -> Open，然后选择 pom.xml 文件（若包含所有源码包，你需要选择 jeesite/root/pom.xml 文件），点击 Open as Project 按钮。

6、这时，Eclipse（IDEA）会自动加载 Maven 依赖包，初次加载会比较慢（根据自身网络情况而定），若工程上有小叉号，请打开 Problems 窗口，查看具体错误内容，直到无错误为止。

7、下载依赖jar文件的过程中，你可以准备数据库环境了

# 初始化数据库

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;

2、 打开文件 /src/main/resources/config/application.yml（v4.0：jeesite.yml） 配置产品和项目名称及 JDBC 连接

## 产品或项目名称、软件开发公司名称
productName: 修改为你的产品名称
companyName: 修改为你的公司名全称

## 产品版本、版权年份
productVersion: V4.3
copyrightYear: 2022

## 数据库连接
jdbc: 

  # MySql 数据库配置（提示：v4.2 及之后使用 MySql 8.x 驱动类的配置方法）
  type: mysql
  driver: com.mysql.cj.jdbc.Driver
  url: jdbc:mysql://127.0.0.1:3306/jeesite?useSSL=false&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=CONVERT_TO_NULL&serverTimezone=UTC
  username: root
  password: 123456
  testSql: SELECT 1

  ## MySql 数据库配置（提示：v4.1 及之前使用 MySql 5.x 驱动类的配置方法）
  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 之后版本的初始化数据不会清空数据，如果已经初始化，将会自动忽略。若 v4.1.x 旧版本遇见 table xxx doesn't exist 的错误信息，忽略即可。

4、如果 /bin/init-data.bat(sh) 无法运行，你可以在 Eclipse 或 IDEA 里找到 com.jeesite.test.InitData.java 文件并打开，若 v4.1.8 之前版本找 com.jeesite.test.InitCoreData.java 文件。然后在空白处右键，点击 Run As -> JUnit Test 运行单元测试，进行初始化数据库脚本。提示：v4.2.0 之前版本：为了防止误操作，你还需要：打开 Run Configurations 找到 Arguments 选项卡，在 VM arguments 里增加 “-Djeesite.initdata=true” 参数，点击Run运行，执行完成后建议将该单元测试 Run Configuration 删除掉，防止误操作，不小心再把你的有用数据清理掉。

# 启动服务

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

2、打开/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

3、Eclipse：找到 Application.java（专业版：ProApplication.java）启动文件并打开，然后在空白处右键，点击 Debug As -> Java Application 即可启动服务。

4、IDEA：右上选择 Application（专业版：ProApplication）运行配置，点击 Debug 图标，启动服务。如果启动的时候提示 NoClassDefFoundError: javax/servlet/ServletOutputStream 错误，请修改 web 项目下的 pom.xml，注释掉 spring-boot-starter-tomcat 的 <scope>provided</scope> 即可。

# Vue 版安装部署

https://jeesite.com/docs/vue-install-deploy/

# Eclipse 推荐设置参数

打开项目你可能会发现 html 文件多处报错，是因为 Beetl 语法和 JS 语法混用的时候语法错误误报问题，设置如下，菜单：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

哇，界面瞬间干净了。

# 部署完成测试运行

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

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

3、这时已经配置完成，开启你的开发之旅吧

# 清理 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、模块创建完成。

# 数据库脚本自动升级

• 每个主要模块下都有一个 versions 文件，该文件为数据库版本检测的关键文件。
• 例如 core 模块的版本检测文件为：/modules/core/src/main/resources/db/upgrade/core/versions 。
• 系统启动时，遍历模块表里的所有模块，检测 versions 文件的版本列表，与其当前模块版本进行对应。
• 找到对应版本，则依次往下进行匹配执行升级。若匹配的版本没有 sql 脚本，则忽略，只更新模块版本。
• 若 versions 文件的版本列表中没有匹配的版本，则提示：升级失败，数据库的版本可能比代码版本新。
• 自己的模块实现，可参考官方 CMS 模块的 InitCmsData 相关代码。

# 使用自己的包路径

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及数据库环境已经具备

2、配置系统环境变量JAVA_HOME指定jdk1.8路径，注意不要包含空格

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属性文件

# 部署到 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、修改web/bin/docker/app.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:4.3

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