Moby Remote API v1.0从 rcli 到 REST 引擎 API 的首版规范全解【免费下载链接】mobyThe Moby Project - a collaborative project for the container ecosystem to assemble container-based systems项目地址: https://gitcode.com/GitHub_Trending/mo/moby本文基于 Moby 仓库中 api/docs/v1.0.md 这份最早的 Remote API 版本规范展开完整还原 v1.0 时期容器、镜像与杂项三类端点的请求/响应格式、查询参数和状态码语义并结合当前仓库的源码如 client/hijack.go、daemon/pkg/opts/hosts.go佐证其背后的连接劫持hijacking机制与默认端口约定帮助读者理解 Docker Engine API 的起源与docker run等命令的底层调用链。1. 设计背景Remote API 取代 rcliv1.0 文档开篇给出了三句关键设计说明见 api/docs/v1.0.md Brief introduction 一节Remote API 正在取代 rcli早期基于远程控制的客户端方案成为命令行客户端与守护进程之间通信的标准通道Docker 守护进程的默认端口是 2375API 整体倾向于 REST 风格但对于 attach、pull 这类需要传输 stdin/stdout/stderr 的复杂命令HTTP 连接会被劫持hijacked在同一连接上透传多路数据流。这三点在当前仓库中依然可以找到对应证据默认端口 2375daemon/pkg/opts/hosts.go 中定义了DefaultHTTPPort 2375 // Default HTTP Port并以此构造默认 TCP 主机地址说明 v1.0 文档中记载的端口约定延续至今。HTTP 作为控制通道当前仓库的 api/README.md 明确写道——Engine API 是命令行客户端用来与守护进程通信的 HTTP API也可被第三方软件用来控制守护进程其组成部分包括api/swagger.yamlAPI 的 Swagger 定义、client/Go 客户端、daemon/提供 API 的守护进程与api/types/客户端/服务端共享的类型。劫持机制客户端实现位于 client/hijack.go后文连接劫持一节将详细展开。2. 容器端点Containers2.1 列出容器GET /containers/json示例请求GET /containers/json?all1before8dfafdbc3a40 HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json [ { Id: 8dfafdbc3a40, Image: ubuntu:latest, Command: echo 1, Created: 1367854155, Status: Exit 0 }, { Id: 9cd87474be90, Image: ubuntu:latest, Command: echo 222222, Created: 1367854155, Status: Exit 0 }, { Id: 3176a2479c92, Image: centos:latest, Command: echo 3333333333333333, Created: 1367854154, Status: Exit 0 }, { Id: 4cb07b47f9fb, Image: fedora:latest, Command: echo 444444444444444444444444444444444, Created: 1367854152, Status: Exit 0 } ]查询参数参数说明all1/True/true 或 0/False/false。显示所有容器默认只显示运行中的容器limit只显示最近创建的limit个容器包含非运行状态的since只显示某个容器 Id 之后创建的容器包含非运行状态的before只显示某个容器 Id 之前创建的容器包含非运行状态的状态码200无错误400参数错误500服务器错误。2.2 创建容器POST /containers/create示例请求POST /containers/create HTTP/1.1 Content-Type: application/json { Hostname:, User:, Memory:0, MemorySwap:0, AttachStdin:false, AttachStdout:true, AttachStderr:true, PortSpecs:null, Tty:false, OpenStdin:false, StdinOnce:false, Env:null, Cmd:[ date ], Dns:null, Image:ubuntu, Volumes:{}, VolumesFrom: }示例响应HTTP/1.1 201 Created Content-Type: application/json { Id:e90e34656806, Warnings:[] }请求体即容器的配置config字段覆盖标准流挂载AttachStdin/Stdout/Stderr、终端与 stdin 行为Tty、OpenStdin、StdinOnce、端口PortSpecs、环境变量Env、命令Cmd、镜像Image与卷Volumes、VolumesFrom等资源限制字段Memory、MemorySwap以 0 表示不限制。状态码201无错误404无此容器406无法附加容器未运行500服务器错误。在当前仓库中客户端对应该端点的实现为 client/container_create.go 中的ContainerCreate方法可据此查看请求的组装与响应含Id、Warnings的解析方式。2.3 检查容器详情GET /containers/(id)/json返回容器id的底层信息。示例请求GET /containers/4fa6e0f0c678/json HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json { Id: 4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2, Created: 2013-05-07T14:51:42.04184702:00, Path: date, Args: [], Config: { Hostname: 4fa6e0f0c678, User: , Memory: 0, MemorySwap: 0, AttachStdin: false, AttachStdout: true, AttachStderr: true, PortSpecs: null, Tty: false, OpenStdin: false, StdinOnce: false, Env: null, Cmd: [ date ], Dns: null, Image: ubuntu, Volumes: {}, VolumesFrom: }, State: { Running: false, Pid: 0, ExitCode: 0, StartedAt: 2013-05-07T14:51:42.08765802:01360, Ghost: false }, Image: b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, NetworkSettings: { IpAddress: , IpPrefixLen: 0, Gateway: , Bridge: , PortMapping: null }, SysInitPath: /home/kitty/go/src/github.com/docker/docker/bin/docker, ResolvConfPath: /etc/resolv.conf, Volumes: {} }可以看到 v1.0 的 inspect 响应已经具备现代 API 的雏形完整长 Id、Config与创建时提交的容器配置同构、State运行状态、进程 PID、退出码、Ghost标记、Image与NetworkSettings等区块。状态码200无错误404无此容器500服务器错误。2.4 查看容器文件系统变更GET /containers/(id)/changes检查容器id文件系统的变更。示例请求GET /containers/4fa6e0f0c678/changes HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json [ { Path: /dev, Kind: 0 }, { Path: /dev/kmsg, Kind: 1 }, { Path: /test, Kind: 1 } ]每一项由变更路径Path与变更类型Kind组成示例中出现了取值0与1两种类型分别对应已变更路径与新增加的路径。状态码200无错误404无此容器500服务器错误。2.5 导出容器GET /containers/(id)/export导出容器id的内容。示例请求GET /containers/4fa6e0f0c678/export HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/octet-stream {{ TAR STREAM }}响应体是一个 TAR 流客户端可按压缩归档直接落盘。状态码200无错误404无此容器500服务器错误。2.6 生命周期操作start / stop / restart / kill四个端点均以POST触发容器id的对应动作启动POST /containers/(id)/startPOST /containers/e90e34656806/start HTTP/1.1HTTP/1.1 200 OK停止POST /containers/(id)/stopPOST /containers/e90e34656806/stop?t5 HTTP/1.1HTTP/1.1 204 OK重启POST /containers/(id)/restartPOST /containers/e90e34656806/restart?t5 HTTP/1.1HTTP/1.1 204 No Content强制终止POST /containers/(id)/killPOST /containers/e90e34656806/kill HTTP/1.1HTTP/1.1 204 No Contentstop 与 restart 都支持查询参数t—— 在强制杀死容器前等待的秒数示例为t5。四者的状态码均为200/204无错误、404无此容器、500服务器错误。2.7 附加到容器POST /containers/(id)/attach示例请求POST /containers/16253994b7c4/attach?logs1stream0stdout1 HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream {{ STREAM }}查询参数v1.0 已经定义了完整的流控制语义参数说明logs1/True/true 或 0/False/false。返回日志默认 falsestream1/True/true 或 0/False/false。返回实时流默认 falsestdin若 streamtrue则附加到 stdin默认 falsestdout若 logstrue 则返回 stdout 日志若 streamtrue 则附加到 stdout默认 falsestderr若 logstrue 则返回 stderr 日志若 streamtrue 则附加到 stderr默认 false状态码200无错误400参数错误404无此容器500服务器错误。2.8 附加到容器WebSocketGET /containers/(id)/attach/ws通过 WebSocket 附加到容器id并按 RFC 6455 实现 WebSocket 协议握手。示例请求GET /containers/e90e34656806/attach/ws?logs0stream1stdin1stdout1stderr1 HTTP/1.1示例响应{{ STREAM }}查询参数与语义与上一节的 raw attach 完全一致logs、stream、stdin、stdout、stderr均默认 false。状态码同样为200/400/404/500。从源码结构看这种 WebSocket 变体是 v1.0 就规划的浏览器/非 HTTP 劫持场景接入方式后续版本见 api/docs/CHANGELOG.md 中 v1.42 一节的记载还为attach/ws补充了对stdin、stdout、stderr参数的真正支持说明 v1.0 文档中的参数设计是演进的起点。2.9 等待容器停止POST /containers/(id)/wait阻塞直到容器id停止然后返回退出码。示例请求POST /containers/16253994b7c4/wait HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json {StatusCode: 0}状态码200无错误404无此容器500服务器错误。2.10 删除容器DELETE /containers/(id)把容器id从文件系统中移除。示例请求DELETE /containers/16253994b7c4?v1 HTTP/1.1示例响应HTTP/1.1 204 OK查询参数v– 1/True/true 或 0/False/false。删除关联到该容器的卷默认 false状态码204无错误400参数错误404无此容器500服务器错误。3. 镜像端点Images3.1 列出镜像GET /images/(format)format可以是json或viz默认 json。JSON 格式示例请求GET /images/json?all0 HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json [ { Repository:ubuntu, Tag:precise, Id:b750fe79269d, Created:1364102658 }, { Repository:ubuntu, Tag:12.04, Id:b750fe79269d, Created:1364102658 } ]viz 格式示例请求GET /images/viz HTTP/1.1示例响应Graphviz digraph可直接用于可视化镜像间的父子依赖图HTTP/1.1 200 OK Content-Type: text/plain digraph docker { d82cbacda43a - 074be284591f 1496068ca813 - 08306dc45919 08306dc45919 - 0e7893146ac2 b750fe79269d - 1496068ca813 base - 27cf78414709 [styleinvis] f71189fff3de - 9a33b36209ed 27cf78414709 - b750fe79269d 0e7893146ac2 - d6434d954665 d6434d954665 - d82cbacda43a base - e9aa60c60128 [styleinvis] 074be284591f - f71189fff3de b750fe79269d [labelb750fe79269d\nubuntu,shapebox,fillcolorpaleturquoise,stylefilled,rounded]; e9aa60c60128 [labele9aa60c60128\ncentos,shapebox,fillcolorpaleturquoise,stylefilled,rounded]; 9a33b36209ed [label9a33b36209ed\nfedora,shapebox,fillcolorpaleturquoise,stylefilled,rounded]; base [styleinvisible] }查询参数all– 1/True/true 或 0/False/false。显示所有镜像状态码200无错误400参数错误500服务器错误。3.2 创建镜像拉取或导入POST /images/create创建一个镜像要么从 registry 拉取要么从来源导入。示例请求POST /images/create?fromImageubuntu HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream {{ STREAM }}查询参数参数说明fromImage要拉取的镜像名fromSrc导入来源-表示 stdinrepo仓库名tag标签registry要从中拉取的 registry状态码200无错误500服务器错误。值得注意的是响应体是application/vnd.docker.raw-stream流拉取/导入是长耗时操作服务端把进度信息以流式写回这正是 v1.0 文档所说的对复杂命令劫持 HTTP 连接的典型场景之一。3.3 向镜像中插入文件POST /images/(name)/insert把url处的文件插入镜像name的path位置。示例请求POST /images/test/insert?path/usrurlmyurl HTTP/1.1示例响应HTTP/1.1 200 OK {{ TAR STREAM }}查询参数url– 文件来源的 URLpath– 文件在镜像中的存放路径状态码200无错误500服务器错误。3.4 检查镜像GET /images/(name)/json返回镜像name的底层信息。示例请求GET /images/centos/json HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json { id:b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, parent:27cf784147099545, created:2013-03-23T22:24:18.818426-07:00, container:3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0, container_config: { Hostname:, User:, Memory:0, MemorySwap:0, AttachStdin:false, AttachStdout:false, AttachStderr:false, PortSpecs:null, Tty:true, OpenStdin:true, StdinOnce:false, Env:null, Cmd: [/bin/bash], Dns:null, Image:centos, Volumes:null, VolumesFrom: } }响应中的parent字段揭示了镜像层的父子链——这与 3.1 节viz输出的 digraph 图互为印证container_config记录了该镜像是由哪个容器container字段在什么配置下提交的。状态码200无错误404无此镜像500服务器错误。3.5 获取镜像历史GET /images/(name)/history示例请求GET /images/fedora/history HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json [ { Id: b750fe79269d, Created: 1364102658, CreatedBy: /bin/bash }, { Id: 27cf78414709, Created: 1364068391, CreatedBy: } ]状态码200无错误404无此镜像500服务器错误。3.6 推送镜像POST /images/(name)/push把镜像name推送到 registry。示例请求POST /images/test/push HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream {{ STREAM }}状态码200无错误404无此镜像500服务器错误。3.7 给镜像打标签POST /images/(name)/tag把镜像name打上新的仓库/标签。示例请求POST /images/test/tag?repomyrepoforce0tagv42 HTTP/1.1示例响应HTTP/1.1 201 OK查询参数参数说明repo要标记到的目标仓库force1/True/true 或 0/False/false默认 falsetag新的标签名状态码201无错误400参数错误404无此镜像500服务器错误。3.8 删除镜像DELETE /images/(name)把镜像name从文件系统中移除。示例请求DELETE /images/test HTTP/1.1示例响应HTTP/1.1 204 No Content状态码204无错误404无此镜像500服务器错误。3.9 搜索镜像GET /images/search在 Docker Hub 上搜索镜像。示例请求GET /images/search?termsshd HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json [ { Name:cespare/sshd, Description: }, { Name:johnfuller/sshd, Description: }, { Name:dhrp/mongodb-sshd, Description: } ]查询参数term即搜索词。状态码200无错误500服务器错误。4. 杂项端点Misc4.1 通过 stdin 构建镜像POST /build从 stdin 传入 Dockerfile 构建镜像。示例请求请求体即包含 Dockerfile 的 TAR 流POST /build HTTP/1.1 {{ TAR STREAM }}示例响应HTTP/1.1 200 OK {{ STREAM }}查询参数t– 构建成功后应用到结果镜像上的仓库名状态码200无错误500服务器错误。4.2 认证信息GET /auth与POST /auth读取默认用户名与邮箱GET /authGET /auth HTTP/1.1HTTP/1.1 200 OK Content-Type: application/json { username:hannibal, email:hannibala-team.com }校验并保存认证配置POST /authPOST /auth HTTP/1.1 Content-Type: application/json { username:hannibal, password:xxxx, email:hannibala-team.com }HTTP/1.1 200 OK Content-Type: text/plainGET 状态码为200/500POST 状态码为200、204均表示无错误与500。4.3 系统级信息GET /info示例请求GET /info HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json { Containers:11, Images:16, Debug:false, NFd: 11, NGoroutines:21, MemoryLimit:true, SwapLimit:false }v1.0 的/info已经同时暴露运行统计容器/镜像数量、打开文件数、goroutine 数与内核能力位MemoryLimit、SwapLimit这是后续版本/info字段不断扩充的起点。状态码200无错误500服务器错误。4.4 版本信息GET /version示例请求GET /version HTTP/1.1示例响应HTTP/1.1 200 OK Content-Type: application/json { Version:0.2.2, GitCommit:5a2a5ccCHANGES, GoVersion:go1.0.3 }状态码200无错误500服务器错误。4.5 从容器变更提交新镜像POST /commit示例请求POST /commit?container44c004db4b17mmessagerepomyrepo HTTP/1.1 Content-Type: application/json { Cmd: [cat, /world], PortSpecs:[22] }示例响应HTTP/1.1 201 OK Content-Type: application/vnd.docker.raw-stream {Id: 596069db4bf5}查询参数参数说明container源容器repo仓库名tag标签m提交说明commit messageauthor作者例如John Hannibal Smith hannibala-team.com状态码201无错误404无此容器500服务器错误。5. 深入docker run一条命令背后的 API 调用序列v1.0 文档用docker run演示了客户端如何组合上述端点。以该命令为例其发起的 API 调用流程为创建容器POST /containers/create如果收到状态码404说明镜像不存在尝试拉取POST /images/create然后重试创建容器启动容器POST /containers/(id)/start如果不是分离detached模式附加到容器POST /containers/(id)/attach使用logs1以便获取容器启动以来的 stdout 和 stderr与stream1如果是分离模式、或只附加了 stdin直接显示容器 Id。这段创建 → 404 则拉取重试 → 启动 → 非分离则附加的编排逻辑就是理解docker run行为的钥匙对客户端而言run 并不是一个原子服务端操作而是多个 API 调用的客户端事务。6. 连接劫持Hijacking机制解析v1.0 文档最后一节说明在该版本中/attach、/pull、/push等端点使用劫持技术把 stdin、stdout、stderr 复用在同一个 socket 上传输且未来可能会改变。当前仓库的客户端实现印证了这一机制见 client/hijack.gosetupHijackConn会显式设置请求头Connection: Upgrade与Upgrade: proto先以标准 HTTP 方式发起请求只有当服务端返回101 SwitchingProtocols时连接才真正转入裸数据通道此后该 TCP 连接不再受 HTTP 帧约束直接承载多路复用流对 TCP 连接启用了 30 秒周期的 KeepAlive注释中解释了原因劫持后的连接可能长时间无输出长命令静默运行某些网络环境会触发ECONNTIMEOUTKeepAlive 可避免客户端进入未知状态postHijackedclient/hijack.go则封装了POST 请求 劫持的组合供 attach 类端点复用。同时v1.0 文档中 attach 响应的Content-Type: application/vnd.docker.raw-stream也表明即便不劫持API 也早在首版就用自定义 MIME 类型区分裸流、多路复用流与 JSON——这套内容协商约定一直延续到当前版本。7. 从 v1.0 到今天这份规范在仓库中的位置api/docs/ 目录按版本存放了每一版 API 规范的文档v1.0 以 Markdown 形式api/docs/v1.0.md保存v1.25 及以后则以 Swagger/OpenAPI YAML 文件如 api/docs/v1.26.yaml提供该目录 README 提醒读者旧版本支持属于尽力而为用户应优先使用最新 API 版本。每个版本的变更记录见 api/docs/CHANGELOG.md其中记录了从 v1.0 之后各版本对containers、images、info等端点的持续演进可以直接对照本文的 v1.0 端点查看字段与行为如何扩展或弃用。当前最新未发布的 API 定义位于 api/swagger.yaml配合 api/README.md 中说明的definitions可复用对象与paths端点两段结构维护并通过make swagger-docs生成预览文档。对需要实现或调试引擎 API 的读者而言v1.0 规范的价值在于它以最小的端点集合12 个容器端点、9 个镜像端点、6 个杂项端点确立了REST 为主、流式端点劫持为辅、JSON 为标准响应体的整体范式这一范式在后续五十余个版本中始终未变只是不断扩展了字段与过滤能力。【免费下载链接】mobyThe Moby Project - a collaborative project for the container ecosystem to assemble container-based systems项目地址: https://gitcode.com/GitHub_Trending/mo/moby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考