快速開始、環(huán)境搭建、修改包名、新建模塊、正式部署

開發(fā)環(huán)境要求

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)（請(qǐng)刪除 .xml 里的 mirror 配置）

3、Eclipse for Java EE 下載 (opens new window) 或 Spring Tools 下載 (opens new window) 或 IDEA 下載 (opens new window)（根據(jù)個(gè)人喜好選擇）

4、MySql 8.x 下載 (opens new window) 或 5.7.11+ 以上版本 下載 (opens new window) 或 Oracle、、Sql Server

5、Git 下載 (opens new window)，可選下載： (opens new window) 或 其它 (opens new window)、DBeaver (opens new window)

6、提示：一般 IDE 中會(huì)自帶部分工具，如果已經(jīng)具備，可免下載（^_^）。

導(dǎo)入到 IDE 工具

1、獲取 JeeSite 源代碼：

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

2、Eclipse：菜單中點(diǎn)擊 File -> Import，然后選擇 Maven -> Maven ，點(diǎn)擊 Next> 按鈕，選擇剛下載的 jeesite 文件夾，點(diǎn)擊 Finish 按鈕。

3、IDEA：菜單中點(diǎn)擊 File -> Open，然后選擇剛下載的 jeesite 文件夾，點(diǎn)擊 Open as Project 按鈕。

4、此時(shí) Eclipse 或 IDEA 會(huì)根據(jù) JeeSite 工程配置，自動(dòng)下載 Maven 依賴并編譯項(xiàng)目。初次加載可能會(huì)較慢（根據(jù)自身網(wǎng)絡(luò)情況而定）若工程上有小叉號(hào)，請(qǐng)打開 窗口，查看具體錯(cuò)誤內(nèi)容，直到無錯(cuò)誤為止。

提示

如果在編譯過程中遇見問題，請(qǐng)?jiān)?“常見問題” 中找找，看看有沒有和您相同的問題

5、下載依賴和編譯過程中，您可先進(jìn)行下一步，準(zhǔn)備數(shù)據(jù)庫環(huán)境

初始化數(shù)據(jù)庫

JeeSite 采用自動(dòng)數(shù)據(jù)庫初始化程序，根據(jù)用戶創(chuàng)建的數(shù)據(jù)庫賬號(hào)自動(dòng)完成表結(jié)構(gòu)和初始數(shù)據(jù)。無需自行執(zhí)行 SQL 文件進(jìn)行初始化，此舉為了更方便的導(dǎo)入不同類型的數(shù)據(jù)庫，如 MySQL、Oracle、、 等，不用維護(hù)多種類型數(shù)據(jù)庫的 SQL 初始數(shù)據(jù)的語句。減少出錯(cuò)率，也提供了更方便的，按需導(dǎo)入 JeeSite 擴(kuò)展模塊的數(shù)據(jù)表和基礎(chǔ)數(shù)據(jù)功能。

1、 創(chuàng)建用戶和授權(quán)（以 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 的初始化庫，直接導(dǎo)入即可，省去執(zhí)行 init-data.bat(sh)，點(diǎn)擊下載 (opens new window)（社區(qū)版用）

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

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

配置您的產(chǎn)品名稱、公司名稱、產(chǎn)品版本和 JDBC 連接，例如：

## 您的產(chǎn)品或項(xiàng)目名稱、軟件開發(fā)公司名稱
productName: 某某信息化管理系統(tǒng)
companyName: 某某信息技術(shù)有限公司
## 您的產(chǎn)品或項(xiàng)目迭代版本、版權(quán)年份
productVersion: V5.7
copyrightYear: 2024
## 數(shù)據(jù)庫連接
jdbc: 
  # MySql 數(shù)據(jù)庫配置（提示：MySql 8.x 驅(qū)動(dòng)類的配置方法，默認(rèn)在 v4.2 及之后版本 ）
  type: mysql
  driver: com.mysql.cj.jdbc.Driver
  # 如果需要提供公鑰進(jìn)行身份驗(yàn)證，MySql 8.2 可添加選項(xiàng)：&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 數(shù)據(jù)庫配置（提示：MySql 5.x 驅(qū)動(dòng)類的配置方法，默認(rèn)在 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

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

3、若剛才導(dǎo)入到的 Eclipse 或 IDEA 的項(xiàng)目，Maven 依賴已經(jīng)完成編譯并無錯(cuò)誤，這時(shí)您就可以執(zhí)行 /bin/init-data.bat(sh) 腳本初始化數(shù)據(jù)庫了，按提示操作。

（注意：v4.2.x 之后版本的初始化數(shù)據(jù)不會(huì)清空數(shù)據(jù)，如果已經(jīng)初始化，將會(huì)自動(dòng)忽略。如果執(zhí)行過程不小心中斷了，請(qǐng)手動(dòng)刪除 jeesite 庫中已經(jīng)創(chuàng)建的 table，再次執(zhí)行 init-data 腳本）

4、如果因您的環(huán)境原因 /bin/init-data.bat(sh) 腳本無法運(yùn)行，您可以在 Eclipse 或 IDEA 里找到 com.jeesite.test..java 文件并打開。

1）Eclipse 在 java 文件空白處右鍵，點(diǎn)擊 Run As -> JUnit Test 運(yùn)行單元測(cè)試，進(jìn)行初始化數(shù)據(jù)庫腳本。

2）IDEA 在 java 文件空白處右鍵，點(diǎn)擊 Run '' 運(yùn)行單元測(cè)試，進(jìn)行初始化數(shù)據(jù)庫腳本。

（注意：v4.1.8 之前版本找 com.jeesite.test..java 文件；v4.2.0 之前版本可能會(huì)提示您：為了防止誤操作，您還需要：打開 Run 找到 選項(xiàng)卡，在 VM 里增加 “-.=true” 參數(shù)，點(diǎn)擊Run運(yùn)行，執(zhí)行完成后建議將該單元測(cè)試 Run 刪除掉，防止誤操作，不小心再把您的有用數(shù)據(jù)清理掉）

提示

如果在初始化數(shù)據(jù)庫遇見問題，請(qǐng)?jiān)?“常見問題” 中找找，看看有沒有和您相同的問題

配置服務(wù)端口

1、當(dāng)前是 Spring Boot 工程，內(nèi)部已經(jīng)集成 Web 容器，您無需另外再下載 Tomcat 進(jìn)行部署，只需按照以下方式進(jìn)行即可。

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

配置您的服務(wù)端口 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

10

11

12

13

啟動(dòng) Web 服務(wù)

注意：JeeSite 一套后端代碼同時(shí)支持兩種前端技術(shù)棧下面，根據(jù)您的需求進(jìn)行選擇啟動(dòng)方式

全棧經(jīng)典版

前端技術(shù)棧： + Beetl。

1、Eclipse：打開 .java 啟動(dòng)文件，在空白處右鍵，點(diǎn)擊 Debug As -> Java 即可啟動(dòng)服務(wù)。

2、IDEA：右上角運(yùn)行調(diào)試配置下拉框，選擇 運(yùn)行配置，點(diǎn)擊 Debug 圖標(biāo)，啟動(dòng)服務(wù)。

Vue 分離版

前端技術(shù)棧：TS + Vue3 + Vite。

1、Eclipse：打開 .java 啟動(dòng)文件，在空白處右鍵，點(diǎn)擊 Debug As -> Java 即可啟動(dòng)服務(wù)。

2、IDEA：右上角運(yùn)行調(diào)試配置下拉框，選擇 運(yùn)行配置，點(diǎn)擊 Debug 圖標(biāo)，啟動(dòng)服務(wù)。

3、分離前端需要單獨(dú)部署 Vue 項(xiàng)目，部署方法詳見：

專業(yè)版用戶

1、若想分離版，請(qǐng)先打開 .yml 設(shè)置 apiMode 為 true，否則請(qǐng)忽略本步。

2、Eclipse：打開 .java 啟動(dòng)文件，在空白處右鍵，點(diǎn)擊 Debug As -> Java 即可啟動(dòng)服務(wù)。

3、IDEA：右上角運(yùn)行調(diào)試配置下拉框，選擇 運(yùn)行配置，點(diǎn)擊 Debug 圖標(biāo)，啟動(dòng)服務(wù)。

部署完成后訪問

1、瀏覽器訪問：:8980/js (opens new window) 分離版：:3100 (opens new window)

2、默認(rèn)最高管理員賬號(hào)：system 密碼：admin

3、恭喜您已經(jīng)部署完成，開啟您的開發(fā)之旅吧

提示

減少 IDE 語法錯(cuò)誤提示

配置 Beetl 第二個(gè)占位符和定界符，讓 html 和 js 語法編寫不同的占位符（5.5.0+默認(rèn)配置）

這樣就可以不用配置 IDE 的 HTML 語法驗(yàn)證，IDE 也不會(huì)報(bào)紅。

beetl-core.

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

正則表達(dá)式全局查找替換：

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

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

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

舊版 Eclipse 推薦設(shè)置參數(shù)

5.4.2 之前版本，打開項(xiàng)目您可能會(huì)發(fā)現(xiàn) html 文件多處報(bào)錯(cuò)，是因?yàn)?Beetl 語法和 JS 語法混用的時(shí)候語法錯(cuò)誤誤報(bào)問題。

設(shè)置如下，可關(guān)閉 IDE HTML 語法檢查，菜單：Window -> ->

哇，界面瞬間干凈了。

清理 Demo 數(shù)據(jù)

為了演示方法，初始化數(shù)據(jù)庫后會(huì)載入一些演示數(shù)據(jù)，執(zhí)行以下腳本即可清理

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;

10

11

新建一個(gè)模塊工程

1、進(jìn)入菜單：系統(tǒng)管理 -> 系統(tǒng)設(shè)置 -> 模塊管理，新建一個(gè)模塊，填寫：

點(diǎn)擊 “保存并生成代碼” 按鈕，即可完成業(yè)務(wù)模塊的工程代碼新建（自動(dòng)化生成模塊工程源碼）

2、打開 /modules/pom.xml 文件，拷貝 core 到新一行，修改為您的模塊名，如：test

v5.3.1 之前版本打開 /root/pom.xml 文件，拷貝 ../modules/core 到新一行，修改為您的模塊名，如：../modules/test

3、在您需要用到的項(xiàng)目引入您的新模塊，如，在 web 項(xiàng)目下用，則打開 /web/pom.xml 文件，加入：

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

4、若您使用的 Eclipse ，將該模塊導(dǎo)入即可。若 IDEA 點(diǎn)擊 Maven Update，則會(huì)自動(dòng)檢測(cè) root 模塊的依賴，并自動(dòng)導(dǎo)入。

5、模塊創(chuàng)建完成。

提示

模塊下新增代碼后，請(qǐng)返回模塊管理菜單，編輯模塊的 “主類全名”，如下：

主類全名：com.jeesite.modules.test.

解釋：類名為該模塊的狀態(tài)驗(yàn)證類，如果該類檢測(cè)不存在，則該模塊狀態(tài)提示 “未安裝”

驗(yàn)證原理：Class.forName("com.jeesite.modules.sys.web.")

v4.2.2之前版本創(chuàng)建模塊方法：

1、舉例創(chuàng)建 jeesite-module-test 模塊功能，拷貝模塊目錄下的 /modules/ 模板項(xiàng)目文件夾

2、然后在相同文件夾 /modules/ 下粘貼，并重命名為您的模塊名，如：/modules/test

3、打開 /modules/test/pom.xml 文件，找到 jeesite-module- 的 元素，修改為您的模塊名，如：jeesite-module-test

4、打開 /root/pom.xml 文件，拷貝 ../modules/core 到新一行，修改為您的模塊名，如：../modules/test

5、在您需要用到的項(xiàng)目引入您的新模塊，如，在 web 項(xiàng)目下用，則打開 /web/pom.xml 文件，加入：

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

6、若您使用的 Eclipse ，將該模塊導(dǎo)入即可。若 IDEA 會(huì)自動(dòng)檢測(cè) root 模塊的依賴，并自動(dòng)導(dǎo)入。

7、啟動(dòng)項(xiàng)目，打開 “系統(tǒng)管理 -> 系統(tǒng)設(shè)置 -> 模塊管理” 菜單，新建一個(gè)模塊，數(shù)據(jù)如下：

點(diǎn)擊 “保存” 按鈕。

8、模塊創(chuàng)建完成。

數(shù)據(jù)庫腳本自動(dòng)升級(jí)

非常好的功能，當(dāng)升級(jí)模塊代碼時(shí)，同時(shí)自動(dòng)更新對(duì)應(yīng)模塊的數(shù)據(jù)庫升級(jí) SQL 腳本，無需運(yùn)維人員手動(dòng)去執(zhí)行腳本。

1、每個(gè)主要模塊下都有一個(gè) 文件，該文件為數(shù)據(jù)庫版本檢測(cè)的關(guān)鍵文件

2、例如 core 模塊的版本檢測(cè)文件為：/modules/core/src/main//db/upgrade/core/

3、系統(tǒng)啟動(dòng)時(shí)，遍歷模塊表里的所有模塊，檢測(cè) 文件的版本列表，與其當(dāng)前模塊版本進(jìn)行對(duì)應(yīng)

4、找到對(duì)應(yīng)版本，則依次往下進(jìn)行匹配執(zhí)行升級(jí)。若匹配的版本沒有 sql 腳本，則忽略，只更新模塊版本

5、若 文件的版本列表中沒有匹配的版本，則提示：升級(jí)失敗，數(shù)據(jù)庫的版本可能比代碼版本新

6、自己的模塊實(shí)現(xiàn)，可參考官方 CMS 模塊的 相關(guān)代碼（含初始化表、菜單、字典等基礎(chǔ)數(shù)據(jù)）

使用自己的包路徑

自己新建的業(yè)務(wù)模塊，可以自定義為自己公司的包名，如：com..modules.xxx

1、.java 的 @n(="包路徑") 增加您的包路徑

2、.yml 中找到 mybatis: : 增加您的包路徑，用逗號(hào)隔開

3、默認(rèn)代碼生成包路徑修改：菜單系統(tǒng)設(shè)置->參數(shù)設(shè)置的gen.為您的包名

4、打開 logback-spring.xml，配置日志級(jí)別

5、修改完成

部署到正式服務(wù)器

1、確保正式服務(wù)器 jdk1.8、11 or 17 及 數(shù)據(jù)庫 環(huán)境已經(jīng)具備

2、配置系統(tǒng)環(huán)境變量 指定 jdk 路徑，注意不要包含中文或空格

3、執(zhí)行 bin/package.bat(sh) 打包項(xiàng)目，在 target 目錄下找到 war 包文件，并拷貝到服務(wù)器上

（根據(jù)自身需要，可以修改為 jar 包，打開 web/pom.xml，吧 修改為 jar 即可）

4、進(jìn)行解壓war包，配置yml相關(guān)參數(shù)，運(yùn)行/WEB-INF/startup.bat(sh)腳本，即可啟動(dòng) Web 服務(wù)

（注意：一定要解壓，否則影響性能，當(dāng)后面發(fā)布更新的時(shí)候，可以部分升級(jí)某個(gè)依賴，不用整包上傳）

（解壓后請(qǐng)刪除war包，war 可以獨(dú)立運(yùn)行，也可以直接放到 tomcat 或其它容器下運(yùn)行）

5、若需修改 jvm 參數(shù)，編輯 startup.bat(sh) 修改 參數(shù)優(yōu)化 jvm 環(huán)境

6、支持啟動(dòng)參數(shù)增加 -Dspring.config.=x:/app.yml 加載指定配置文件

7、若需要配置環(huán)境，則指定 -Dspring..active=prod，則加載 -prod.yml 屬性文件

部署到外部 Web 容器

1、修改 .yml 中的 server.servlet.context-path 值，除了前面多一個(gè) / 外，后面與 web/pom.xml 中的 一致。如果部署路徑設(shè)置不一致，可能會(huì)出現(xiàn) cookie 無法存儲(chǔ)，不能登錄問題

2、執(zhí)行 bin/package.bat(sh) 打包項(xiàng)目，在 target 目錄下找到 war 包文件

3、如果為 Tomcat，可將 war 文件拷貝到 webapps 目錄，并啟動(dòng) Tomcat 即可；其它 Web 服務(wù)，如 、TongWeb、JBoss、 等，可根據(jù)對(duì)應(yīng)部署方法進(jìn)行操作（注意：必須支持 Servlet 3.1+）

部署到 Docker

1、打開 parent/pom.xml 修改容器地址 docker. 為您的Docker地址，鏡像名稱默認(rèn)為 ${project.groupId}/${project.}:4.3 規(guī)則

2、執(zhí)行 parent/bin/package.bat(sh) 對(duì)，上一步的修改進(jìn)行編譯到本地 Maven 倉庫

3、打開 web/pom.xml 修改 docker.run.port 運(yùn)行端口，與 .yml 里的服務(wù)端口一致

4、 會(huì)激活了 prod 環(huán)境，請(qǐng)修改 -prod.yml 中的 jdbc 數(shù)據(jù)庫連接配置和 file 文件存儲(chǔ)根路徑

5、修改 web/bin/docker/ 中的配置，根據(jù)您的項(xiàng)目環(huán)境情況進(jìn)行配置和修改

6、執(zhí)行 web/bin/docker-build.bat(sh) 進(jìn)行編譯打包鏡像文件并上傳至 Docker

7、進(jìn)入 Docker 服務(wù)器，啟動(dòng)鏡像，舉例： docker run -p 8980:8980 com.jeesite/jeesite-web:5.5

【使用過程中的常見問題匯總】