Apache ShenYu: a plugin-chain Java gateway whose routes belong in Admin, not in the gateway

Every request walks an ordered plugin chain

Apache ShenYu is a Java gateway for service proxying, protocol conversion and API governance, and its central idea is an ordered plugin chain that HTTP requests pass through. Plugins carry selector and rule matching where it applies: a selector narrows which traffic a plugin handles, and the rules beneath it decide what happens to the requests that match.

The quick start shows the shape with the divide plugin. Its selector condition matches the uri /index.html with the match operator, the selector handler points at an upstream of shenyu-demo:80 over http with a weight of 100, and the rule handler sets loadBalance to random.

Which plugins exist in a given gateway is decided when the gateway is built, because Spring Boot starters select them. When the shipped set is not enough, the extension points are custom Java plugins, SPI implementations and WASM plugin APIs. The practical consequence is that running ShenYu is partly a Java build exercise: adding behaviour means putting a starter or your own plugin on the gateway classpath, not flipping a switch in a web console.

Admin owns the configuration and gateway replicas only cache it

ShenYu splits into two processes. ShenYu Admin persists plugins, selectors, rules, metadata and authentication data, then distributes that configuration to gateway replicas, which apply each update to a local cache.

The default transport between them is WebSocket sync, which is why the quick start generates a SHENYU_SYNC_WEBSOCKET_TOKEN and hands it to the Admin container. HTTP long polling, ZooKeeper, Nacos and etcd are the alternative sync modes. Apollo still works during its deprecation release but is planned to move to an external extension, with a migration note in docs/plugin-store-apollo.md. Consul sync already lives outside the core as an external extension, described in docs/plugin-store-consul.md. If your configuration center today is Apollo or Consul, choose with that in mind: one is on its way out of the core and the other already needs a separate artifact.

Services can also announce themselves instead of being typed in by hand. Client SDKs register service addresses and API metadata with Admin, registry integrations handle discovery, and an optional Kubernetes controller reconciles Ingress and Endpoints resources.

The Docker quick start generates four secrets before anything runs

The fastest path needs Docker and OpenSSL, and every command has to run in the same shell so the exported variables carry across. The first part creates a network, generates the secrets, starts Admin and starts a sample upstream:

docker network create shenyu

export SHENYU_JWT_SECRETKEY="$(openssl rand -hex 32)"
export SHENYU_SYNC_WEBSOCKET_TOKEN="$(openssl rand -hex 32)"
export SHENYU_LOCAL_KEY="$(openssl rand -hex 24)"
export SHENYU_LOCAL_SHA512KEY="$(printf %s "$SHENYU_LOCAL_KEY" | openssl dgst -sha512 -r | awk '{print $1}')"

docker run -d --name shenyu-admin --network shenyu -p 127.0.0.1:9095:9095 \
  -e SHENYU_JWT_SECRETKEY -e SHENYU_SYNC_WEBSOCKET_TOKEN \
  apache/shenyu-admin:latest

docker run -d --name shenyu-demo --network shenyu nginx:stable-alpine

Admin receives the JWT secret and the WebSocket sync token as environment variables. SHENYU_LOCAL_KEY is the value you later send in the localKey header, and SHENYU_LOCAL_SHA512KEY is its SHA-512 digest, computed with openssl dgst and awk. Admin is published only on 127.0.0.1:9095, so with these flags it is not reachable from other machines. The upstream is a stock nginx:stable-alpine container named shenyu-demo. The gateway itself runs as a third container, shenyu-bootstrap, on the same network.

Both ShenYu images are pulled by the latest tag, so the quick start does not pin a release. The newest tagged release on GitHub is v2.7.1 from 8 July 2026; anyone reproducing a setup across machines should pin a version explicitly. Once both services are up, Admin answers on port 9095 and the gateway on 9195:

curl -fsS http://localhost:9095/actuator/health
curl -fsS http://localhost:9195/actuator/health

A route posted to one gateway disappears with that gateway

The quick start configures its sample route by calling the gateway directly: a POST to http://localhost:9195/shenyu/plugin/selectorAndRules with a JSON body naming the divide plugin, and a localKey header carrying SHENYU_LOCAL_KEY. That call changes only the gateway instance that received it. It does not write the route to Admin, so other replicas never see it and Admin has nothing to redistribute.

Admin, in turn, defaults to an in-memory H2 database. Put together, the demo setup has no durable home for routes at all: the gateway-local route was never stored centrally, and an Admin left on in-memory H2 does not keep its data on disk. For anyone moving past a demo, the consequence is concrete. Centrally managed, durable routes have to be configured in Admin, and Admin has to be backed by a persistent database. The repository carries a db/ directory at the top level; check the official documentation at shenyu.apache.org for the supported databases before planning a deployment.

Once the route exists, verification is a plain request through the gateway:

curl -i http://localhost:9195/index.html

A working setup returns the NGINX welcome page, served from shenyu-demo through ShenYu.

SOFA, Tars, Hystrix and Consul have left the default build

Several integrations have moved out of the default gateway distribution into plugin-store starters. SOFA and Tars gateway plugins are now external starters. To proxy those protocols you install the matching starter on the gateway classpath, while Admin metadata, the client registration SDKs and the existing protocol configuration examples stay as they were.

Hystrix is deprecated and survives only as an external plugin, covered in docs/plugin-store-hystrix.md. Resilience4j and Sentinel are the fault-tolerance options that remain in the core. Consul sync has the same external status, and Apollo is scheduled to follow.

This is the part of an upgrade that breaks quietly. A gateway built from the default distribution that used to proxy a SOFA or Tars service, or relied on Hystrix for circuit breaking, will not have those plugins until you add the starters yourself. Admin will still hold the metadata for those services, so the configuration looks intact while the gateway has no plugin to execute it. Teams on those stacks should budget for a custom gateway build rather than the default distribution, and should plan a move from Hystrix to Resilience4j or Sentinel.

Dubbo, gRPC, MQTT listeners and an MCP server plugin share one chain

Upstream support covers HTTP and Spring Cloud services, WebSocket connections, and Apache Dubbo and gRPC backends. Optional TCP and MQTT listeners add ingress beyond HTTP, which matters if device traffic and API traffic are meant to pass through the same gateway.

On the traffic side, plugins provide a WAF, request signing, authentication, load balancing, rate limiting and fault tolerance. Responses can be cached in memory or in Redis, URLs can be rewritten or redirected, and requests and responses can be transformed in flight. Observability comes from metrics and logging plugins that can ship to Kafka and Elasticsearch, while Admin sends alerts by email and DingTalk.

The newest group targets AI traffic: an AI proxy, prompt processing, token limits, sensitive-word filtering, AI request and response transformation, and an MCP server plugin that speaks SSE and Streamable HTTP. These sit in the same plugin chain as everything else, so a team already running ShenYu in front of Java services can put model calls behind the same authentication and rate limiting plugins instead of deploying a separate AI gateway.

The Makefile builds images with tests switched off

The repository is a Maven multi-module build with a wrapper, mvnw, and the Makefile drives it. The build-admin target runs the wrapper against shenyu-dist/shenyu-admin-dist and build-bootstrap against shenyu-dist/shenyu-bootstrap-dist, both with the release profile, -DskipTests, and Javadoc, RAT and JaCoCo checks turned off. VERSION defaults to 2.7.1-SNAPSHOT. Images are named apache/shenyu-admin and apache/shenyu-bootstrap on docker.io with the tag latest unless you override REGISTRY, REPOSITORY_PREF or TAG, and the default target, build-all-image, builds both. A smoke-image target runs script/docker-image-smoke.sh to check the container runtime contract of the images.

Because skipping tests is baked into these targets, an image built this way has not run the test suite. If you are shipping your own plugins in a custom gateway image, run the tests as a separate step rather than trusting a green make. Windows contributors get a dedicated note on checkout and long-path problems in docs/windows-checkout.md.

The project is moving: the last push landed on 3 November 2026, and releases v2.7.0.2, v2.7.0.3 and v2.7.1 arrived in August 2025, November 2025 and July 2026.

Editorial conclusion

Apache ShenYu fits Java teams that want a gateway they extend through Spring Boot starters and custom plugins, with Spring Cloud, Dubbo or gRPC upstreams and one Admin pushing configuration to every replica. It fits poorly if you expect routes set by calling a gateway to stick, or if you depend on SOFA, Tars, Hystrix or Consul and expect them in the default build. Before adopting it, decide on a sync mode, back Admin with a persistent database instead of in-memory H2, and pin image versions rather than running latest.

Frequently asked questions

Official sources

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