Overview

Relevant source files

• .asf.yaml
• README.md
• pom.xml

Apache ShenYu is a Java-based API Gateway designed for service proxy, protocol conversion, and API governance in microservices architectures. It functions as a reactive gateway built on Spring Boot 3.x and Project Reactor, routing and transforming requests to backend services through a plugin-based architecture.

This document provides a high-level overview of ShenYu's architecture, core components, and request processing model. For detailed information about specific subsystems:

• For module structure and Maven organization, see Project Architecture and Module Structure
• For plugin system details, see Plugin Catalog
• For database schema, see Data Model and Database Schema
• For deployment instructions, see Deployment

System Architecture

Apache ShenYu implements a control plane/data plane separation pattern. shenyu-admin manages and persists configuration; shenyu-bootstrap executes the request pipeline entirely from in-memory caches.

ShenYu Control Plane / Data Plane (key class names shown)

Sources: pom.xml30-52 README.md59-90

Core Components

shenyu-bootstrap

The shenyu-bootstrap module is the gateway runtime that handles incoming requests. It runs as a Spring Boot application and processes traffic through a chain of plugins.

Key Classes:

• org.apache.shenyu.bootstrap.ShenyuBootstrapApplication - Main entry point
• org.apache.shenyu.web.handler.ShenyuWebHandler - Request handler
• org.apache.shenyu.plugin.base.chain.DefaultShenyuPluginChain - Plugin execution chain

The bootstrap module requires Java 17+ and uses Netty for reactive request handling.

Sources: pom.xml36 README.md107-112 pom.xml84

shenyu-admin

The shenyu-admin module provides the control plane for managing gateway configuration through a web UI and REST API. It persists configuration to a relational database and notifies gateway instances of changes.

Key Components:

• Admin web UI (React) on port 9095
• REST API for configuration management
• SelectorService — manages routing selectors
• RuleService — manages routing rules
• PluginService — manages plugin configurations

Sources: pom.xml31 README.md100-105

Database Schema

ShenYu supports multiple database backends with a unified schema:

Database	Support Status
H2	Development/testing
MySQL	Production
PostgreSQL	Production
Oracle	Production
OpenGauss	Production
OceanBase	Production

Core Tables:

• plugin — plugin definitions and global configuration
• selector — module-level routing rules
• rule — method-level routing rules
• meta_data — service metadata for RPC protocols
• dashboard_user — admin user accounts
• app_auth — application authentication credentials

See page 2 for full schema documentation.

Sources: pom.xml108-192

Request Processing Flow

Request Flow Steps:

1. Request Reception: Netty server receives request on port 9195
2. Context Creation: GlobalPlugin (order=-1) initializes ShenyuContext
3. Plugin Execution: Plugins execute in order determined by PluginEnum.code
4. Selector Matching: Each plugin matches against configured selectors
5. Rule Matching: If selector matches, evaluate associated rules
6. Request Processing: Matched rule's handler processes the request
7. Backend Proxy: Appropriate protocol plugin forwards to backend
8. Response Handling: Response plugins modify output if configured

Sources: README.md166-187 README.md190-199

Multi-Module Maven Structure

The project is organized as a multi-module Maven build:

Sources: pom.xml30-52

Key Features

Protocol Support

ShenYu provides proxy plugins for multiple RPC protocols:

Protocol	Plugin	Port	Description
HTTP	divide	9195	HTTP/HTTPS proxy
Apache Dubbo	dubbo	9195	Dubbo RPC proxy
gRPC	grpc	9195	gRPC protocol conversion
Spring Cloud	spring-cloud	9195	Spring Cloud service proxy
WebSocket	websocket	9195	WebSocket protocol support
Motan	motan	9195	Motan RPC proxy
SOFA RPC	sofa	9195	SOFA RPC proxy
Tars	tars	9195	Tars RPC proxy

Sources: README.md81 pom.xml122 pom.xml128-130

Security and Traffic Control

ShenYu includes plugins for authentication, authorization, and traffic management:

• Authentication: Sign, OAuth 2.0, JWT, Casdoor
• Authorization: App authentication via app_auth table
• Traffic Control: Rate limiting, Hystrix, Sentinel, Resilience4j
• Security: WAF plugin for request filtering

Sources: README.md82-83

Data Synchronization Strategies

Configuration changes propagate from Admin to Bootstrap instances through seven synchronization mechanisms:

Strategy	Implementation Class	Use Case
WebSocket	WebSocketDataChangedListener	Default, low latency
ZooKeeper	ZookeeperDataChangedListener	Distributed coordination
Nacos	NacosDataChangedListener	Alibaba ecosystem
etcd	EtcdDataChangedListener	Kubernetes environments
HTTP Long Polling	HttpLongPollingDataChangedListener	No external dependencies
Apollo	ApolloDataChangedListener	Apollo configuration center
Polaris	PolarisDataChangedListener	Tencent service governance

Each gateway instance maintains an in-memory ConcurrentHashMap cache updated by the chosen synchronization strategy.

Sources: README.md190-199 pom.xml131-162

Service Discovery

ShenYu integrates with multiple service registries:

• ZooKeeper
• Nacos
• Eureka
• Consul
• Kubernetes
• etcd
• Polaris

The DiscoveryUpstreamService abstracts registry interactions, and UpstreamCheckService performs health checks on discovered services.

Sources: README.md81 pom.xml116-162

Multi-Tenancy

Namespace isolation is supported via the namespace_id column in configuration tables:

• selector.namespace_id
• rule.namespace_id
• meta_data.namespace_id
• app_auth.namespace_id

The namespace_plugin_rel table maintains plugin configurations per namespace. See page 4.10 for full multi-tenancy documentation.

Sources: pom.xml30-52

Plugin Architecture

Plugins execute in a defined order specified by PluginEnum.code. Each request traverses all enabled plugins in the DefaultShenyuPluginChain via the ShenyuPlugin.execute() method.

Plugin execution order (PluginEnum sort values)

Plugins are categorized by function:

Category	Order Range	Examples
Infrastructure	-1 to 15	GlobalPlugin, CachePlugin, MetricsPlugin
Security	20–50	SignPlugin, JwtPlugin, WafPlugin
Traffic Control	60–150	RateLimiterPlugin, SentinelPlugin, HystrixPlugin
Transformation	70–120	RequestPlugin, RewritePlugin, RedirectPlugin
Proxy	199–320	DividePlugin, DubboPlugin, GrpcPlugin, WebSocketPlugin
Response	220–420	ResponsePlugin, CryptorResponsePlugin

Sources: README.md164-175

AI Integration (v2.7.1+)

Version 2.7.1 introduces AI proxy capabilities through the aiProxy plugin:

Supported Providers:

• OpenAI
• DeepSeek
• Moonshot
• OpenAPI (generic)
• ALiYun

Configuration:

• provider - AI service provider
• baseUrl - API endpoint URL
• model - Model identifier (e.g., gpt-4o-mini)
• apiKey - Authentication key
• temperature - Sampling temperature (0-1)
• maxTokens - Maximum response tokens
• stream - Enable streaming responses
• prompt - System prompt template

Sources: pom.xml189-191

Quick Start

To deploy ShenYu with Docker:

Default admin credentials:

• Username: admin
• Password: 123456 (stored SHA-512 hashed in the database)

Sources: README.md92-112

Technical Requirements

• JDK: 17 or higher
• Spring Boot: 3.3.1
• Build Tool: Maven 3.8+
• Node.js: v12.14.1+ (for Admin UI)
• Databases: H2, MySQL 8.x, PostgreSQL, Oracle, OpenGauss, OceanBase

Sources: pom.xml84 pom.xml138 README.md202-205

Configuration Hierarchy

ShenYu's routing configuration follows a three-level hierarchy:

1. Plugin: Global settings for a protocol or feature
2. Selector: Module-level routing (e.g., by URI prefix)
3. Rule: Method-level routing with specific conditions

Each level has associated conditions evaluated using operators: match, =, regex, contains, exclude, startsWith, endsWith, pathPattern.

Sources: README.md178-187

Monitoring and Observability

ShenYu supports multiple observability integrations:

• Metrics: Prometheus exporter via shenyu-plugin-metrics
• Logging: Elasticsearch, ClickHouse, Kafka backends
• Tracing: OpenTelemetry integration
• Health Checks: Upstream health monitoring with zombie recovery

The operation_record_log table provides audit trails for configuration changes.

Sources: README.md84 shenyu-admin/src/main/resources/sql-script/h2/schema.sql357-365