本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 Amazon ECR 时排查 Docker 命令和问题
<a name="common-errors-docker"></a>

有时，针对 Amazon ECR 运行 Docker 命令可能导致错误消息。一些常见错误消息和可能的解决办法解释如下。

**Topics**
+ [Docker 日志不包含预期的错误消息](#debug)
+ [从 Amazon ECR 存储库提取镜像时，出现错误：“Filesystem Verification Failed”(文件系统验证失败) 或“404: Image Not Found”(404：找不到镜像)](#error-filesystem-verification-failed)
+ [从 Amazon ECR 提取镜像时，出现错误：“Filesystem Layer Verification Failed”(文件系统分层验证失败)](#error-filesystem-layer-verification)
+ [推送到存储库时出现 HTTP 403 错误或“no basic auth credentials”(没有基础级验证凭证) 错误](#error-403)

## Docker 日志不包含预期的错误消息
<a name="debug"></a>

要开始调试任何 Docker 相关问题，首先在您的主机实例上运行的 Docker 守护程序中开启 Docker 调试输出。如果您使用从 Amazon ECS 容器实例上的 Amazon ECR 中提取的映像，则请参阅 *Amazon Elastic Container Service Developer Guide* 中的 [Configuring verbose output from the Docker daemon](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-debug-mode.html)。

## 从 Amazon ECR 存储库提取镜像时，出现错误：“Filesystem Verification Failed”(文件系统验证失败) 或“404: Image Not Found”(404：找不到镜像)
<a name="error-filesystem-verification-failed"></a>

在 Docker 1.9 或更高版本中使用 **docker pull** 命令从 Amazon ECR 存储库提取镜像时，可能会收到错误 `Filesystem verification failed`。如果使用的是 1.9 之前的 Docker 版本，则可能收到错误 `404: Image not found`。

以下为一些可能的原因及它们的解释。

本地磁盘已满  
如果运行 **docker pull** 命令的本地磁盘已满，那么对本地文件计算的 SHA-1 哈希值可能与 Amazon ECR 计算的 SHA-1 哈希值不同。确保本地磁盘有足够的剩余空间可存储所提取的 Docker 镜像。为腾出空间存储新镜像，可以删除旧镜像。使用 **docker images** 命令可查看所有已下载到本地的 Docker 镜像的列表及这些镜像的大小。

由于网络错误，客户端无法连接到远程存储库  
调用 Amazon ECR 存储库需要 Internet 连接正常。验证网络设置，然后验证其他工具和应用程序是否可以访问 Internet 上的资源。如果在私有子网中对 Amazon EC2 实例运行 **docker pull**，请验证该子网是否具有连接至 Internet 的路由。可使用网络地址转换 (NAT) 服务器或托管的 NAT 网关。  
目前，对 Amazon ECR 存储库的调用还要求通过您的公司防火墙访问 Amazon Simple Storage Service (Amazon S3)。如果贵企业或组织使用的是允许服务终端节点的防火墙软件或 NAT 设备，请确保当前区域的 Amazon S3 服务终端节点在允许范围内。  
如果您通过 HTTP 代理使用 Docker，可以对 Docker 进行相应的代理设置。有关更多信息，请参阅 Docker 文档中的 [HTTP 代理](https://docs.docker.com/engine/admin/systemd/#/http-proxy)。

## 从 Amazon ECR 提取镜像时，出现错误：“Filesystem Layer Verification Failed”(文件系统分层验证失败)
<a name="error-filesystem-layer-verification"></a>

您可能在使用 `image image-name not found` 命令提取镜像时收到错误 **docker pull**。如果检查 Docker 日志，可能会看到与下面类似的错误：

```
filesystem layer verification failed for digest sha256:2b96f...
```

此错误表示镜像的一个或多个层下载失败。以下为一些可能的原因及它们的解释。

您正在使用旧版本的 Docker  
在使用低于 1.10 的 Docker 版本时，有少数情况会出现此错误。请将您的 Docker 客户端升级至 1.10 或更高版本。

您的客户端遇到网络错误或磁盘错误  
 如前文对 `Filesystem verification failed` 消息的讨论中所述，磁盘已满或网络问题可能会导致一个或多个层无法下载。请遵循上述建议确保您的文件系统未满，并且您在网络中有对 Amazon S3 的访问权限。

## 推送到存储库时出现 HTTP 403 错误或“no basic auth credentials”(没有基础级验证凭证) 错误
<a name="error-403"></a>

有时，即使您已使用 **aws ecr get-login-password** 命令成功通过 Docker 身份验证，也可能会从 **docker push** 或 **docker pull** 命令收到 `HTTP 403 (Forbidden)` 错误或者错误消息 `no basic auth credentials`。以下是此问题的一些已知的原因：

您已验证到其他区域  
身份验证请求与特定的区域相关联，不能跨区域使用。例如，如果您从美国西部 (俄勒冈) 获得授权令牌，不能使用它对您在美国东部 (弗吉尼亚北部) 的存储库进行身份验证。要解决此问题，请确保您已从存储库所在的同一区域检索了身份验证令牌。有关更多信息，请参阅 [Amazon ECR 中的私有注册表身份验证](registry_auth.md)。

您已进行身份验证以推送到您没有权限的存储库  
您没有必要的权限来推送到存储库。有关更多信息，请参阅 [Amazon ECR 中的私有存储库策略](repository-policies.md)。

您的令牌已过期。  
对于使用 `GetAuthorizationToken` 操作获取的令牌，默认授权令牌有效期为 12 小时。

`wincred` 凭证管理器中的错误  
某些版本的适用于 Windows 的 Docker 使用名为 `wincred` 的凭证管理器，但它无法正确处理 **aws ecr get-login-password** 生成的 Docker 登录命令（有关更多信息，请参阅[使用私有存储库 `CredsStore` 失败](https://github.com/moby/moby/issues/22910)）。可以运行作为输出的 Docker 登录命令，但如果尝试推送或提取镜像，这些命令会失败。修复这个错误的方法是，对于从 **aws ecr get-login-password** 输出的 Docker 登录命令，删除其注册表参数中的 `https://` 方案。如下所示为不带 HTTPS 方案的 Docker 登录命令示例。  

```
docker login -u AWS -p <password> <aws_account_id>.dkr.ecr.<region>.amazonaws.com
```