pig-mesh/pig: a Spring Cloud RBAC platform that ships as microservices or a single bootable JAR

What pig solves, and which team it fits

Every internal tool needs the same scaffolding before it does anything useful: an authorization server, a user and role table set, a permission check that survives across services, a gateway, and a way to see whether the services are alive. pig ships that scaffolding as a Maven multi-module project so a team starts from a working login and menu tree instead of wiring Spring Authorization Server by hand.

The README is explicit about scope. The open source version keeps authentication, the gateway, user permissions, monitoring, code generation and scheduled tasks. It removes the multi-tenant, data-permission, dynamic routing, workflow, payment, WeChat official account, reporting and mobile services that appear in the commercial edition. That sentence is the most important one in the repository, because it defines the boundary of what a free build can do. If your product needs per-tenant data isolation, this is not the starting point the README describes.

The audience is therefore a Java team that already knows Spring Boot and wants an RBAC baseline it can extend, plus a Vue 3 front end in a separate repository, pig-ui. It is not aimed at someone who wants a finished admin product with every enterprise module included.

How the modules fit together at runtime

The repository layout doubles as an architecture diagram. pig-register runs Nacos on 8848, 9848 and 18080 and acts as the service registry and configuration source. pig-gateway is Spring Cloud Gateway on 9999 and is the single entry point for backend calls. pig-auth is the authorization service on 3000, built on Spring Authorization Server, and the README lists authorization code, password and refresh token as the supported login and authorization flows. pig-upms splits into pig-upms-api, the shared API surface, and pig-upms-biz on 4000, which owns the user, role and permission tables.

Around those sit the visual services: pig-monitor on 5001, pig-codegen on 5002 and pig-quartz on 5007. The pig-common modules are the shared plumbing, covering datasource switching, caching, logging, object storage, Sentinel wrappers, Swagger, OpenFeign extensions, Excel import and export, XSS handling and security utilities. A BOM module, pig-common-bom, centralises dependency versions.

One design decision worth noting: the README states that gateway routes are maintained in pig-gateway/src/main/resources/application.yml and in Nacos configuration, and that the project no longer depends on a dynamic routing table. That is a simplification, and it has a cost. Adding a service means editing configuration and restarting or refreshing, not inserting a row into a route table at runtime.

Installing pig and getting the stack up

The README lists the base environment as JDK 17 or newer, Maven 3.9 or newer, Docker with Docker Compose, and Node.js 20.19.0 or newer if you run the pig-ui front end. The Docker Compose file in the repository builds images from the local module directories, so the Maven build has to succeed before Compose has anything to run.

For the microservice layout, the documented sequence is a full build with the cloud profile, then a Compose build and start from the repository root:

mvn clean install -T 4 -Pcloud
docker compose build && docker compose up

After the containers come up, backend traffic goes through the gateway on port 9999 and the Nacos console listens on 8848. The Compose file defines pig-mysql, pig-redis, pig-register, pig-gateway, pig-auth, pig-upms, pig-monitor, pig-quartz and pig-codegen, each on a shared spring_cloud_default network, with only the gateway, Nacos and monitor ports published to the host.

If you would rather run one process instead of a mesh, the boot profile activates the pig-boot module. The README gives this pair of commands:

mvn clean install -T 4 -Pboot
docker compose -f docker-compose-boot.yml build && docker compose -f docker-compose-boot.yml up

The single application listens on 9999 as well. Note that pig-boot only participates in the build under the boot profile, so a plain install without a profile will not produce it.

Database initialisation is handled by the Docker image built from the db/ directory. According to the README, business tables are initialised into the pig schema and Nacos configuration into pig_config. The Compose service sets MYSQL_ROOT_PASSWORD to root and starts MySQL with --lower_case_table_names=1. Those defaults are for local use; anyone deploying beyond a laptop should change them before the stack is reachable.

Where the open source edition stops short

The clearest limitation is stated by the project itself. Multi-tenant support, data permission, dynamic routing, workflow, payment, reporting and mobile services are commercial modules, not part of this repository. A team that reads the feature list on the commercial site and then clones this repository will find the gap immediately. Data permission in particular is the kind of thing that is expensive to retrofit once your queries are written, because it usually means reworking the persistence layer rather than adding a filter.

The second constraint is the configuration model for routes. With dynamic routing removed, the route table lives in application.yml and Nacos. That is easier to reason about in a small deployment and harder to change at runtime in a large one. If your platform expects services to register routes on their own, you are adding that back yourself.

The third is operational weight. The microservice profile runs Nacos, MySQL, Redis and at least six application containers. That is a reasonable local development stack and a heavy one for a small team that only needs a login and a user table. The boot profile exists precisely for that case, but the README does not describe how to scale it or how it behaves under load, so capacity planning is on you.

Finally, this is a Java and Vue codebase with Chinese-language documentation on wiki.pig4cloud.com. The README itself is in Chinese. Teams without anyone who reads Chinese will be working from the code and the English fragments in the repository.

pig compared with assembling Spring Security yourself

The real alternative is not another admin template. It is starting from Spring Boot and Spring Authorization Server directly, adding Spring Cloud Gateway and a user table of your own. That path gives you exactly the modules you need and nothing else, and it avoids inheriting someone else's package structure and upgrade cadence. The cost is that you write the authorization server configuration, the token customisation, the permission checks and the front end menus before your product does anything.

pig takes the opposite position: it hands you a working set of those pieces with a fixed module boundary, and you accept that boundary. The difference shows up when requirements diverge. If you need a permission model that is not role-based, or an authorization flow the README does not list, you are modifying the platform rather than configuring it. If you need the standard flows and a conventional RBAC tree, the platform saves weeks.

A second comparison is between pig's own two deployment modes. The cloud profile gives you independent scaling and the visual services on their own ports. The boot profile collapses everything into one process on 9999. Choosing between them early matters, because the README describes them as separate build profiles with separate Compose files, and switching later means re-testing configuration that was written for the other topology.

Licence, maintenance and upgrade cost

pig is licensed under Apache 2.0. The README states that commercial use is allowed but that class author and copyright information must be retained. That is a permissive licence with an attribution condition, and it is worth reading the LICENSE file rather than relying on the summary, since the summary is not a legal document.

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent and versioned: v4.1.0 on 2026-07-08, v4.0.0 on 2026-06-05, and v3.9.2 on 2025-10-31. The jump from 3.9.2 to 4.0.0 landed alongside Spring Boot 4 and Spring Cloud 2025, which is the kind of upgrade that touches most modules at once.

That release pattern tells you what maintenance looks like in practice. You are tracking a platform that moves with the Spring ecosystem, so a major Spring Boot release becomes a project of its own. The README also notes that the package name was unified to com.pig4cloud.pig, which is a rename that will break any code you wrote against an older package layout. Budget for reading release notes before each upgrade rather than pulling the latest tag on a Friday.

Contributions go through pull requests against the current development branch, and the README asks for Java formatting to be applied first:

mvn spring-javaformat:apply

If you fork and modify, that command keeps your diffs aligned with the project's style and makes upstream patches easier to apply.

Editorial conclusion

Adopt pig if you want a Spring Authorization Server based RBAC foundation you can read end to end, and if the open source module set matches what you need to build on. Do not adopt it expecting multi-tenant isolation or data-scope rules out of the box, because the README states those live in the commercial edition. Before committing, verify that the db/ scripts initialise both the pig and pig_config schemas on your MySQL version, that the gateway routes in pig-gateway/src/main/resources/application.yml match your service names, and that port 9999 is free on the machine that will run the gateway.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pig-mesh/pig on GitHub
3. Project website
4. README
5. Releases