Docker#

该模块提供基于 Docker 容器标签在 HTTP 和 stream 上下文中动态配置代理服务器组的功能。为了使该功能正常工作，必须在组中配置共享内存区域（参见 http 和 stream 的 zone 描述）。

备注

该模块支持与 Docker 及其替代品（如 Podman）一起工作，只要它们实现了兼容的 API。

该模块通过 API 连接到 Docker 守护进程，与之交互的方法由 docker_endpoint 指令指定。获取运行中容器列表后， Angie 分析它们是否存在合适的标签。如果容器描述包含带有端口的标签，则该容器的地址和端口，以及来自该容器其他标签的参数，将自动添加到 Angie 配置中相应的 upstream 块中。

备注

同一个容器可以添加到多个 upstream 组；只需指定多组带有不同组名和端口的标签即可。

如果容器在不同端口上运行多个不同的服务，这特别有用；每个服务可以与自己的组相关联。

然后，该模块订阅容器生命周期事件，并开始在不重新加载 Angie 的情况下更新代理服务器配置：

当启动带有合适标签的容器时，其内部 IP 地址会被添加到指定的组中；
当停止或删除容器时，它会自动从组中移除；
当使用 docker pause 命令暂停容器时，服务器会被标记为 down，而使用 docker unpause 时则标记为 up。

配置示例#

模块的指令始终位于 http 上下文中，但代理服务器组可以定义在 http 上下文和 stream 上下文中。

http 的配置示例：

http {

    # 连接选项示例：
    # docker_endpoint http://127.0.0.1:2375;
    # docker_endpoint https://127.0.0.1:2376;
    docker_endpoint unix:/var/run/docker.sock;

    # Docker 响应缓冲区最大大小（可选）
    # docker_max_object_size 128k;

    upstream u {

        zone z 1m; # 需要共享内存区域
    }

    server {

        listen 80;
        server_name example.com;

        location / {

            proxy_pass http://u;
        }
    }
}

stream 上下文中的类似配置：

http {

    # 连接选项示例：
    # docker_endpoint http://127.0.0.1:2375;
    # docker_endpoint https://127.0.0.1:2376;
    docker_endpoint unix:/var/run/docker.sock;

    # Docker 响应缓冲区最大大小（可选）
    # docker_max_object_size 128k;
}

stream {

    upstream u {

        zone z 1m;
    }

    server {

        listen 12345;
        proxy_pass u;
    }
}

当收到容器事件时， Angie 会查找形如 angie.http.upstreams.<name>.port=<port>`（HTTP 上下文）或 :samp:`angie.stream.upstreams.<name>.port=<port>`（stream 上下文）的标签。当存在标签时，容器在指定 Docker 网络中的地址（如果未指定 :samp:`angie.network 标签，则使用第一个可用网络）将被添加到相应的代理服务器组中。

如果容器停止或被移除，服务器将从组中移除；如果容器被暂停，服务器将被标记为 down。

带有 Angie 识别标签的 docker-compose.yml 文件片段：

services:
  myapp:
    image: myapp:latest
    labels:
      - "angie.http.upstreams.u.port=8080"
      - "angie.network=my_bridge"
      - "angie.http.upstreams.u.weight=2"
      - "angie.http.upstreams.u.max_conns=50"
      - "angie.http.upstreams.u.max_fails=3"
      - "angie.http.upstreams.u.fail_timeout=10s"
      - "angie.http.upstreams.u.backup=true"

标签#

标签指定代理服务器组中的服务器参数，类似于 server 指令的参数：

标签	用途
`angie.(http\|stream).upstreams.<name>.port=<port>` （必需）	Angie 将连接到的容器端口；容器本身被添加到名为 `<name>` 的组中。
`angie.network=<docker-network>`	从中获取容器 IP 地址的 Docker 网络名称。
`angie.(http\|stream).upstreams.<name>.weight=<n>`	`weight` 参数的值。
`angie.(http\|stream).upstreams.<name>.max_conns=<n>`	最大同时连接数 (`max_conns`)。
`angie.(http\|stream).upstreams.<name>.max_fails=<n>`	失败尝试阈值 (`max_fails`)。
`angie.(http\|stream).upstreams.<name>.fail_timeout=<t>`	计算失败尝试的间隔 (`fail_timeout`)。
`angie.(http\|stream).upstreams.<name>.backup=true\|false`	将服务器标记为 `backup`。
`angie.(http\|stream).upstreams.<name>.sid=<string>`	为代理服务器设置自定义服务器标识符 (`sid`)。
`angie.(http\|stream).upstreams.<name>.slow_start=<time>`	启用 `slow_start` 模式，并配置时间周期。

指令#

docker_endpoint#

语法	`docker_endpoint` `URL`;
默认值	—
上下文	http

指定连接到 Docker 守护进程的方法并启用容器事件跟踪。支持以下选项：

`unix:/var/run/docker.sock`	通过 Unix 套接字连接（例如，`/var/run/docker.sock`）。
`http://host:port`, `https://host:port`	通过 HTTP 或 HTTPS 连接到远程 Docker API。

连接可以通过 client 上下文进一步配置，其中模块添加了两个命名 location 块：

@docker_events 用于接收容器事件；
@docker_containers 用于获取容器信息。

默认情况下，它们包含带有连接地址的 proxy_pass 指令和其他几个最佳默认设置，可以向其添加来自 Proxy 模块的其他设置。

如果指定了该指令， Angie 将使用指定方法打开与 Docker 的连接，请求运行中容器列表，分析它们的标签并处理所有后续容器事件，根据标签在代理服务器组中添加或删除服务器。

小技巧

要通过 Unix 套接字访问 Docker 守护进程（/var/run/docker.sock 或其他），运行 Angie 的用户必须对该套接字具有读写权限。

docker_max_object_size#

语法	`docker_max_object_size` `<size>`;
默认值	`64k`
上下文	http

设置用于 Docker 请求的 JSON 响应和容器事件流的最大缓冲区大小。

对于常规请求（API 版本、容器列表、容器信息）：整个响应必须适合缓冲区，否则会发生错误。
对于容器事件，使用流式处理并重用缓冲区，这允许处理无限的事件流。

典型值 64k 足以处理大约 25 个容器。

当发生 Docker API 连接错误或响应处理错误时，模块会在特定时间间隔后自动重试。获取特定容器信息的最大重试尝试次数限制为两次*额外*尝试；之后，模块将停止对该容器的尝试。