# JeecgBoot Admin Guide

A complete operational and architectural reference for **JeecgBoot 3.9.2** — the `boot3` line built on Spring Boot 3.5.5 and Java 17. This guide is for administrators, DevOps engineers, architects, and developers who deploy, configure, secure, operate, and extend JeecgBoot. It is the source-based companion to the **User Guide** (which covers day-to-day feature usage).

> [!NOTE]
> Versions in this guide are taken from the actual `pom.xml` and configuration files at commit `3f826c4` (2026-05-21), **not** the project README — the README in this snapshot still lists the older Spring Boot 2.7 stack and is stale for the `boot3` branch.

---

## 1. Executive Summary

JeecgBoot is an enterprise **low-code / AI development platform**. It combines a Java backend (Spring Boot 3, optionally Spring Cloud Alibaba microservices) with a Vue 3 frontend and a code generator, plus a large suite of low-code tools: Online Forms, JimuReport reporting, JimuBI dashboards, a form/process designer, and an AI module (chat, RAG knowledge base, AI workflow).

**Key architectural facts an operator must know:**

| Aspect | Value |
|---|---|
| Backend framework | Spring Boot **3.5.5**, Java **17** (17/21/24/25 supported) |
| Microservice stack | Spring Cloud **2025.0.0** + Spring Cloud Alibaba **2023.0.3.3**, Nacos **2.0.4** |
| Persistence | MyBatis-Plus **3.5.12**, dynamic-datasource **4.3.1**, Druid **1.2.24** |
| Security | Apache Shiro **2.0.5** (jakarta) + JWT (java-jwt **4.5.0**), stateless tokens |
| Cache / lock | Redis (jedis **3.8.0**), Redisson distributed locks |
| Scheduling | Quartz (clustered, JDBC store) + xxl-job **2.4.1** |
| Messaging | RabbitMQ, RocketMQ (microservice mode) |
| Reporting | JimuReport **2.3.4**, JimuBI **2.3.2**, AutoPoi **2.0.4** |
| AI | langchain4j **1.12.2** (OpenAI/Ollama/Gemini/Zhipu/Qianfan/DashScope/Anthropic), pgvector |
| Frontend | Vue 3 + TypeScript + Vite 6 + Ant Design Vue + Pinia + ECharts |
| Default monolith port | `8080`, context path `/jeecg-boot` |
| Default credentials | `admin` / `123456` |
| License | Apache License 2.0 |

**Deployment shapes:** a single Spring Boot process (**monolith**, port 8080) or a set of **Spring Cloud microservices** behind a gateway (port 9999) with Nacos service discovery. The same business code runs in both; which one is active is decided at runtime by the presence of service-discovery configuration.

> [!IMPORTANT]
> JeecgBoot ships with **development-friendly defaults that are unsafe for production**: default credentials, exposed Druid/Knife4j consoles, verbose error stack traces, permissive CORS, and `lowCodeMode: dev`. §5 (Security) lists every one and how to harden it. Do not expose a default install to the internet.

---

## 2. Architecture

### 2.1 High-level topology (monolith)

```text
                  Browser (Vue 3 SPA, :3100 dev / nginx :80 prod)
                         │  REST + X-Access-Token (JWT)
                         ▼
        ┌──────────────────────────────────────────┐
        │  jeecg-system-start  (Spring Boot, :8080) │
        │  context-path /jeecg-boot                 │
        │                                           │
        │  Shiro JWT filter chain ── CORS filter    │
        │  Controllers → Services → MyBatis-Plus    │
        │  Quartz scheduler · WebSocket endpoints   │
        └───────┬───────────────┬───────────┬───────┘
                │               │           │
                ▼               ▼           ▼
            MySQL/…          Redis     File store
         (dynamic DS)    (cache/lock)  local/MinIO/OSS
                                          │
                          (optional) PostgreSQL+pgvector  ← AI RAG
```

### 2.2 High-level topology (microservices)

```text
   Browser ─▶ Gateway (:9999) ─▶ Nacos (:8848 registry+config)
                  │
                  ├─▶ jeecg-system-cloud-start  (:7001)
                  ├─▶ jeecg-demo-cloud-start    (:7002)
                  ├─▶ Sentinel (:9000)   flow control
                  ├─▶ xxl-job  (:9080)   distributed jobs
                  ├─▶ Spring Boot Admin / Monitor (:9111)
                  └─▶ RabbitMQ / RocketMQ / Seata / ShardingSphere (optional)
```

Inter-service calls use **OpenFeign**; resilience via **Sentinel**; config and discovery via **Nacos**; distributed transactions via **Seata**; sharding via **ShardingSphere**.

### 2.3 Maven module layout

```text
jeecg-boot-parent (org.jeecgframework.boot3:3.9.2)
├─ jeecg-boot-base-core         Core: config, security, MyBatis-Plus, utils, AI config beans
├─ jeecg-module-system
│  ├─ jeecg-system-biz          System business logic (users, roles, menus, dict, online, jimureport)
│  ├─ jeecg-system-start        ★ MONOLITH entry point (port 8080)
│  └─ jeecg-system-api
│     ├─ jeecg-system-local-api   API interfaces for monolith (in-process)
│     └─ jeecg-system-cloud-api   API interfaces for microservices (OpenFeign)
├─ jeecg-boot-module
│  ├─ jeecg-module-demo         Example business module (CRUD samples)
│  └─ jeecg-boot-module-airag   AI module: langchain4j, RAG, aiflow (liteflow), tools
└─ jeecg-server-cloud           (active only under -PSpringCloud profile)
   ├─ jeecg-cloud-gateway       Gateway (9999)
   ├─ jeecg-cloud-nacos         Embedded Nacos (8848)
   ├─ jeecg-system-cloud-start  System microservice (7001)
   ├─ jeecg-demo-cloud-start    Demo microservice (7002)
   └─ jeecg-visual
      ├─ jeecg-cloud-monitor    Spring Boot Admin (9111)
      ├─ jeecg-cloud-xxljob     xxl-job admin (9080)
      ├─ jeecg-cloud-sentinel   Sentinel dashboard (9000)
      └─ jeecg-cloud-test       Samples: rabbitmq, rocketmq, seata, shardingsphere
```

> [!NOTE]
> The `-Pdev` profile activates only the monolith modules. The `-PSpringCloud` profile (active by default in the parent POM via an `activeByDefault` profile) adds `jeecg-server-cloud`. Use `-Pdev,SpringCloud` to build the cloud stack.

### 2.4 Monolith vs. microservice switching

This is decided by a Spring `Condition` reading `CommonConstant.CLOUD_SERVER_KEY` from the environment:

- `JeecgCloudCondition` — beans annotated with it load **only** when service-discovery config is present (microservice mode).
- `CorsFilterCondition` — the in-app `CorsFilter` loads **only** when service discovery is *absent* (monolith mode). In microservice mode, CORS is the gateway's job.

So the same codebase self-configures based on whether it finds Nacos/cloud config. No code change is needed to switch — only the build profile and runtime config.

### 2.5 Request lifecycle (backend)

```text
HTTP request → CORS filter (monolith only)
            → Shiro filter chain
                 ├─ anon paths (login, register, thirdLogin, sms, captcha) → pass
                 └─ protected paths → JwtFilter validates X-Access-Token
                        → stateless (noSessionCreation), authz cached in Redis
            → @RestController (org.jeecg.modules.*)
            → @Service (IService / MyBatis-Plus)
            → Mapper (BaseMapper, dynamic datasource via @DS)
            → DB
Response ← unified Result<T> JSON (ObjectMapper: yyyy-MM-dd HH:mm:ss, GMT+8)
```

### 2.6 Persistence and dynamic datasource

- **MyBatis-Plus** provides the `IService`/`BaseMapper` CRUD layer, `LambdaQueryWrapper` conditional queries, and `IPage` pagination. Global config: `id-type: ASSIGN_ID` (snowflake IDs), `table-underline: true`, mapper XML at `classpath*:org/jeecg/**/xml/*Mapper.xml`.
- **dynamic-datasource** lets services target named datasources via `@DS("name")`. The default is `master`. Add datasources under `spring.datasource.dynamic.datasource.*`.
- **Druid** is the connection pool and SQL monitor (stat + wall filters). The `DruidConfig` bean strips Druid's built-in ad banner; `DruidWallConfigRegister` relaxes the `selectWhereAlwayTrueCheck` wall rule at startup.
- **ShardingSphere** (optional) provides sharding and read/write splitting; configured via `sharding.yaml` referenced through a `jdbc:shardingsphere:` datasource URL. The `databaseName` in `sharding.yaml` must match the `@DS` name and the datasource key.

### 2.7 Web/MVC configuration (from `WebMvcConfiguration`)

- **CORS**: `allowCredentials=true`, `allowedOriginPattern=*`, all headers/methods — monolith only, via `CorsFilterCondition`.
- **Static resources**: serves uploaded files from `jeecg.path.upload` (default `/opt/upFiles`) and `jeecg.path.webapp` (`/opt/webapp`) plus classpath static, with a 30-day `Cache-Control`.
- **Root redirect**: `/` → `/doc.html` (Knife4j). Can be repointed to a packaged `index.html`.
- **ObjectMapper**: BigDecimal as plain, lenient deserialization, `yyyy-MM-dd HH:mm:ss` date formats, JSR-310 (LocalDate/Time) serializers.
- **WebSocket**: `ServerEndpointExporter` plus a `WebsocketFilter` registered for endpoints `/websocket/*`, `/taskCountSocket/*`, `/eoaSocket/*`, `/eoaNewChatSocket/*`, `/newsWebsocket/*`, `/dragChannelSocket/*`, `/vxeSocket/*`.

### 2.8 API documentation (Knife4j / springdoc)

OpenAPI 3 via `Swagger3Config` (springdoc + Knife4j UI). The security scheme is the `X-Access-Token` API-key header, auto-applied to all operations except the public set (`/sys/login`, `/sys/phoneLogin`, `/sys/mLogin`, `/sys/sms`, `/sys/randomImage/**`, `/sys/thirdLogin/**`, `/sys/user/register`, `/sys/cas/client/validateLogin`, `/test/jeecgDemo/demo3`). Enabled by `knife4j.enable`; gated off in production by `knife4j.production`.

---

## 3. Requirements and Capacity

### 3.1 Software prerequisites

| Component | Version | Required? |
|---|---|---|
| JDK | 17+ (17/21/24/25) | Yes |
| Maven | 3.x | Yes (build) |
| Node.js | 20+ (`v20.15.0`) | Yes (frontend build) |
| pnpm | 9+ | Yes (frontend) |
| MySQL | 5.7+ | Yes (or another supported DB) |
| Redis | recent | Yes |
| Docker + Docker Compose | recent | For container deployment |
| PostgreSQL + pgvector | — | Only for AI knowledge base (RAG) |
| Nacos / Sentinel / RabbitMQ | per stack | Only for microservice mode |

Supported databases: MySQL, Oracle 11g, SQL Server 2017, PostgreSQL, MariaDB, TiDB, Dameng (达梦 / `DmJdbcDriver18`), Kingbase (人大金仓 / `kingbase8`).

### 3.2 Environment preflight

Run the bundled checker before provisioning:

```bash
python check_jeecgenv.py
```

It validates JDK 17+, Maven, Node 20+, pnpm 9+, and prints reference config blocks for MySQL, Redis, AI chat, and the pgvector store.

### 3.3 Sizing notes

- The monolith is a single JVM; size heap for your dataset and concurrency. Druid pool defaults: `initial-size=5`, `min-idle=5`, `maxActive=1000`, `maxWait=60000ms`.
- Quartz thread pool is **10** threads; the AI RAG scheduler (`TaskSchedulerConfig`) adds a separate 10-thread `ThreadPoolTaskScheduler`.
- The AIRAG module pulls large optional dependencies (Kotlin scripting, GraalJS, Groovy — ~50MB each, marked `provided`/`runtime`). Exclude unused script engines to slim the artifact.
- Microservice mode multiplies the footprint (gateway + Nacos + per-service JVMs + Sentinel + middleware). Plan memory accordingly.

---

## 4. Configuration Mastery

All backend configuration lives in `jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/`:

| File | Purpose |
|---|---|
| `application.yml` | Selects the active profile (`@profile.name@`) and imports `config/application-liteflow.yml` |
| `application-dev.yml` | The main config (database, Redis, jeecg.*, integrations) |
| `application-prod.yml`, `application-test.yml`, `application-docker.yml` | Environment overrides |
| `application-{postgresql,oracle,sqlserver,dm8,kingbase8}.yml` | Per-database datasource overrides |
| `logback-spring.xml` | Logging |
| `flyway/sql/{db}/` | Versioned migration SQL |
| `jeecg/` | Code-generator templates |

The active profile is set at build time via the Maven `profile.name` property (`dev`/`test`/`docker`/`prod`).

### 4.1 Server and framework

| Key | Default | Notes |
|---|---|---|
| `server.port` | `8080` | Backend port |
| `server.servlet.context-path` | `/jeecg-boot` | All paths are prefixed |
| `server.error.include-stacktrace` | `ALWAYS` | **Disable in prod** (info leak) |
| `server.compression.enabled` | `true` | gzip for JSON/JS/CSS ≥1KB |
| `spring.servlet.multipart.max-file-size` | `10MB` | Upload limit |
| `spring.jackson.time-zone` | `GMT+8` | Timestamp zone |
| `management.endpoints.web.exposure.include` | `metrics,httpexchanges,jeecghttptrace` | Actuator surface |

### 4.2 Datasource (Druid + dynamic)

```yaml
spring:
  datasource:
    druid:
      stat-view-servlet:
        enabled: true
        loginUsername: admin       # ← Druid console creds — CHANGE/DISABLE in prod
        loginPassword: 123456
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/jeecg-boot?characterEncoding=UTF-8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
          username: root
          password: root
          driver-class-name: com.mysql.cj.jdbc.Driver
```

> [!CAUTION]
> The Druid stat-view servlet is **enabled with `admin`/`123456`** by default and exposes SQL, sessions, and URI stats at `…/jeecg-boot/druid/`. Disable it or change the credentials before any non-local deployment.

### 4.3 Cache, scheduling, mail

| Area | Keys | Default |
|---|---|---|
| Redis | `spring.data.redis.host/port/password/database` | `127.0.0.1:6379`, db 0, no password |
| Quartz | `spring.quartz.job-store-type` | `jdbc`, clustered (`isClustered: true`), 10 threads |
| Mail | `spring.mail.host/username/password` | `smtp.163.com`, placeholder creds |
| Flyway | `spring.flyway.enabled` | `false`; `clean-disabled: true` (**keep true** — prevents schema wipe) |
| MyBatis-Plus | `mybatis-plus.global-config.db-config.id-type` | `ASSIGN_ID` (snowflake), `table-underline: true` |

> [!WARNING]
> `spring.flyway.clean-disabled` **must remain `true` in production**. Setting it `false` allows Flyway to drop all tables in the schema — a catastrophic data-loss risk the config comments explicitly warn about.

### 4.4 The `jeecg.*` namespace (platform settings)

Bound by `JeecgBaseConfig` (`@ConfigurationProperties(prefix="jeecg")`):

| Key | Purpose | Default |
|---|---|---|
| `jeecg.uploadType` | File store backend: `local` / `minio` / `alioss` | `local` |
| `jeecg.path.upload` | Local upload root | `/opt/upFiles` |
| `jeecg.path.webapp` | Local webapp path | `/opt/webapp` |
| `jeecg.signatureSecret` | HMAC signing key for sensitive (dictionary) APIs | a shared default — **change it** |
| `jeecg.signUrls` | Endpoints that require request signing | dict/sms endpoints |
| `jeecg.shiro.excludeUrls` | Extra paths excluded from Shiro auth | demo/bigscreen paths |
| `jeecg.smsSendType` | `aliyun` / `tencent` | `aliyun` |
| `jeecg.domainUrl.pc` / `.app` | Frontend base URLs | `:3100` / `:8051` |
| `jeecg.firewall.dataSourceSafe` | Require data source for Online report/chart | `false` |
| `jeecg.firewall.lowCodeMode` | `dev` (online design on) / `prod` (off) | `dev` |
| `jeecg.firewall.is-concurrent` | Allow same account multi-login | `true` |

Integration sub-namespaces (all default to `??` placeholders — fill what you use):

- `jeecg.oss.*` — Aliyun OSS keys + SMS templates (`accessKey`, `secretKey`, `endpoint`, `bucketName`, `sms-template.*`).
- `jeecg.tencent.*` — Tencent Cloud SMS (`secretId`, `secretKey`, `sdkAppId`, `region`).
- `jeecg.minio.*` — MinIO (`minio_url`, `minio_name`, `minio_pass`, `bucketName`).
- `jeecg.jmreport.*` — JimuReport: `saasMode`, `firewall.dataSourceSafe`, `firewall.lowCodeMode`, `gao-de-api.*` (Amap key for BI maps).
- `jeecg.xxljob.*` — xxl-job: `enabled` (default `false`), `adminAddresses` (`http://127.0.0.1:9080/xxl-job-admin`), `appname`, `accessToken`, `address`, `port` (30007).
- `jeecg.redisson.*` — distributed lock: `address`, `password`, `type: STANDALONE`, `enabled: true`.
- `jeecg.baidu-api.*` — Baidu OCR (`app-id`, `api-key`, `secret-key`).
- `jeecg.file-view-domain` — online file-preview server (`http://fileview.jeecg.com`).

### 4.5 AI configuration

Bound by `AiChatConfig` (`prefix=jeecg.ai-chat`) and `AiRagConfigBean` (`prefix=jeecg.airag`):

```yaml
jeecg:
  ai-chat:
    enabled: true
    model: deepseek-chat
    apiKey: ??                       # ← REQUIRED for AI chat
    apiHost: https://api.deepseek.com/v1
    timeout: 60
    ai-model-draw:    { provider: QWEN,  model: wan2.2-t2i-flash, apiKey: sk-?? }   # text→image
    ai-model-pic-draw:{ provider: QWEN,  model: wan2.5-i2i-preview, apiKey: sk-?? } # image→image
    ai-model-voice:   { provider: ZHIPU, model: glm-tts, voice: tongtong, speed: 1.0 }
    ai-model-video:   { provider: ZHIPU }
    ai-model-embed:   { provider: QWEN,  model: text-embedding-v1 }   # default embeddings
  ai-rag:
    allow-sensitive-nodes: sql,stdio   # ← enables SQL/command-line AI flow nodes (risky)
    embed-store:                       # pgvector store for RAG
      host: 127.0.0.1
      port: 5432
      database: postgres
      user: postgres
      password: postgres
      table: embeddings
    brave-search:                      # AI agent web search (optional)
      api-key: ??
      count: 10
      timeout: 15
```

> [!CAUTION]
> `jeecg.ai-rag.allow-sensitive-nodes: sql,stdio` enables **SQL execution** and **command-line (stdio)** nodes in AI workflows. These let AI flows run database queries and shell commands. Remove `stdio` (and `sql` if not needed) on any multi-tenant or internet-facing deployment — they are powerful and a serious risk if an attacker can author flows.

### 4.6 Authentication integrations

- **Knife4j basic auth**: `knife4j.basic.enable/username/password` (`jeecg`/`jeecg1314`). Enable + change in prod, or set `knife4j.production: true` to disable docs entirely.
- **JustAuth third-party login** (`justauth.*`): GitHub, WeChat Enterprise/Open, DingTalk — each with `client-id`/`client-secret`/`redirect-uri`.
- **CAS SSO**: `cas.prefixUrl` for single sign-on.

---

## 5. Security

> [!IMPORTANT]
> JeecgBoot is a legitimate, widely-used open-source platform, but its defaults are tuned for developer convenience. Treat every item below as a required hardening step before exposing an instance. JeecgBoot's public issue tracker actively receives security reports (privilege-escalation, SSRF, SQL-injection, and OAuth open-redirect reports appear in the open issues for 3.9.x); **the single most important control is to run a patched, current release.**

### 5.1 Authentication and authorization model

- **Stateless JWT via Shiro.** Login (`/sys/login`) issues a JWT; the frontend returns it in the `X-Access-Token` header on every request. A custom Shiro realm (extending `AuthorizingRealm`) validates the token (`doGetAuthenticationInfo`) and resolves roles/permissions (`doGetAuthorizationInfo`), with the chain running in `noSessionCreation` (no server session). Authorization data is cached in Redis (`shiro-redis`).
- **RBAC + wildcard permissions** (`@RequiresPermissions("user:edit")`, `@RequiresRoles("admin")`), extended with **data permissions** (row-level) and **field permissions**, all enforced server-side.
- **Request signing.** Sensitive dictionary/SMS endpoints (`jeecg.signUrls`) require an HMAC signature derived from `jeecg.signatureSecret`. The frontend and backend secrets must match.

### 5.2 Hardening checklist

- [ ] Change the `admin`/`123456` account password (and all default-seeded accounts).
- [ ] Rotate `jeecg.signatureSecret` to a unique value (and update the frontend to match).
- [ ] Disable or re-credential the **Druid** stat-view servlet (`spring.datasource.druid.stat-view-servlet`).
- [ ] Set `knife4j.production: true` (or strong `knife4j.basic` creds) to lock API docs in prod.
- [ ] Set `server.error.include-stacktrace`/`include-exception`/`include-message` to off — the dev config leaks stack traces.
- [ ] Set `jeecg.firewall.lowCodeMode: prod` and `jeecg.jmreport.firewall.lowCodeMode: prod` to disable online design tools.
- [ ] Set `jeecg.firewall.dataSourceSafe: true` (and the JimuReport one) so Online report/chart cannot use arbitrary platform data sources.
- [ ] Consider `jeecg.firewall.is-concurrent: false` to prevent the same account logging in from multiple locations.
- [ ] Remove `stdio` (and review `sql`) from `jeecg.ai-rag.allow-sensitive-nodes`.
- [ ] Restrict CORS — the monolith default `allowedOriginPattern=*` with `allowCredentials=true` is permissive; front the app with a reverse proxy enforcing allowed origins, or override `WebMvcConfiguration`'s CORS bean.
- [ ] Validate every JustAuth `redirect-uri` against an allowlist (open-redirect class of issues has been reported on `thirdLogin`).
- [ ] Keep `spring.flyway.clean-disabled: true`.
- [ ] Set real, non-`??` credentials for any enabled integration (OSS/SMS/mail/AI) and store secrets outside the repo (env vars / Nacos / a vault).
- [ ] Stay on the latest 3.9.x patch; monitor the GitHub issue tracker and advisories.

### 5.3 Network exposure

In production, expose **only** the frontend (nginx) and, if needed, the backend API behind a reverse proxy. Do **not** expose Nacos (8848), Druid console, Knife4j, Sentinel (9000), Spring Boot Admin (9111), or xxl-job (9080) to the public internet — these are operator tools with weak or default credentials.

### 5.4 Multi-tenancy (SaaS)

JeecgBoot supports a SaaS multi-tenant model. When enabled, MyBatis-Plus rewrites SQL to scope queries by `tenant_id` (a tenant-line handler), and the `TENANT_ID` header carries tenant context. Verify tenant isolation end-to-end before hosting multiple customers — tenant-scoping bugs are a recurring class of issue in multi-tenant low-code platforms.

---

## 6. Operations

### 6.1 Build

```bash
# Monolith
cd jeecg-boot && mvn clean install -Pdev          # or -Pprod / -Pdocker
# Microservices
mvn clean install -Pdev,SpringCloud

# Frontend
cd jeecgboot-vue3 && pnpm install
pnpm build                 # generic prod build
pnpm run build:docker      # monolith docker build
pnpm run build:dockercloud # cloud docker build
```

The build skips tests by default (`maven-surefire-plugin` `skipTests=true`).

### 6.2 Run

- **Monolith:** run `org.jeecg.JeecgSystemApplication` (module `jeecg-system-start`). Listens on `:8080` at `/jeecg-boot`.
- **Microservices:** start Nacos, then gateway, system, demo, and any middleware. Each service is a separate Spring Boot jar.

### 6.3 Docker deployment

Two compose files ship at the repo root:

| File | Stack |
|---|---|
| `docker-compose.yml` | Monolith: MySQL (`jeecg-boot/db`), Redis, backend, Vue/nginx |
| `docker-compose-cloud.yml` | Microservices: MySQL (host `13306`), Redis, Nacos (`8848`), system, demo, gateway (`9999`), Sentinel (`9000`), xxl-job (`9080`), pgvector, Vue/nginx (`80`) |

One-click scripts (`start-docker-compose.sh` / `start-docker-compose-cloud.sh`, plus `.bat` variants) compile both halves and bring the stack up. They also add `jeecg-boot-system`/`jeecg-boot-gateway` and `jeecg-boot-mysql` to `/etc/hosts`.

Base image: `java:17-anolis` (Anolis/RHEL family), timezone `Asia/Shanghai`, `LANG=en_US.UTF-8`. The compose MySQL uses `utf8mb4`, `lower_case_table_names=1`, `caching_sha2_password`, `max_allowed_packet=128M`.

> [!NOTE]
> Microservice components also support **Kubernetes** and **Jenkins** per the README; Loki+Grafana and SkyWalking are referenced for distributed logging and tracing. Those are external to this repository's compose files.

### 6.4 Database migrations (Flyway)

Flyway is **disabled by default** (`spring.flyway.enabled: false`) — initial schema comes from the bundled SQL in `jeecg-boot/db/`. Versioned migrations live under `jeecg-system-start/src/main/resources/flyway/sql/{mysql,...}/` using the naming `V[date]_[seq]__[module]_[op]_[desc].sql` (run-once, `V` prefix) and `R__*.sql` (repeatable, `R` prefix, re-runs when changed). To enable auto-migration, set `spring.flyway.enabled: true` and point `locations` at your DB folder. Archive old increments and clear `flyway_schema_history` (rows `installed_rank > 1`) when starting a new baseline.

> [!WARNING]
> Enabling Flyway disables the "lazy-initialization startup acceleration" option and runs migrations on boot. Test migrations against a copy of production first; never run with `clean-disabled: false`.

### 6.5 Monitoring and logs

- **In-app**: System Monitoring menu (Redis, server/JVM, Quartz, online users, request trace, SQL via Druid, system logs, datasource, gateway routes).
- **Microservice**: Spring Boot Admin (`9111`, `admin`/`admin`), Sentinel (`9000`, `sentinel`/`sentinel`) — Sentinel rules persist to Nacos and currently govern the gateway.
- **Actuator/Prometheus**: `micrometer-registry-prometheus` is included; the exposed endpoints are `metrics`, `httpexchanges`, and a custom `jeecghttptrace`.
- **Logging**: logback (`logback-spring.xml`); xxl-job handler logs default to `logs/jeecg/job/jobhandler/` with 30-day retention.

### 6.6 Backups

Back up: the application database(s), Redis (if you rely on cached state beyond tokens), the file-upload store (`/opt/upFiles` for local mode, or the MinIO/OSS bucket), and the pgvector store if AI RAG is in use. Online Forms, generated menus, dictionaries, and permission rules all live in the database — a DB backup captures the low-code configuration.

---

## 7. Developer Internals

### 7.1 Repository structure (top level)

```text
README.md / README.en-US.md / README.ja-JP.md   Project intro (multi-language)
README-AI.md                                     AI feature notes
check_jeecgenv.py                                Environment preflight checker
docker-compose.yml / docker-compose-cloud.yml    Deployment stacks
start-docker-compose*.sh / .bat                  One-click start scripts
LICENSE                                          Apache 2.0
jeecg-boot/                                       Backend (Maven multi-module)
jeecgboot-vue3/                                   Frontend (Vue 3 / Vite / pnpm)
```

### 7.2 Frontend internals

- **Stack**: Vue 3 + TypeScript + Vite 6 + Ant Design Vue + Pinia + ECharts. Based on the Vben-admin architecture.
- **Structure** (`jeecgboot-vue3/src/`): `api/` (HTTP services), `components/` (the Jeecg component library — `Table`, `Form`, `jeecg/JVxeTable`, `Modal`, `Drawer`, `Tinymce`, `Markdown`, `Cropper`, etc.), `views/` (pages), `router/` (dynamic routing + guards), `store/` (Pinia), `hooks/`, `utils/`, `layouts/`, `locales/` (i18n), `settings/`, `directives/`, `design/` (themes).
- **Cross-cutting features**: dynamic menu routing, i18n (zh-CN/en/ja), theme switching, **qiankun** micro-frontend host (`src/qiankun/`), and an **Electron** desktop wrapper (`electron/` + `src/electron/`).
- **HTTP**: an Axios wrapper (`src/utils/http/axios/`) attaches the `X-Access-Token` header and centralizes error handling.

### 7.3 Backend code patterns

- **Layering**: `@RestController` → `IService`/`ServiceImpl` (MyBatis-Plus) → `BaseMapper` + XML. Unified `Result<T>` response envelope.
- **Config beans**: `JeecgBaseConfig` (the `jeecg.*` root), `AiChatConfig`, `AiRagConfigBean`, `WebMvcConfiguration` (CORS/static/JSON/WebSocket), `Swagger3Config`, `DruidConfig`, `RestTemplateConfig`, `TaskSchedulerConfig`. Conditions: `JeecgCloudCondition`, `CorsFilterCondition`.
- **AutoPoi Excel**: `@Excel(name="Gender", dicCode="sex")` auto-translates dictionary values on import/export (`AutoPoiDictConfig`).
- **Lombok** is used pervasively (`@Data`, `@Slf4j`) — the IDE Lombok plugin is mandatory.
- **Conventions** (from in-code comments): changes are wrapped in `update-begin`/`update-end` author/date markers and reference issue IDs — preserve these when merging upstream.

### 7.4 AI module (jeecg-boot-module-airag)

Built on **langchain4j 1.12.2** with broad provider coverage (OpenAI, Ollama, Gemini, Zhipu, Qianfan, DashScope, Anthropic) and **pgvector** for embeddings. Document parsing uses Apache **Tika** and POI (Word/Excel/PPT/PDF/text). **AI workflow** ("aiflow") is built on **liteflow** with pluggable script engines (Groovy/JS/Kotlin/Python/Aviator). **MCP** support and a tools/skills system are present (`langchain4j-mcp`, `langchain4j-skills`, experimental shell skills). `poi-tl` powers Word-template generation; `jsoup` parses HTML.

> [!CAUTION]
> The AI module bundles a **shell-execution skill** (`langchain4j-experimental-skills-shell`) and scripting engines. Combined with `allow-sensitive-nodes: stdio`, AI flows can run shell commands. Audit who can author AI flows and disable shell/stdio capabilities unless you specifically need them.

### 7.5 Testing strategy

Backend tests use `spring-boot-starter-test` + JUnit Platform, but the build **skips tests by default** (`maven-surefire-plugin` `skipTests=true`); test coverage in the repository is sparse (the briefing flagged low test coverage). The microservice `jeecg-cloud-test-*` modules are runnable samples (RabbitMQ, RocketMQ, Seata, ShardingSphere), not unit tests. If you fork JeecgBoot for a product, **add a real test suite** — especially around permissions, data-permission rules, and tenant isolation — and stop skipping tests in CI.

### 7.6 Suggested improvements (observations)

- **Tighten production defaults.** Ship a `application-prod.yml` that flips every §5 hardening item by default, so production is secure-by-default rather than secure-by-checklist.
- **Externalize secrets.** Replace the `??` placeholders and inline `signatureSecret` with environment-variable / Nacos / vault references; never commit live keys.
- **Add automated tests** for auth, RBAC, data permissions, and multi-tenant scoping; enable them in CI (`skipTests=false`).
- **Pin/scan dependencies.** The stack is large with many custom-repo artifacts; add dependency vulnerability scanning and watch the security tracker.
- **Document the monolith↔microservice switch** prominently — the `CLOUD_SERVER_KEY` condition is powerful but non-obvious to new operators.

---

## 8. Troubleshooting (operational)

### Error: application fails to start, `Cannot create datasource` / SQL errors at boot

**Cause:** Database unreachable, wrong credentials, or schema not imported.
**Solution:** Verify the `master` datasource URL/credentials in `application-{profile}.yml`; import the SQL from `jeecg-boot/db/`; confirm the DB engine matches the profile.
**Prevention:** Run `check_jeecgenv.py`; use the bundled `docker-compose.yml` MySQL for local.

### Error: `NOAUTH Authentication required` / Redis errors

**Cause:** Redis password mismatch or Redis down.
**Solution:** Set `spring.data.redis.password` and `jeecg.redisson.password`; start Redis. Redis is mandatory.

### Error: microservices can't find each other / gateway 503

**Cause:** Nacos not running or services not registered (wrong `config.server-addr`/`namespace`).
**Solution:** Start Nacos (`8848`); confirm each service's Nacos namespace/group (`springboot3` / `DEFAULT_GROUP` by default) and that they are `UP` in the Nacos console.
**Prevention:** Bring up Nacos before other services; use the cloud compose file which orders dependencies.

### Error: Sentinel dashboard is empty

**Cause:** Expected on first load — Sentinel only shows rules after a microservice request has flowed through the gateway.
**Solution:** Make a request through the gateway, then refresh. Sentinel here governs the gateway and persists rules to Nacos.

### Error: file uploads return 404 when served back

**Cause:** `jeecg.path.upload`/`webapp` not writable or not matching the static resource handler.
**Solution:** Ensure `/opt/upFiles` and `/opt/webapp` exist and are writable, or switch `jeecg.uploadType` to `minio`/`alioss` with valid keys.

### Error: scheduled jobs run multiple times in a cluster

**Cause:** Quartz misconfiguration across instances.
**Solution:** Quartz is configured clustered (`isClustered: true`) with a shared JDBC store — ensure all instances point at the same database and have synchronized clocks. For distributed jobs, prefer xxl-job.

### Error: Online report/chart can query arbitrary data / data source

**Cause:** `dataSourceSafe: false` (dev default).
**Solution:** Set `jeecg.firewall.dataSourceSafe: true` and `jeecg.jmreport.firewall.dataSourceSafe: true`, and `lowCodeMode: prod`.

### Error: `compilation failed` / dependency download errors

**Cause:** Wrong JDK, missing Lombok, or unreachable Jeecg/Aliyun Maven mirrors.
**Solution:** JDK 17+, Lombok plugin, `mvn -U` to refresh; verify the Aliyun (`maven.aliyun.com`) and Jeecg (`maven.jeecg.org`) repositories are reachable.

---

## 9. Quick Reference

### Ports

| Service | Port | Default creds |
|---|---|---|
| Backend (monolith) | 8080 (`/jeecg-boot`) | `admin`/`123456` |
| Gateway | 9999 | — |
| Nacos | 8848 | (Nacos default) |
| System cloud service | 7001 | — |
| Demo cloud service | 7002 | — |
| Spring Boot Admin (monitor) | 9111 | `admin`/`admin` |
| xxl-job admin | 9080 | `admin`/`123456` |
| Sentinel | 9000 | `sentinel`/`sentinel` |
| MySQL (cloud compose) | 13306→3306 | `root`/`root` |
| pgvector | 5432 | `postgres`/`postgres` |
| Druid console | `…/jeecg-boot/druid/` | `admin`/`123456` |
| Knife4j docs | `…/jeecg-boot/doc.html` | (basic: `jeecg`/`jeecg1314` if enabled) |

### Key build profiles

| Profile | Effect |
|---|---|
| `dev` (default) | Monolith, dev config, Nacos addr `jeecg-boot-nacos:8848`, namespace `springboot3` |
| `test` / `prod` / `docker` | Environment overrides |
| `SpringCloud` | Adds `jeecg-server-cloud` modules |

### Critical hardening settings (production)

| Setting | Dev default | Production |
|---|---|---|
| `admin` password | `123456` | change |
| `jeecg.signatureSecret` | shared default | rotate |
| `spring.datasource.druid.stat-view-servlet.enabled` | `true` | `false` / re-credential |
| `knife4j.production` | `false` | `true` |
| `server.error.include-stacktrace` | `ALWAYS` | `never` |
| `jeecg.firewall.lowCodeMode` | `dev` | `prod` |
| `jeecg.firewall.dataSourceSafe` | `false` | `true` |
| `jeecg.ai-rag.allow-sensitive-nodes` | `sql,stdio` | remove `stdio` |
| `spring.flyway.clean-disabled` | `true` | `true` (never `false`) |

### Configuration file map

| Need | File |
|---|---|
| Main config | `jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application-dev.yml` |
| Profile selector | `application.yml` |
| DB-specific | `application-{postgresql,oracle,sqlserver,dm8,kingbase8}.yml` |
| Liteflow (AI flow) | `config/application-liteflow.yml` |
| Logging | `logback-spring.xml` |
| Migrations | `flyway/sql/{db}/` |
| Schema/seed | `jeecg-boot/db/*.sql` |

---

_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._