4. 分发失败分类：网络故障、权限问题、存储不足、配置错误、依赖缺失

制品分发失败的原因通常可以归纳为五大类。快速识别失败类型，是执行后续恢复步骤的前提。本节将逐一分析每种失败的表现、根因与初步排查方向。

4.1 五大失败类型总览

4.2 网络故障

网络故障是分发失败中最常见的一类，通常表现为连接超时、路由不可达或连接被拒绝。故障可能发生在源端、目标端或中间网络链路。

• 连接超时： 目标主机未在指定时间内响应。检查防火墙规则、安全组策略、网络 ACL。
• 路由不可达： 源端无法找到通往目标主机的路径。检查路由表、VPN 隧道状态、DNS 解析记录。
• 连接被拒绝： 目标端口未监听或服务未启动。确认目标服务状态、端口监听情况。

# 快速诊断网络故障示例
# 1. 检查 DNS 解析
nslookup artifacts.internal.company.com

# 2. 测试端口连通性
telnet artifacts.internal.company.com 443

# 3. 追踪路由路径
traceroute artifacts.internal.company.com

# 4. 检查本地网络接口
ip addr show

4.3 权限问题

权限问题通常源于身份认证失败或授权不足。在制品分发场景中，常见于 过期、服务账户角色绑定错误或存储桶策略配置不当。

• 认证失败： 凭证无效、令牌过期、证书不受信任。
• 授权不足： 用户/服务账户缺少对目标存储桶、仓库或 API 的写入/读取权限。
• 密钥轮换未同步： 分发系统使用的密钥已被轮换，但客户端未更新。

# 检查 AWS S3 权限示例
aws s3 ls s3://my-artifacts-bucket/ --profile deploy-role

# 检查 Kubernetes RBAC
kubectl auth can-i create pods --as=system:serviceaccount:default:deployer

# 验证令牌有效性
curl -I -H "Authorization: Bearer $" https://artifacts.internal.company.com/v2/

4.4 存储不足

存储不足导致分发失败时，目标端无法接收新制品。此问题在长时间运行的系统或日志未轮转的环境中尤为突出。

4.5 配置错误

配置错误通常发生在环境迁移、配置管理工具更新或手动修改配置文件后。错误配置会导致分发系统无法正确连接目标端点或解析制品路径。

• 端点 URL 错误： 协议、域名、端口或路径拼写错误。
• 环境变量缺失： 分发脚本依赖的变量未定义或值为空。
• 配置文件格式错误： YAML/JSON 缩进错误、多余逗号、类型不匹配。

# 验证配置文件示例
# 检查 YAML 格式
python -c "import yaml; yaml.safe_load(open('deploy-config.yaml'))"

# 检查 JSON 格式
cat config.json | jq .

# 验证环境变量
echo $ARTIFACT_REPO_URL

4.6 依赖缺失

依赖缺失发生在制品运行时所需的库、模块或基础镜像未就绪。此问题在制品分发到新环境或基础镜像版本更新后尤为常见。

• 运行时库缺失： 如 libssl.so.1.1、libc.so.6 版本不匹配。
• 语言级依赖： Python 的 requirements.txt 中包未安装，Node.js 的 node_modules 缺失。
• 基础镜像问题： 分发目标节点缺少制品依赖的特定操作系统包或内核模块。

# 检查依赖缺失示例
# Python 环境
pip list | grep -i requests

# 系统库检查
ldd /usr/local/bin/my-artifact | grep "not found"

# 容器镜像依赖
docker run --rm my-image:latest ldd /app/artifact

4.7 失败分类决策流程

以下 SVG 流程图展示了从收到分发失败告警到确定失败类型的快速决策路径，帮助运维人员按优先级逐步缩小排查范围。

4.8 分类排查清单

以下清单可作为 Runbook 的快速参考，帮助一线运维人员按步骤完成失败分类。

1. 第一步： 检查网络连通性（ping、telnet、curl）。
2. 第二步： 验证认证凭证与授权策略（令牌、角色绑定）。
3. 第三步： 检查目标存储空间（磁盘、inode、配额）。
4. 第四步： 核对分发配置文件与环境变量（端点、路径、格式）。
5. 第五步： 验证制品依赖完整性（库、模块、基础镜像）。