Docker#

Added in version 1.10.0.

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

备注

该模块支持与 Docker 及其替代品（如 Podman）配合使用，这些替代品实现了兼容的 API。建议使用 Podman 4.9.3 及以上版本。

该模块通过 API 连接到 Docker 守护进程，与其交互的方法由 docker_endpoint 指令指定。在获取正在运行的容器列表后，Angie 会分析它们是否存在合适的标签。这些标签用于确定目标 upstream 组，并决定服务器地址是否包含容器端口。对于每个匹配的组，Angie 会将所选 Docker 网络中的容器地址，以及其余标签中的参数，添加到 Angie 配置中相应的 upstream 块。

备注

同一个容器可以添加到多个 upstream 组。要实现这一点，只需指定多组具有不同组名和不同 port 标签值的标签即可。

这在容器在不同端口上运行多个不同服务时特别有用——每个服务可以关联到自己的组。

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

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

当从源代码构建时，该模块默认会被构建；可以通过构建选项 --without-http_docker_module 禁用它。

在来自我们的软件仓库的包和镜像中，该模块已包含在构建中。

配置示例#

该模块的指令始终位于 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 上下文）或 angie.stream.upstreams.<name>.port=<port> （用于 stream 上下文）的标签。当存在标签时，容器在所选 Docker 网络中的地址将添加到相应的代理服务器组。网络优先取自 angie.(http|stream).upstreams.<name>.network 标签（如果为该上游设置了此标签）；否则取自作用于整个容器的 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=<value>` （必需）	将容器添加到名为 `<name>` 的组。该值设置为 Angie 连接的容器端口号；对于无端口的 stream 组（PRO），设置为 `*`。
`angie.network=<docker-network>`	用于获取容器 IP 地址的 Docker 网络名称。
`angie.(http\|stream).upstreams.<name>.network=<docker-network>`	此代理上游所用的 Docker 网络名称；优先于 `angie.network` 标签。
`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 套接字（/var/run/docker.sock 或其他）访问 Docker 守护进程，Angie 运行所使用的用户必须对此套接字具有读写权限。

docker_max_object_size#

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

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

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

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

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