后端容器编排【免费下载链接】docker-pyA Python library for the Docker Engine API项目地址https://gitcode.com/gh_mirrors/do/docker-py点击查看免费下载导读本指南围绕 docs/containers.rst 所定义的容器管理接口展开系统讲解 Docker SDK for Pythondocker-py中client.containers集合与Container对象的全部能力从run/create创建容器到list/get查询容器再到logs、exec_run、stats等运行时交互以及commit、get_archive等文件系统操作。读完本文你将掌握用 Python 完成docker 命令行能做的一切容器操作的完整 API 用法并通过 docker/models/containers.py 与 docker/api/container.py 的源码剖析理解其底层调用链与参数分派机制。概览容器管理的两大入口容器管理功能由两个类承担均位于 docker/models/containers.pyContainerCollection代表服务器上的容器集合挂在client.containers上负责创建、查询、清理容器对应 CLI 的docker run、docker create、docker ps、docker rm -aprune。Container单个容器的本地模型对象封装了对该容器的一切操作启停、日志、执行、监控等对应 CLI 的docker start/stop/restart/logs/exec/stats/commit等命令。ContainerCollection继承自 docker/models/resource.py 中的Collection基类Container继承Model基类。Model基类提供了id取attrs[Id]、short_idID 截取前 12 位、reload()重新从 daemon 拉取并刷新attrs等通用能力并规定attrs保存服务器返回的原始 JSON 表示。一、ContainerCollection容器的创建、查询与清理文档定义集合上可用五个方法run、create、get、list、prune。1.1 run一键运行并等待或后台运行run(image, commandNone, **kwargs)是最高层级的入口等价于docker run。默认行为是等待容器运行结束并返回其日志当detachTrue时立即返回Container对象等价于docker run -d。import docker client docker.from_env() # 前台运行返回日志字节串 out client.containers.run(alpine, echo hello world) # bhello world\n # 后台运行返回 Container 对象 container client.containers.run(bfirsh/reticulate-splines, detachTrue) print(container.logs()) # Reticulating spline 1...\nReticulating spline 2...\n从源码看run的执行流程相当值得注意docker/models/containers.py若传入Image对象先取其id作为镜像标识弹出stream、detach两个专用参数detach与remove同用时若 API 版本 1.25 则转为 daemon 侧auto_removeTrue否则直接抛RuntimeError老版本 daemon 不支持组合校验参数互斥关系network与network_mode不能同时使用networking_config必须搭配network调用create()创建容器若抛出ImageNotFound异常则自动client.images.pull(image, platformplatform)拉取镜像后重试创建container.start()启动容器若detachTrue直接返回对象前台模式下先检查日志驱动只有json-file或journald驱动才可能读取日志否则out为None随后container.wait()阻塞等待退出码退出码非 0 时收集 stderr 日志并抛出docker.errors.ContainerErrorremoveTrue时自动移除容器。# 指定名称、环境变量、端口映射与资源限制 client.containers.run( nginx:1.25, nameweb-app, detachTrue, ports{80/tcp: 8080}, environment{NGINX_HOST: example.com}, mem_limit512m, cpu_shares512, )run的关键返回语义非 detach 模式返回日志字节串stdout/stderr由参数控制默认只取 stdoutdetachTrue返回ContainerstreamTrue且非 detach 时返回日志生成器。注意只有json-file或journald日志驱动下日志才可读否则返回None。1.2 create只创建不启动create(image, commandNone, **kwargs)等价于docker create参数与run一致除stdout、stderr、remove外返回尚未启动的Container对象。创建后需手动调用container.start()启动。create内部把参数交给_create_container_args()拆分成容器配置与主机配置两部分再调用底层self.client.api.create_container()见 docker/api/container.py 中的create_container方法最后通过get(resp[Id])反查拿到完整对象。container client.containers.create(ubuntu, sleep 60, namepending) container.start() # 稍后手动启动 container.stop()1.3 get按 ID 或名称获取容器get(id_or_name)按名称或 ID 精确获取单个容器内部调用inspect_container并包装成Container对象。容器不存在时抛出docker.errors.NotFound。container client.containers.get(45e6d2de7c54) print(container.attrs[Config][Image]) # bfirsh/reticulate-splines1.4 list等价 docker pslist(allFalse, beforeNone, filtersNone, limit-1, sinceNone, sparseFalse, ignore_removedFalse)返回Container对象列表。默认只列出运行中的容器。# 列出所有容器含已退出 all_containers client.containers.list(allTrue) # 按过滤条件查询 client.containers.list( filters{ status: exited, # restarting | running | paused | exited exited: 0, # 指定退出码 label: [envprod, tierbackend], # key 或 keyvalue 或列表 ancestor: nginx:1.25, # 镜像名[:tag]、镜像 ID 或 imagedigest name: web, # 按名称过滤 since: old_container, # 在某个容器之后创建 before: new_container, # 在某个容器之前创建 } )filters支持exited退出码、statusrestarting/running/paused/exited、label支持key、keyvalue或列表、id、name、ancestor、before、since。两个进阶参数值得注意sparseTrue不逐个 inspect 容器直接返回 daemon 列表接口的稀疏数据保证不被阻塞此时对象上labels、status等依赖完整attrs的属性可能不可用需调用Container.reload()补全。labels属性在稀疏对象上会抛出DockerException(Label data is not available for sparse objects. Call reload()...)。ignore_removedTrue在列表遍历过程中容器被并发移除导致NotFound时静默跳过源码中list对每个 ID 调用self.get(r[Id])捕获NotFound后根据该参数决定是否忽略。1.5 prune清理已停止的容器prune(filtersNone)清理所有已停止容器等价于docker container prune。它直接透传到底层APIClient.prune_containers其文档字符串也被复制到集合方法上即源码中的prune.__doc__ APIClient.prune_containers.__doc__。可传filters{until: ...}之类的过滤条件返回包含ContainersDeleted、SpaceReclaimed等键的字典。二、Container 对象的属性与数据访问Container是服务器上容器对象的本地表示其attrs属性保存 daemon 返回的完整原始 JSON来自inspect。文档明确列出的核心属性属性说明底层实现要点attrs服务器返回的原始表示dict来自Model基类可被reload()刷新id容器完整 ID取attrs[Id]short_idID 截取前 12 字符由Model.short_id提供也用于__repr__image容器所用镜像取attrs[ImageID]回退attrs[Image]并调用self.client.images.get()返回Image对象labels标签字典取attrs[Config][Labels]稀疏对象上会抛DockerExceptionname容器名称取attrs[Name]并去除前导/status状态running/exited 等State为 dict 时取State[Status]否则直接取State源码中还有两个文档未单列但同样实用的只读属性health取attrs[State][Health][Status]返回healthy、unhealthy或unknownports取attrs[NetworkSettings][Ports]返回端口映射字典key 形如80/tcpvalue 为宿主机绑定列表。本地属性是缓存性质的容器状态变化后调用container.reload()重新查询 daemon 才能拿到最新attrs。三、容器生命周期管理Container对象提供与 CLI 一一对应的生命周期方法文档第 3455 行列举的start/stop/restart/kill/pause/unpause/wait/remove/rename/resize# 启动与停止 container.start() # 等价 docker start container.stop(timeout10) # 等待 10 秒后 SIGKILL默认 10 container.restart(timeout10) # 等价 docker restart # 强制终止与信号 container.kill(signalSIGTERM) # 默认 SIGKILL可传信号名或编号 # 暂停/恢复冻结 cgroup 内进程 container.pause() container.unpause() # 阻塞等待退出并返回退出码等价 docker wait result container.wait() # 返回 dict退出码在 result[StatusCode] # condition 支持 not-running默认、next-exit、removed需 API 1.30 result container.wait(conditionnext-exit) # 删除与重命名 container.remove(vFalse, linkFalse, forceFalse) # v: 同时删除关联卷link: 仅删除链接force: 对运行中容器强删SIGKILL container.rename(new-name) # 调整 TTY 会话尺寸 container.resize(height40, width120)底层对应 docker/api/container.py 中的 REST 调用stop会先把请求超时累加timeout秒以避免等待期间连接超时wait在 API 版本低于 1.30 时传入condition会抛InvalidVersionupdate_container标注了utils.minimum_version(1.22)。四、运行时交互日志、执行、进程与监控4.1 attach 与 attach_socketattach(**kwargs)挂接到容器输出流logs()本质上是它的包装区别是logs不必先拉取全部历史即可流式获取。参数stdout默认 True、stderr默认 True、streamTrue 时返回字符串迭代器、logs包含此前输出。默认返回整个输出字符串streamTrue返回生成器。attach_socket(**kwargs)则返回底层 socket 对象支持params如 stdout/stderr/stream与wsTrue改用 WebSocket 而非裸 HTTP便于自定义读写。4.2 logs获取与流式跟踪日志logs(**kwargs)等价于docker logs参数见 docker/models/containers.py 中Container.logs的文档stdout/stderr是否包含对应流默认均 Truestream默认 FalseTrue 时返回阻塞式生成器可逐行迭代实时输出timestamps默认 FalseTrue 时附加时间戳tail默认all可传整数只取末尾 N 行sincedatetime、整数 epoch 秒或浮点秒只取此后日志follow默认与stream一致until只取此时间之前的日志API 1.35 时抛InvalidVersion底层 docker/api/container.py 的logs有对应校验。# 一次性取全部日志 logs container.logs() # 流式跟踪阻塞生成器逐行打印 for line in container.logs(streamTrue, followTrue): print(line.strip()) # 取最近 50 行并带时间戳 tail container.logs(tail50, timestampsTrue)底层logs会把since/until的 datetime 转换为时间戳非法类型抛InvalidArgument流式返回CancellableStream包装对象。4.3 exec_run在容器内执行命令exec_run(cmd, ...)等价于docker exec返回具名元组ExecResult定义于 docker/models/containers.py 末尾ExecResult namedtuple(ExecResult, exit_code,output)含exit_code与output两个字段。# 基本用法 exit_code, output container.exec_run(ls -la /etc) # 以指定用户、工作目录和额外环境变量执行 result container.exec_run( npm run build, usernode, workdir/app, environment{NODE_ENV: production}, ) # 分离执行不等结果 container.exec_run(nohup ./daemon.sh, detachTrue) # 分别获取 stdout 与 stderr exit_code, (stdout, stderr) container.exec_run( cat /etc/shadow, demuxTrue )完整参数stdout默认 True、stderr默认 True、stdin默认 False、tty默认 False、privileged、user默认 root、detach、stream流式响应与 detach 互斥、socket返回连接 socket 以自定义读写、environment字典或[KEYvalue]列表、workdir、demux分别返回 stdout/stderr。返回语义源码可见底层先exec_create再exec_start当socket或stream为 True 时exit_code为Noneoutput 分别为 socket 或生成器demuxTrue时 output 为(stdout_bytes, stderr_bytes)二元组其余情况通过exec_inspect取真实退出码。4.4 top查看容器内进程top(ps_argsNone)等价于docker top返回容器内运行进程列表ps_args可传aux等 ps 参数。4.5 stats流式监控资源统计stats(**kwargs)等价于docker stats返回容器资源使用统计。参数decode仅 stream 模式下生效True 时逐条解码为 dict、stream默认 TrueFalse 时只返回当前快照。# 单次快照 current container.stats(streamFalse) # 流式监控decodeTrue 时每条为 dict for stat in container.stats(streamTrue, decodeTrue): print(stat[cpu_stats], stat[memory_stats])底层 docker/api/container.py 的stats还支持one_shot仅取单次统计需 API 1.41 且必须搭配streamFalse否则抛InvalidVersion/InvalidArgument。五、镜像与文件系统操作5.1 commit容器提交为镜像commit(repositoryNone, tagNone, **kwargs)等价于docker commit。参数repository目标仓库、tag目标标签、message提交信息、author、pause提交前是否暂停容器、changes提交时应用的 Dockerfile 指令、conf容器配置字典。返回提交产生的Image对象内部经api.commit后client.images.get(resp[Id])。image container.commit(repositorymyrepo/web, tagv1, messagesnapshot after setup)5.2 diff查看文件系统变更diff()等价于docker diff返回变更条目列表每项包含Path与Kind属性Kind为 0修改、1新增、2删除。5.3 export导出文件系统为 tarexport(chunk_size2*1024*1024)将容器文件系统导出为 tar 归档流生成器chunk_size控制每次迭代返回的字节数传None则按收到即返回流式传输。对应底层api.export。with open(container_fs.tar, wb) as f: for chunk in container.export(): f.write(chunk)5.4 get_archive / put_archive文件进出容器get_archive(path, chunk_size..., encode_streamFalse)从容器中取回文件/目录tar 流返回二元组(bits, stat)bits为原始 tar 数据流stat为路径信息 dict含name、size、mode、mtime、linkTarget等键。encode_streamTrue时传输过程做 gzip 压缩。bits, stat container.get_archive(/bin/sh) print(stat) # {name: sh, size: 1075464, mode: 493, mtime: ..., linkTarget: } with open(sh_bin.tar, wb) as f: for chunk in bits: f.write(chunk)put_archive(path, data)反向操作将 tar 数据解压到容器内指定目录该路径必须已存在成功返回 True。这两对方法组合起来可实现容器与宿主机之间的文件双向迁移常用于备份与恢复场景。六、update动态调整容器资源update(**kwargs)等价于docker update对运行中容器热调整资源配额返回含Warnings键的 dict。可用参数底层api.update_container要求 API 1.22blkio_weight块 IO 相对权重范围 101000cpu_periodCPU CFS 周期微秒cpu_quotaCPU CFS 配额微秒cpu_sharesCPU 相对份额cpuset_cpus/cpuset_mems允许执行的 CPU / 内存节点mem_limit/mem_reservation内存上限 / 软限制memswap_limit内存swap 总量-1表示禁用 swapkernel_memory内核内存限制restart_policy重启策略字典。container.update( mem_limit1g, cpu_shares1024, restart_policy{Name: on-failure, MaximumRetryCount: 5}, )七、源码级剖析run 参数如何拆分为容器配置与主机配置这是理解整个容器 API 的关键机制。在 docker/models/containers.py 中_create_container_args()通过两张参数清单把run/create的高层 kwargs 拆分为底层create_container的两部分RUN_CREATE_KWARGS直接传给容器创建的容器级配置镜像、命令、hostname、entrypoint、environment、labels、tty、user、working_dir、healthcheck、stop_signal、platform 等 21 项RUN_HOST_CONFIG_KWARGS包装进HostConfig的主机级配置端口绑定、卷、cap_add/cap_drop、cpu/memory 资源限制、network_mode、privileged、restart_policy、ulimits、tmpfs、log_config 等 60 余项特殊参数单独处理ports转为host_config_kwargs[port_bindings]volumes转为host_config_kwargs[binds]network构造NetworkingConfig并同时设置network_mode拆分完成后若有剩余 kwargs调用create_unexpected_kwargs_error(run, kwargs)抛出异常——这也是拼错参数名会被立即报错的原因对应测试 tests/unit/models_containers_test.py 中的test_create_container_args。最终create_kwargs[host_config] HostConfig(**host_config_kwargs)交给APIClient.create_container发送到 daemon。这种两级配置设计容器配置 vs 主机配置与 Docker Engine API 中Config和HostConfig的分离一一对应。run 的常用参数速查镜像与命令image、commandstr 或 list网络network、network_modebridge/none/container:name|id/hosthost 模式与ports互斥、ports字典key 为port/protocolvalue 可为整数端口、None随机端口、(127.0.0.1, port)元组或多端口列表、dns/dns_opt/dns_search、extra_hosts、mac_address、publish_all_ports资源cpu_count/cpu_percent仅 Windows、cpu_period/cpu_quota/cpu_shares/cpuset_cpus/cpuset_mems、nano_cpus、mem_limit支持100000b/1000k/128m/1g或裸字节、mem_reservation、mem_swappiness0100、memswap_limit、pids_limit-1不限制、shm_size、ulimits权限与安全privileged、cap_add/cap_drop、security_opt、device_cgroup_rules、devices、device_requestsGPU 等传docker.types.DeviceRequest、userns_mode、uts_mode、pid_mode、read_only、oom_kill_disable、oom_score_adj、sysctls存储volumes字典{宿主机路径: {bind: 容器内路径, mode: rw|ro}}或[/host:/container]列表、volumes_from、mountsdocker.types.Mount对象列表比 volumes 更强大、tmpfs、volume_driver、storage_opt行为detach、remove、auto_remove、restart_policy{Name: on-failure|always, MaximumRetryCount: n}、healthchecktest支持[]继承、[NONE]禁用、[CMD, args...]、[CMD-SHELL, cmd]interval/timeout/start_period单位为纳秒且至少 1ms、init、stdin_open、tty、working_dir、entrypoint、labels、name、hostname、domainname、user、stop_signal、platformos[/arch[/variant]]仅当需要拉镜像时生效、versionAPI 版本默认1.35。八、错误语义与测试印证run的异常语义源码明确容器以非零退出码结束时抛docker.errors.ContainerError含容器、退出码、命令、镜像与 stderr 输出镜像不存在抛ImageNotFoundrun会自动尝试 pulldaemon 错误抛APIError。wait超时抛requests.exceptions.ReadTimeout。ContainerCollection还继承了Collection.__call__的防护逻辑误用旧式client.containers(...)调用会抛出明确提示引导使用docker.APIClient。上述全部行为在 tests/unit/models_containers_test.py 中都有对应用例验证例如test_run、test_run_detach、test_run_pull验证 ImageNotFound 自动拉取、test_run_with_error验证 ContainerError、test_run_networking_config_without_network验证参数互斥校验、test_list_ignore_removed、test_exec_run_failure等可作为阅读实现时的辅助参照。结语client.containers与Container对象构成了 docker-py 容器管理的完整入口。掌握run的参数分派机制RUN_CREATE_KWARGS/RUN_HOST_CONFIG_KWARGS拆分、端口/卷/网络的特殊处理理解attrs的缓存与reload()刷新语义再配合exec_run、logs(streamTrue)、stats(decodeTrue)与get_archive/put_archive的组合使用即可在 Python 应用中实现从容器编排、日志采集到数据备份的端到端能力。更多容器相关文档可继续阅读 docs/index.rst、docs/client.rst 与 docs/api.rst。赞分享后端容器编排【免费下载链接】docker-pyA Python library for the Docker Engine API项目地址https://gitcode.com/gh_mirrors/do/docker-py点击查看免费下载相关推荐Laravel Translations UI 社区贡献指南如何参与开源项目开发Laravel Translations UI 社区贡献指南如何参与开源项目开发 Laravel Translations UI 是一个为 Laravel 应终极指南使用Docker SDK for Python高效管理容器编排平台终极指南使用Docker SDK for Python高效管理容器编排平台 Docker SDK for Python是一个用于Docker Engine A后端容器编排coding-competitions-archive深度探索Distributed Code Jam难题解析coding competitions archive深度探索Distributed Code Jam难题解析 在编程竞赛领域Distributed Cod上一篇uBlockOrigin-HUGE-AI-Blocklist插件开发基于项目数据的浏览器工具栏扩展下一篇The JavaScript Way 开源书籍仓库全解析内容体系、写作特色与 MkDocs 本地部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考