Docker API接口调用教程｜一键部署

在日常运维、容器平台开发、自动化部署和 DevOps 场景中，Docker API 是非常实用的一把“瑞士军刀”。很多人平时只会使用 docker ps、docker run 这些命令，但其实这些命令背后，本质上都是在调用 Docker Daemon 暴露出来的 API 接口。

如果你想做一个容器管理平台、自动拉起服务、动态查询容器状态，或者希望把 Docker 操作集成到自己的系统里，那么学会 Docker API 的调用方式就非常重要。

本文将从基础概念讲起，带你一步步完成：

• Docker API 的基本认识
• 本地与远程调用方式
• 常见接口示例
• Python 调用示例
• 一键部署一个 Docker API 调用测试项目
• 常见问题与安全建议

一、Docker API 到底是什么？

Docker API 是 Docker Daemon 提供的一组 HTTP 接口，用来控制和查询 Docker 引擎的运行状态。

你可以把它理解为：

• docker ps = 调用了列出容器的 API
• docker images = 调用了列出镜像的 API
• docker run = 调用了创建并启动容器的 API

也就是说，Docker 命令行只是 API 的一个客户端。
如果你想写程序管理 Docker，最直接的方式就是通过 API 进行调用。

Docker API 常见能力

• 查看 Docker 版本、信息
• 查询镜像、容器、网络、卷
• 创建、启动、停止、删除容器
• 拉取镜像、构建镜像
• 执行容器命令
• 查看容器日志

二、调用 Docker API 之前需要准备什么？

1）确保已安装 Docker

先确认本机 Docker 正常运行：

docker version
docker info

如果能正常输出版本和系统信息，说明环境没问题。

2）理解 Docker API 的访问方式

Docker API 常见有两种访问方式：

方式一：本机 Unix Socket

这是最常见、最安全的方式。Docker 默认监听：

/var/run/docker.sock

通过 socket 可以直接访问 Docker API，不需要额外开放网络端口。

方式二：TCP 远程访问

适合远程管理 Docker，但必须做好 TLS 安全配置。
不建议生产环境直接开放 2375 这种无加密端口。

三、最简单的 Docker API 调用方式：curl + Unix Socket

如果你只是想先快速测试，推荐直接通过本机 socket 调用。

1）查看 Docker 版本

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

返回结果类似：

{
  "Version": "27.0.3",
  "ApiVersion": "1.45",
  "GitCommit": "...",
  "GoVersion": "go1.22",
  "Os": "linux",
  "Arch": "amd64"
}

2）查看 Docker 信息

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

这个接口会返回很多信息，比如：

• 容器数量
• 镜像数量
• 存储驱动
• CPU / 内存
• 网络模式

3）查看当前运行中的容器

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

如果想看所有容器，包括已停止的，可以加参数：

curl --unix-socket /var/run/docker.sock \
  "http://localhost/containers/json?all=true"

四、Docker API 常用接口速查

下面整理一份最常用的接口清单，方便你查阅。

五、用 API 创建一个容器

接下来演示一个最经典的操作：通过 API 创建并启动 nginx 容器。

1）创建容器

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

如果成功，会返回类似：

{
  "Id": "xxxxxxxxxxxxxxxxxxxx",
  "Warnings": []
}

2）启动容器

把上一步返回的 Id 拿出来：

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

3）访问容器

如果映射端口成功，可以在浏览器访问：

http://127.0.0.1:8080

你会看到 nginx 的欢迎页面。

六、用 Python 调用 Docker API

如果你要在业务系统里集成 Docker 管理功能，Python 是非常常见的选择。

这里推荐使用官方生态常用的 docker SDK。

1）安装依赖

pip install docker

2）Python 示例：获取版本与容器列表

import docker

client = docker.DockerClient(base_url='unix://var/run/docker.sock')

# 查看版本
version = client.version()
print("Docker Version:", version["Version"])

# 查看容器
containers = client.containers.list(all=True)
for c in containers:
    print(c.name, c.status)

3）Python 示例：启动一个 nginx 容器

import docker

client = docker.DockerClient(base_url='unix://var/run/docker.sock')

container = client.containers.run(
    "nginx:alpine",
    name="demo-nginx",
    ports={"80/tcp": 8080},
    detach=True
)

print("Container ID:", container.id)

4）Python 示例：停止并删除容器

import docker

client = docker.DockerClient(base_url='unix://var/run/docker.sock')
container = client.containers.get("demo-nginx")

container.stop()
container.remove()
print("removed")

七、一个可直接运行的 Docker API 调用测试项目

如果你希望快速拥有一个“能直接访问 Docker API 的小服务”，下面这个示例非常适合做测试环境。

它的作用很简单：

• 提供一个 HTTP 服务
• 通过 Docker Socket 访问宿主机 Docker
• 对外暴露几个常用接口
• 方便你调试和学习

1）项目结构

docker-api-demo/
├── app.py
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

2）requirements.txt

flask==3.0.3
docker==7.1.0

3）app.py

from flask import Flask, jsonify
import docker

app = Flask(__name__)
client = docker.DockerClient(base_url="unix://var/run/docker.sock")

@app.route("/")
def index():
    return jsonify({
        "message": "Docker API Demo is running"
    })

@app.route("/api/version")
def version():
    return jsonify(client.version())

@app.route("/api/info")
def info():
    return jsonify(client.info())

@app.route("/api/containers")
def containers():
    data = []
    for c in client.containers.list(all=True):
        data.append({
            "id": c.id,
            "name": c.name,
            "status": c.status,
            "image": c.image.tags
        })
    return jsonify(data)

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

4）Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

ENV DOCKER_HOST=unix:///var/run/docker.sock

EXPOSE 5000

CMD ["python", "app.py"]

5）docker-compose.yml

services:
  docker-api-demo:
    build: .
    container_name: docker-api-demo
    ports:
      - "5000:5000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

6）一键启动

在项目目录执行：

docker compose up -d --build

启动完成后，测试接口：

curl http://127.0.0.1:5000/
curl http://127.0.0.1:5000/api/version
curl http://127.0.0.1:5000/api/info
curl http://127.0.0.1:5000/api/containers

这样你就完成了一个Docker API 调用演示环境的一键部署。

八、如果要远程调用 Docker API，怎么做？

本地 socket 只能在宿主机上使用。如果你想远程访问 Docker API，建议采用 TLS 加密方式。

推荐原则

• 不要裸露开放 2375
• 一定要启用 TLS
• 限制访问来源 IP
• 配合防火墙和身份认证

常见远程访问格式

https://docker-host:2376

调用时需要客户端证书，例如：

curl --cert client-cert.pem \
     --key client-key.pem \
     --cacert ca.pem \
     https://docker-host:2376/version

安全提醒

远程暴露 Docker API 风险非常高。
如果配置不当，攻击者几乎可以直接控制你的宿主机。因此，生产环境务必谨慎。

九、调用 Docker API 时常见问题

1）permission denied while trying to connect to the Docker daemon socket

通常是当前用户没有权限访问 /var/run/docker.sock。

解决方法之一：

sudo usermod -aG docker $USER
newgrp docker

然后重新登录终端。

2）Cannot connect to the Docker daemon

可能原因有：

• Docker 服务没启动
• socket 路径不对
• 容器内未挂载 /var/run/docker.sock

检查 Docker 状态：

systemctl status docker

启动 Docker：

sudo systemctl start docker

3）API 版本不兼容

有些旧脚本会写死 API 版本，比如：

/v1.41/containers/json

如果 Docker 升级后接口变化，可能报错。
建议优先使用：

http://localhost/containers/json

让客户端自动协商版本。

十、安全最佳实践

Docker API 很强大，也意味着它的权限非常高。
下面这些建议非常重要：

1）尽量只使用本机 socket

本机 socket 更安全，减少网络暴露风险。

2）不要直接开放 2375

2375 是未加密端口，暴露后很危险。

3）远程访问必须启用 TLS

至少要做到双向证书认证。

4）限制容器对宿主机 socket 的访问

挂载 docker.sock 的容器，本质上接近拥有宿主机 root 权限。

5）给 API 增加鉴权

如果你自己做管理平台，一定要加：

• 登录认证
• 权限控制
• 审计日志
• IP 白名单

十一、适合哪些场景使用 Docker API？

Docker API 不只是“技术爱好者的玩具”，它在真实业务中非常常见，尤其适用于：

• 容器管理平台
• CI/CD 自动化部署
• 动态任务调度
• 微服务平台编排
• 日志和监控采集
• 开发测试环境自动化初始化

如果你想做一个“点击按钮就自动启动环境”的系统，Docker API 就是核心能力之一。

十二、总结

Docker API 的本质，就是通过 HTTP 接口直接控制 Docker 引擎。
相比只会用命令行，掌握 API 调用后，你可以把容器能力真正集成到自己的系统中，完成自动化部署、弹性管理和平台化运维。

本文带你完成了这些内容：

• 了解 Docker API 的基础概念
• 使用 curl 调用常用接口
• 用 Python 访问 Docker
• 一键部署一个 Docker API 调用测试项目
• 理解远程访问和安全注意事项

如果你是刚开始接触 Docker API，建议先从本机 socket 调用入手，熟悉 /version、/info、/containers/json 这些接口，再逐步扩展到创建、启动、停止和删除容器。
如果你后续要做生产系统，务必优先考虑 TLS、鉴权与访问控制。

如果你愿意，我还可以继续帮你补一版：

1. 更适合发布到公众号/博客的排版版
2. 带目录和摘要的 SEO 增强版
3. 补充 Java / Go / Node.js 的 Docker API 调用示例
4. 做成“可直接复制运行”的完整项目源码版