如何调试Docker推送至Google Artifacts Registry的"manifest unknown"错误？

我们通过GitLab CI将镜像推送至Google Artifacts Registry，用于部署到Google Cloud Run，但该流程突然失效。

执行的CI脚本 #

- echo $SERVICE_ACCOUNT_KEY > ./____keyfile.json
- gcloud auth activate-service-account --key-file="./____keyfile.json"
- gcloud auth configure-docker europe-west1-docker.pkg.dev
- docker pull $DOCKER_IMAGE:$DOCKER_IMAGE_TAG # 拉取之前推送到GitLab私有镜像仓库的构建好的镜像
- docker tag $DOCKER_IMAGE:$DOCKER_IMAGE_TAG europe-west1-docker.pkg.dev/project-id/repository/$DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG
- docker push europe-west1-docker.pkg.dev/project-id/repository/$DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG

推送操作输出日志 #

The push refers to repository [europe-west1-docker.pkg.dev/project-id/repository/some-name]
bcf45157cf76: Preparing
151948c565a1: Preparing
5455690f232d: Preparing
65f565da952a: Preparing
66b19dc4e200: Preparing
e796b82d6587: Preparing
dcd9c7cf433b: Preparing
1f1a410f80c7: Preparing
b45078e74ec9: Preparing
e796b82d6587: Waiting
dcd9c7cf433b: Waiting
1f1a410f80c7: Waiting
b45078e74ec9: Waiting
151948c565a1: Layer already exists
65f565da952a: Layer already exists
bcf45157cf76: Layer already exists
66b19dc4e200: Layer already exists
5455690f232d: Layer already exists
e796b82d6587: Layer already exists
dcd9c7cf433b: Layer already exists
b45078e74ec9: Layer already exists
1f1a410f80c7: Layer already exists
manifest unknown: Requested entity was not found.

该错误信息过于笼统，无法定位具体问题，请问是否可以查看更详细的日志？

获取更详细日志的方法 #

1. 开启Docker推送调试模式 #

在docker push命令中添加--debug参数，同时关闭内容信任以避免额外校验干扰：

DOCKER_CONTENT_TRUST=0 docker push --debug europe-west1-docker.pkg.dev/project-id/repository/$DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG

此命令会输出Docker与镜像仓库交互的完整HTTP请求、响应细节，包括认证状态、路径校验结果等，能直接定位具体故障点。

2. 增强gcloud命令日志级别 #

在所有gcloud相关命令后添加--verbosity=debug参数，比如：

gcloud auth activate-service-account --key-file="./____keyfile.json" --verbosity=debug
gcloud auth configure-docker europe-west1-docker.pkg.dev --verbosity=debug

这会输出gcloud认证、配置过程的详细日志，排查是否存在服务账号权限不足、密钥失效、区域配置错误等问题。

3. 校验CI环境变量正确性 #

在脚本中添加echo命令打印关键变量值，确认推送路径是否正确：

echo "当前推送目标：europe-west1-docker.pkg.dev/project-id/repository/$DOCKER_IMAGE_NAME:$DOCKER_IMAGE_TAG"

避免因变量值错误（比如镜像名称、标签拼写错误）导致推送至不存在的仓库路径。

内容的提问来源于stack exchange，提问作者macrozone