使用cr-diagnosis排查镜像推送与拉取异常

诊断模式

cr-diagnosis通过提供 DNS 测试、域名连通性测试、自动抓包分析以及镜像拉取验证，快速定位网络连通性、凭据及权限问题。

针对不同的问题场景，cr-diagnosis提供了四种不同的测试：

• DNS 测试：查询实例域名的解析记录，检测域名解析是否正常。

• 连通性测试：测试实例域名的连通性，验证 DNS 解析 IP 与实际连接 IP 是否一致。

• 认证测试：模拟客户端发起镜像拉取请求，分析推拉凭据及 RAM 权限问题。

• 抓包分析：对ACR服务域名进行抓包分析，检测网络问题。

  连通性测试失败时触发，用户确认后才会执行。

以上四种测试可以通过两种诊断模式执行：

安全性保证

• 所有网络请求均为 GET、HEAD 只读操作，不会修改系统配置和存储数据。

• cr-diagnosis不会存储任何凭据信息，测试过程中仅通过 HTTPS 请求向 ACR 实例发起访问。

• 进行抓包分析时，cr-diagnosis会精确捕获与诊断目标相关的流量，不获取其他网络活动的信息。

DNS 解析失败

问题现象：域名无法解析，docker pull 报错 no such host。

诊断命令：

cr-diagnosis -m network ACR_DOMAIN

诊断输出：

...

[DNS] DNS-RESOLVER
├─ [ERROR] Error: no such host

[WARN] DIAGNOSIS COMPLETE - Some checks failed

结果解读：DNS 解析失败，域名无法解析为 IP 地址。后续连通性测试和认证测试阶段已跳过。

修复建议：

• 如果使用内网域名，请确认实例是否已配置专有网络的访问控制。

• 检查当前环境的 DNS 配置是否正常，可尝试使用 nslookup 或 dig 命令手动解析域名。

网络丢包或延迟（抓包分析）

问题现象：镜像拉取间歇性失败，怀疑存在网络丢包或延迟，无法判断具体原因。

诊断命令：

cr-diagnosis -y -c --save-pcap ./capture.pcap ACR_DOMAIN

诊断输出：

═══════════════════════════════════════════════════════════════
                       PACKET CAPTURE REPORT                      
═══════════════════════════════════════════════════════════════
  [Capture Info]
    Interface: en0
    Duration: 10.001s
    Target Domains: xxx.cr.aliyuncs.com
    Target IPs: 8.xxx.xxx.xxx
  [Packet Statistics]
    Total Packets: 5
    Total Bytes: 390
    TCP Packets: 5
    UDP Packets: 0
    DNS Packets: 0
    TLS Packets: 0
  [TCP Handshake]
    SYN: 5, SYN-ACK: 0, RST: 0, FIN: 0
    Attempts: 1, Succeeded: 0, Failed: 0
  [Key Packets]
    15:07:29.873 30.xxx.xxx.xxx:61593 -> 8.xxx.xxx.xxx:443 [SYN] TCP Handshake: SYN
    15:07:30.872 30.xxx.xxx.xxx:61593 -> 8.xxx.xxx.xxx:443 [SYN] TCP Handshake: SYN
    15:07:31.874 30.xxx.xxx.xxx:61593 -> 8.xxx.xxx.xxx:443 [SYN] TCP Handshake: SYN
    15:07:32.874 30.xxx.xxx.xxx:61593 -> 8.xxx.xxx.xxx:443 [SYN] TCP Handshake: SYN
    15:07:33.874 30.xxx.xxx.xxx:61593 -> 8.xxx.xxx.xxx:443 [SYN] TCP Handshake: SYN
  [Diagnosis]
    SYN packets sent but no SYN-ACK received. Target may be unreachable or firewalled. | TCP handshake failed. Check network connectivity and firewall rules.

结果解读：TCP 握手过程中持续发送 SYN 包但未收到 SYN-ACK 响应，表明目标不可达或存在防火墙拦截。可能的原因包括：实例入口访问控制阻止了连接、网络链路存在丢包或限速。

修复建议：

• 检查 ACR 实例的网络访问控制策略，确认当前 IP 是否已列入白名单。

• 使用保存的 pcap 文件通过 Wireshark 等工具进行深入分析。

• 检查网络链路是否存在瓶颈或拥塞。

• 确认是否存在网络限速策略。

认证失败（凭据错误）

问题现象：网络连通正常，但认证测试不通过。

诊断命令：

cr-diagnosis -u USERNAME -p PASSWORD ACR_DOMAIN /NAMESPACE/IMAGE_NAME:TAG

诊断输出：

[AUTH] AUTH-FLOW
├─ [ERROR] token request with credentials failed: token request failed with status 401: {"error":"incorrect username or password"}
├─ Realm Domain: dockerauth.cn-hangzhou.aliyuncs.com
│  ├─ Actual IP: 120.xxx.xxx.xxx (IPv4)
│  └─ [OK] IP Match
├─ Token Request: [WARN] 401 Unauthorized
│  ├─ URL: https://dockerauth.cn-hangzhou.aliyuncs.com/auth?service=registry.aliyuncs.com:cn-hangzhou:china:cri-xxx9&scope=
│  └─ [ERROR] token request with credentials failed: token request failed with status 401: {"error":"incorrect username or password"}

结果解读：认证服务可达，但使用凭据获取 Token 失败（HTTP 401），返回错误信息 incorrect username or password，说明用户名或密码不正确。

修复建议：

• 确认用户名和密码是否正确。

• 若使用临时凭据，确认凭据未过期。

权限不足

问题现象：认证测试通过，但无法拉取镜像。

诊断命令：

cr-diagnosis -y -u USERNAME -p PASSWORD ACR_DOMAIN /NAMESPACE/IMAGE_NAME:TAG

诊断输出：

[AUTH] AUTH-FLOW
├─ Realm Domain: dockerauth-xxx.aliyuncs.com
├─ Anonymous Token Test: [OK] 200 OK
├─ Token Request: [OK] 200 OK
├─ Token Validation: [ERROR] 403 Forbidden
│  └─ [ALERT] Insufficient permissions for the target resource

[WARN] DIAGNOSIS COMPLETE - Some checks failed

结果解读：凭据有效且认证成功（Token Request 返回 200），但在验证 Token 访问目标资源时返回 403 Forbidden，说明当前凭据无权访问目标资源。

修复建议：

• 确认命名空间和镜像名称拼写正确。

• 检查 RAM 用户的权限策略，确认用户是否拥有 cr:PullRepository、cr:PushRepository 等ACR相关权限。如果尚未配置权限，请参见管理权限策略授权更新授权配置。