零基础也能上手：Docker API 实战入门，HTTP 调用容器管理全流程

发布人：慈云数据-客服中心发布时间：8小时前阅读量：1

Docker API接口调用教程｜零基础可学

Docker 不只是一个“命令行工具”，它背后其实有一套可以通过 HTTP 调用的 API 接口。
如果你学会了 Docker API，就能做到：

用代码自动创建、启动、停止容器
批量管理镜像
监控容器状态
把 Docker 能力集成到自己的系统里
写自动化运维脚本、平台管理系统

很多新手一听到“API”“HTTP”“JSON”就觉得很复杂，其实 Docker API 并不难。
你可以把它理解成：把平时输入的 Docker 命令，换成请求接口的方式来执行。

本文将带你从零开始，认识 Docker API、学会调用方式，并通过实例真正跑起来。

一、什么是 Docker API

Docker API 是 Docker Engine 对外提供的接口，底层基于 HTTP/REST 风格。
它允许你通过请求地址来操作 Docker，而不是只能在终端里敲 docker run、docker ps 这些命令。

比如：

docker ps 可能对应“查看容器列表”的 API
docker images 可能对应“查看镜像列表”的 API
docker run 可能对应“创建并启动容器”的多个 API 组合

Docker API 的作用非常大，常见场景包括：

自动化部署
容器编排系统
私有云平台
CI/CD 流水线
远程管理 Docker 主机

二、Docker API 的基本特点

在开始调用之前，你需要先理解几个关键点：

1. Docker API 本质上是 HTTP 接口

你可以使用：

curl
Python requests
JavaScript fetch
Postman
任何支持 HTTP 的工具

2. 返回数据通常是 JSON

Docker API 返回的内容大多是 JSON 格式，方便程序解析。

3. 通常通过 Docker Daemon 提供服务

真正响应 API 请求的是 Docker 守护进程 dockerd，不是 docker 命令本身。

4. 默认不建议直接暴露到公网

Docker API 权限非常高，一旦暴露不当，风险很大。
这一点后面会重点讲。

三、调用 Docker API 前的准备

在动手之前，请确认你的机器上已经安装并启动了 Docker。

1. 检查 Docker 是否正常运行

docker version

如果能看到客户端和服务端版本，说明 Docker 正常。

2. 查看 Docker Socket

在 Linux 上，Docker 默认通过 Unix Socket 提供本地访问：

/var/run/docker.sock

这意味着你可以通过 socket 直接发 HTTP 请求，而不一定要开 TCP 端口。

3. 查看 API 版本

Docker API 有版本号，例如：

/v1.41/
/v1.44/

建议在请求时带上版本前缀，以保证兼容性。

你也可以先查看 Docker 支持的版本：

docker version

四、最简单的 Docker API 调用方式

下面用 curl 直接调用 Docker API，这是学习阶段最直观的方法。

注意：以下示例以 Linux 本地 Docker 为例。

1. 测试 Docker 是否可访问

curl --unix-socket /var/run/docker.sock http://localhost/_ping

如果返回：

OK

说明 API 通了。

2. 查看 Docker 版本信息

curl --unix-socket /var/run/docker.sock http://localhost/version

返回内容类似：

{
  "Version": "24.xx.x",
  "ApiVersion": "1.44",
  "GitCommit": "...",
  "GoVersion": "go1.xx",
  ...
}

这个接口很实用，可以帮助你确认 Docker 引擎版本和 API 版本。

五、常用 Docker API 接口介绍

下面列出几个最常见、最实用的接口。

功能	API 示例	说明
查看版本	`GET /version`	获取 Docker 引擎版本
测试连通性	`GET /_ping`	返回 OK 表示服务正常
查看容器列表	`GET /containers/json`	类似 `docker ps`
查看镜像列表	`GET /images/json`	类似 `docker images`
查看某容器详情	`GET /containers/{id}/json`	获取容器详细信息
创建容器	`POST /containers/create`	创建容器
启动容器	`POST /containers/{id}/start`	启动容器
停止容器	`POST /containers/{id}/stop`	停止容器
删除容器	`DELETE /containers/{id}`	删除容器
获取日志	`GET /containers/{id}/logs`	查看容器日志

六、实际演示：查看容器列表

1. 请求接口

curl --unix-socket /var/run/docker.sock http://localhost/v1.44/containers/json

2. 可能返回

[
  {
    "Id": "abc123...",
    "Image": "nginx:latest",
    "Names": ["/web"],
    "State": "running",
    "Status": "Up 2 hours"
  }
]

这个接口的含义很接近 docker ps，你可以通过它在程序里获取正在运行的容器信息。

七、实际演示：创建一个容器

创建容器时，通常要先发 POST /containers/create，然后再启动它。

1. 创建容器请求

下面创建一个 nginx 容器，名字叫 my-nginx：

curl -X POST \
  --unix-socket /var/run/docker.sock \
  -H "Content-Type: application/json" \
  -d '{
    "Image": "nginx:latest",
    "HostConfig": {
      "PortBindings": {
        "80/tcp": [
          {
            "HostPort": "8080"
          }
        ]
      }
    }
  }' \
  http://localhost/v1.44/containers/create?name=my-nginx

2. 返回结果示例

{
  "Id": "f5a8c9d...",
  "Warnings": null
}

这里的 Id 就是刚刚创建好的容器 ID。

八、启动容器

创建完容器后，还需要启动它。

请求接口

curl -X POST \
  --unix-socket /var/run/docker.sock \
  http://localhost/v1.44/containers/f5a8c9d/start

如果成功，通常不会返回太多内容，可能是空响应。
你可以再执行一次容器列表确认：

curl --unix-socket /var/run/docker.sock http://localhost/v1.44/containers/json

这时就能看到 my-nginx 在运行了。

九、停止和删除容器

1. 停止容器

curl -X POST \
  --unix-socket /var/run/docker.sock \
  http://localhost/v1.44/containers/f5a8c9d/stop

2. 删除容器

停止后即可删除：

curl -X DELETE \
  --unix-socket /var/run/docker.sock \
  http://localhost/v1.44/containers/f5a8c9d

如果容器正在运行，删除时可能会失败。
你也可以加上强制删除逻辑，但建议先停止再删，避免误操作。

十、查看容器日志

日志接口在排查问题时非常有用。

curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.44/containers/f5a8c9d/logs?stdout=1&stderr=1&tail=100"

参数说明：

stdout=1：显示标准输出
stderr=1：显示标准错误
tail=100：只看最后 100 行

如果你在调试应用容器，这个接口非常常用。

十一、用 Python 调用 Docker API

如果你希望在程序里自动化控制 Docker，可以直接用 Python 请求接口。

方式一：通过 Unix Socket 调用

Python 的 requests 默认不直接支持 Unix Socket，但可以借助第三方库。
一种简单方式是使用 requests-unixsocket。

安装：

pip install requests-unixsocket

示例代码：

from requests_unixsocket import Session

session = Session()
url = "http+unix://%2Fvar%2Frun%2Fdocker.sock/version"

resp = session.get(url)
print(resp.json())

方式二：使用普通 HTTP 调用远程 Docker

如果 Docker 开了 TCP 端口，可以直接用普通 requests：

import requests

resp = requests.get("http://127.0.0.1:2375/version")
print(resp.json())

不过这类方式要特别注意安全问题，后面会讲。

十二、如何通过 TCP 访问 Docker API

除了 Unix Socket，Docker 也可以配置为监听 TCP 端口。
例如在某些远程管理场景下，会开放：

tcp://0.0.0.0:2375

然后你就可以直接访问：

curl http://127.0.0.1:2375/version

但要注意：

2375 默认是明文无加密的，风险极高。

如果必须远程访问，建议：

使用 TLS 加密
限制 IP 白名单
只开放内网
配合认证机制
不要直接暴露公网

十三、常见错误与排查方法

1. `Cannot connect to the Docker daemon`

原因可能是：

Docker 服务没启动
当前用户没权限访问 /var/run/docker.sock
Docker 安装异常

解决方式：

sudo systemctl start docker

或者把当前用户加入 docker 组：

sudo usermod -aG docker $USER

然后重新登录。

2. 返回 404 Not Found

常见原因：

API 版本写错
路径拼错
容器 ID 不存在

建议先通过 /version 确认 API 版本，再调用对应接口。

3. 返回 500 Internal Server Error

这通常说明 Docker 引擎内部执行失败，可能是：

镜像不存在
宿主机资源不足
容器配置有问题
权限不足

可以通过查看 Docker 日志进一步排查。

十四、零基础学习 Docker API 的建议路线

如果你是第一次接触 Docker API，可以按下面的顺序学习：

第一步：先会 Docker 命令

建议先熟悉这些命令：

docker ps
docker images
docker run
docker stop
docker rm
docker logs

因为 API 本质上就是把这些操作程序化。

第二步：学习 HTTP 基础

重点了解：

GET / POST / DELETE
请求头
JSON 格式
状态码 200 / 201 / 404 / 500

第三步：先用 curl 练习

不要一上来就写代码，先用 curl 试通接口，最容易理解。

第四步：再用语言封装

比如用：

Python
Java
Go
Node.js

把 Docker API 集成进自己的项目。

十五、Docker API 的安全建议

这一部分非常重要，很多新手容易忽略。

1. 不要直接暴露到公网

Docker API 权限极高，如果暴露在公网，攻击者可能直接控制你的主机。

2. 尽量使用 Unix Socket

本地管理优先使用：

/var/run/docker.sock

比直接开 TCP 安全得多。

3. 远程访问务必启用 TLS

如果业务必须远程调用 Docker API，请务必做加密和身份校验。

4. 控制访问权限

不要让不可信程序随意访问 Docker Socket。
因为拥有 Docker 权限，很多时候几乎等同于拥有主机 root 权限。

5. 最小权限原则

只给必要的系统、用户和服务开放访问权限。

十六、一个完整的小例子：从查询到启动

下面我们把前面的内容串起来，做一个完整流程。

1. 检查服务是否可用

curl --unix-socket /var/run/docker.sock http://localhost/_ping

返回 OK 后继续。

2. 查看版本

curl --unix-socket /var/run/docker.sock http://localhost/version

确认 API 版本。

3. 拉取镜像

严格来说，拉取镜像对应另一个 API，比如 POST /images/create。
如果你还在学习阶段，也可以先用命令行：

docker pull nginx:latest

4. 创建容器

curl -X POST \
  --unix-socket /var/run/docker.sock \
  -H "Content-Type: application/json" \
  -d '{
    "Image": "nginx:latest"
  }' \
  http://localhost/v1.44/containers/create?name=test-nginx

5. 启动容器

curl -X POST \
  --unix-socket /var/run/docker.sock \
  http://localhost/v1.44/containers/容器ID/start

6. 查看运行状态

curl --unix-socket /var/run/docker.sock http://localhost/v1.44/containers/json

7. 查看日志

curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.44/containers/容器ID/logs?stdout=1&stderr=1&tail=50"

8. 停止并删除

curl -X POST --unix-socket /var/run/docker.sock http://localhost/v1.44/containers/容器ID/stop
curl -X DELETE --unix-socket /var/run/docker.sock http://localhost/v1.44/containers/容器ID

十七、总结

Docker API 的核心思想其实很简单：

把 Docker 的操作变成 HTTP 请求。

只要你掌握了：

如何连接 Docker
如何调用接口
如何解析 JSON
如何处理容器生命周期

你就已经能用 Docker API 做很多自动化工作了。

记住这几个重点：

本地优先用 Unix Socket
API 一般需要指定版本号
常用方法是 GET / POST / DELETE
返回结果大多是 JSON
不要随意暴露 Docker API 到公网

如果你是零基础，建议先从这三个接口开始练习：

/_ping
/version
/containers/json

把它们跑通以后，再去尝试创建、启动、停止容器，你会发现 Docker API 并没有想象中难。

如果你愿意，我还可以继续帮你写一篇：

《Docker API 接口调用实战：Python版》
《Docker API 常用接口大全》
《Docker API 远程调用配置教程》

你只要回复一个标题，我可以直接接着写。

文章标签： Docker API 容器 HTTP

上一篇：Docker API 实战：从接口调用到 Python 管理容器源码示例

下一篇：Docker 部署教程 2026 实战版：从镜像构建到 Compose 编排，一篇讲透项目上线

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们