JeecgBoot User Guide

JeecgBoot is an AI-powered, low-code development platform for building Java enterprise web applications. It pairs a Spring Boot 3 backend with a Vue 3 + Ant Design Vue frontend and a powerful code generator, so you build the parts that are unique to your business and let the platform generate the repetitive 70%.

This guide is for developers and application builders who want to install JeecgBoot, run it, and use its features to deliver systems faster — admin dashboards (MIS), OA, ERP, CRM, and SaaS products. It covers installation, the day-to-day low-code workflows (code generator, Online Forms, reports, dashboards), the AI features, permissions, and troubleshooting.

Note

This guide documents JeecgBoot 3.9.2 (the boot3 line: Spring Boot 3.5.5 / Java 17). Architecture, full configuration reference, deployment, and security hardening live in the companion Admin Guide. This guide focuses on using the platform.

1. Quick Start

The fastest way to see JeecgBoot running is the one-click Docker script. The fastest way to develop with it is to run the backend and frontend separately in your IDE.

1.1 What you are starting

JeecgBoot ships as two source trees that run together:

Important

Default login: admin / 123456. Change this password immediately on any environment that is reachable by anyone but you.

1.2 One-command Docker start (monolith)

If you have Docker, Maven, and pnpm installed, the repository root ships a one-click script that compiles both halves and starts the full stack with Docker Compose:

Linux / macOS

./start-docker-compose.sh

Windows

start-docker-compose.bat

The script performs five steps: checks for docker, docker-compose, mvn, and pnpm; adds jeecg-boot-system and jeecg-boot-mysql host entries to your hosts file; compiles the backend with mvn clean install -Pdocker; builds the frontend with pnpm install && pnpm run build:docker; and runs docker-compose up -d.

========================================
  JEECG Boot started (wait ~1 minute for all containers)
========================================
Frontend:  http://localhost
Backend API: http://localhost:8080/jeecg-boot

Tip

Wait roughly one minute after the script finishes — MySQL and the backend need time to initialize before the login page works.

1.3 Develop in your IDE (recommended for building apps)

# 1. Backend — compile and run the monolith entry point
cd jeecg-boot
mvn clean install -Pdev
# then run the main class:
#   org.jeecg.JeecgSystemApplication  (module: jeecg-system-start, port 8080)

# 2. Frontend — in a second terminal
cd jeecgboot-vue3
pnpm install
pnpm dev

Open http://localhost:3100, log in with admin / 123456, and you are in.

Note

Before the backend will start, you need a MySQL database and Redis running, with the connection details set in application-dev.yml. See §2 Installation.

1.4 Verify your environment first

The repository includes an environment checker script. Run it before installing to confirm you have the right tool versions:

python check_jeecgenv.py

==================================================
JeecgBoot Runtime Environment Check
==================================================
Checking JDK 17+...     ✅ JDK version 17 (meets 17+ requirement)
Checking Maven...       ✅ Maven installed
Checking Node.js 20+... ✅ Node.js version 20 (meets 20+ requirement)
Checking PNPM 9+...     ✅ PNPM version 9 (meets 9+ requirement)

The script also prints reference MySQL, Redis, AI, and pgvector configuration blocks so you know exactly which files to edit.

2. Installation and Setup

2.1 Requirements

Optional, only if you use the AI features:

2.2 Create the database

1. Create a MySQL schema named jeecg-boot (UTF-8 / utf8mb4).
2. Import the SQL bootstrap script shipped in the repository under jeecg-boot/db/ (the *.sql table-and-seed-data file). This creates the sys_* tables (users, roles, menus, dictionaries) and seeds the admin account.

Tip

The bundled docker-compose.yml builds a ready-to-use MySQL image from jeecg-boot/db/ with the schema pre-loaded — the easiest way to get a working database for local development. It exposes MySQL on host port 13306.

2.3 Configure the backend

Edit jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application-dev.yml and set at least your database and Redis connections:

spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/jeecg-boot?characterEncoding=UTF-8&useUnicode=true&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
          username: root
          password: root          # ← change me
          driver-class-name: com.mysql.cj.jdbc.Driver
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password:                    # ← set if your Redis requires one

Note

JeecgBoot uses a dynamic datasource. The connection above is the master datasource; you can add more named datasources and switch between them per-service. The full configuration reference (mail, OSS, SMS, AI, multi-tenant, firewall) is in the Admin Guide.

2.4 Build and run

# Backend (monolith)
cd jeecg-boot
mvn clean install -Pdev
# Run main class: org.jeecg.JeecgSystemApplication

# Frontend
cd jeecgboot-vue3
pnpm install
pnpm dev          # development server on :3100

When the backend starts you can confirm it is healthy by opening the built-in API docs at:

http://localhost:8080/jeecg-boot/doc.html

This is the Knife4j (OpenAPI 3) interface — JeecgBoot redirects the backend root path straight to it.

2.5 Choosing a different database

JeecgBoot ships a separate profile-specific config for each supported database. To run on PostgreSQL, Oracle, SQL Server, Dameng, or Kingbase, use the matching application-*.yml (e.g. application-postgresql.yml, application-oracle.yml, application-dm8.yml, application-kingbase8.yml) and import that database's SQL script. The application code is database-agnostic — one codebase runs on all of them.

Warning

Import the SQL script that matches your database engine. The MySQL script will not run unmodified on Oracle or PostgreSQL.

2.6 Microservice (Spring Cloud) mode — optional

JeecgBoot can run as a single application (monolith) or as Spring Cloud Alibaba microservices, and you can switch between them freely. Microservice mode adds a Nacos registry, a gateway, and supporting middleware:

Start the whole cloud stack with the cloud one-click script:

./start-docker-compose-cloud.sh

It builds the backend with mvn clean install -Pdev,SpringCloud, builds the frontend with pnpm run build:dockercloud, and brings up MySQL, Redis, Nacos, the gateway, the system/demo services, Sentinel, xxl-job, pgvector, and the Vue frontend via docker-compose-cloud.yml. In this mode the frontend talks to the gateway on :9999.

Tip

For building business applications, start with the monolith — it is simpler to run and develop against. Switch to microservices only when you actually need independent scaling. Deployment details for both modes are in the Admin Guide.

3. Core Concept: The Low-Code Workflow

JeecgBoot's central idea is a three-step development paradigm:

OnlineCoding  →  Code Generator  →  Manual MERGE
(configure)      (generate code)    (hand-edit complex logic)

• Simple screens (basic CRUD over a table) are built by configuration only — no code, using Online Forms.
• Complex screens are generated as real frontend + backend + SQL code by the Code Generator, then you hand-merge custom logic.

This is why the platform claims to remove ~70% of repetitive Java work while staying fully flexible: you always end up with real, editable code for anything non-trivial.

Note

Online Forms = zero code, run from configuration. Code Generator = low code, produces source you own and edit. Knowing which to use is the single most useful skill in JeecgBoot. Use Online for throwaway/simple admin screens; use the generator when you need custom business logic.

4. Everyday Usage

These are the tasks you will perform constantly while building an application. Most are reached from the left-hand menu of the admin UI after you log in.

4.1 Generate a CRUD module with the Code Generator

The code generator turns a database table (or an online-modeled table) into a complete add/delete/update/query module — frontend page, backend controller/service/mapper/entity, SQL, and a menu entry — in one step.

Typical flow:

1. Open System Tools → Code Generation in the menu.
2. Pick or model a database table.
3. Choose a template style. JeecgBoot ships four template sets: two single-table styles, one tree style, and three one-to-many styles.
4. Configure the 23 supported field controls (text, select, date, popup, upload, switch, etc.), validation rules, and query behavior.
5. Generate. The generated module appears in the menu and is immediately usable.

Tip

The generator supports single-table, tree, one-to-many, and one-to-one data models. Choose the model that matches your data shape before generating — switching later means regenerating.

Important

Generated code is yours to edit. After generating, add your business rules directly in the produced Java/Vue files. Re-generating overwrites — keep custom logic in clearly marked merge zones or separate methods so you do not lose it.

4.2 Build a screen with no code (Online Form)

Online Form development ("OnlineCoding") lets you build a working CRUD screen entirely through web configuration — no generation, no compile:

1. Open Online → Form Development (Online Coding).
2. Create a form: define fields, types, validation, and the data model (single table, tree, one-to-many, one-to-one).
3. Save. The screen is live immediately — you can add, edit, delete, and query records through it.

Online Forms support the same rich controls and query filters as generated code, plus Excel import/export. They are ideal for screens that do not need custom server logic.

Note

Online Forms run in dev mode by default (jeecg.firewall.lowCodeMode: dev). Production deployments often switch online design tools off — see the Admin Guide's security section. If "Online Coding" menu items are missing or read-only in a deployed environment, the platform is in prod low-code mode by design.

4.3 Manage users, roles, and permissions (RBAC)

JeecgBoot uses Role-Based Access Control with unusually fine granularity. From the System Management menu:

Permission granularity goes well beyond "can open this page":

• Menu permission — which pages appear.
• Button permission — which actions (Add/Edit/Delete/Export buttons) are visible/enabled.
• Data permission — row-level filtering (e.g. a manager sees only their department's records).
• Field permission — different users can see/edit different fields on the same form.

Tip

Set up your department tree and roles first, then assign data-permission rules. Data permissions are evaluated server-side, so they are real security boundaries, not just UI hiding.

4.4 Use data dictionaries

Dictionaries centralize coded values (status codes, types, gender, etc.) so you define them once and reference them everywhere. From System Management → Data Dictionary, create a dictionary with a code and its items. Fields in forms, generated code, and Excel import/export can reference a dictionary code to translate stored values (e.g. 1/2) into labels (e.g. "Male"/"Female") automatically.

4.5 Import and export Excel

Every generated module and Online Form includes Excel import/export out of the box, including one-to-many (master-detail) export. Dictionary-backed fields are translated automatically: export writes the label, import converts the label back to the stored value. Use the Export/Import buttons on any list screen.

4.6 Schedule background tasks

From System Monitoring → Scheduled Tasks (Quartz-backed), create timed jobs by class and cron expression. Jobs are stored in the database and run in a clustered scheduler, so they survive restarts and work across multiple backend instances.

For distributed, high-volume scheduling in microservice mode, JeecgBoot also integrates xxl-job (admin console on port 9080). Create an executor whose AppName matches your service name, then register jobs against it.

4.7 Send messages (SMS, email, WeChat)

The Message Center sends notifications over multiple channels: SMS (Aliyun or Tencent Cloud), email, and WeChat/DingTalk push. Templates are configured in system settings; the channel and provider keys are set in configuration (see Admin Guide). WebSocket-based in-app notifications are also built in.

4.8 Upload and manage files

File upload works against three interchangeable backends, selected by a single setting (jeecg.uploadType): local disk, MinIO, or Aliyun OSS. As a user you just use the upload controls on forms; the storage target is an admin configuration choice. Online file preview is supported for common document types.

5. Low-Code Designers

Beyond basic CRUD, JeecgBoot includes a suite of visual designers. Each produces artifacts you can embed in your application and assign to menus/roles.

5.1 Online Report

Configure data reports without coding: pick or write a data source, lay out columns, add grouping and aggregation. Reports can be exported and embedded. Reached from the Online → Report menu.

5.2 Online Chart

Configure charts (bar, line, pie, etc.) from a data source through the UI, with custom layout — no coding. The frontend also ships reusable chart components (Bar, Line, Pie, Radar, Gauge, RankList, and more) you can drop into custom Vue pages:

<template>
  <Bar :chartData="chartData" />
</template>

<script lang="ts" setup>
  import Bar from '/@/components/chart/Bar.vue';
  const chartData = [
    { name: 'Jan', value: 320 },
    { name: 'Feb', value: 457 },
    { name: 'Mar', value: 182 },
  ];
</script>

5.3 Report Designer (JimuReport)

JeecgBoot integrates JimuReport — a print-style report designer for pixel-accurate reports, PDF/Excel/Word output, and complex layouts (invoices, statements). Design reports in a spreadsheet-like canvas and bind cells to data.

5.4 Dashboard / Big-Screen Designer (JimuBI)

The big-screen designer (drag-and-drop) builds data dashboards and visualization "big screens" for control rooms and executive displays, with a library of widgets and an Amap (高德) map integration for geographic visualizations.

5.5 Form Designer

The form designer lets users lay out custom forms visually — single-table and one-to-many — using controls like input, select, radio, checkbox, textarea, date, popup, and list. Useful for letting non-developers build data-entry forms.

5.6 Workflow / Process Designer

JeecgBoot supports online process design: draw a flow visually, attach a form (configured, designed, or coded), and configure node routing in the page. Process and form are deliberately decoupled, so you can change routing without touching the form. This dramatically reduces the Java needed to stand up a BPM workflow.

Note

The exact designer features available in your install depend on the JeecgBoot edition and which optional modules (JimuReport, JimuBI, workflow) are enabled. The README's online demo (boot3.jeecg.com) shows the full set.

6. AI Features

JeecgBoot 3.9.2 ("low-code v2.0") integrates large-language-model features. The default provider is DeepSeek; ChatGPT, Qwen/Qwq, Zhipu (智谱), and locally-hosted Ollama models are also supported.

6.1 AI Chat Assistant

Once AI is configured, open the JeecgBoot home page and click "AI Assistant" on the right side of the home screen to open the chat dialog. The assistant can answer questions and help drive the platform.

6.2 AI-assisted building

With AI enabled, the platform offers:

• AI table creation — describe a table in natural language and have it modeled.
• AI report generation — generate reports from a prompt.
• AI drawing / voice / video — text-to-image, image-to-image, TTS, and video generation through configured providers (Qwen, Zhipu).

6.3 AI Knowledge Base (RAG)

The AIRAG module provides a retrieval-augmented knowledge base: upload documents (Word, Excel, PPT, PDF, text, Markdown — parsed via Apache Tika and POI), embed them into a pgvector store, and chat grounded in your own content. It also supports AI workflow orchestration and MCP tool management.

Important

AI features are off until configured. You must supply an API key (jeecg.ai-chat.apiKey) and, for the knowledge base, a running PostgreSQL with the pgvector extension (jeecg.ai-rag.embed-store). The bundled docker-compose-cloud.yml includes a pgvector container to make this easy. Configuration details are in the Admin Guide.

6.4 Natural-language coding with Skills

JeecgBoot 3.9.2 introduces AI Skills — a companion capability (paired with Claude Code) that generates full-stack code, forms, reports, dashboards, and BPMN flows from a single natural-language sentence. The Skills package and documentation are hosted separately (the jeecgboot/skills repository); the platform exposes hooks for it through the jeecg.ai-chat.skills-dir setting.

7. The Frontend Toolkit

When you write custom Vue pages (beyond generated code), JeecgBoot gives you a large component library on top of Ant Design Vue. The most distinctive components:

The frontend also provides: dynamic menu routing, internationalization (i18n, multiple languages), theme/style switching, a qiankun micro-front-end integration, and an Electron desktop wrapper.

Tip

Prefer the platform components over raw Ant Design Vue ones — they are wired into JeecgBoot's permissions, dictionaries, and API conventions, so things like button permissions and dictionary translation "just work".

8. System Monitoring

From the System Monitoring menu you can observe a running instance in real time:

• Redis monitor — cache keys and memory.
• Server monitor — CPU, memory, disk, JVM.
• Quartz / scheduled tasks — job status and history.
• Online users, request tracing, SQL monitoring (via Druid), and system logs.
• Data-source monitor and gateway route view (microservice mode).

In microservice mode, Spring Boot Admin (port 9111) and Sentinel (port 9000) add cluster-wide health and flow-control dashboards.

9. How It Works (Concepts)

You do not need this section to use JeecgBoot, but it explains the moving parts you will encounter.

9.1 Architecture in one paragraph

A Vue 3 single-page app calls a Spring Boot REST API. The backend authenticates each request with a JWT carried in the X-Access-Token header, validated by Apache Shiro. Data access uses MyBatis-Plus over a dynamic datasource. Redis caches tokens and supports distributed locks. The same backend codebase runs either as one process (monolith, port 8080) or as Spring Cloud microservices behind a gateway (port 9999) — controlled by whether service-discovery (Nacos) configuration is present.

9.2 Authentication model

• You log in (/sys/login) and receive a JWT.
• The frontend sends that token in the X-Access-Token header on every request.
• Shiro runs in stateless mode (no server session) — the token is validated each call, with authorization (roles/permissions) cached in Redis.
• Public endpoints (login, register, third-party login, SMS, captcha) are explicitly excluded from authentication.

9.3 Permissions model

Permissions follow RBAC with a wildcard permission string model (e.g. user:edit). On top of role→menu→button mapping, JeecgBoot adds row-level data permissions and field-level permissions, all enforced server-side.

Note

The full architecture, the dynamic-datasource and multi-tenant internals, the Shiro filter chain, and how monolith/microservice switching is decided are documented in depth in the Admin Guide.

10. Troubleshooting

Common issues, with the cause and the fix. Errors and behaviors below are drawn from the project's configuration and its community issue tracker.

Issue: Login page loads but admin / 123456 is rejected

Cause: The database SQL script was not imported, or the backend is pointing at the wrong/empty schema. Solution: Import the SQL script from jeecg-boot/db/ into your jeecg-boot schema, confirm application-dev.yml master datasource points at it, and restart the backend. Prevention: Run python check_jeecgenv.py and verify the database before first start.

Issue: Backend fails to start — Redis connection refused

Cause: Redis is not running, or the host/port/password in application-dev.yml is wrong. Solution: Start Redis and set spring.data.redis.host/port/password. Redis is mandatory — the app will not run without it. Prevention: The bundled docker-compose.yml includes a Redis container.

Issue: Backend compiles in Maven but not in IntelliJ IDEA

Cause: The Lombok plugin is not installed/enabled in IDEA, so Lombok-generated getters/setters are invisible to the IDE. Solution: Install the Lombok plugin and enable annotation processing in IDEA settings. Prevention: This is a documented requirement — install Lombok before opening the project.

Issue: pnpm install fails or the frontend won't build

Cause: Node.js or pnpm is too old. Vite 6 requires Node 20+, and the project requires pnpm 9+. Solution: Upgrade to Node v20.15.0+ and pnpm 9+. Do not use npm or yarn. Prevention: Run check_jeecgenv.py, which verifies both versions.

Issue: compilation failed building the backend (community issue #8229)

Cause: Wrong JDK (older than 17), missing Lombok, or a partial Maven dependency download from the custom Jeecg/Aliyun repositories. Solution: Confirm JDK 17+, run mvn clean install -Pdev -U to force-update dependencies, and ensure the Aliyun/Jeecg Maven mirrors are reachable. Prevention: Use the JDK and Maven mirror setup from the official setup docs.

Issue: A route named "PageNotFound" has been added as a child of a route with the same name (community issue #9412)

Cause: A duplicate dynamic-route registration in the Vue router, typically after customizing menus. Solution: Ensure each dynamic menu/route name is unique; remove duplicate menu entries in Menu Management. Prevention: Avoid reusing reserved route names like PageNotFound for menus.

Issue: Online Form / Online Report design menus are missing or read-only in production

Cause: This is intentional. jeecg.firewall.lowCodeMode (and jeecg.jmreport.firewall.lowCodeMode) is set to prod, which disables online design tools for safety. Solution: Online design is meant to be done in dev. If you must enable it in a deployed environment, change lowCodeMode to dev (understand the security trade-off first) or grant the lowdeveloper role. Prevention: Design online artifacts in development, then promote them.

Issue: Excel image export/import broke after upgrading (community issue #9605)

Cause: Behavior changes in the Online form Excel image handling between versions. Solution: Re-check the field's Excel configuration after upgrading; re-save the Online form definition. Track the issue upstream for the version-specific fix. Prevention: Re-test Excel import/export of image fields after any major version upgrade.

Issue: AI Assistant button does nothing / AI features unavailable

Cause: AI is not configured (jeecg.ai-chat.apiKey is still ??), or for the knowledge base, pgvector is not running. Solution: Set a valid API key (DeepSeek by default) and, for RAG, start PostgreSQL with the pgvector extension and fill in jeecg.ai-rag.embed-store. Prevention: Use the AI config blocks printed by check_jeecgenv.py.

Issue: Frontend can't reach the backend / CORS or 404 on API calls

Cause: In monolith mode the frontend must target :8080/jeecg-boot; in microservice mode it must target the gateway on :9999. Mismatched base URL causes 404s. Solution: Confirm the frontend's API base URL matches your run mode. CORS is auto-enabled in monolith mode only. Prevention: Use the matching frontend build target (pnpm dev / build:docker for monolith, build:dockercloud for cloud).

Issue: Cached route still refreshes when switching tabs (community issue #6543)

Cause: A known interaction between dynamic-route menu caching and tab switching. Solution: Verify the menu's "cache route" (keep-alive) setting; track the upstream issue for the fix. Prevention: Test keep-alive behavior on menus you mark as cached.

Tip

JeecgBoot is a Chinese-origin project with an extensive official documentation center (help.jeecg.com) and an online demo (boot3.jeecg.com). For UI-walkthrough questions beyond this guide, those are the authoritative references.

11. Frequently Asked Questions

Q: Is JeecgBoot free and can I use it commercially? Yes. JeecgBoot is released under the Apache License 2.0, which permits commercial use, modification, and redistribution. The license asks that derivative works not misrepresent themselves as official JeecgBoot releases.

Q: Monolith or microservices — which should I pick? Start with the monolith (jeecg-system-start, port 8080). It is simpler to run and develop. Switch to microservices (Nacos + gateway) only when you need independent scaling or deployment of modules. JeecgBoot supports switching between the two without rewriting business code.

Q: Which databases can I use? MySQL (default, 5.7+), Oracle 11g, SQL Server 2017, PostgreSQL, MariaDB, TiDB, Dameng (达梦), and Kingbase (人大金仓). One codebase runs on all of them — pick the matching application-*.yml profile and SQL script.

Q: What's the difference between Online Forms and the Code Generator? Online Forms run from configuration with zero code — best for simple screens. The Code Generator produces real frontend+backend source you edit by hand — best when you need custom business logic. This "configure simple, generate complex" split is JeecgBoot's core philosophy.

Q: Do I have to know Chinese to use JeecgBoot? No. The UI supports internationalization and ships English (the README is available in English and Japanese). Some community issues and parts of the official doc center are primarily in Chinese, but the platform itself is multilingual.

Q: How do I change the default admin password? Log in as admin, open user settings, and change the password — or reset it from User Management. Do this immediately on any shared or internet-reachable environment.

Q: Do I need Redis? Yes. Redis is required for token caching, dictionary caching, and distributed locks. The application will not start correctly without it.

Q: Do I need the AI features to use JeecgBoot? No. AI is entirely optional and disabled until you supply an API key. All low-code, code-generation, reporting, and workflow features work without it.

Q: Where is the API documentation for a running instance? At http://localhost:8080/jeecg-boot/doc.html (Knife4j / OpenAPI 3). The backend root path redirects there automatically.

Q: Can I build a mobile app? Yes. JeecgBoot has a companion uni-app project (jeecgboot/jeecg-uniapp) for building apps that run on Android/iOS, mini-programs, and H5 from one codebase.

Q: What is the upgrade story between versions? JeecgBoot uses incremental SQL scripts (Flyway-style naming under jeecg-system-start/.../flyway/sql/). Apply the version's migration SQL and rebuild. Always re-test Online Forms, Excel import/export, and custom routes after a major upgrade.

Q: How do I report a bug? Open an issue on the GitHub tracker at github.com/jeecgboot/JeecgBoot/issues using the bug-report template.

12. Quick Reference

Default credentials and addresses

Common commands

# Verify environment
python check_jeecgenv.py

# Backend — build & run monolith
cd jeecg-boot && mvn clean install -Pdev
# run org.jeecg.JeecgSystemApplication

# Backend — build for microservices
mvn clean install -Pdev,SpringCloud

# Frontend
cd jeecgboot-vue3
pnpm install
pnpm dev                 # dev server
pnpm build               # production build
pnpm run build:docker    # monolith docker build
pnpm run build:dockercloud  # cloud docker build

# One-click Docker (monolith)
./start-docker-compose.sh

# One-click Docker (microservices)
./start-docker-compose-cloud.sh

Run modes at a glance

Where to configure things (files)

Note

Anything in the configuration files above — full keys, security hardening, deployment, and architecture — is documented exhaustively in the JeecgBoot Admin Guide.