# 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:

| Source tree | What it is | Default address |
|---|---|---|
| `jeecg-boot/` | Spring Boot backend (Java) — REST API, code generator, low-code engine | `http://localhost:8080/jeecg-boot` |
| `jeecgboot-vue3/` | Vue 3 + TypeScript frontend (Ant Design Vue) | `http://localhost:3100` (dev server) |

> [!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"

    ```bash
    ./start-docker-compose.sh
    ```

=== "Windows"

    ```bat
    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`.

```text
========================================
  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)

```bash
# 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](#2-installation-and-setup).

### 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:

```bash
python check_jeecgenv.py
```

```text
==================================================
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

| Component | Required version | Notes |
|---|---|---|
| **JDK** | 17+ | Also supports 21 / 24 / 25. The build targets Java 17. |
| **Maven** | 3.x | Backend dependency management and build. |
| **Node.js** | 20+ (e.g. `v20.15.0`) | Required by Vite 6. |
| **pnpm** | 9+ | The frontend package manager (npm/yarn are not the supported path). |
| **MySQL** | 5.7+ | Default database. Oracle, PostgreSQL, SQL Server, MariaDB, TiDB, Dameng (达梦), Kingbase (人大金仓) are also supported. |
| **Redis** | any recent | Required — used for caching, tokens, and distributed locks. |
| **IDE** | IntelliJ IDEA | The **Lombok plugin must be installed** for the backend to compile in-IDE. |

Optional, only if you use the AI features:

| Component | Used for |
|---|---|
| **PostgreSQL + pgvector** | AI knowledge base (RAG) vector store. |
| **AI API key** (DeepSeek by default) | AI chat assistant, AI table/report generation. |

### 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:

```yaml
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

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

```bash
# 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:

```text
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:

| Service | Port | Role |
|---|---|---|
| Gateway | `9999` | Single entry point for all API traffic |
| Nacos | `8848` | Service registry + config center |
| System service | `7001` | Core system module |
| Demo service | `7002` | Example business module |
| Monitor (Spring Boot Admin) | `9111` | Health/metrics dashboard (`admin`/`admin`) |
| xxl-job admin | `9080` | Distributed scheduled-task console (`admin`/`123456`) |
| Sentinel | `9000` | Flow control / circuit breaking (`sentinel`/`sentinel`) |

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

```bash
./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:

```text
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:

| Screen | What you control |
|---|---|
| **User Management** | Accounts, password reset, department/role assignment, enable/disable |
| **Role Management** | Roles and which roles a user has |
| **Menu / Permission** | Which menus and **buttons** a role can see and use |
| **Department (Org)** | Organizational tree; users belong to departments |
| **Data Permission Rules** | Row-level rules — different users see different *rows* of the same table |

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:

```html
<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:

| Component | Use |
|---|---|
| **JVxeTable** | High-performance editable/row-edit table for complex ERP-style grids (faster and more flexible than the basic table). |
| **BasicTable** (`Table`) | The standard list table with built-in query, paging, and toolbar. |
| **BasicForm** (`Form`) | Schema-driven forms with the 20+ Jeecg controls (upload, cron picker, user-select, area-select, etc.). |
| **BasicModal / BasicDrawer** | Standardized modal and drawer dialogs via `useModal()` / `useDrawer()` hooks. |
| **Icon / Markdown / Tinymce / CodeEditor / Cropper / Qrcode** | Ready-made building blocks. |

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

| Item | Value |
|---|---|
| Default login | `admin` / `123456` |
| Backend (monolith) | `http://localhost:8080/jeecg-boot` |
| Frontend dev server | `http://localhost:3100` |
| API docs (Knife4j) | `http://localhost:8080/jeecg-boot/doc.html` |
| Gateway (microservice) | `http://localhost:9999` |
| Nacos | `http://localhost:8848` |
| Spring Boot Admin monitor | `http://localhost:9111` (`admin`/`admin`) |
| xxl-job console | `http://localhost:9080/xxl-job-admin` (`admin`/`123456`) |
| Sentinel | `http://localhost:9000` (`sentinel`/`sentinel`) |
| Druid SQL monitor | `…/jeecg-boot/druid/` (`admin`/`123456`) |

### Common commands

```bash
# 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

| | Monolith | Microservices |
|---|---|---|
| Entry point | `jeecg-system-start` (8080) | Gateway (9999) + Nacos (8848) |
| Build profile | `-Pdev` / `-Pdocker` | `-Pdev,SpringCloud` |
| Frontend build | `build:docker` | `build:dockercloud` |
| Best for | Development, most apps | Independent scaling, large teams |

### Where to configure things (files)

| Setting | File |
|---|---|
| Database, Redis, app settings | `jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application-dev.yml` |
| Per-database overrides | `application-{postgresql,oracle,sqlserver,dm8,kingbase8}.yml` |
| Database schema/seed | `jeecg-boot/db/*.sql` |
| Frontend | `jeecgboot-vue3/` (Vite + pnpm) |

> [!NOTE]
> Anything in the configuration files above — full keys, security hardening, deployment, and architecture — is documented exhaustively in the **JeecgBoot Admin Guide**.

---

_Generated June 2026 from jeecgboot/JeecgBoot at 3f826c4. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._