API#

该模块提供了HTTP RESTful接口,以JSON格式访问有关Web服务器实例的基本信息,以及客户端连接、共享内存区域、DNS查询、HTTP请求、HTTP响应缓存、流模块 的TCP/UDP会话,和 限制连接限制连接限制请求上游 模块的区域的指标。

API接受 GETHEAD HTTP请求;其他请求方法会导致错误:

{
    "error": "MethodNotAllowed",
    "description": "请求的API元素\"/\"不允许使用POST方法。"
}

Angie PRO API有一个:ref:动态配置 <api_config>,允许在不重新加载配置或重启Angie本身的情况下更新设置;目前,它支持在上游配置单个对等体。

Directives#

api#

语法

api path;

默认

上下文

location

location 中启用HTTP RESTful接口。

path 参数是必需的,其工作方式类似于 alias 指令,但作用于API树,而不是文件系统层次结构。

在指定为前缀位置时:

location /stats/ {
    api /status/http/server_zones/;
}

与特定前缀位置 /stats/ 匹配的请求URI部分将被指令参数中的路径 /status/http/server_zones/ 替换。例如,对于请求 /stats/foo/,将访问:samp:/status/http/server_zones/foo/ API元素。

还可以使用变量:api /status/$module/server_zones/$name/,并且指令也可以在正则表达式位置内指定:

location ~^/api/([^/]+)/(.*)$ {
    api /status/http/$1_zones/$2;
}

在这里,类似于 alias,参数定义了到API元素的完整路径。例如,从 /api/location/bar/data/ 将填充以下位置变量:

$1 = "location"
$2 = "bar/data/"

这导致插值结果为 /status/http/location_zones/bar/data API请求。

备注

在Angie PRO中,您可以将 动态配置API 与反映当前状态的不可变 指标API 解耦:

location /config/ {
    api /config/;
}

location /status/ {
    api /status/;
}

总体来说,它用于精确配置API访问权限,例如:

location /status/ {
    api /status/;

    allow 127.0.0.1;
    deny  all;
}

或者:

location /blog/requests/ {
    api /status/http/server_zones/blog/requests/;

    auth_basic           "blog";
    auth_basic_user_file conf/htpasswd;
}

api_config_files#

语法

api_config_files on | off;

默认

off

上下文

location

启用或禁用 config_files 对象,该对象列出当前由服务器实例加载的所有Angie配置文件的内容,在 /status/angie/ API部分。例如,使用以下配置:

location /status/ {
    api /status/;
    api_config_files on;
}

/status/angie/ 的查询大约返回以下内容:

{
    "version":"1.8.2",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-02-13T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

默认情况下,该对象是禁用的,因为配置文件可能包含额外的敏感机密详细信息。

指标#

Angie在API的 /status/ 部分公开使用情况指标;您可以通过定义相应的 location 使其可访问。 完全访问:

location /status/ {
    api /status/;
}

子树访问,如前所述:

location /stats/ {
    api /status/http/server_zones/;
}

示例配置#

配置了 location /status/resolverhttp upstreamhttp serverlocationcachelimit_connlimit_req 区域:

http {

    resolver 127.0.0.53 status_zone=resolver_zone;
    proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:2m;
    limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
    limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;

    upstream upstream {
        zone upstream 256k;
        server backend.example.com service=_example._tcp resolve max_conns=5;
       keepalive 4;
    }

    server {
        server_name www.example.com;
        listen 443 ssl;

        status_zone http_server_zone;
        proxy_cache cache_zone;

        access_log /var/log/access.log main;

        location / {
            root /usr/share/angie/html;
            status_zone location_zone;
            limit_conn limit_conn_zone 1;
            limit_req zone=limit_req_zone burst=5;
        }
        location /status/ {
            api /status/;

            allow 127.0.0.1;
            deny all;
        }

    }
}

响应 curl https://www.example.com/status/ 时返回以下JSON:

JSON tree
{
    "angie": {
        "version":"1.8.2",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-02-13T12:58:39.789Z"
    },

    "connections": {
        "accepted":2257,
        "dropped":0,
        "active":3,
        "idle":1
    },

    "slabs": {
        "cache_zone": {
            "pages": {
                "used":2,
                "free":506
            },

            "slots": {
                "64": {
                    "used":1,
                    "free":63,
                    "reqs":1,
                    "fails":0
                },

                "512": {
                    "used":1,
                    "free":7,
                    "reqs":1,
                    "fails":0
                }
            }
        },

        "limit_conn_zone": {
            "pages": {
                "used":2,
                "free":2542
            },

            "slots": {
                "64": {
                    "used":1,
                    "free":63,
                    "reqs":74,
                    "fails":0
                },

                "128": {
                    "used":1,
                    "free":31,
                    "reqs":1,
                    "fails":0
                }
            }
        },

        "limit_req_zone": {
            "pages": {
                "used":2,
                "free":2542
            },

            "slots": {
                "64": {
                    "used":1,
                    "free":63,
                    "reqs":1,
                    "fails":0
                },

                "128": {
                    "used":2,
                    "free":30,
                    "reqs":3,
                    "fails":0
                }
            }
        }
    },

    "http": {
        "server_zones": {
            "http_server_zone": {
                "ssl": {
                    "handshaked":4174,
                    "reuses":0,
                    "timedout":0,
                    "failed":0
                },

                "requests": {
                    "total":4327,
                    "processing":0,
                    "discarded":8
                },

                "responses": {
                    "200":4305,
                    "302":12,
                    "404":4
                },

                "data": {
                    "received":733955,
                    "sent":59207757
                }
            }
        },

        "location_zones": {
            "location_zone": {
                "requests": {
                    "total":4158,
                    "discarded":0
                },

                "responses": {
                    "200":4157,
                    "304":1
                },

                "data": {
                    "received":538200,
                    "sent":177606236
                }
            }
        },
        "caches": {
            "cache_zone": {
                "size":0,
                "cold":false,
                "hit": {
                    "responses":0,
                    "bytes":0
                },

                "stale": {
                    "responses":0,
                    "bytes":0
                },

                "updating": {
                    "responses":0,
                    "bytes":0
                },

                "revalidated": {
                    "responses":0,
                    "bytes":0
                },

                "miss": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                },

                "expired": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                },

                "bypass": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                }
            }
        },

        "limit_conns": {
            "limit_conn_zone": {
                "passed":73,
                "skipped":0,
                "rejected":0,
                "exhausted":0
            }
        },

        "limit_reqs": {
            "limit_req_zone": {
                "passed":54816,
                "skipped":0,
                "delayed":65,
                "rejected":26,
                "exhausted":0
            }
        },

        "upstreams": {
            "upstream": {
                "peers": {
                    "192.168.16.4:80": {
                        "server":"backend.example.com",
                        "service":"_example._tcp",
                        "backup":false,
                        "weight":5,
                        "state":"up",
                        "selected": {
                            "current":2,
                            "total":232
                        },

                        "max_conns":5,
                        "responses": {
                            "200":222,
                            "302":12
                        },

                        "data": {
                            "sent":543866,
                            "received":27349934
                        },

                        "health": {
                            "fails":0,
                            "unavailable":0,
                            "downtime":0
                        },

                        "sid":"<server_id>"
                    }
                },

                "keepalive":2
            }
        }
    },

    "resolvers": {
        "resolver_zone": {
            "queries": {
                "name":442,
                "srv":2,
                "addr":0
            },

            "responses": {
                "success":440,
                "timedout":1,
                "format_error":0,
                "server_failure":1,
                "not_found":1,
                "unimplemented":0,
                "refused":1,
                "other":0
            }
        }
    }
}

每个 JSON 分支可以单独请求,构造相应的请求,例如:

$ curl https://www.example.com/status/angie
$ curl https://www.example.com/status/connections
$ curl https://www.example.com/status/slabs
$ curl https://www.example.com/status/slabs/<zone>/slots
$ curl https://www.example.com/status/slabs/<zone>/slots/64
$ curl https://www.example.com/status/http/
$ curl https://www.example.com/status/http/server_zones
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>/ssl

备注

默认情况下,模块使用 ISO 8601 字符串作为日期值; 要改用整数纪元格式, 请在查询字符串中添加 date=epoch 参数:

$ curl https://www.example.com/status/angie/load_time

  "2024-04-01T00:59:59+01:00"

$ curl https://www.example.com/status/angie/load_time?date=epoch

  1711929599

服务器状态#

/status/angie#

{
    "version": "1.8.2",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-02-13T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

version

字符串;正在运行的 Angie Web 服务器的版本

build

字符串;编译时指定的特定构建名称

address

字符串;接受 API 请求的服务器地址

generation

数字;自上次启动以来的配置重载总数

load_time

字符串或数字;最后一次配置重载的时间, 格式为 date; 字符串具有毫秒精度

config_files

对象;其成员是所有当前由服务器实例加载的 Angie 配置文件的绝对路径, 其值是文件内容的字符串表示, 例如:

{
    "/etc/angie/angie.conf": "server {\n  listen 80;\n  # ...\n\n}\n"
}

小心

config_files 对象仅在 /status/angie/ 可用时,如果启用了 api_config_files 指令。

连接全局指标#

/status/connections#

{
  "accepted": 2257,
  "dropped": 0,
  "active": 3,
  "idle": 1
}

accepted

数字;已接受的客户端连接总数

dropped

数字;已丢弃的客户端连接总数

active

数字;当前活动的客户端连接数

idle

数字;当前空闲的客户端连接数

共享内存区域的 slab 分配器指标#

/status/slabs/<zone>#

使用 slab allocation 的共享内存区域的使用统计, 例如 limit_connlimit_reqHTTP cache

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
proxy_cache cache_zone;

指定的共享内存区域将收集以下统计信息:

pages

对象;内存页面统计信息

    used

数字;当前使用的内存页面数量

    free

数字;当前空闲的内存页面数量

slots

对象;每个插槽大小的内存插槽统计信息。 slots 对象包含请求的内存插槽大小的字段(例如 81632 等,直到页面大小的一半)

    used

数字;当前指定大小的内存插槽的使用数量

    free

数字;当前指定大小的内存插槽的空闲数量

    reqs

数字;尝试分配指定大小的内存插槽的总数

    fails

数字;未能分配指定大小的内存插槽的尝试次数

示例:

{
  "pages": {
    "used": 2,
    "free": 506
  },

  "slots": {
    "64": {
      "used": 1,
      "free": 63,
      "reqs": 1,
      "fails": 0
  }
}

解析器 DNS 查询#

/status/resolvers/<zone>#

要收集解析器统计信息, 必须在 resolver 指令中设置 status_zone 参数 (HTTPStream):

resolver 127.0.0.53 status_zone=resolver_zone;

指定的共享内存区域将收集以下统计信息:

queries

对象;查询统计信息

    name

数字;解析名称到地址的查询数量 (A 和 AAAA 查询)

    srv

数字;解析服务到地址的查询数量 (SRV 查询)

    addr

数字;解析地址到名称的查询数量 (PTR 查询)

responses

对象;响应统计信息

    success

数字;成功响应的数量

    timedout

数字;超时查询的数量

    format_error

数字;响应代码为 1 (格式错误) 的响应数量

    server_failure

数字;响应代码为 2 (服务器失败) 的响应数量

    not_found

数字;响应代码为 3 (名称错误) 的响应数量

    unimplemented

数字;响应代码为 4 (未实现) 的响应数量

    refused

数字;响应代码为 5 (拒绝) 的响应数量

    other

数字;以其他非零代码完成的查询数量

sent

对象;发送的 DNS 查询统计信息

    a

数字;A 类型查询的数量

    aaaa

数字;AAAA 类型查询的数量

    ptr

数字;PTR 类型查询的数量

    srv

数字;SRV 类型查询的数量

响应代码在 RFC 10354.1.1 节中描述。

各种 DNS 记录类型在 RFC 1035RFC 2782RFC 3596 中详细说明。

示例:

{
  "queries": {
    "name": 442,
    "srv": 2,
    "addr": 0
  },

  "responses": {
    "success": 440,
    "timedout": 1,
    "format_error": 0,
    "server_failure": 1,
    "not_found": 1,
    "unimplemented": 0,
    "refused": 1,
    "other": 0
  },

  "sent": {
    "a": 185,
    "aaaa": 245,
    "srv": 2,
    "ptr": 12
  }
}

HTTP 服务器和位置#

/status/http/server_zones/<zone>#

要收集 server 指标, 请在 server 上下文中设置 status_zone 指令:

server {
    ...
    status_zone server_zone;
}

要按自定义值分组指标,请使用替代语法。 在这里,指标按 $host 聚合, 每个组作为独立区域报告:

status_zone $host zone=server_zone:5;

指定的共享内存区域将收集以下统计信息:

ssl

对象;SSL 统计信息。 如果 server 设置了 listen ssl;,则存在

    handshaked

数字;成功的 SSL 握手总数

    reuses

数字;在 SSL 握手期间会话重用的总数

    timedout

数字;超时的 SSL 握手总数

    failed

数字;失败的 SSL 握手总数

requests

对象;请求统计信息

    total

数字;客户端请求的总数

    processing

数字;当前正在处理的客户端请求数

    discarded

数字;未发送响应的客户端请求总数

responses

对象;响应统计信息

    <code>

数字;状态为 <code> (100-599) 的非零响应数量

    xxx

数字;其他状态代码的非零响应数量

data

对象;数据统计信息

    received

数字;从客户端接收的字节总数

    sent

数字;发送到客户端的字节总数

示例:

"ssl": {
  "handshaked": 4174,
  "reuses": 0,
  "timedout": 0,
  "failed": 0
},

"requests": {
  "total": 4327,
  "processing": 0,
  "discarded": 0
},

"responses": {
  "200": 4305,
  "302": 6,
  "304": 12,
  "404": 4
},

"data": {
  "received": 733955,
  "sent": 59207757
}

/status/http/location_zones/<zone>#

要收集 location 指标,请在 locationif in location 的上下文中设置 status_zone 指令:

location / {
    root /usr/share/angie/html;
    status_zone location_zone;
    if ($request_uri ~* "^/condition") {
        # ...
        status_zone if_location_zone;
    }
}

要按自定义值对指标进行分组,请使用替代语法。 在这里,指标按 $host 进行聚合, 每个组作为独立区域报告:

status_zone $host zone=server_zone:5;

指定的共享内存区域将收集以下统计信息:

requests

对象;请求统计信息

    total

数字;客户端请求的总数

    discarded

数字;完成但未发送响应的客户端请求总数

responses

对象;响应统计信息

    <code>

数字;具有状态 <code>(100-599)的非零响应数量

    xxx

数字;具有其他状态码的非零响应数量

data

对象;数据统计信息

    received

数字;从客户端接收的总字节数

    sent

数字;发送给客户端的总字节数

示例:

{
  "requests": {
    "total": 4158,
    "discarded": 0
  },

  "responses": {
    "200": 4157,
    "304": 1
  },

  "data": {
    "received": 538200,
    "sent": 177606236
  }
}

流服务器#

/status/stream/server_zones/<zone>#

要收集 server 指标, 在 server 上下文中设置 status_zone 指令:

server {
    ...
    status_zone server_zone;
}

要按自定义值对指标进行分组,请使用替代语法。 在这里,指标按 $host 进行聚合, 每个组作为独立区域报告:

status_zone $host zone=server_zone:5;

指定的共享内存区域将收集以下统计信息:

ssl

对象;SSL统计信息。 如果 server 设置了 listen ssl; 则存在

    handshaked

数字;成功的SSL握手总数

    reuses

数字;SSL握手期间会话重用的总数

    timedout

数字;超时的SSL握手总数

    failed

数字;失败的SSL握手总数

connections

对象;连接统计信息

    total

数字;客户端连接的总数

    processing

数字;当前正在处理的客户端连接数量

    discarded

数字;完成但未创建会话的客户端连接总数

    discarded

数字;转发到另一个监听端口的客户端连接总数,使用 pass 指令

sessions

对象;会话统计信息

    success

数字;完成状态为200的会话数量,表示成功完成

    invalid

数字;完成状态为400的会话数量,当客户端数据无法解析时发生,例如PROXY协议头

    forbidden

数字;完成状态为403的会话数量,当访问被禁止时,例如,当访问限制于某些客户端地址

    internal_error

数字;完成状态为500的会话数量,内部服务器错误

    bad_gateway

数字;完成状态为502的会话数量,错误网关,例如,如果无法选择或访问上游服务器

    service_unavailable

数字;完成状态为503的会话数量,服务不可用,例如,当访问限制于连接数时

data

对象;数据统计信息

    received

数字;从客户端接收的总字节数

    sent

数字;发送给客户端的总字节数

示例:

{
  "ssl": {
    "handshaked": 24,
    "reuses": 0,
    "timedout": 0,
    "failed": 0
  },

  "connections": {
    "total": 24,
    "processing": 1,
    "discarded": 0,
    "passed": 2
  },

  "sessions": {
    "success": 24,
    "invalid": 0,
    "forbidden": 0,
    "internal_error": 0,
    "bad_gateway": 0,
    "service_unavailable": 0
  },

  "data": {
    "received": 2762947,
    "sent": 53495723
  }
}

HTTP缓存#

proxy_cache cache_zone;

/status/http/caches/<cache>#

对于每个配置了 proxy_cache 的区域,存储以下数据:

{
  "name_zone": {
    "size": 0,
    "cold": false,
    "hit": {
      "responses": 0,
      "bytes": 0
    },

    "stale": {
      "responses": 0,
      "bytes": 0
    },

    "updating": {
      "responses": 0,
      "bytes": 0
    },

    "revalidated": {
      "responses": 0,
      "bytes": 0
    },

    "miss": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    },

    "expired": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    },

    "bypass": {
      "responses": 0,
      "bytes": 0,
      "responses_written": 0,
      "bytes_written": 0
    }
  }
}

size

数字;缓存的当前大小

max_size

数字;配置的缓存最大大小限制

cold

布尔值;在 缓存加载器 从磁盘加载数据时为 true

hit

对象;有效缓存响应的统计信息 (proxy_cache_valid)

    responses

数字;从缓存读取的响应总数

    bytes

数字;从缓存读取的总字节数

stale

对象;从缓存中获取的过期响应的统计信息 (proxy_cache_use_stale)

    responses

数字;从缓存读取的响应总数

    bytes

数字;从缓存读取的总字节数

updating

对象;在更新响应时从缓存中获取的过期响应的统计信息 (proxy_cache_use_stale 更新)

    responses

数字;从缓存读取的响应总数

    bytes

数字;从缓存读取的总字节数

revalidated

对象;从缓存中获取的过期和重新验证响应的统计信息 (proxy_cache_revalidate)

    responses

数字;从缓存读取的响应总数

    bytes

数字;从缓存读取的总字节数

miss

对象;未在缓存中找到的响应的统计信息

    responses

数字;对应响应的总数

    bytes

数字;从代理服务器读取的总字节数

    responses_written

数字;写入缓存的响应总数

    bytes_written

数字;写入缓存的总字节数

expired

对象;未从缓存中获取的过期响应的统计信息

    responses

数字;对应响应的总数

    bytes

数字;从代理服务器读取的总字节数

    responses_written

数字;写入缓存的响应总数

    bytes_written

数字;写入缓存的总字节数

bypass

对象;未在缓存中查找的响应的统计信息 (proxy_cache_bypass)

    responses

数字;对应响应的总数

    bytes

数字;从代理服务器读取的总字节数

    responses_written

数字;写入缓存的响应总数

    bytes_written

数字;写入缓存的总字节数

Added in version 1.2.0: PRO

在Angie PRO中,如果使用 proxy_cache_path 指令启用 缓存分片, 单个分片作为 shards 对象的成员公开:

shards

对象;列出单个分片作为成员

    <shard>

对象;表示一个单独的分片,其缓存路径作为名称

        sizes

数字;分片的当前大小

        max_size

数字;如果配置,则最大分片大小

        cold

布尔值;在 缓存加载器 从磁盘加载数据时为 true

{
  "name_zone": {
    "shards": {
        "/path/to/shard1": {
            "size": 0,
            "cold": false
        },

        "/path/to/shard2": {
            "size": 0,
            "cold": false
        }
    }
}

limit_conn#

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;

/status/http/limit_conns/<zone>, /status/stream/limit_conns/<zone>#

每个配置了 limit_conn in httplimit_conn in stream 上下文的对象,具有以下字段:

{
  "passed": 73,
  "skipped": 0,
  "rejected": 0,
  "exhausted": 0
}

passed

数字;通过的连接总数

skipped

数字;通过零长度键或键超过255字节的连接总数

rejected

数字;超过配置限制的连接总数

exhausted

数字;由于区域存储耗尽而拒绝的连接总数

limit_req#

limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;

/status/http/limit_reqs/<zone>#

每个配置了 limit_req 的对象,具有以下字段:

{
  "passed": 54816,
  "skipped": 0,
  "delayed": 65,
  "rejected": 26,
  "exhausted": 0
}

passed

数字;通过的请求总数

skipped

数字;通过零长度键或键超过65535字节的请求总数

delayed

数字;延迟请求的总数

rejected

数字;被拒绝的请求总数

exhausted

数字;由于区域存储耗尽而拒绝的请求总数

HTTP上游#

Added in version 1.1.0.

要启用以下指标的收集, 在 upstream 上下文中设置 zone 指令, 例如:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

/status/http/upstreams/<upstream>#

其中 <upstream> 是任何通过 zone 指令指定的 upstream 的名称

{
    "peers": {
        "192.168.16.4:80": {
            "server": "backend.example.com",
            "service": "_example._tcp",
            "backup": false,
            "weight": 5,
            "state": "up",
            "selected": {
                "current": 2,
                "total": 232
            },

            "max_conns": 5,
            "responses": {
                "200": 222,
                "302": 12
            },

            "data": {
                "sent": 543866,
                "received": 27349934
            },

            "health": {
                "fails": 0,
                "unavailable": 0,
                "downtime": 0
            },

            "sid": "<server_id>"
        }
    },

    "keepalive": 2
}

peers

对象;包含上游对等体的指标作为子对象, 其名称是对等体地址的规范表示。 每个子对象的成员:

    server

字符串; server 指令的参数

    service

字符串;服务名称,如在 server 指令中指定(如果已配置)

    slow_start
    (PRO 1.4.0+)

数字;为服务器指定的 slow_start 值, 以秒为单位表示。

当通过动态配置 API 的 相应子部分 设置值时, 可以指定数字或具有毫秒精度的 时间 值。

    backup

布尔值;对于备份服务器为 true

    weight

数字;配置的 weight

    state

字符串;对等体的当前状态:

  • checking (PRO):设置为 essential,正在检查中, 仅发送 probe requests

  • down:手动禁用,不发送请求

  • draining (PRO):类似于 down, 但是来自使用 sticky 绑定的会话的请求仍然被发送

  • recovering:在故障后恢复 根据 slow_start,逐渐发送更多请求

  • unavailable:达到 max_fails 限制, 在 fail_timeout 间隔尝试客户端请求

  • unhealthy (PRO):运作不正常, 仅发送 probe requests

  • up:正常运作,请求如常发送

    selected

对象;对等体选择统计信息

        current

数字;当前连接到对等体的连接数

        total

数字;转发到对等体的请求总数

        last

字符串或数字;上次选择对等体的时间, 格式化为 date

    max_conns

数字;配置的 maximum 同时连接数(如果已指定)

    responses

对象;响应统计信息

        <code>

数字;状态 <code> 的非零响应数 (100-599)

        xxx

数字;其他状态代码的非零响应数

    data

对象;数据统计信息

        received

数字;从对等体接收到的字节总数

        sent

数字;发送到对等体的字节总数

    health

对象;健康统计信息

        fails

数字;与对等体通信的失败尝试总数

        unavailable

数字;由于达到 max_fails 限制而变为 unavailable 的次数

        downtime

数字;对等体在选择时处于 unavailable 状态的总时间(以毫秒为单位)

        downstart

字符串或数字;对等体变为 unavailable 的时间, 格式化为 date

        header_time
        (PRO 1.3.0+)

数字;从对等体接收响应头的平均时间(以毫秒为单位); 参见 response_time_factor (PRO)

        response_time
        (PRO 1.3.0+)

数字;接收整个对等体响应的平均时间(以毫秒为单位); 参见 response_time_factor (PRO)

    sid

字符串;上游组中服务器的 configured id

keepalive

数字;当前缓存的连接数

health/probes (PRO)#

在 1.2.0 版本发生变更: PRO

如果上游配置了 upstream_probe (PRO) 探针, 则 health 对象还具有一个 probes 子对象, 存储对等体的健康探针计数器, 同时对等体的 state 也可以是 checkingunhealthy, 除了上表中列出的值:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 10,
                "fails": 10,
                "last": "2025-02-13T09:56:07Z"
            }
        }
    }
}

statechecking 值不计为 downtime, 这意味着具有配置为 essential 的探针的对等体尚未被检查; unhealthy 值意味着对等体出现故障。 这两种状态也意味着对等体不包含在负载均衡中。 有关健康探针的详细信息,请参见 upstream_probe

probes 中的计数器:

count

数字;此对等体的探针总数

fails

数字;探针失败的总数

last

字符串或数字;最后一次探测时间, 格式化为 date

queue#

在 1.4.0 版本发生变更.

如果为上游配置了 request queue, 则上游对象还包含一个嵌套的 queue 对象, 其中保存了队列中请求的计数器:

{
    "queue": {
        "queued": 20112,
        "waiting": 1011,
        "dropped": 6031,
        "timedout": 560,
        "overflows": 13
    }
}

计数器值是跨所有工作进程聚合的:

queued

数字;进入队列的请求总数

waiting

数字;当前队列中的请求数

dropped

数字;由于客户端提前关闭连接而从队列中移除的请求总数

timedout

数字;由于超时而从队列中移除的请求总数

overflows

数字;队列溢出发生的总次数

流式上游#

要启用以下指标的收集, 请在 upstream 上下文中设置 zone 指令, 例如:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

/status/stream/upstreams/<upstream>#

这里,<upstream> 是配置了 zone 指令的 upstream 的名称。

{
    "peers": {
        "192.168.16.4:1935": {
            "server": "backend.example.com",
            "service": "_example._tcp",
            "backup": false,
            "weight": 5,
            "state": "up",
            "selected": {
                "current": 2,
                "total": 232
            },

            "max_conns": 5,
            "data": {
                "sent": 543866,
                "received": 27349934
            },

            "health": {
                "fails": 0,
                "unavailable": 0,
                "downtime": 0
            }
        }
    }
}

peers

对象;包含上游对等体的指标作为子对象, 其名称是对等体地址的规范表示。 每个子对象的成员:

    server

字符串;由 server 指令设置的地址

    service

字符串;如果由 server 指令设置,则为服务名称

    slow_start
    (PRO 1.4.0+)

数字;为服务器指定的 slow_start 值, 以秒为单位表示。

当通过动态配置 API 的 相应子部分 设置值时, 可以指定数字或具有毫秒精度的 时间 值。

    backup

布尔值;对于备份服务器为 true

    weight

数字;对等体的 weight

    state

字符串;对等体的当前状态:

  • up:正常运作,请求如常发送

  • down:手动禁用,不发送请求

  • draining (PRO):类似于 down, 但是来自使用 sticky 绑定的会话的请求仍然被发送

  • unavailable:达到 max_fails 限制, 在 fail_timeout 间隔尝试客户端请求

  • recovering:在故障后恢复 根据 slow_start,逐渐发送更多请求

  • checking (PRO):设置为 essential,正在检查中, 仅发送 probe requests

  • unhealthy (PRO):运作不正常, 仅发送 probe requests

    selected

对象;对等体的选择指标

        current

数字;当前连接到对等体的连接数

        total

数字;转发到对等体的总连接数

        last

字符串或数字;最后一次选择对等体的时间, 格式化为 date

    max_conns

数字; maximum 对等体的同时活动连接数(如果已设置)

    data

对象;数据传输指标

        received

数字;从对等体接收的字节总数

        sent

数字;发送到对等体的字节总数

    health

对象;对等体健康指标

        fails

数字;达到对等体的失败尝试总数

        unavailable

数字;对等体由于达到 max_fails 限制而变为 unavailable 的次数

        downtime

数字;对等体在选择中 不可用 的总时间(以毫秒为单位)

        downstart

字符串或数字;对等体最后一次变为 不可用 的时间, 按 date 格式化

        connect_time
        (PRO 1.4.0+)

数字;与对等体建立连接所需的平均时间(以毫秒为单位); 请参见 response_time_factor (PRO) 指令。

        first_byte_time
        (PRO 1.4.0+)

数字;从对等体接收响应的第一个字节所需的平均时间(以毫秒为单位); 请参见 response_time_factor (PRO) 指令。

        last_byte_time
        (PRO 1.4.0+)

数字;从对等体接收完整响应所需的平均时间(以毫秒为单位); 请参见 response_time_factor (PRO) 指令。

在 1.4.0 版本发生变更: PRO

在 Angie PRO 中,如果上游配置了 upstream_probe (PRO) 探测, 则 health 对象还具有一个 probes 子对象, 用于存储对等体的健康探测计数器, 同时,对等体的 state 也可以是 checkingunhealthy, 除了上表中列出的值:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 2,
                "fails": 2,
                "last": "2025-02-13T11:03:54Z"
            }
        }
    }
}

statechecking 值不算作 downtime 这意味着配置为 essential 的对等体尚未被检查; 而 unhealthy 值表示对等体发生故障。 这两种状态还意味着对等体不包括在负载均衡中。 有关健康探测的详细信息,请参见 upstream_probe

probes 中的计数器:

count

数字;此对等体的总探测次数

fails

数字;总失败探测次数

last

字符串或数字;最后探测时间, 按 date 格式化

动态配置 API(仅 PRO)#

Added in version 1.2.0.

该 API 包含一个 /config 部分,允许以 JSON 格式动态更新 Angie 的配置,使用 PUTPATCHDELETE HTTP 请求。 所有更新都是原子的;新设置要么作为整体应用, 要么根本不应用。 在发生错误时,Angie 会报告原因。

/config 的子部分#

目前,针对上游中各个服务器的配置在 /config 部分可用, 适用于 HTTPstream 模块;可动态配置的设置数量 正在逐步增加。

/config/http/upstreams/<upstream>/servers/<name>#

允许配置单个上游对等体, 包括删除现有对等体或添加新对等体。

URI 路径参数:

<upstream>

上游的名称;要通过 /config 进行配置,必须 配置一个 zone 指令,以定义一个共享 内存区域。

<name>

对等体在上游中的名称,定义为 <service>@<host>,其中:

  • <service>@ 是可选的服务名称,用于 SRV 记录解析。

  • <host> 是服务的域名(如果存在 resolve) 或其 IP;此处可以定义一个可选端口。

例如,以下配置:

upstream backend {
    server backend.example.com service=_http._tcp resolve;
    server 127.0.0.1;
    zone backend 1m;
}

允许以下对等体名称:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/

该 API 子部分允许设置 weightmax_connsmax_failsfail_timeoutbackupdownsid 参数,如 server 中所述。

备注

此处没有单独的 drain 选项; 要启用 drain, 将 down 设置为字符串值 drain

$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down

示例:

curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": true,
    "down": false,
    "sid": ""
}

实际上可用的参数仅限于当前负载均衡方法支持的参数 的 upstream。 因此,如果上游配置为 random

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

您将无法添加定义 backup 的新对等体:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com
{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

备注

即使使用兼容的负载均衡方法,backup 参数 只能在新对等体创建时设置。

/config/stream/upstreams/<upstream>/servers/<name>#

允许配置单个上游对等体, 包括删除现有对等体或添加新对等体。

URI 路径参数:

<upstream>

上游的名称;要通过 /config 进行配置,必须 配置一个 zone 指令,以定义一个共享 内存区域。

<name>

对等体在上游中的名称,定义为 <service>@<host>,其中:

  • <service>@ 是可选的服务名称,用于 SRV 记录解析。

  • <host> 是服务的域名(如果存在 resolve) 或其 IP;此处可以定义一个可选端口。

例如,以下配置:

upstream backend {
    server backend.example.com:8080 service=_example._tcp resolve;
    server 127.0.0.1:12345;
    zone backend 1m;
}

允许以下对等体名称:

$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/

该 API 子部分允许设置 weightmax_connsmax_failsfail_timeoutbackupdown 参数,如 server 中所述。

备注

此处没有单独的 drain 选项; 要启用 drain, 将 down 设置为字符串值 drain

$ curl -X PUT -d \"drain\" \
  http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down

示例:

curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": true,
    "down": false,
}

实际上可用的参数仅限于当前负载均衡方法支持的参数 的 upstream。 因此,如果上游配置为 random

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

您将无法添加定义 backup 的新对等体:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com
{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

备注

即使使用兼容的负载均衡方法,backup 参数 只能在新对等体创建时设置。

在删除服务器时,您可以设置 connection_drop=<value> 参数 (PRO)以覆盖 proxy_connection_drop 设置:

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000

HTTP 方法#

让我们考虑适用于此部分的所有 HTTP 方法的语义, 给定以下上游配置:

http {
    # ...

    upstream backend {
        zone upstream 256k;
        server backend.example.com resolve max_conns=5;
        # ...
    }

    server {
        # ...

        location /config/ {
            api /config/;

            allow 127.0.0.1;
            deny all;
        }
    }
}

GET#

GET HTTP 方法在 /config 中的任何现有路径查询实体, 就像它对其他 API 部分所做的那样。

例如, /config/http/upstreams/backend/servers/ 上游服务器分支允许这些查询:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config

您可以使用 defaults=on 获取默认参数值:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on
{
    "backend.example.com": {
        "weight": 1,
        "max_conns": 5,
        "max_fails": 1,
        "fail_timeout": 10,
        "backup": false,
        "down": false,
        "sid": ""
    }
}

PUT#

PUT HTTP 方法在指定路径创建一个新的 JSON 实体 或 完全 替换一个现有实体。

例如,要设置 backend.example.com 服务器在 backend 上游中 早先未指定的 max_fails 参数:

$ curl -X PUT -d '2' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
{
    "success": "更新成功",
    "description": "现有的配置 API 实体 \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" 已被替换更新。"
}

验证更改:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
    "max_conns": 5,
    "max_fails": 2
}

删除#

DELETE HTTP 方法删除指定路径下的 先前定义 设置; 在执行此操作时,如果有任何默认值,则会返回到默认值。

例如,要删除 backend 上游中 backend.example.com 服务器的先前设置的 max_fails 参数:

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
{
    "success": "重置成功",
    "description": "配置 API 实体 \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" 已重置为默认值。"
}

使用 defaults=on 验证更改:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
{
    "weight": 1,
    "max_conns": 5,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": false,
    "down": false,
    "sid": ""
}

max_fails 设置已恢复为默认值。

在删除服务器时,您可以设置 connection_drop=<value> 参数 (PRO)以覆盖 proxy_connection_dropgrpc_connection_dropfastcgi_connection_dropscgi_connection_dropuwsgi_connection_drop 设置:

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000

补丁#

PATCH HTTP 方法在指定路径下创建一个新实体 或部分替换或补充现有的实体 (RFC 7386) 通过在其有效负载中提供 JSON 定义。

该方法的操作如下:如果新定义中的实体 在配置中存在,则它们会被覆盖;否则,它们将被添加。

例如,要更改 backend 上游中 backend.example.com 服务器的 down 设置, 同时保持其他设置不变:

$ curl -X PATCH -d '{ "down": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
    "success": "更新成功",
    "description": "现有的配置 API 实体 \"/config/http/upstreams/backend/servers/backend.example.com\" 已合并更新。"
}

验证更改:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
    "max_conns": 5,
    "down": true
}

PUT 不同,随 PATCH 请求提供的 JSON 对象 已与 现有对象合并,而不是覆盖它。

null 值是一个特殊情况;它们用于 删除 在这种合并过程中 的特定配置项目。

备注

此删除与 DELETE 相同; 特别是,它会恢复默认值。

例如,要删除之前添加的 down 设置 并同时更新 max_conns

$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
    "success": "更新成功",
    "description": "现有的配置 API 实体 \"/config/http/upstreams/backend/servers/backend.example.com\" 已合并更新。"
}

验证更改:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
{
    "max_conns": 6
}

提供了 nulldown 参数被删除; max_conns 被更新。