GeezerVison

Apache ShenYu is a Java-based gateway for service proxying, protocol conversion, and API governance. An extensible plugin chain processes requests, while ShenYu Admin manages and distributes configuration to gateway replicas.

Start with the English documentation, 中文文档, or the official downloads.

Use Docker and OpenSSL to start ShenYu Admin, a gateway, and an example HTTP service. Run the commands below in the same shell.

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

docker run -d --name shenyu-bootstrap --network shenyu -p 127.0.0.1:9195:9195 \
  -e SHENYU_SYNC_WEBSOCKET_URLS=ws://shenyu-admin:9095/websocket \
  -e SHENYU_SYNC_WEBSOCKET_TOKEN \
  -e SHENYU_HEARTBEAT_SERVERLISTS=http://shenyu-admin:9095 \
  -e SHENYU_LOCAL_ENABLED=true -e SHENYU_LOCAL_SHA512KEY \
  apache/shenyu-bootstrap:latest

Admin listens on http://localhost:9095; the gateway listens on http://localhost:9195. Wait for both services to start, then check their health endpoints:

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

The following request configures the divide plugin on this gateway to forward /index.html to the example service:

curl -fsS http://localhost:9195/shenyu/plugin/selectorAndRules \
  -H 'Content-Type: application/json' \
  -H "localKey: ${SHENYU_LOCAL_KEY}" \
  -d '{
    "pluginName": "divide",
    "selectorHandler": "[{\"upstreamUrl\":\"shenyu-demo:80\",\"protocol\":\"http\",\"weight\":100}]",
    "conditionDataList": [
      {"paramType": "uri", "operator": "match", "paramValue": "/index.html"}
    ],
    "ruleDataList": [{
      "ruleHandler": "{\"loadBalance\":\"random\"}",
      "conditionDataList": [
        {"paramType": "uri", "operator": "match", "paramValue": "/index.html"}
      ]
    }]
  }'

This request updates only this gateway instance; it does not write the route to Admin. For centrally managed, durable routes, configure them in Admin with a persistent database instead of the default in-memory H2 database.

SOFA and Tars support is no longer bundled in the default gateway distribution. To run those protocols, install the matching plugin-store starter in the gateway classpath and keep using the existing Admin metadata, client registration SDKs, and examples for protocol configuration.

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

The response should contain the NGINX welcome page served through ShenYu.

ShenYu (神禹) is an honorific name for Xia Yu, an ancient Chinese ruler also known as Da Yu. He is remembered for crossing the Yellow River three times for the benefit of the people and successfully controlling its floods. Alongside Yao and Shun, he is regarded as one of ancient China's three greatest kings.

The name reflects three ideas:

• It promotes the traditional virtues of Chinese civilization.
• It echoes a gateway's central role in governing traffic.
• It expresses the community's commitment to being fair, just, open, and meritocratic, in tribute to ShenYu and in keeping with the Apache Way.

• Contribute to ShenYu
• Windows checkout and long-path troubleshooting
• Split Java client migration and contribution guide
• Join the development mailing list

The Known Users page lists registered users in registration order.

Organizations using Apache ShenYu are welcome to register through GitHub issue #68. Registration is for open source users only.

Apache ShenYu is licensed under the Apache License, Version 2.0.