ACR镜像拉取失败主因是未认证，需用AccessKey或临时令牌登录对应地域域名；K8s需配置imagePullSecrets；域名须与ACR实例一致；Webhook需配Jenkins插件及CSRF豁免。
ACR 镜像拉取失败：unauthorized: authentication required
这是最常见问题，本质是 Docker 客户端没带有效凭证访问私有仓库。ACR 不接受匿名拉取，哪怕镜像设为“公开”，也仍需登录（ACR 的“公开”仅指可被他人搜索到，不等于免认证）。
实操建议：
- 必须先执行
docker login --username=xxx --password=yyy registry.cn-hangzhou.aliyuncs.com，其中域名要和镜像地址前缀完全一致（比如镜像为registry.cn-shanghai.aliyuncs.com/abc/myapp，就该用上海地域域名登录） - 密码不能直接填主账号密码；应使用 ACR 控制台「访问凭证」页生成的长期访问凭证（
AccessKey ID+AccessKey Secret），或更安全的临时令牌（通过 STS 或 RAM 角色获取） - CI/CD 场景下避免硬编码凭证；推荐用
aliyun-acr-credentials这类插件自动注入，或挂载~/.docker/config.json作为 Secret
Pod 启动报错：Failed to pull image "xxx": rpc error: code = Unknown desc = unauthorized: authentication required
K8s 集群拉不到 ACR 镜像，通常不是镜像地址写错，而是缺少 imagePullSecrets 绑定。
实操建议：
- 先确认 Secret 是否存在：运行
kubectl get secret regcred -n default，它必须是用docker-registry类型创建的，且数据字段为.dockerconfigjson - Secret 必须和 Pod 在同一命名空间；跨 namespace 不生效（K8s 默认行为）
- Deployment 中需显式声明：
spec.template.spec.imagePullSecrets: [{name: regcred}]；不要依赖默认 ServiceAccount 自动挂载（除非你改过defaultSA 的imagePullSecrets字段） - 阿里云 ACK 用户可启用「容器镜像服务企业版」+「集群自动同步凭证」功能，省去手动维护 Secret 步骤
ACR 镜像地址里的地域域名选错导致超时或 404
ACR 实例分地域部署，每个实例有唯一域名（如 registry.cn-beijing.aliyuncs.com）。用错域名不会跳转，而是直连失败或返回 404 Not Found（因该域名下根本不存在你的命名空间）。
实操建议：
- 镜像地址前缀必须与 ACR 实例控制台显示的「公网访问地址」完全一致；注意区分「专有网络访问地址」（VPC 内网用）和「公网地址」（ECS 公网/本地开发用）
- 不同地域的实例之间不互通；不能把杭州实例的镜像地址写成上海的域名，哪怕你账号下两个实例都开了
- 多地域部署时，建议在 CI 流水线中用变量控制镜像前缀，例如：
IMAGE_REPO=${ACR_REGION}.aliyuncs.com/my-namespace
配置 ACR Webhook 触发 Jenkins 构建但收不到回调
ACR Webhook 默认只触发 POST 请求，但 Jenkins 若未开启 CSRF 保护豁免或未配对 Webhook URL 路径，会直接拒收。
实操建议：
- Webhook 地址必须是 Jenkins 可公网访问的 URL，且路径以
/generic-webhook-trigger/invoke结尾（对应 Generic Webhook Trigger 插件） - Jenkins 系统配置里要关闭
Prevent Cross Site Request Forgery exploits，或为该 URL 添加 CSRF 白名单（否则 403） - ACR 控制台配置 Webhook 时，“事件类型”至少勾选
push；“过滤器”填镜像名（如myapp），不要带仓库域名或命名空间前缀 - 调试时打开 Jenkins 日志（
org.jenkinsci.plugins.gwt级别设为 FINE），看是否收到请求、卡在哪一步
