Apache ShenYu 发行包构建与 Docker 部署实战：shenyu-dist 模块全解析

Apache ShenYu（Java 原生 API 网关）的 shenyu-dist 模块承担着整个项目的打包与发布职责，它负责把分散在各子模块的代码、依赖、配置文件与数据库脚本统一装配成可发布、可运行的二进制发行包和 Docker 镜像。本文以 shenyu-dist/README.md 为主线，结合仓库中的 Dockerfile、assembly 描述符与启动脚本，完整讲解从源码构建发行包、Docker 镜像构建、容器启动、环境变量覆盖到 docker-compose 一键部署的完整链路，读完即可独立完成 ShenYu 的发行与部署。

一、shenyu-dist 模块定位与组成

shenyu-dist 是 ShenYu 顶层的打包发布模块（packaging 类型为 pom），本身不包含业务代码，而是通过 Maven 的 assembly 与 docker 插件组织整个项目的产物。从根目录 pom.xml 中的 module 声明可以看到，它聚合了四个子模块：

子模块	产物	用途
shenyu-src-dist	源码包（zip）	发布源码压缩包
shenyu-admin-dist	Admin 二进制包（tar.gz）	管理控制台可运行包
shenyu-bootstrap-dist	Bootstrap 二进制包（tar.gz）	网关运行时可执行包
shenyu-docker-compose-dist	docker-compose 部署包（tar.gz）	一站式容器化部署

四个子模块的装配关系定义在 shenyu-dist/pom.xml 中，并在构建阶段通过 checksum-maven-plugin 为产出的 *.tar.gz、*.zip 生成 SHA-512 校验文件（*.sha512），保证发布物可校验、可溯源。当前仓库版本为 2.7.2-SNAPSHOT，因此构建出的包名与镜像 Tag 均以此为基准，而非 README 示例中的 2.2.1。

二、从源码快速构建发行包

README 的 Quickstart 给出了两条命令，这是获得所有发行物的起点：

git clone https://github.com/apache/shenyu.git
cd shenyu
mvn clean package -Dmaven.javadoc.skip=true -Dmaven.test.skip=true

参数说明：

• -Dmaven.javadoc.skip=true：跳过 javadoc 生成，加速构建；
• -Dmaven.test.skip=true：跳过测试执行与测试编译，适用于纯构建场景；
• 建议同时使用 -Dcheckstyle.skip=true 跳过静态检查（可选）。

构建完成后，各子模块产物会按各自 assembly 描述符输出到对应模块的 target 目录，同时 shenyu-dist 根目录下会出现 dist 目录，README 原文："Then you will see the dist directory in root directory." 其中核心产物包括：

• shenyu-admin 二进制包（{version}-admin-bin.tar.gz）；
• shenyu-bootstrap 二进制包（{version}-bootstrap-bin.tar.gz）；
• 源码包 {version}-src.zip；
• docker-compose 部署包。

发布包内部结构

二进制包的结构由 assembly 描述符决定，以 Admin 为例参见 shenyu-admin-dist/src/main/assembly/binary.xml：

shenyu-admin-bin/
├── bin/            # 启动脚本（startup.sh / startup.bat 等，Unix/Windows 双版本）
├── conf/           # application*.yml、logback.xml 等配置
├── lib/            # 全部运行依赖 jar
├── ext-lib/        # 扩展依赖目录（默认空，供用户放自定义 jar）
├── db/             # 数据库初始化与升级脚本（来自仓库根 db/ 目录）
├── LICENSE / NOTICE
└── README.txt

其中 conf 目录的 yml 文件直接取自 shenyu-admin/src/main/resources，db 目录直接拷贝仓库根 db 下的多数据库 schema 与升级 SQL（mysql/pg/oracle/ob/og），这意味着发行包里自带完整的数据初始化能力；ext-lib 目录被刻意保留为空，供用户在运行时以挂载方式加入扩展 jar。Bootstrap 包结构与此对称，可对照 shenyu-bootstrap-dist/src/main/assembly/binary.xml。

三、构建 Docker 镜像并启动容器

README 给出了开箱即用的 Docker 构建方式，构建时会按 docker profile 激活各 dist 子模块的 Dockerfile：

cd shenyu
mvn clean package -Prelease,docker -Dmaven.javadoc.skip=true -Dmaven.test.skip=true

构建成功后在 docker images 中可以看到类似如下两个镜像：

REPOSITORY                TAG                    IMAGE ID            CREATED             SIZE
apache/shenyu-bootstrap   2.2.1                  0002944cca64        About an hour ago   200MB
apache/shenyu-admin       2.2.1                  1a4b73d6dd6d        About an hour ago   215MB

镜像名与 Tag 规则为 apache/shenyu-{admin|bootstrap}:{version}，Tag 随当前构建版本变化（当前仓库为 2.7.2-SNAPSHOT 对应镜像）。

创建网络并启动

docker network create shenyu
docker run -d -p 9095:9095 --net shenyu apache/shenyu-admin:2.2.1
docker run -d -p 9195:9195 --net shenyu apache/shenyu-bootstrap:2.2.1

端口约定是理解整个架构的关键：

• 9095：ShenYu Admin 管理端端口（Dockerfile 中 EXPOSE 9095）；
• 9195：ShenYu Bootstrap 网关入口端口（Dockerfile 中 EXPOSE 9195）。

两个容器共用 shenyu 网络，便于 Bootstrap 通过容器名访问 Admin 完成数据同步。

启动完成后，访问管理端：http://IP:9095/，使用默认账号 admin / 123456 登录即可进入控制台。默认环境下 Admin 使用 H2 内存数据库（README 原文 Note："The Docker environment uses an H2 database by default."），即开即用，适合快速体验；生产环境建议通过环境变量切换为 MySQL/PostgreSQL（见下文）。

四、通过环境变量与卷挂载定制部署

方式一：环境变量覆盖配置

Docker 容器内配置以环境变量形式透传为 Spring 属性，README 给出的 MySQL 示例：

docker run -e "SPRING_PROFILES_ACTIVE=mysql" \
  -e "spring.datasource.url=jdbc:mysql://192.168.1.9:3306/shenyu?useUnicode=true&characterEncoding=utf-8&useSSL=false" \
  -e "spring.datasource.password=123456" \
  -d -p 9095:9095 --net shenyu apache/shenyu-admin:2.2.1

参数含义：

环境变量	作用
SPRING_PROFILES_ACTIVE=mysql	激活 application-mysql.yml profile，切换数据源类型
spring.datasource.url	JDBC 连接串，需替换为实际数据库地址与库名
spring.datasource.password	数据库密码

对应地，Admin 源码资源中提供了 application-mysql.yml、application-pg.yml、application-h2.yml 等多套 profile（位于 shenyu-admin/src/main/resources），激活哪个 profile 即使用哪套数据源配置。数据库初始化 SQL 则位于发行包 db 目录及仓库根 db 目录。

方式二：挂载自定义配置文件

更彻底的自定义方式是把本地 application.yml 所在目录挂载进容器覆盖默认配置：

docker run -v D:\tmp\conf:/opt/shenyu-admin/conf/ -d -p 9095:9095 --net shenyu apache/shenyu-admin:2.2.1

注意容器内配置路径为 /opt/shenyu-admin/conf/（对应 Dockerfile 中 ENV LOCAL_PATH /opt/shenyu-admin），Bootstrap 对应路径为 /opt/shenyu-bootstrap/conf/。Windows 路径写法（如 D:\tmp\conf）在 Linux 环境请替换为 /path/to/conf。

此外，两个镜像还暴露了 JVM 调优环境变量：Admin 为 ADMIN_JVM，Bootstrap 为 BOOT_JVM，传入后即覆盖启动脚本中的默认 JVM 参数，例如：

docker run -e "ADMIN_JVM=-Xmx4g -Xms4g" -d -p 9095:9095 apache/shenyu-admin:2.7.2-SNAPSHOT

五、容器内部启动原理

镜像与启动脚本揭示了部署的内部机制，理解后可更精准地排障。

镜像基础

• Admin 镜像：Dockerfile 基于 amazoncorretto:17.0.11-alpine3.19，构建分为两阶段：先用 alpine 解压 target/${APP_NAME}.tar.gz 到 /opt/shenyu-admin，再拷贝进运行时镜像，并创建非 root 用户 shenyu 以最小权限运行；
• Bootstrap 镜像：Dockerfile 基于 eclipse-temurin:17-centos7，同样以 shenyu 用户运行。

启动脚本逻辑

两个镜像的 ENTRYPOINT 均指向各自 entrypoint.sh，核心逻辑一致（参见 Admin entrypoint.sh 与 Bootstrap entrypoint.sh）：

1. 配置扩展覆盖：[[ -d ./conf-ext ]] && cp -f ./conf-ext/* ./conf，若容器内存在 conf-ext 目录，则将其内容覆盖到 conf——这是"配置文件热替换"的另一种方式；
2. 组装 classpath：.:${DEPLOY_DIR}/conf:${DEPLOY_DIR}/lib/*:${EXT_LIB}/*，即 conf、lib 下所有 jar、ext-lib 下所有扩展 jar 均进入类路径，印证了 ext-lib 目录的扩展用途；
3. JVM 参数选择：若 ADMIN_JVM/BOOT_JVM 为空，使用内置默认参数（如 -server -Xmx2g -Xms2g -Xmn1g），否则直接采用环境变量值；
4. 启动主类：Admin 为 org.apache.shenyu.admin.ShenyuAdminBootstrap，Bootstrap 为 org.apache.shenyu.bootstrap.ShenyuBootstrapApplication。

因此，若需自定义 JVM 或替换配置，优先使用 ADMIN_JVM/BOOT_JVM 环境变量与 conf-ext 目录，而非修改镜像内部文件。

六、docker-compose 一键部署（附加方案）

除逐容器启动外，仓库还提供了 docker-compose 编排产物。shenyu-docker-compose-dist 的 assembly 描述符（source.xml）会装配三套开箱即用的部署方案：stand-alone-mysql、stand-alone-h2、stand-alone-pg，每套均包含对应的 docker-compose.yaml、Admin 与 Bootstrap 的 conf（自动取自 shenyu-admin/src/main/resources 与 shenyu-bootstrap/src/main/resources）以及初始化脚本。使用方式参考 shenyu-docker-compose-dist/README.md：

# 1. 下载安装脚本并执行（${version} 替换为 v2.4.2 / latest 等）
sh ./install.sh ${version}

# 2. 修改配置文件

# 3. 启动
docker-compose -f ./docker-compose.yaml up -d
# docker 版本大于 1.25.5 时可用新命令
docker compose -f ./docker-compose.yaml up -d

该方案适合快速拉起完整 ShenYu（网关 + 管理端 + 数据库）用于本地联调与轻量生产。

七、源码包发布与完整性校验

shenyu-src-dist 负责生成官方源码包 {version}-src.zip，其装配规则（source.xml）值得关注：打包时会排除 .github、target、构建产物、IDE 配置（.idea、.project 等）以及 shenyu-integrated-test、shenyu-examples、shenyu-e2e 等测试/示例模块，使源码包聚焦于核心工程。

发布链路还配有校验环节：根目录 Makefile 与 shenyu-dist/release_check.py 脚本负责发布前的自动化检查（校验文件完整性、版本一致性等），加上前述 checksum-maven-plugin 生成的 SHA-512 校验和，共同构成从构建、校验到发布的质量闭环。

八、部署注意事项小结

• 默认 H2：Docker 默认环境使用 H2 数据库，数据不持久化，重启即丢失，仅适合体验；生产环境务必切换 MySQL/PostgreSQL 并挂载数据卷；
• 版本对齐：README 中的镜像 Tag（2.2.1）为示例，实际以当前构建版本为准（本仓库为 2.7.2-SNAPSHOT），拉取镜像与写脚本时请保持一致；
• 网络与端口：Admin（9095）与 Bootstrap（9195）务必置于同一 docker 网络，且宿主端口映射不可冲突；
• 配置优先级：容器内配置优先级为 conf-ext 覆盖 → 环境变量 → 挂载卷中的 application.yml，按需选择定制手段；
• 扩展 jar：自定义插件可通过挂载至容器内 ext-lib 目录加入类路径，无需重新构建镜像。

至此，从 mvn clean package 到 Docker 启动、从二进制包结构到 docker-compose 编排的完整发行链路已经打通。对照本文给出的源码路径（shenyu-dist/pom.xml、admin Dockerfile、bootstrap Dockerfile），即可按需定制自己的 ShenYu 发行与部署方案。