# XXL-CONF is a configuration centre that only needs a database

> XXL-CONF is a Java distributed configuration centre and service registry whose distinguishing claim is that it depends on nothing but a database, with no message broker, no cache server and no coordination service. Configuration pushes to clients in seconds through an internal broadcast mechanism, and clients fall back to a local snapshot file when the centre is unreachable.

**xuxueli/xxl-conf** — A configuration center and service registry.（分布式配置中心与注册中心，XXL-CONF）

- Repository: https://github.com/xuxueli/xxl-conf
- Website: http://www.xuxueli.com/xxl-conf/
- Stars: 696 · Forks: 380
- Language: Java
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/xuxueli-xxl-conf

## One database is the entire infrastructure requirement

XXL-CONF is a distributed configuration centre and registration centre, providing dynamic configuration management, service registration and discovery and other core capabilities.

The claim that defines the project is the second feature in both lists, and it is repeated for the configuration centre and the registry centre. Lightweight, depending only on a DB with no other third-party dependencies, so building, deploying and integrating is simple, with a one minute learning curve.

That is a real architectural decision rather than a marketing line. The usual distributed configuration centres need a message broker for the push mechanism, and often a separate cache tier. XXL-CONF replaces the broker with an internal broadcast mechanism, and the client side caching with a multi-level cache design that is described as giving very high read performance, with a single machine able to handle high-concurrency configuration reads.

The reason the design is possible is stated for the cross-datacentre case. Because the server side is a stateless service and the cluster nodes offer equivalent service, deploying across datacentres only requires requesting the configuration centre in your own datacentre, which achieves active-active across sites.

The Java project is GPL-3.0 licensed, the homepage is at xuxueli.com/xxl-conf, the last push was on 2026-10-09, and the releases are 2.2.1 from 2026-06-07, 2.2.0 from 2026-01-02 and 2.1.0 from 2025-10-11.

## The configuration centre runs on twenty-two numbered features

The feature list for the configuration centre is numbered to twenty-two, and reading it in order tells you what the system does and in what order the guarantees hold.

The first three are the adoption story: simple and easy to use with flexible integration, lightweight with only a database dependency, and a WebUI that provides an online management interface so configuration data can be operated on directly and intuitively.

Then availability and performance. The configuration centre supports cluster deployment, improving disaster recovery and availability. The high performance claim comes from the local cache on the client side together with the multi-level cache design, so configuration reads are very fast and a single machine can carry high-concurrency reads.

Real-time guarantees come next. The system has an internal broadcast mechanism, and for changes such as configuration modification, addition and deletion, it supports pushing changed configuration to clients within seconds. The consistency strategy is a combination of startup warm-up, full inspection and incremental listening, so the startup phase actively initialises the full remote configuration locally, and there is a periodic configuration comparison inspection plus incremental change detection.

Then the hot update promise: after configuration data changes, the client configuration data updates in real time and takes effect, with no need to restart the service machine.

And the degradation story, which is the most interesting of the set. The client periodically syncs configuration data to a local configuration snapshot file, and in the extreme case where the configuration centre is unavailable, such as a centre outage, the client degrades to using the local snapshot file to guarantee system availability.

The remaining items are about the shape of the data and the access pattern. Multiple data types, String, Boolean, Short, Integer, Long, Float, Double and similar. Multiple access methods through API, annotations and Listener. Configuration change listening with custom Listener logic, for example to dynamically refresh a JDBC connection pool. Multiple environments as custom namespaces with data isolated between them. And cross-language support through a language-independent configuration centre OpenAPI in RESTFUL form, giving the ability to pull configuration and to be aware of changes in real time.

## The registry centre reuses the same machinery with a different job

The registry centre is described in twelve features, and the first four are literally the same as the configuration centre's. Simple and easy to use, lightweight with only a database dependency, cluster deployment for disaster recovery and availability, and the same high performance claim from local caching and a multi-level cache design.

From the fifth feature the two lists diverge, and the differences tell you what a registry has to do that a configuration does not.

The real-time claim is sharper here. With the internal broadcast mechanism, changes such as a new service coming online or going offline can be pushed to clients within one second.

Then there is the multi-state feature, which is the most substantial part of the registry design. A service has built-in multiple states supporting a range of business scenarios. The normal state supports dynamic registration and discovery, with service registration information updated in real time. The locked state means registration information is maintained manually and stays fixed. The disabled state means the service must not be used and its registration information is fixed as empty.

That is a capability most registries lack. A locked service is one that is deliberately out of the pool but still visible, which is how you drain a node during a deploy without deregistering it, and a disabled service is one that is present in the registry with no instances, so clients fail fast rather than waiting for a timeout.

The registry also exposes an OpenAPI for service registration, deregistration, heartbeat and query, again in a language-independent RESTFUL form, and the multi-environment support works the same way with namespaces isolating the data.

The access token model is identical in both lists. To improve system security, the server and client perform a security check, and communication is only allowed when the AccessToken on both sides matches.

## The access token and the user model are the security surface

Two of the configuration centre's later features are about who can do what, and they are worth separating because they operate at different levels.

The access token is the machine-to-machine control. To improve system security, the server and client perform a security check, and only a matching AccessToken on both sides permits communication. This is a shared secret between the configuration centre and the client library, and it is a simple model, which is appropriate for a system whose selling point is that it has few dependencies.

User management is the human side. It supports adding and maintaining users online, with two types, ordinary users and administrators, for flexible control of system permissions.

The configuration permission control is project-scoped. Permissions are controlled along the project dimension, and administrators have all project permissions while ordinary users have view and manage permission only for the projects they have been assigned.

The project granularity is the detail that matters in practice, because a configuration centre usually holds secrets for many systems, and per-project scoping is the minimum that lets one team be prevented from reading another team's configuration.

Two other features are about recovery and about scale. Historical version rollback records configuration change history promptly after a change, supporting comparison of historical configuration versions and quick retrospective. And containerisation provides official Docker images that are continuously updated and pushed to DockerHub.

The empty configuration handling is the small one that shows the operational thinking. It proactively caches null or non-existent type configuration to avoid configuration requests penetrating to the remote configuration server and triggering an avalanche problem.

## The compose file shows a two-service deployment with a schema you mount yourself

The docker-compose file is short and it shows how the database-only claim works in practice.

There are two services. The mysql service runs the mysql:8.4 image as xxl-conf-mysql, with the root password and the database name xxl_conf, port 3306 published, and the character set set to utf8mb4 with the utf8mb4_unicode_ci collation. The healthcheck runs mysqladmin ping against localhost with a 20 second timeout and 10 retries.

The schema is mounted in rather than created by the app. The tables_xxl_conf.sql file from the doc/db directory is mounted into the docker-entrypoint-initdb.d path, and the comment notes it only executes on the first database initialisation. The persistent data, configuration and log directories are mounted from a host path that defaults to a path under the user home directory and is recommended to be customised.

The xxl-conf-admin service builds from the xxl-conf-admin directory with its own Dockerfile, and the image is tagged as local by default, with a commented alternative to pull a published version from DockerHub. The environment passes the Spring datasource URL, username and password as PARAMS arguments, and the same root password as the database service, with the comments noting that they must match. Port 8080 is published, and the service waits for the database to report healthy before starting.

Both services join a bridge network named xxl-conf-network.

That last detail is the one to notice. The admin service talks to the database by service name, so there is no host port in the datasource URL, and the only published port for the application is 8080. The database port is published for the developer's convenience rather than for the application.

## A project that has been in production since 2015

The development section is short and it is the oldest part of the documentation, and it reads differently from the feature lists.

It says that in 2015 the XXL-CONF project repository was created on GitHub with the first commit, followed by system structure design, UI selection and interaction design. It states that XXL-CONF has since been connected into the online product lines of several companies, with use cases including e-commerce business, O2O business and dynamic configuration of core middleware, and that as of 2018-03-15 the companies connected included a list of named Shenzhen and Zhejiang organisations.

That dated list is worth reading for what it is. The documentation is a snapshot of 2018, kept in a repository that has been continuously updated since. The feature lists are current, the development history is not.

For an evaluator, that tells you something useful about the project's shape. The configuration and registry centres are the product, and the surrounding work is packaging, the admin interface, the client libraries and the documentation. The repository layout matches that division, with xxl-conf-admin/ for the web interface, xxl-conf-core/ for the shared core, and xxl-conf-samples/ for the sample clients, alongside a pom.xml at the root as a Maven multi-module build.

The samples directory is the part to look at first if you are integrating, because the client library behaviour is easier to learn from a working example than from the feature list. The doc/ directory holds the database schema and the documentation sources, and there is a docker-compose.yml at the root for local runs.

The project is published to Maven Central under the com.xuxueli group with the xxl-conf-core artifact, and it is maintained by xuxueli with the copyright held from 2015 onward. The documentation is Chinese, with a community page and a donate link alongside it, and the contribution guidance is to open a pull request for a bug fix or an issue to discuss a new feature.

## Conclusion

Adopt XXL-CONF if you want a configuration centre and service registry you can run without adding a broker to your infrastructure, since the whole design is a database plus a broadcast mechanism. Skip it if you need cross-datacentre active-active with a hard consistency guarantee, since the design is stateless servers with local caching rather than a consensus layer, and if you need a maintained community around a Chinese-language project, since the documentation is Chinese. Verify first that your team can work with the Chinese documentation, that the MySQL schema file applies to your database version, and how you want to handle the AccessToken scheme, since it is the only authentication between server and client.

## FAQ

### What infrastructure does XXL-CONF need?

Only a database. Both the configuration centre and the registry centre list lightness as depending only on a DB with no other third-party dependencies, and the docker compose file runs just a MySQL service and the admin service, with the schema mounted in from the doc/db directory.

### How does XXL-CONF push configuration changes to clients?

It uses an internal broadcast mechanism, and changes such as modifications, additions and deletions are pushed to clients within seconds, so the client configuration updates and takes effect without restarting the service. Consistency comes from a combination of startup warm-up, periodic full inspection and incremental change detection.

### What happens when the XXL-CONF server is unavailable?

The client periodically syncs configuration data to a local snapshot file and degrades to using it in the extreme case where the configuration centre is down, such as a centre outage, so the system stays available. A separate safeguard caches null or non-existent configuration values so those requests do not reach the remote server and cause an avalanche.

## Sources

- [License: GPL-3.0](https://github.com/xuxueli/xxl-conf/blob/master/LICENSE)
- [Project website](http://www.xuxueli.com/xxl-conf/)
- [README](https://github.com/xuxueli/xxl-conf/blob/master/README.md)
- [Releases](https://github.com/xuxueli/xxl-conf/releases)
- [xuxueli/xxl-conf on GitHub](https://github.com/xuxueli/xxl-conf)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xuxueli-xxl-conf