Go client for the Docker Engine API（1.45版本）使用心得（持续更新中）

本文链接：https://blog.csdn.net/MZS2254399401/article/details/140243086

client api版本： 1.45
docker版本： 1.45
golang版本： 1.21

其中，golang的版本最好与开发sdk的版本保持一致最好。

Container

func (cli *Client) ContainerExecAttach

func (cli *Client) ContainerExecAttach(ctx context.Context, execID string, config container.ExecAttachOptions) (types.HijackedResponse, error)

ContainerExecAttach attaches a connection to an exec process in the server. It returns a types.HijackedConnection with the hijacked connection and the a reader to get output. It’s up to the called to close the hijacked connection by calling types.HijackedResponse.Close.

该函数会将链接附加在服务器中的一个执行线程中，需要搭配函数ContainerExecCreate一起使用，函数返回被劫持的链接以及获取执行线程的输出Reader实例，并且该劫持链接需要调用Close方法来进行手动关闭，例如：
res, err1 := apiClient.ContainerExecAttach(context.Background(), res.ID, container.ExecAttachOptions{})
if err1 != nil {
    panic(err1)
}
defer res.Close()
//执行后续对res的处理逻辑
...

参数解释：

入参：
- ctx(context.Context)：不清楚，默认即可；
- execID(string)：ContainerExecCreate函数返回的已经创建在docker容器的进程id号；
- config(container.ExecAttachOptions)：进程执行附加配置可选项，默认即可。
出参：
- types.HijackedResponse：函数执行的响应信息，其中包含响应信息的mediaType、网络链接以及响应信息的Reader实例。

func (cli *Client) ContainerExecCreate

func (cli *Client) ContainerExecCreate(ctx context.Context, container string, options container.ExecOptions) (types.IDResponse, error)

ContainerExecCreate creates a new exec configuration to run an exec process.

在docker容器中创建一条新的执行配置来执行exec进程。值得注意的是，程序执行到这还没有开始执行shell命令，该函数会返回一个ID号，需要借助其他函数，例如：ContainerExecStart、ContainerExecAttach来执行shell命令/脚本的进程，该ID号执行一次之后就失效了。

参数解释：

入参：
- ctx(context.Context)：不清楚，默认即可；
- container(string)：容器名称或者容器id都可以；
- options(container.ExecOptions)：执行shell命令/脚本可选配置项，可以使用默认值，但针对里面的几个配置项还是需要进行解释的，因为很有用：
  - AttachStdin(bool)：允许附加标准输入，使得用户与容器交互变成可能；
  - AttachStderr(bool)：允许附加标准异常，使得执行shell命令/脚本的函数能够将异常信息输出出来；
  - AttachStdout(bool)：允许附加标准输出，使得执行shell命令/脚本的函数能够将输出信息输出出来；
  - Cmd([]string)：需要执行的shell命令以及参数。
    执行的shell命令中有时候需要携带一些参数，例如：[]string{“sh”, “-c”, “ls -a”}，该shell命令中使用了-c参数，对于常用的可选参数解释如下：
    - -c : command 后面跟一个字符串，这个字符串可以是我们平常执行的任何命令，有参数选项时一定要用引号括起来
    - -x : 后面跟shell脚本，可以详细的显示shell脚本的执行信息
  需要注意的是：如果需要获取容器中shell命令/脚本的输出信息，则启动shell脚本的函数则需要使用ContainerExecAttach，该函数的使用示例如下：
```
//执行shell命令/脚本，其中res.ID入参则是函数ContainerExecCreate执行后的返回结果
res, err1 := apiClient.ContainerExecAttach(context.Background(), res.ID, container.ExecAttachOptions{})
if err1 != nil {
    panic(err1)
}
defer res.Close()
stdout := new(bytes.Buffer)
stderr := new(bytes.Buffer)
//将返回的信息拷贝至标准输出流以及标准异常流
_, err2 := stdcopy.StdCopy(stdout, stderr, res.Reader)
if err2 != nil {
    panic(err2)
}
s := stdout.String()
fmt.Println(s)
i := stderr.String()
fmt.Println(i)
```
出参：
- types.IDResponse：原文注释： Response to an API call that returns just an Id；理解为：对仅返回 ID 的 API 调用的响应，即返回一个ID号，用于后续执行shell命令/脚本。

func (cli *Client) ContainerExecStart

func (cli *Client) ContainerExecStart(ctx context.Context, execID string, config container.ExecStartOptions) error

ContainerExecStart starts an exec process already created in the docker host.

该函数将会执行已经在docker容器中创建的执行进程，该函数只做执行操作，不会对docker有标准输入输出的附加信息。

参数解释：

入参：
- ctx(context.Context)：不清楚，默认即可；
- execID(string)：ContainerExecCreate函数返回的已经创建在docker容器的进程id号；
- config(container.ExecStartOptions)：启动执行进程的可选配置项，默认即可。

func (cli *Client) ContainerRemove

func (cli *Client) ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error

ContainerRemove kills and removes a container from the docker host.

该函数直接kill掉docker容器的进程，与stop命令不同的是，直接kill掉的容器，再start后进程号会发生改变，而stop命令则是会给一段时间（默认10秒）给容器保存数据，从而达到安全停止容器，重新start容器，其进程号不变。当然，在使用该函数的过程中发现默认情况下无法直接移除容器，会提示需要stop容器之后再remove，因此需要搭配ContainerStop函数使用。

参数解释：

入参：
- ctx(context.Context)：不清楚，默认即可；
- containerID(string)：容器id；
- options(container.RemoveOptions)：容器移除配置可选项，在删除容器时，其附属资源还需要进一步处理，例如：卷（Volumes）、链接（Links）等，这时候可以通过该配置项来进行选择是否随同容器进行删除。配置项参数解释如下：
  - RemoveVolumes(bool)：是否删除容器所关联的卷；
  - RemoveLinks(bool)：是否删除容器的链接；
  - Force(bool)：是否强制删除容器，如果为true，则会强制kill掉容器的进程，并且移除容器，默认情况下是false。

func (cli *Client) ContainerStop

func (cli *Client) ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error

ContainerStop stops a container. In case the container fails to stop gracefully within a time frame specified by the timeout argument, it is forcefully terminated (killed).

该函数会停止容器，但是不会移除容器，如果在设定的时间内（默认10秒）没有办法正常停止容器，则会直接使用kill命令来终止容器进程。

参数解释：

入参：
- ctx(context.Context)：不清楚，默认即可；
- containerID(string)：容器id；
- options(container.StopOptions)：容器停止配置可选项，该配置可选项参数解释如下：
  - Signal(string)：终止容器进程的信号量，采用默认的SIGTERM即可，即在不清楚自定义的配置情况下不建议配置；
  - Timeout(*int)：配置安全停止容器的允许时间，单位为秒，如果超过时间没有安全停止的话则会kill掉容器进程，有几个特殊值：0（立即强制终止容器进程）、-1（不限制时间）。注意参数类型为*int。

func (cli *Client) CopyToContainer

func (cli *Client) CopyToContainer(ctx context.Context, containerID, dstPath string, content io.Reader, options container.CopyToContainerOptions) error

CopyToContainer copies content into the container filesystem. Note that content must be a Reader for a TAR archive

将宿主机的文件内容拷贝至容器中，注意：文件内容必须是tar文件类型的Reader对象，可以使用如下代码获得文件的Reader对象：
file, err := os.Open("./index.tar")
其中file实例实现有Reader接口，因此可以直接当做函数的io.Reader参数。

注意：该函数会将传输进容器内的tar文件进行解压。