3、常见故障分类

在流水线集成 IDP 制品签名链路的实际运维中，故障可归纳为五大类：密钥类、网络类、权限类、配置类和环境类。每一类故障的根因、表现和排查路径差异显著。以下通过分类表格、故障树 SVG 和详细说明，帮助您建立系统化的故障分类认知。

3.1 故障分类总览

3.2 密钥类故障

密钥是签名链路的信任锚点。密钥类故障通常直接导致签名操作失败或验证不通过。常见子类包括：

• 私钥不可用：私钥文件损坏、被误删除、或被加密但解密密码错误。
• 证书过期或吊销：签名证书或中间 CA 证书超出有效期，或被列入 CRL/OCSP 吊销列表。
• 密钥算法不匹配：签名工具使用 RSA 密钥，但验证方只支持 ECDSA；或密钥长度不符合策略要求。
• HSM/KMS 连接异常：硬件安全模块（HSM）或云密钥管理服务（KMS）网络不可达、API 限流、或密钥句柄失效。

3.3 网络类故障

签名链路通常涉及多个远程端点：密钥服务器、证书吊销列表（CRL）分发点、时间戳服务器（TSA）、以及制品仓库。网络故障会阻断这些通信。

• 防火墙/安全组规则：出站端口被限制（如 443、8443），或目标 IP 不在白名单内。
• DNS 解析失败：CRL 分发点域名无法解析，导致证书验证挂起。
• TLS 握手异常：证书链不完整、服务器使用自签名证书、或 TLS 版本不兼容。
• 代理配置错误：CI/CD 环境通过代理访问外网，但代理认证信息缺失或代理地址错误。

# 测试 CRL 分发点可达性
curl -vI https://crl.example.com/root.crl

# 测试时间戳服务器连通性
openssl s_client -connect timestamp.example.com:443 -servername timestamp.example.com

3.4 权限类故障

在云原生或微服务架构中，签名操作通常由流水线中的服务账号（Service Account）或 IAM 角色执行。权限不足是常见故障源。

• KMS 密钥策略：IAM 角色未被授予 kms:Sign 或 kms:Verify 权限。
• RBAC 绑定缺失：Kubernetes 中，Pod 使用的 ServiceAccount 未绑定到允许访问签名 Secret 的 Role。
• 资源级权限限制：密钥策略中指定了 aws:SourceArn 条件，但流水线使用的 ARN 不匹配。
• 审计日志权限不足：无法读取 CloudTrail 或审计日志，导致无法追溯签名失败原因。

3.5 配置类故障

配置类故障往往源于人为疏忽或模板化流水线的参数传递错误。这类故障在流水线迁移或环境复制时尤为高发。

• 签名配置文件格式错误：YAML/JSON 缩进错误、字段名拼写错误、或引用了不存在的密钥别名。
• 环境变量遗漏：签名工具依赖 SIGN_KEY_ID、CERT_PATH 等变量，但流水线未注入。
• CI/CD 参数错位：签名阶段使用了构建阶段的输出变量，但变量名在上下游不一致。
• 签名算法参数不匹配：配置中指定 algorithm: SHA256withRSA，但实际密钥只支持 SHA384withECDSA。

3.6 环境类故障

环境类故障通常与签名工具链的依赖和运行时上下文相关。这类故障在容器化部署或异构 CI/CD 平台中尤为突出。

• 签名工具未安装：流水线 Agent 镜像中缺少 cosign、gpg、openssl 等签名工具。
• 动态链接库缺失：HSM 客户端依赖的 PKCS#11 库（如 libsofthsm2.so）未正确安装或路径未配置。
• 操作系统 CA 证书库不完整：容器镜像基于 Alpine，缺少 ca-certificates 包，导致 HTTPS 证书验证失败。
• 时区/时间不同步：签名验证依赖时间戳，但 Agent 系统时间与 NTP 偏差过大，导致证书有效期判断错误。

3.7 故障分类关系图

以下 SVG 图展示了五大故障类别之间的依赖关系与典型故障传播路径，帮助您快速定位故障根因。

3.8 故障排查优先级矩阵

根据故障影响范围和修复成本，以下矩阵可帮助团队制定故障响应策略：