3、Docker API概述：Docker Engine API版本、RESTful接口、默认通信端口（2375/2376）

Docker Engine API 是 Docker 守护进程（dockerd）对外暴露的核心控制接口。所有 Docker 客户端（包括 CLI、Docker Compose、Kubernetes 的 dockershim、第三方管理工具）都通过该 API 与守护进程通信。理解 API 版本、RESTful 设计以及默认端口，是后续配置鉴权拦截和排查通信故障的基础。

3.1 Docker Engine API 版本机制

Docker Engine API 采用显式版本号策略，确保客户端与守护进程之间的向后兼容性。每个 API 请求都必须指定版本号，格式为 vX.YY。

版本字段 说明 示例
主版本（X） 重大架构变更，不保证向后兼容 v1 → v2（极少发生）
次版本（YY） 功能增删、字段变更，向后兼容 v1.24 → v1.41
最新版 客户端可协商使用守护进程支持的最高版本 v1.47（Docker 25.x）
最佳实践：生产环境中始终在请求路径中指定 API 版本，避免依赖默认版本协商。例如：/v1.41/containers/json。这可以防止因守护进程升级导致客户端请求行为意外变化。

3.2 RESTful 接口设计

Docker Engine API 严格遵循 RESTful 风格，使用 HTTP 方法对资源进行 CRUD 操作。所有请求和响应体均采用 JSON 格式。

HTTP 方法 操作语义 典型资源路径
GET 列出资源或获取单个资源详情 /containers/json、/containers/{id}/json
POST 创建新资源或触发操作 /containers/create、/containers/{id}/start
PUT 全量更新资源 /networks/{id}
DELETE 删除资源 /containers/{id}、/images/{id}

以下是一个典型的容器列表请求示例：

# 请求
GET /v1.41/containers/json?all=true HTTP/1.1
Host: localhost:2375

# 响应（截取）
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "Id": "a1b2c3d4e5f6...",
    "Names": ["/my-app"],
    "Image": "nginx:1.25",
    "State": "running",
    "Status": "Up 2 hours",
    "Ports": [{"PrivatePort": 80, "PublicPort": 8080, "Type": "tcp"}]
  }
]

3.3 默认通信端口：2375 与 2376

Docker 守护进程默认监听两个 TCP 端口，分别对应未加密和加密通信。这是鉴权拦截配置的入口点。

端口 协议 TLS 用途 安全风险
2375 HTTP 无 明文 API 通信（仅限内网或调试） 极高——任何能访问该端口的人可完全控制 Docker 守护进程
2376 HTTPS 强制 加密 API 通信（生产环境标准） 低——需客户端证书认证
安全警告：切勿将 2375 端口暴露到公网或不可信网络。未加密的 Docker API 没有任何身份验证机制，攻击者可以通过 docker -H tcp://<IP>:2375 run --privileged ... 直接获取宿主机 root 权限。生产环境必须使用 2376 端口并配置 TLS 双向认证。

3.4 Docker API 通信架构总览

下图展示了 Docker 客户端通过 RESTful API 与守护进程通信的完整路径，以及端口 2375/2376 在其中的位置。

Docker API 通信架构图 Docker API 通信架构与端口示意 Docker 客户端 Docker CLI Docker Compose SDK (Go/Python) 第三方管理工具 RESTful API 请求 GET /v1.41/containers/json POST /v1.41/containers/create DELETE /v1.41/containers/{id} Docker 守护进程 dockerd 容器运行时 镜像管理 网络 & 存储 默认监听端口 2375（HTTP，明文） / 2376（HTTPS，TLS加密）

3.5 端口配置与验证

Docker 守护进程通过 /etc/docker/daemon.json 配置文件控制监听地址和端口。以下是常见配置场景：

{
  "hosts": [
    "unix:///var/run/docker.sock",
    "tcp://0.0.0.0:2375",
    "tcp://0.0.0.0:2376"
  ],
  "tls": true,
  "tlscacert": "/etc/docker/ca.pem",
  "tlscert": "/etc/docker/server-cert.pem",
  "tlskey": "/etc/docker/server-key.pem"
}

验证端口是否正常监听：

# 查看 Docker 守护进程监听端口
ss -tlnp | grep -E '2375|2376'

# 测试 2375 端口（明文）
curl http://localhost:2375/v1.41/version

# 测试 2376 端口（TLS）
curl --cacert /etc/docker/ca.pem \
     --cert /etc/docker/cert.pem \
     --key /etc/docker/key.pem \
     https://localhost:2376/v1.41/version
故障排查要点：
  • 如果 2375 端口无法访问，检查 daemon.json 中是否显式配置了 tcp://0.0.0.0:2375，以及防火墙是否放行。
  • 如果 2376 端口连接失败，优先检查 TLS 证书路径和权限，以及 tlsverify 是否设置为 true。
  • 使用 docker system info 查看当前守护进程的 Server Version 和 Registry 配置，确认 API 版本兼容性。

3.6 版本协商与故障场景

当客户端请求的 API 版本与守护进程不匹配时，Docker 会返回明确的错误码。下表列出常见版本相关故障：

错误场景 HTTP 状态码 错误信息示例 解决方案
客户端版本过高 400 Bad Request client version 1.47 is too new. Maximum supported API version is 1.45 降低客户端 API 版本或升级 Docker Engine
客户端版本过低 400 Bad Request client version 1.12 is too old. Minimum supported API version is 1.24 升级客户端 SDK 或 Docker CLI
未指定版本 200 OK（但行为不确定） 守护进程使用默认版本，可能返回意外字段 始终在 URL 中显式指定版本号
← 上一章 📖 返回目录 下一章 →