Apache ShenYu 安装指南

目标：基于 Ubuntu 22.04 真实环境实测的 Apache ShenYu 2.7.1 二进制安装指南，覆盖 OpenJDK 17 安装、admin 与 bootstrap 发行包下载解压与 sha512 校验、H2 存储确认、默认账号密码初始化、divide 选择器规则上游注册、网关代理回显验证与 systemd 托管开机自启，附常见故障排查。

一、环境信息

项目	说明
操作系统	Ubuntu 22.04.5 LTS（GNU/Linux 5.15.0 x86_64）
Java	OpenJDK 17.0.20.1（openjdk-17-jre-headless，apt 安装）
ShenYu 版本	Apache ShenYu 2.7.1（dlcdn.apache.org 官方二进制）
管理端	shenyu-admin，默认端口 9095
网关端	shenyu-bootstrap，默认端口 9195
数据同步	websocket（bootstrap 订阅 admin 推送）
元数据库	H2 内存库（演示与开发），生产建议 MySQL 或 PostgreSQL
堆内存限制	admin 与 bootstrap 各 -Xms256m -Xmx256m

ShenYu 由两个独立进程组成：shenyu-admin（管理端，负责配置管理、插件管理、用户认证并向网关推送配置）与 shenyu-bootstrap（网关端，负责流量代理与插件执行）。二者均以 spring boot fat jar 方式启动，安装过程互不依赖，仅运行期通过 websocket 同步配置。

二、前置条件

具备 root 或 sudo 权限的 Ubuntu 22.04 环境。
网络可达 dlcdn.apache.org（下载二进制包）。
至少 2GB 空闲磁盘（两个 tar.gz 共约 390MB，解压后约 1GB）。
一个可用于演示的后端 HTTP 服务（本文用 python3 内置 http.server 模拟）。

三、版本选型说明

发行目录 https://dlcdn.apache.org/shenyu/ 当前提供 2.7.0.3 与 2.7.1 两个版本目录，2.7.1 目录下提供 admin-bin 与 bootstrap-bin 两类 tar.gz 包及配套 sha512、asc 校验文件：

包名	说明
apache-shenyu-2.7.1-admin-bin.tar.gz	管理端二进制发行包，内含 lib、conf、bin、db 目录
apache-shenyu-2.7.1-bootstrap-bin.tar.gz	网关端二进制发行包，内含 lib、conf、bin 目录

实际可下载的版本以发行目录实时列表为准；历史版本请改用 archive.apache.org/dist/shenyu/。本文全部命令与回显均在 2.7.1 下实测。

四、部署步骤

4.1 安装 OpenJDK 17 与基础工具

sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jre-headless wget curl iproute2 procps python3

实测回显（节选）：

Setting up openjdk-17-jre-headless:amd64 (17.0.20.1+1-1-22.04-Ubuntu) ...
Processing triggers for man-db (2.10.2-1) ...

验证版本：

$ java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

4.2 下载并校验发行包

$ cd /opt
$ sudo wget -q https://dlcdn.apache.org/shenyu/2.7.1/apache-shenyu-2.7.1-admin-bin.tar.gz
$ sudo wget -q https://dlcdn.apache.org/shenyu/2.7.1/apache-shenyu-2.7.1-bootstrap-bin.tar.gz
$ ls -l apache-shenyu-2.7.1-*
-rw-r--r-- 1 root root 162479596 Jul  8 03:10 apache-shenyu-2.7.1-admin-bin.tar.gz
-rw-r--r-- 1 root root 245983537 Jul  8 03:10 apache-shenyu-2.7.1-bootstrap-bin.tar.gz

用官方 sha512 文件校验完整性（值以官方发布为准，逐字符比对）：

$ curl -s https://dlcdn.apache.org/shenyu/2.7.1/apache-shenyu-2.7.1-admin-bin.tar.gz.sha512
a8d06a7bb7837412d4bc327be30cac2ccc79b9e4dca0b5ed20d635ede3bd5f0da01ddfa74cefb33e71d860cf28685d3c952544075d36cc74fd38dc1e6143dbc9  apache-shenyu-2.7.1-admin-bin.tar.gz
$ sha512sum apache-shenyu-2.7.1-admin-bin.tar.gz
a8d06a7bb7837412d4bc327be30cac2ccc79b9e4dca0b5ed20d635ede3bd5f0da01ddfa74cefb33e71d860cf28685d3c952544075d36cc74fd38dc1e6143dbc9  apache-shenyu-2.7.1-admin-bin.tar.gz

bootstrap 包同理校验（官方值 df4e9a12faf4bdaa3dd4170ae19ca302ff3ac94c57cd87d43d37da06084aaa55f02203d3b2d0cafede1f84fcaf0354d917efea7e399a6308e7d0181e05dba724）。

4.3 解压并确认目录结构

$ sudo tar -xzf apache-shenyu-2.7.1-admin-bin.tar.gz
$ sudo tar -xzf apache-shenyu-2.7.1-bootstrap-bin.tar.gz
$ ls /opt/apache-shenyu-2.7.1-admin-bin
LICENSE  NOTICE  README.txt  bin  conf  db  ext-lib  lib  licenses
$ ls /opt/apache-shenyu-2.7.1-admin-bin/conf
application-h2.yml  application-mysql.yml  application-ob.yml  application-og.yml  application-oracle.yml  application-pg.yml  application.yml  logback.xml
$ ls /opt/apache-shenyu-2.7.1-admin-bin/bin
start.bat  start.sh  stop.bat  stop.sh

关键目录说明：

路径	说明
bin/start.sh、bin/stop.sh	启停脚本，通过 ADMIN_JVM（admin）或 BOOT_JVM（bootstrap）环境变量注入 JVM 参数
conf/application.yml	主配置：端口、同步方式、认证等
conf/application-h2.yml	H2 存储配置（admin 默认激活）
conf/application-mysql.yml、application-pg.yml	生产数据库配置模板
lib	全部依赖 jar，主类为 fat classpath 启动
logs	启动后生成，运行日志 shenyu-admin.log、shenyu-bootstrap.log

4.4 确认 admin 存储与端口配置

发行包默认已按 H2 存储、端口 9095 配置好，确认关键值即可：

$ sed -n '16,18p;20,24p' /opt/apache-shenyu-2.7.1-admin-bin/conf/application.yml
server:
  port: 9095
  address: 0.0.0.0
spring:
  profiles:
    active: h2

application-h2.yml 中的数据源关键字段（默认值，无需修改，url 中的库名为用户 home 目录下的 shenyu）：

shenyu:
  database:
    dialect: h2
    init_script: "sql-script/h2/schema.sql"
    init_enable: true
spring:
  datasource:
    driver-class-name: org.h2.Driver
    username: sa
    password: sa

url 完整值为 jdbc:h2:mem: 加上 home 路径、库名与参数，形如 jdbc:h2:mem:<home>/shenyu;DB_CLOSE_DELAY=-1;MODE=MySQL;，其中 DB_CLOSE_DELAY=-1 表示连接不断开时保持内存库存活。

4.5 启动 admin

$ export ADMIN_JVM='-server -Xms256m -Xmx256m -Xmn128m'
$ cd /opt/apache-shenyu-2.7.1-admin-bin/bin && ./start.sh
Start with the environment variable JAVA_OPTS set: -server -Xms256m -Xmx256m -Xmn128m
Starting the ShenYu-Admin ...
Please check the log files: /opt/apache-shenyu-2.7.1-admin-bin/logs/shenyu-admin.log

等待约 10 秒后确认启动成功（日志关键行）：

Tomcat started on port 9095 (http) with context path '/'
Started ShenyuAdminBootstrap in 10.089 seconds (process running for 10.907)

4.6 启动网关 bootstrap

发行包默认已指向本机 admin（ws://localhost:9095/websocket），确认后直接启动：

$ grep -A1 'websocket' /opt/apache-shenyu-2.7.1-bootstrap-bin/conf/application.yml | head -3
    websocket:
      urls: ws://localhost:9095/websocket
$ export BOOT_JVM='-server -Xms256m -Xmx256m -Xmn128m'
$ cd /opt/apache-shenyu-2.7.1-bootstrap-bin/bin && ./start.sh
Start with the environment variable JAVA_OPTS set: -server -Xms256m -Xmx256m -Xmn128m
Starting the ShenYu-Bootstrap ...
Please check the log files: /opt/apache-shenyu-2.7.1-bootstrap-bin/logs/shenyu-bootstrap.log

启动成功（日志关键行）：

Netty started on port 9195 (http)
Started ShenyuBootstrapApplication in 5.112 seconds (process running for 6.018)

4.7 验证监听端口

$ ss -tlnp | grep -E '9095|9195'
LISTEN 0      100                *:9095            *:*    users:(("java",pid=5996,fd=333))
LISTEN 0      128                *:9195            *:*    users:(("java",pid=6108,fd=574))
$ curl -s http://localhost:9095/actuator/health
{"status":"UP"}
$ curl -s http://localhost:9195/actuator/health
{"status":"UP","components":{"diskSpace":{"status":"UP","details":{"total":843834499072,"free":330458386432,"threshold":10485760,"path":"/opt/apache-shenyu-2.7.1-bootstrap-bin/.","exists":true}},"ping":{"status":"UP"},"refreshScope":{"status":"UP"}}}

4.8 网关代理验证（divide 插件）

准备一个后端演示服务：

$ mkdir -p /var/www/backend
$ echo '<h1>Hello from backend on port 8500</h1>' > /var/www/backend/index.html
$ nohup python3 -m http.server 8500 --directory /var/www/backend >/var/www/backend/server.log 2>&1 &
$ curl -s http://localhost:8500/
<h1>Hello from backend on port 8500</h1>

登录管理端获取 token（2.7.1 登录接口为 GET）：

$ curl -s 'http://localhost:9095/platform/login?userName=admin&password=q1w2e3r4'
{"code":200,"message":"login dashboard user success","data":{"id":"1","userName":"admin","role":1,"enabled":true,"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiZXhwIjoxNzkxODU5MTU2fQ.DCHfswN-SAqZW2NVoDnmL4i7hq6tarlciceYGKC4rr8","expiredTime":86400000}}

默认密码为 123456，密码复杂度校验会拒绝 q1w2e3r4 这类纯小写加数字的值，本文通过覆盖 H2 初始化脚本方式把示例账号密码落为 q1w2e3r4，做法见第五章 5.4。

依次注册 divide 选择器、规则与上游（token 放在 X-Access-Token 请求头，命名空间用默认值 649330b6-c2d7-4edc-be8e-8a54df9eb385）：

# 1. 创建 divide 选择器（pluginId 固定为 5）
$ curl -s -X POST http://localhost:9095/selector -H "X-Access-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "pluginId": "5", "name": "http-backend", "matchMode": 0, "type": 0, "sort": 1,
  "enabled": true, "loged": true, "continued": true, "matchRestful": false,
  "handle": "[]", "selectorConditions": [],
  "namespaceId": "649330b6-c2d7-4edc-be8e-8a54df9eb385" }'
{"code":200,"message":"create success","data":"2109479217540501504"}

# 2. 创建规则：精确匹配 /index.html
$ curl -s -X POST http://localhost:9095/rule -H "X-Access-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "selectorId": "2109479217540501504", "name": "index-html", "matchMode": 0, "sort": 1,
  "enabled": true, "loged": true, "matchRestful": false,
  "handle": "{\"loadBalance\":\"random\",\"retry\":0,\"timeout\":3000}",
  "ruleConditions": [{"paramType":"uri","operator":"=","paramName":"/","paramValue":"/index.html"}],
  "namespaceId": "649330b6-c2d7-4edc-be8e-8a54df9eb385" }'
{"code":200,"message":"create success","data":1}

# 3. 绑定本地服务发现上游（dashboard 前端同款接口）
$ curl -s -X POST http://localhost:9095/proxy-selector/binding -H "X-Access-Token: $TOKEN" -H "Content-Type: application/json" -d '{
  "selectorId": "2109479217540501504", "name": "http-backend", "pluginName": "divide",
  "type": "local", "forwardPort": 8500, "listenerNode": "", "handler": "{}", "props": "{}",
  "discovery": {"discoveryType": "local", "serverList": "", "props": "{}", "name": "http-backend"},
  "discoveryUpstreams": [{"protocol": "http://", "url": "localhost:8500", "status": 1, "weight": 50, "props": "{}"}],
  "namespaceId": "649330b6-c2d7-4edc-be8e-8a54df9eb385" }'
{"code":200,"message":"create success","data":null}

经网关访问验证代理链路：

$ curl -s http://localhost:9195/index.html
<h1>Hello from backend on port 8500</h1>

网关日志同步出现 divide 命中记录：

divide selector success match , selector name :http-backend
divide rule success match , rule name :index-html

五、配置说明

5.1 默认端口

进程	端口	配置项
shenyu-admin	9095	conf/application.yml 中 server.port
shenyu-bootstrap	9195	conf/application.yml 中 server.port
演示后端	8500	python3 -m http.server 参数

5.2 JVM 堆内存（256-512MB）

start.sh 通过环境变量覆盖默认 JVM 参数：admin 用 ADMIN_JVM（默认 -Xmx2g），bootstrap 用 BOOT_JVM（默认 -Xmx4g）。演示环境各限 256MB：

export ADMIN_JVM='-server -Xms256m -Xmx256m -Xmn128m'
export BOOT_JVM='-server -Xms256m -Xmx256m -Xmn128m'

生效验证：

$ ps -ef | grep [j]ava | grep -oE 'Xms256m -Xmx256m' | sort | uniq -c
      2 Xms256m -Xmx256m
$ jps -l
8533 org.apache.shenyu.bootstrap.ShenyuBootstrapApplication
8439 org.apache.shenyu.admin.ShenyuAdminBootstrap

5.3 H2 存储与数据持久性

H2 为内存库（jdbc:h2:mem:），admin 重启后配置清空，网关会因同步数据丢失返回 -107 错误，需重新注册选择器与规则。生产环境切换 MySQL：将 conf/application.yml 中 spring.profiles.active 由 h2 改为 mysql，并按 application-mysql.yml 填写数据源后重启 admin。

5.4 默认账号与密码初始化

默认账号 admin / 123456，密码以 sha512 存储于 H2 初始化脚本。管理端修改密码接口校验复杂度（至少 8 位且含大小写字母、数字、特殊字符）：

$ curl -s -X PUT http://localhost:9095/dashboardUser/modify-password/1 -H "X-Access-Token: $TOKEN" -H "Content-Type: application/json" -d '{"id":"1","userName":"admin","oldPassword":"123456","password":"q1w2e3r4"}'
{"code":500,"message":"Request error! invalid argument [password: Minimum length of 8, including upper and lower case letters, numbers and special characters]","data":null}

若需将密码初始化为 q1w2e3r4 这类不符合复杂度的值，可覆盖初始化脚本：从 lib/shenyu-admin-2.7.1.jar 内提取 sql-script/h2/schema.sql，将 admin 用户行的 password 哈希替换为 sha512("q1w2e3r4") 即 e553465e3d1ad816a8a8c33176a2ff00fb58f6f55502c89e7593242accc1b0d3c2a2b5fc300a085b5051ecbdd2195b05a53a198ec98d9f75d323cc3c563592f9，写入 conf/sql-script/h2/schema.sql（classpath 中 conf 目录优先于 lib 内 jar），重启 admin 后用新密码登录成功。生产环境建议改用符合复杂度的强密码并保留该复杂度校验。

六、systemd 托管（开机自启）

6.1 编写服务单元

注意：start.sh 会将 java 进程放入后台后退出，不适合 Type=simple 直接托管；systemd 应直接托管 java 主进程（经 bash -c exec 包装以展开 classpath 通配符）。

/etc/systemd/system/shenyu-admin.service：

[Unit]
Description=Apache ShenYu Admin (port 9095)
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/apache-shenyu-2.7.1-admin-bin
ExecStart=/bin/bash -c 'exec java -server -Xms256m -Xmx256m -Xmn128m -classpath .:conf:lib/*:ext-lib/* org.apache.shenyu.admin.ShenyuAdminBootstrap >> logs/shenyu-admin.log 2>&1'
ExecStop=/bin/bash -c 'ps ax | grep "org.apache.shenyu.admin.ShenyuAdminBootstrap" | grep -v grep | awk "{print $1}" | xargs -r kill'
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

/etc/systemd/system/shenyu-gateway.service（网关，主类不同）：

[Unit]
Description=Apache ShenYu Bootstrap Gateway (port 9195)
After=network.target shenyu-admin.service

[Service]
Type=simple
WorkingDirectory=/opt/apache-shenyu-2.7.1-bootstrap-bin
ExecStart=/bin/bash -c 'exec java -server -Xms256m -Xmx256m -Xmn128m -classpath .:conf:lib/*:ext-lib/* org.apache.shenyu.bootstrap.ShenyuBootstrapApplication >> logs/shenyu-bootstrap.log 2>&1'
ExecStop=/bin/bash -c 'ps ax | grep "org.apache.shenyu.bootstrap.ShenyuBootstrapApplication" | grep -v grep | awk "{print $1}" | xargs -r kill'
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

6.2 启用与验证

$ sudo systemctl daemon-reload
$ sudo systemctl enable --now shenyu-admin
$ sudo systemctl enable --now shenyu-gateway
Created symlink /etc/systemd/system/multi-user.target.wants/shenyu-admin.service → /etc/systemd/system/shenyu-admin.service.
Created symlink /etc/systemd/system/multi-user.target.wants/shenyu-gateway.service → /etc/systemd/system/shenyu-gateway.service.
$ systemctl is-active shenyu-admin; systemctl is-active shenyu-gateway
active
active
$ systemctl status shenyu-admin --no-pager -l
● shenyu-admin.service - Apache ShenYu Admin (port 9095)
     Loaded: loaded (/etc/systemd/system/shenyu-admin.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 02:58:57 UTC; 1min 36s ago
   Main PID: 8439 (java)
      Tasks: 81 (limit: 5753)
     Memory: 523.2M

启用后重启系统，两进程随开机拉起；admin 重启会清空 H2 数据（见 5.3），需重新注册演示配置。

七、注意事项

2.7.1 登录接口为 GET /platform/login，参数名为 userName（大小写敏感），POST 会返回 405。
管理端所有业务接口需携带 X-Access-Token 请求头，token 有效期 86400000 毫秒（24 小时），对应 shenyu.jwt.expired-seconds。
上游健康检查默认关闭（shenyu.upstreamCheck.enabled: false），而上游 props 中 healthCheckEnabled 默认为 true，会导致新注册上游始终无法进入健康列表，网关报 -119；演示环境建议将 bootstrap 中该项改为 true，详见常见问题。
divide 选择器若无匹配条件且 continued 为 true，未命中规则的路径也会透传到后端，注意缩小选择器匹配范围。
日志路径：admin 为 logs/shenyu-admin.log，bootstrap 为 logs/shenyu-bootstrap.log，排障优先看这两份文件。

八、常见问题

8.1 网关返回 -107 Can not find selector

{"code":-107,"message":"divide:Can not find selector, please check your configuration!"}

admin 重启后 H2 内存库数据丢失、或 bootstrap 与 admin 的 websocket 未连通导致。排查：先 curl admin 的 /platform/login 确认管理端在线，再在 bootstrap 日志中确认 websocket 连接与 PLUGIN 分组同步日志，最后重新注册选择器、规则与上游。

8.2 网关返回 -119 Can not find healthy upstream url

{"code":-119,"message":"Can not find healthy upstream url, please check your configuration!"}

上游已同步（bootstrap 日志可见 DISCOVER_UPSTREAM 分组、pluginName divide 的事件），但健康检查未运行：bootstrap 默认 shenyu.upstreamCheck.enabled 为 false，而上游 props 默认 healthCheckEnabled 为 true，新上游必须通过探测才能进入健康列表。将该项改为 true 并重启 bootstrap 后恢复（首次探测间隔 5000 毫秒，阈值 1 次成功即标记健康）。

8.3 登录提示 username or password error

确认三件事：参数名是 userName 而非 username；默认密码 123456（或已按 5.4 初始化为 q1w2e3r4）；admin 进程确实在 9095 监听。若通过覆盖 schema.sql 方式改过密码，需重启 admin 使其生效。

8.4 注册选择器报 matchRestful 不能为空

{"code":500,"message":"Request error! invalid argument [matchRestful: must not be null]","data":null}

2.7.1 的 SelectorDTO 必填 matchRestful 字段，请求体中补 "matchRestful": false 即可。

九、卸载方式

$ sudo systemctl disable --now shenyu-admin
$ sudo systemctl disable --now shenyu-gateway
Removed "/etc/systemd/system/multi-user.target.wants/shenyu-admin.service".
Removed "/etc/systemd/system/multi-user.target.wants/shenyu-gateway.service".
$ sudo rm /etc/systemd/system/shenyu-admin.service /etc/systemd/system/shenyu-gateway.service
$ sudo systemctl daemon-reload
$ sudo rm -rf /opt/apache-shenyu-2.7.1-admin-bin /opt/apache-shenyu-2.7.1-bootstrap-bin /opt/apache-shenyu-2.7.1-*.tar.gz

如需保留演示后端则一并清理：kill 8500 端口的 python3 进程并删除 /var/www/backend。

十、参考链接

ShenYu 官方文档：https://shenyu.apache.org/docs/index/
发行包下载：https://dlcdn.apache.org/shenyu/
历史版本归档：https://archive.apache.org/dist/shenyu/
源码仓库：https://github.com/apache/shenyu