1. Project Overview

A rapid development scaffold for quickly building enterprise-level backend management systems. It also provides various convenient starters for functional extensions. Key features include separate frontend and backend user management, menu permissions, data permissions, scheduled tasks, access logs, operation logs, exception logs, unified exception handling, XSS filtering, SQL injection prevention, and more.

2. Open Source License

Licensed under MIT

3. Screenshots

Demo:

4. Feature Overview

Business Modules

BallCat provides the following five business modules to meet common backend management requirements. Users can integrate them as needed:

• ballcat-auth (Authorization Module) : Provides an authorization server supporting OAuth2, integrating features such as login image verification codes and an AES password decryption filter. It currently uses Spring-Security-OAuth2 as its foundation and will migrate to the spring-authorization-server project in the future.

• ballcat-system (System Module) : Provides essential core features for backend management systems, including user management, role management, menu management, organizational structure, dictionary management, and system configuration.

• ballcat-log (Logging Module) : Provides logging functionality for login logs, operation logs, and access logs. It also provides TraceId to correlate all log information associated with a single request. Logs are stored in MySQL by default, and users can customize the log processing logic as needed.

• ballcat-i18n (Internationalization Module) : Provides a database-based solution for storing internationalization configuration and information, with dual local + Redis caching to improve internationalization processing efficiency.

• ballcat-notify (Notification Module) : Currently provides system announcement functionality. Notification-related features will be added in the next version.

Functional Modules

The functional modules are independent of business logic. Projects other than BallCat can also integrate these modules to extend their functionality. Users can select and integrate modules according to their actual business requirements.

Including, but not limited to, the following features :

• Data permission control implemented at the ORM layer, using Jsqparse to parse SQL and inject SQL statements to enforce permission scopes.

• Internationalization support, which not only supports Spring's native file-based configuration but also allows custom dynamic loading of internationalization configurations.

• Annotations supporting Redis caching, distributed locks, cache breakdown prevention, global key prefixes, and other features.

• Quickly implement Excel import and export functionality using annotations.

• Payment functionality: Includes Alipay, WeChat Pay, USDT cryptocurrency, and more.

• An object storage wrapper based on the S3 protocol, allowing a single codebase to support most cloud platforms, such as Alibaba Cloud, Qiniu Cloud, and Tencent Cloud.

Currently available functional modules

See the README.md documentation for details

5. Tech Stack

Tech Stack

Spring Boot、Spring Security、Spring Authorization Server、Mybatis Plus、Hutool

The BallCat organization aims to provide a series of foundational capabilities for rapid project development, making it easier for users to quickly extend functionality according to project requirements.

When developing with other admin management scaffolding frameworks in the past, developers often encountered situations where secondary development was required due to project-specific business requirements. After extensive development, once the original project released an update, keeping custom modifications synchronized became difficult.

To solve this problem, BallCat has designed all its business and functional components as pluggable dependencies, allowing users to freely assemble and remove them.

During development, users can introduce the modules provided by BallCat as dependencies. When the BallCat project is upgraded, users only need to update the version numbers to obtain the latest features.

BallCat has published all JAR packages to the Maven Central Repository. It also provides detailed changelogs and incremental SQL scripts for each version update.

Quick Setup

Follow this guide to quickly set up a standalone admin management system using BallCat.

Environment Preparation

Before getting started, make sure you have configured the following environment:

WARNING

For MySQL versions 5.7.x and earlier, support for NULL as the default value of the timestamp type must be enabled. Execute the following SQL before running the database scripts.

set session explicit_defaults_for_timestamp = 1;

Note: This setting only takes effect within the current session, so you must execute the SQL scripts in the same session after applying the setting.

Additionally, please install the Lombok plugin in your development tool. For instructions on using Lombok, refer to its official documentationopen in new window.

Recent versions of IntelliJ IDEA already include the Lombok plugin.

Database configuration

Version: MySQL 5.7.8+
Default character set: utf8mb4
Default collation: utf8mb4_general_ci

• Execute the database scripts in the ballcat/doc directory in the following order:

# Database creation script
scheme.sql
# Core database
ballcat.sql

# Internationalization-related SQL. Skip this script if internationalization is not required.
ballcat-i18n.sql

The default oauth2_registered_client script includes a test client. This client is intended for development and testing environments only. When logging in, it bypasses the CAPTCHA verification and password decryption processes. Please delete this client in production environments.

Note: The files under ballcat/doc/update_sql are incremental SQL scripts for upgrading between versions. They do not need to be executed during the initial setup.
When upgrading your BallCat project, for example, from version 0.5.0 to version 0.6.0, you must execute the 0.6.0.sql script in the update_sql folder.

Configure Local Hosts

We recommend using the switchHost software to manage your hosts configuration!

You can also modify the local hosts file directly:
On Windows, the hosts file is located at C:\Windows\System32\drivers\etc\hosts

Add the following host entries:

127.0.0.1 ballcat-mysql
127.0.0.1 ballcat-redis
127.0.0.1 ballcat-job
127.0.0.1 ballcat-admin

Replace 127.0.0.1 with your development environment's IP address as needed.

Server Preparation

See the README.md documentation for details