gesellix/testimage

Docker客户端

一个用Groovy编写的Docker HTTP客户端

![构建状态]([] ![最新版本 ]([]

镜像概述和主要用途

该客户端库旨在支持所有现有API端点，这使其能够替代官方Docker客户端二进制文件使用。虽然使用起来可能稍欠便捷，但它提供了更多访问远程API的自由，以及使用一些不太常用端点的能力。有关当前API覆盖的详细信息，请参见https://github.com/gesellix/docker-client/blob/master/roadmap.md%E3%80%82

该客户端可视为执行HTTP请求的薄包装，减少了代码中手动配置TLS或认证编码的需求。大多数常见环境变量（如DOCKER_HOST、DOCKER_TLS_VERIFY或DOCKER_CERT_PATH）将按预期工作。

核心功能和特性

• 完整API覆盖：支持所有Docker远程API端点，API覆盖率达100%
• 简化配置：自动处理TLS和认证编码，减少手动配置工作
• 环境变量支持：兼容常见Docker环境变量，如DOCKER_HOST、DOCKER_TLS_VERIFY等
• 灵活配置覆盖：可通过Java系统属性覆盖现有DOCKER_*环境变量
• 原始响应返回：返回包含头信息的Docker daemon原始响应，响应体在content属性中
• 流响应支持：支持流响应（如日志、事件），并提供回调机制处理流数据

使用场景和适用范围

• 替代官方Docker客户端二进制文件进行Docker操作
• 在Gradle脚本中集成Docker功能
• 需要直接访问Docker远程API的应用开发
• 需要使用Docker远程API中较少见端点的场景
• Docker客户端集成测试

使用方法和配置说明

基础使用

Gradle配置

首先添加Bintray仓库：

groovy
repositories {
  maven { url 'http://dl.bintray.com/gesellix/docker-utils' }
}

然后添加依赖（请确保使用最新版本）：

groovy
dependencies {
  compile 'de.gesellix:docker-client:2016-12-10T23-39-48'
}

DockerClientImplSpec和DockerClientImplIntegrationSpec中的测试可提供使用示例参考。

默认配置

默认Docker主机预期在unix:///var/run/docker.sock可用。使用Docker Machine时，通过eval "$(docker-machine env default)"配置的现有环境变量已足够。

对于原生包Docker for Mac和Docker for Windows，默认配置同样适用：

• Mac的默认配置与Linux相同：unix:///var/run/docker.sock
• Windows使用命名管道：//./pipe/docker_engine

配置覆盖

可通过Java系统属性覆盖现有DOCKER_*环境变量：

groovy
System.setProperty("docker.host", "192.168.99.100")
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")

注意：返回的Docker daemon原始响应包含头信息，实际响应体在content属性中。某些端点返回流数据，可通过stream属性访问。对于日志或事件流等场景，需提供回调函数处理每个响应行，见示例3。

使用示例

示例1：docker info

连接运行在VM（boot2docker/machine）中的Docker daemon的基本示例：

groovy
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")
def dockerClient = new DockerClientImpl(System.env.DOCKER_HOST)
def info = dockerClient.info().content

示例2：docker run

运行一个通过主机HTTP端口4712访问的容器：

groovy
System.setProperty("docker.cert.path", "/Users/${System.getProperty('user.name')}/.docker/machine/machines/default")
def dockerClient = new DockerClientImpl(System.env.DOCKER_HOST)
def image = "busybox"
def tag = "latest"
def cmds = ["sh", "-c", "ping 127.0.0.1"]
def containerConfig = ["Cmd"         : cmds,
                       "ExposedPorts": ["4711/tcp": [:]],
                       "HostConfig"  : ["PortBindings": [
                               "4711/tcp": [
                                       ["HostIp"  : "0.0.0.0",
                                        "HostPort": "4712"]]
                       ]]]
def result = dockerClient.run(image, containerConfig, tag).content

示例3：docker logs --follow

groovy
def callback = new DockerAsyncCallback() {
    def lines = []

    @Override
    def onEvent(Object line) {
        println line
        lines << line
    }
}

dockerClient.logs("foo", [tail: 1], callback)

// callback.lines将收集所有日志行
// 可将其实现为fifo而非上述List

与Gradle Docker Plugin集成

开发此Docker客户端的主要目的是在Gradle脚本中利用Docker远程API。通过使用https://github.com/gesellix/gradle-docker-plugin%E5%8F%AF%E6%96%B9%E4%BE%BF%E5%9C%B0%E9%9B%86%E6%88%90%E5%88%B0Gradle%E4%B8%AD%EF%BC%8C%E8%AF%A5%E6%8F%92%E4%BB%B6%E5%B0%86%E4%B8%8EDocker%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%BA%93%E4%B8%80%E8%B5%B7%E5%BC%80%E5%8F%91%E3%80%82

贡献和未来计划

如遇功能异常或有建议，请https://github.com/gesellix/docker-client/issues%E3%80%82%E4%B9%9F%E6%AC%A2%E8%BF%8E%E6%8F%90%E4%BA%A4PR%EF%BC%81

当前开发者API尚不完善，计划在原始接口之上添加更便捷的层，使80%的常见用例无需深入源代码即可实现。如需讨论用例实现，请创建issue参与讨论！

许可证

版权所有2015 Tobias Gesellchen (@gesellix)

根据Apache许可证2.0版（"许可证"）授权；除非符合许可证，否则不得使用此文件。您可以在以下位置获取许可证副本：

[***]

除非适用***要求或书面同意，否则根据许可证分发的软件按"原样"分发，不提供任何明示或暗示的担保或条件。有关许可证下权限和限制的具体语言，请参见许可证。