2. 发布包结构解析：标准发布包的目录结构
调度器发布包采用标准化的目录布局，确保在不同环境（开发、测试、生产）中保持一致的部署体验。理解各目录的职责与版本号规范，是后续校验工作的基础。
2.1 标准目录结构总览
一个合规的调度器发布包应包含以下四个核心目录及一个版本标识文件：
scheduler-release-2.4.1/
├── bin/ # 可执行脚本与启动入口
├── conf/ # 配置文件与模板
├── lib/ # 依赖库与核心 JAR 包
├── logs/ # 运行时日志输出目录（初始为空）
└── VERSION # 版本标识文件（纯文本，仅含版本号）
校验要点： 首次校验时，应确认
logs/ 目录存在但为空；若发现预置日志文件，说明发布包可能被污染或打包流程不规范。
2.2 各目录职责与校验关注点
| 目录 | 职责说明 | 典型文件 | 校验关注点 |
|---|---|---|---|
| bin/ | 存放启动、停止、状态检查等可执行脚本；是调度器进程管理的入口。 | start.sh, stop.sh, scheduler.sh |
脚本是否具有可执行权限（+x）；Shebang 行是否正确；是否包含硬编码路径。 |
| conf/ | 存储所有配置文件，包括主配置、日志配置、安全策略等。 | scheduler.yaml, logback.xml, security.properties |
配置文件是否完整；是否包含占位符未替换；敏感信息（密码、密钥）是否加密。 |
| lib/ | 包含调度器运行时依赖的所有 JAR 包及核心引擎包。 | scheduler-core-2.4.1.jar, netty-*.jar |
JAR 包数量与预期清单一致；无重复依赖；无 SNAPSHOT 版本混入。 |
| logs/ | 运行时日志输出目录；初始状态必须为空。 | （初始无文件） | 目录是否存在；权限是否允许调度器进程写入；是否被误打包了旧日志。 |
2.3 版本号规范与命名规则
调度器发布包采用 语义化版本 2.0.0（SemVer）规范，格式为 MAJOR.MINOR.PATCH，并附加构建元数据标识：
scheduler-release-{MAJOR}.{MINOR}.{PATCH}-{BUILD_META}.tar.gz
示例：
scheduler-release-2.4.1-20250315.tar.gz
scheduler-release-3.0.0-rc1.tar.gz
版本号各段含义：
- MAJOR（主版本号）： 不兼容的 API 修改或架构重构时递增。例如从 2.x 升级到 3.x 需要迁移配置。
- MINOR（次版本号）： 向下兼容的功能新增。例如新增调度策略、新增校验规则。
- PATCH（修订号）： 向下兼容的问题修复。例如修复内存泄漏、修复配置解析异常。
- BUILD_META（构建元数据）： 可选字段，标识构建日期、RC 版本或 Git Commit ID。例如
20250315、rc1、beta2。
2.4 命名规则校验清单
在发布包校验流程中，命名规则是自动化校验的第一道关卡。以下为必须通过的校验项：
- 前缀匹配： 必须以
scheduler-release-开头。 - 版本号格式：
MAJOR.MINOR.PATCH必须为数字，且符合 SemVer 规范。 - 禁止 SNAPSHOT： 发布包名称中不得包含
SNAPSHOT字样。 - 扩展名： 必须为
.tar.gz或.zip，禁止使用.rar或未压缩目录。 - 目录与包名一致性： 解压后的顶层目录名称必须与包名（不含扩展名）完全一致。
常见错误： 部分打包脚本会将
logs/ 目录误打包为包含旧日志的版本，导致生产环境启动时日志轮转异常。校验时务必检查 logs/ 目录是否为空。
2.5 发布包结构关系图
下图展示了标准发布包的四层结构及其与外部环境的交互关系：
2.6 版本号与目录的对应关系
版本号不仅标识发布包的整体版本，还直接影响 lib/ 目录中核心 JAR 包的命名。以下为版本号与内部文件的对应规则：
| 发布包版本 | 核心 JAR 包名称 | VERSION 文件内容 | 校验一致性要求 |
|---|---|---|---|
2.4.1 |
scheduler-core-2.4.1.jar |
2.4.1 |
三者必须完全一致 |
3.0.0-rc1 |
scheduler-core-3.0.0-rc1.jar |
3.0.0-rc1 |
构建元数据（rc1）必须同步 |
2.5.0 |
scheduler-core-2.5.0.jar |
2.5.0 |
不允许出现 2.5.0-SNAPSHOT |
校验自动化脚本示例： 以下脚本用于快速验证发布包版本一致性：
#!/bin/bash
# 校验发布包版本一致性
PACKAGE_NAME="scheduler-release-2.4.1.tar.gz"
EXPECTED_VERSION="2.4.1"
# 解压并读取 VERSION 文件
tar -xzf "$PACKAGE_NAME" -C /tmp/verify
ACTUAL_VERSION=$(cat /tmp/verify/scheduler-release-2.4.1/VERSION)
# 校验版本号
if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
echo "ERROR: 版本不匹配！期望 $EXPECTED_VERSION，实际 $ACTUAL_VERSION"
exit 1
fi
# 校验核心 JAR 包
JAR_COUNT=$(ls /tmp/verify/scheduler-release-2.4.1/lib/scheduler-core-*.jar 2>/dev/null | wc -l)
if [ "$JAR_COUNT" -ne 1 ]; then
echo "ERROR: 核心 JAR 包数量异常（期望 1 个，实际 $JAR_COUNT 个）"
exit 1
fi
echo "SUCCESS: 版本一致性校验通过"
2.7 目录结构校验流程
在实际校验工作中，建议按以下步骤依次检查发布包结构：
- 步骤一： 检查包名是否符合
scheduler-release-{version}.tar.gz格式。 - 步骤二： 解压后检查顶层目录名称是否与包名一致。
- 步骤三： 确认
bin/、conf/、lib/、logs/四个目录均存在。 - 步骤四： 检查
logs/目录是否为空。 - 步骤五： 读取
VERSION文件，与包名中的版本号比对。 - 步骤六： 检查
lib/中核心 JAR 包的版本号是否与VERSION一致。
常见陷阱： 部分 CI/CD 流水线在打包时可能遗漏
VERSION 文件，或错误地将 logs/ 目录排除在外。建议在自动化校验脚本中增加对这两个要素的强制检查。