docker sdk自动化流程需显式处理四步异常：拉取须指定tag防404、构建须消费logs防阻塞、打标前校验格式、推送须stream遍历判成功。
直接用 docker.from_env() 就能连上本地 Docker 守护进程，但镜像拉取、构建、打标、推送这四步里，任意一步出错都会卡住自动化流程——尤其是 client.images.pull() 和 client.images.build() 的错误处理不写清楚，脚本一跑就静默失败。
拉取镜像时 tag 不写全会默认 latest，但私有仓库常禁用 latest
很多团队在 Harbor 或自建 registry 中禁用 latest 标签，防止意外覆盖。这时如果只写 client.images.pull('myapp')，SDK 会自动补 :latest，然后返回 404 Client Error，但错误信息藏在异常的 response.status_code 里，不是标准 Python 异常类型。
- 必须显式指定 tag：
client.images.pull('myapp', tag='v2.3.1') - 捕获异常时要检查
docker.errors.ImageNotFound和docker.errors.APIError两类 - 私有仓库需提前
client.login()，否则拉取时会报401 Unauthorized，且不会提示缺登录
build() 返回的 logs 是生成器，不消费就会卡住构建过程
client.images.build() 默认返回一个 (image, logs) 元组，其中 logs 是个 generator。如果你只取 image 却不遍历 logs，Docker 守护进程会卡在流式响应阶段，后续操作（比如打标或推送）会超时或阻塞。
- 安全做法是始终消费日志：
for log in logs: print(log.get("stream", "").strip()) - 若只想后台构建不看日志，改用底层 API：
client.api.build(..., decode=True)，再手动丢弃 chunk -
path参数必须是字符串路径，不能是Path对象；相对路径以当前工作目录为基准，不是脚本所在目录
给镜像打多个 tag 时，tag() 方法不校验仓库地址格式
image.tag() 只做字符串拼接，不会验证 repository 是否符合 host:port/namespace/repo 规范。一旦传入非法格式（比如漏了 registry.example.com 前缀），后续 push() 会报 400 Bad Request，错误信息里只说 “invalid reference format”，很难定位是哪个 tag 出的问题。
- 推送前先用正则粗筛：
re.match(r'^[a-z0-9.-]+(:[0-9]+)?(/[a-z0-9._-]+)+:[a-z0-9._-]+$', full_tag) - 每个
tag()调用后，检查image.tags是否已更新，避免重复打标导致镜像膨胀 - 不要对同一镜像频繁
tag()+push()，Docker 会复用层，但 registry 端可能触发 rate limit
push() 不等上传完成就返回，需 stream=True + 检查最后一行状态
client.images.push('myapp:v1.2') 默认是异步发起请求，立刻返回一个 generator，不代表上传结束。如果紧接着执行部署逻辑，可能拿到的是未完全推送成功的镜像。
- 务必加
stream=True并遍历输出：for line in client.images.push('myapp:v1.2', stream=True): ... - 最后一行通常是
{"status":"Pushed","progressDetail":{},"id":"v1.2"}，用json.loads(line).get("status") == "Pushed"判断成功 - 私有仓库推送失败时，
line可能是{"errorDetail":{"message":"unauthorized: authentication required"}}，得提前login()
真正难的不是调哪个方法，而是每个方法背后都藏着 Docker daemon 的状态机和 registry 的策略约束；一次 push 失败，可能是镜像没 build 成、tag 拼错了、login 过期了、网络 DNS 解析失败，或者 registry 配额满了——而 SDK 报的错往往只说“something went wrong”。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
