3. 校验流程总览：校验生命周期
调度器发布包的校验并非单一操作，而是一条从接收包到最终准入决策的完整链路。理解这条生命周期的每个阶段，是构建可靠校验体系的基础。本章将拆解校验流程的五个核心环节，并给出可落地的流程图设计。
3.1 校验生命周期五阶段
一个发布包从进入调度器到被允许部署，需要依次经历以下五个阶段：
| 阶段 | 输入 | 核心动作 | 输出 |
|---|---|---|---|
| ① 接收包 | HTTP/HTTPS 上传、对象存储拉取 | 格式验证、元数据提取、临时存储 | 原始包 + 元数据记录 |
| ② 解压 | 压缩包（.tar.gz / .zip / .tgz） | 解压到临时目录、检查目录结构 | 解压后的文件树 |
| ③ 完整性校验 | 解压后的文件列表 | 计算 SHA-256 哈希，与清单比对 | 完整性校验结果（通过/失败） |
| ④ 内容校验 | 配置文件、二进制、脚本 | Schema 验证、版本约束、安全扫描 | 内容校验结果（通过/失败） |
| ⑤ 签名校验 | 签名文件 + 公钥证书 | 非对称解密、摘要比对 | 签名校验结果（通过/失败） |
五个阶段串行执行，任一阶段失败则立即终止流程并返回失败原因。只有全部通过，才会进入最终的准入决策。
3.2 校验流程图设计
下图展示了完整的校验生命周期，包含决策分支和异常退出路径。
3.3 各阶段关键设计要点
设计原则：每个阶段都应具备幂等性——同一发布包在相同环境下多次校验，结果必须一致。这是保证可审计和可复现的基础。
3.3.1 接收包阶段
- 格式白名单：只允许
.tar.gz、.tgz、.zip三种格式，拒绝其他扩展名。 - 元数据提取：记录包名、版本号、大小、上传时间、来源 IP 等，用于后续审计。
- 防重放攻击：检查包的唯一标识（如 SHA-256 摘要）是否已在历史记录中存在，防止重复提交。
3.3.2 解压阶段
- 路径穿越防护：解压时检查每个文件路径，拒绝包含
../或路径的条目。 - 目录结构校验：强制要求包内包含
manifest.yaml和signature.sig两个必需文件。 - 资源限制：设置解压超时（默认 30 秒）和最大文件数量（默认 5000 个），防止 ZIP 炸弹攻击。
3.3.3 完整性校验阶段
- 哈希算法：统一使用 SHA-256，禁用已废弃的 MD5 或 SHA-1。
- 校验清单：从
manifest.yaml中读取每个文件的预期哈希值，逐文件比对。 - 增量校验：对于大文件（超过 100MB），支持分块哈希校验，避免内存溢出。
3.3.4 内容校验阶段
- Schema 验证：对 YAML/JSON 配置文件进行 JSON Schema 校验，确保字段类型和必填项正确。
- 版本约束：检查包内声明的依赖版本是否与当前调度器环境兼容。
- 安全扫描：对二进制文件进行已知漏洞签名匹配，对脚本文件进行危险函数检测。
3.3.5 签名校验阶段
- 非对称算法：使用 ECDSA P-256 或 RSA 2048+，私钥由发布者持有，公钥预置在调度器信任库。
- 签名对象：签名内容为
manifest.yaml的 SHA-256 哈希值，而非整个包，避免大文件签名性能问题。 - 证书链验证：如果使用 X.509 证书，需验证证书链是否完整、是否在有效期内、是否被吊销。
3.4 准入决策模型
当五个阶段全部通过后，调度器进入准入决策阶段。决策结果不仅依赖校验结果，还受以下策略影响：
| 策略类型 | 说明 | 示例 |
|---|---|---|
| 强制策略 | 所有校验必须通过，否则拒绝 | 签名校验失败 → 直接拒绝 |
| 警告策略 | 校验通过但存在低风险问题，允许部署但记录告警 | 内容校验发现已废弃的 API 版本 |
| 灰度策略 | 校验通过后，先部署到灰度环境，观察一段时间后再全量 | 新版本先部署到 10% 的节点 |
| 阻断策略 | 特定条件下即使校验通过也拒绝部署 | 当前集群负载超过 80% 时暂停部署 |
最佳实践：建议将强制策略作为默认配置，警告策略用于非关键字段的兼容性提示，灰度策略用于大版本升级场景。阻断策略应结合监控系统动态调整。
3.5 校验流程的架构分层
从软件架构视角，校验流程可以抽象为三个层次，每层职责清晰，便于扩展和维护。
3.6 异常处理与审计
校验流程中任何阶段的失败都不应被静默忽略。标准做法如下：
- 结构化错误码：每个阶段定义独立的错误码前缀（如
INTEGRITY_ERR、SIGNATURE_ERR），便于快速定位。 - 审计日志：记录每个阶段的开始时间、结束时间、结果、耗时、操作人（如果涉及人工介入）。
- 重试机制：对于网络抖动或临时存储故障导致的失败，允许最多重试 3 次，每次间隔 5 秒。
- 熔断保护：如果连续 10 个包校验失败，触发熔断，暂停校验服务并告警。
注意：不要将校验失败信息直接返回给调用方，避免泄露内部路径、哈希值或签名算法细节。应返回通用错误码，详细原因仅记录在审计日志中。
3.7 流程设计检查清单
在实现校验流程前，建议对照以下清单进行设计评审：
- 是否每个阶段都有明确的输入/输出定义？
- 是否所有阶段都具备幂等性？
- 是否对解压路径穿越和 ZIP 炸弹做了防护？
- 完整性校验是否使用了 SHA-256 或更安全的算法？
- 签名校验是否验证了证书链和有效期？
- 准入决策是否支持强制、警告、灰度三种模式？
- 是否所有失败都有结构化错误码和审计日志？
- 是否实现了重试和熔断保护？