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:

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)

                  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)

   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

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)

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

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:

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

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

4.1 Server and framework

4.2 Datasource (Druid + dynamic)

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

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")):

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

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

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

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)

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

Key build profiles

Critical hardening settings (production)

Configuration file map