Apache ShenYu 配置参数详解

目标：逐项详解 Apache ShenYu 2.7.1 的 admin 与 bootstrap 两侧配置参数，覆盖服务监听、H2 元数据库与初始化脚本、JWT 认证有效期、websocket 配置同步、命名空间、跨域、上游健康检查与 JVM 堆内存限制等，全部默认值与生效行为均经真实环境实测验证。

一、环境信息

二、前置条件

1. 已按《Apache ShenYu 安装指南》完成双进程部署并能通过网关代理访问后端。
2. 熟悉 spring boot 的 YAML 配置语法与环境变量覆盖机制（ShenYu 两个进程均为标准 spring boot 应用）。
3. 本文所有默认值均摘自 2.7.1 发行包 conf 目录原始文件，并经运行时行为验证。

三、参数查看与修改方式

1. 直接查看配置文件：admin 为 conf/application.yml 与 conf/application-h2.yml；bootstrap 为 conf/application.yml。
2. 运行时确认生效值：spring boot 原生支持环境变量覆盖（属性名点号转下划线大写，如 SHENYU_JWT_EXPIRED_SECONDS），启动脚本则通过 ADMIN_JVM、BOOT_JVM 注入 JVM 参数。
3. REST 接口核验：登录后 GET /v3/api-docs 查看全部接口定义；GET /namespace/list 确认命名空间；GET /namespace-plugin/listByNamespace?namespace=649330b6-c2d7-4edc-be8e-8a54df9eb385 确认插件清单（实测返回 45 个插件，divide 编号 5）。
4. 修改后重启对应进程生效：admin 修改后需重启，注意 H2 内存库重启丢数据（见 5.2）。

四、参数总览

五、核心参数分类详解

5.1 admin 服务监听参数

server:
  port: 9095
  address: 0.0.0.0

实测确认：port 决定管理端监听端口，dashboard 前端与 REST 调用均使用该端口；address 为 0.0.0.0 时监听全部网卡，ss 验证结果为 LISTEN 0 100 *:9095 *:*。改为 127.0.0.1 可限制仅本机访问。

5.2 admin 元数据库与初始化参数（application-h2.yml）

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

关键行为实测：

1. url 形如 jdbc:h2:mem:库名，DB_CLOSE_DELAY=-1 保证连接期间内存库存活；进程退出即清空。实测 admin 重启后 selector、rule、上游全部丢失，网关立刻返回 -107 Can not find selector。
2. init_enable 为 true 时每次启动执行 init_script；该脚本在 classpath 中查找，conf 目录优先于 lib 内 jar，因此把同名脚本放到 conf/sql-script/h2/schema.sql 即可覆盖默认初始化（实测用此方式自定义 admin 初始密码）。
3. 生产切换 MySQL：将 application.yml 中 spring.profiles.active 改为 mysql，按 application-mysql.yml 填数据源，首次启动 admin 会自动建表。

5.3 admin 认证与安全参数

shenyu:
  jwt:
    expired-seconds: 86400000

1. expired-seconds：登录 token 有效期，实测登录返回 expiredTime 86400000（24 小时）与之对应。
2. 登录接口：GET /platform/login，参数 userName、password，位于 shiro 白名单；其余业务接口需请求头 X-Access-Token。
3. 默认账号 admin / 123456（schema.sql 中 sha512 存储）。修改密码接口 PUT /dashboardUser/modify-password/1 强制复杂度：至少 8 位且含大小写字母、数字、特殊字符，实测 q1w2e3r4 被拒并返回 Minimum length of 8, including upper and lower case letters, numbers and special characters。
4. shiro 段的 whiteList 默认含 /platform/login、/platform/secretInfo、/actuator/health、/v3/api-docs 等，可按需增删。

5.4 admin 配置同步与注册中心参数

shenyu:
  sync:
    websocket:
      enabled: true
      messageMaxSize: 10240
      allowOrigins: ws://localhost:9095;ws://localhost:9195;

1. sync.websocket.enabled：管理端 websocket 推送开关，实测网关通过该通道接收 PLUGIN、SELECTOR、RULE、DISCOVER_UPSTREAM 等分组数据，关闭后网关无法获得配置。
2. shenyu.register.registerType: http：管理端作为客户端注册中心（接收 shenyu-client 上报），本机演示无需改动。
3. shenyu.cluster.enabled: false：管理端集群开关，true 时通过 jdbc 或 redis 同步多实例状态，forward-list 定义可转发到其他实例的接口前缀（如 /shenyu-client/**）。

5.5 bootstrap 网关服务参数

server:
  port: 9195
shenyu:
  netty:
    http:
      webServerFactoryEnabled: true
      selectCount: 1
      workerCount: 8
      accessLog: false

1. port：网关 HTTP 监听端口，实测启动后 ss 显示 LISTEN 0 128 *:9195 *:*。
2. netty.http.workerCount：Netty worker 线程数，实测默认 8；低配环境按 CPU 调整。
3. switchConfig.local: true：本地兜底配置开关。
4. file.maxSize: 10：上传文件大小上限（MB）。

5.6 bootstrap 配置同步与命名空间参数

shenyu:
  namespace: 649330b6-c2d7-4edc-be8e-8a54df9eb385
  sync:
    websocket:
      urls: ws://localhost:9095/websocket
      allowOrigin: ws://localhost:9195

1. namespace：网关订阅的命名空间。实测该值即 admin 默认命名空间（GET /namespace/list 返回 id 1、namespaceId 649330b6-c2d7-4edc-be8e-8a54df9eb385、名称 default），REST 注册选择器、规则、上游时 namespaceId 必须与之完全一致，否则配置不会同步到网关。
2. sync.websocket.urls：admin 推送地址。跨机部署时改为 admin 实际地址；分布式部署中多个地址用逗号分隔。
3. shenyu.register.enabled: false：网关实例自身是否注册到注册中心，单机演示保持 false。
4. shenyu.heartbeat：网关对 admin 的心跳探活，serverLists 默认 http://localhost:9095，props 中的 username、password 必须与 admin 账号一致，实测改密码后需同步修改该段。

5.7 bootstrap 跨域与健康检查参数

shenyu:
  cross:
    enabled: true
    allowedMethods: "*"
    allowedAnyOrigin: true
    maxAge: "18000"
    allowCredentials: true
  upstreamCheck:
    enabled: false
    poolSize: 10
    timeout: 3000
    healthyThreshold: 1
    unhealthyThreshold: 1
    interval: 5000
    printEnabled: true
    printInterval: 60000

cross 段控制网关层跨域响应头，默认放行全部来源。

upstreamCheck 是本文实测重点：该开关默认 false，但新注册上游的 props 默认 healthCheckEnabled 为 true，即上游必须探测成功才进入健康列表，两处默认值组合导致全新部署注册上游后必然报 -119 Can not find healthy upstream url。实测将 enabled 改为 true 后，网关按 interval 5000 毫秒、healthyThreshold 1 次对上游发起 TCP 探测，首次成功即标记健康，代理恢复。生产建议保留 true 并按网络情况调整 timeout 与阈值。

5.8 JVM 参数（ADMIN_JVM、BOOT_JVM）

bin/start.sh 通过环境变量注入 JVM 参数：

启动输出会回显生效值（Start with the environment variable JAVA_OPTS set: -server -Xms256m -Xmx256m -Xmn128m），并可用 ps 与 jps -v 双重验证：

$ ps -ef | grep [j]ava | grep -oE 'Xms256m -Xmx256m' | sort | uniq -c
      2 Xms256m -Xmx256m
$ jps -v | grep ShenyuAdmin | tr ' ' '\n' | grep -E 'Xms|Xmx'
-Xms256m
-Xmx256m

实测 256MB 堆可稳定支撑演示级流量（admin 含 H2 初始化与 websocket 推送），生产按并发与插件数量调大。

六、生产配置模板

admin conf/application.yml 关键段（MySQL 存储示例）：

server:
  port: 9095
  address: 0.0.0.0
spring:
  profiles:
    active: mysql
shenyu:
  sync:
    websocket:
      enabled: true
  jwt:
    expired-seconds: 86400
  cluster:
    enabled: false

bootstrap conf/application.yml 关键段（对接远端 admin）：

server:
  port: 9195
shenyu:
  namespace: 649330b6-c2d7-4edc-be8e-8a54df9eb385
  sync:
    websocket:
      urls: ws://192.168.1.62:9095/websocket
  heartbeat:
    enabled: true
    serverLists: http://192.168.1.62:9095
    props:
      username: admin
      password: Q1w2e3r4.
  upstreamCheck:
    enabled: true
    timeout: 3000
    healthyThreshold: 1
    unhealthyThreshold: 2
    interval: 5000
  cross:
    enabled: true
    allowedAnyOrigin: false

systemd 托管模板（以 admin 为例，直接托管 java 主进程）：

[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 -Xms512m -Xmx512m -Xmn256m -classpath .:conf:lib/*:ext-lib/* org.apache.shenyu.admin.ShenyuAdminBootstrap >> logs/shenyu-admin.log 2>&1'
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

七、常见问题

7.1 修改端口后启动报端口占用

server.port 与其他进程冲突时启动失败。用 ss -tlnp 检查占用者后修改端口，或释放占用进程；admin 端口修改后需同步修改 bootstrap 的 sync.websocket.urls 与 heartbeat.serverLists。

7.2 配置了选择器但网关不生效

三查：请求体 namespaceId 是否等于 bootstrap 的 shenyu.namespace；bootstrap 日志是否出现对应分组的 handleResult 同步记录；upstreamCheck.enabled 是否为 true（否则上游进不了健康列表，报 -119）。

7.3 改了 heartbeat 密码后网关频繁告警

shenyu.heartbeat.props 的 username、password 用于网关探活 admin，必须与管理端账号一致；admin 改密后同步修改并重启 bootstrap。

7.4 H2 模式重启后配置全丢

这是 H2 内存库的预期行为（DB_CLOSE_DELAY=-1 仅保证进程存活期数据有效）。生产切换 spring.profiles.active 为 mysql 或 pg；演示环境可将注册流程脚本化，重启后一键重放（selector、rule、proxy-selector/binding 三个接口）。

八、参考链接

1. ShenYu 官方配置文档：https://shenyu.apache.org/docs/index/
2. admin 配置样例（源码仓库）：https://github.com/apache/shenyu/tree/v2.7.1/shenyu-dist/shenyu-admin-dist/src/main/resources/conf
3. bootstrap 配置样例（源码仓库）：https://github.com/apache/shenyu/tree/v2.7.1/shenyu-dist/shenyu-bootstrap-dist/src/main/resources/conf