API#

API 模块实现了一个 HTTP RESTful 接口,用于以 JSON 格式获取 Web 服务器的基本信息,以及关于客户端连接、共享内存区域、DNS 查询、HTTP 请求、HTTP 响应缓存、stream 模块会话,以及 limit_conn http、limit_conn stream、limit_req 和 http upstream 模块区域的 统计信息。

该接口接受 GET 和 HEAD HTTP 方法; 使用其他方法的请求将导致错误:

{
    "error": "MethodNotAllowed",
    "description": "The POST method is not allowed for the requested API element \"/\"."
}

在 Angie PRO 中,此接口包含一个 动态配置 部分,允许在不重新加载配置或重启的情况下更改设置;目前,可以配置 upstream 中的各个服务器。

指令#

api#

语法

api path;

默认值

—

上下文

location

在 location 中启用 HTTP RESTful 接口。

path 参数是必需的。与 alias 指令类似,它设置用于替换 location 中指定路径的路径,但是是在 API 树上而不是文件系统上。

如果在前缀 location 中指定:

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

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

允许使用变量:api /status/$module/server_zones/$name/ 以及在正则表达式 location 中使用:

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

这里 path 参数定义了 API 元素的完整路径; 因此,从对 /api/location/data/ 的请求中将提取以下变量:

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

最终请求将是 /status/http/location_zones/data/。

备注

在 Angie PRO 中,您可以分离 动态配置 API 和反映当前状态的不可变 状态 API:

location /config/ {
    api /config/;
}

location /status/ {
    api /status/;
}

path 参数还允许控制 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 放置在前缀带有尾部斜杠的 location 中(例如,:samp:location /name/),并且 auto_redirect 指令设置为 default,则不带尾部斜杠的请求将被重定向(/name -> /name/)。

api_config_files#

语法

api_config_files on | off;

默认值

off

上下文

location

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

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

对 /status/angie/ 的请求返回大致如下内容:

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

默认情况下,输出被禁用,因为配置文件可能包含特别敏感的机密信息。

指标#

Angie 在 /status/ API 部分发布使用统计信息；您可以通过设置适当的 location 来开放访问权限。完全访问：

location /status/ {
    api /status/;
}

部分访问的示例，如上所示：

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

配置示例#

配置包含 location /status/、resolver、upstream 中的 http、http server、location、cache、http 中的 limit_conn 和 limit_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;
        proxy_cache_valid 200 10m;

        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/，Angie 返回：

JSON 树
{
    "angie": {
        "version":"1.10.3",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-11-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 格式字符串表示日期； 如需使用整数 UNIX 纪元格式， 请在查询字符串中添加 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.10.3",
    "build_time": "2025-11-13T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-11-13T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

version

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

build

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

build_time

字符串;Angie 可执行文件的构建时间, 采用 日期 格式

address

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

generation

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

load_time

字符串;上次配置重新加载的时间, 采用 日期 格式; 字符串值具有毫秒分辨率

config_files

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

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

警告

config_files 对象仅在启用 api_config_files 指令时才在 /status/angie/ 中可用。

连接#

/status/connections#

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

accepted

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

dropped

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

active

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

idle

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

使用 slab 分配的共享内存区#

/status/slabs/<zone>#

使用 slab 分配 的共享内存区的使用统计信息,例如 limit_conn、limit_req 和 HTTP 缓存:

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;
proxy_cache_valid 200 10m;

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

pages

对象;内存页统计信息

    used

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

    free

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

slots

对象;每个槽大小的内存槽统计信息。slots 对象包含内存槽大小的数据(8、16、32 等,最大为页面大小的一半字节数)

    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 参数 (HTTP 或 Stream):

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 1035 的 4.1.1 节中描述。

各种 DNS 记录类型在 RFC 1035、 RFC 2782 和 RFC 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 指标，请在 location 或 if 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
  }
}

Stream 服务器#

/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

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

    passed

数字; 通过 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;
proxy_cache_valid 200 10m;

/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

布尔值; 当 cache loader 从磁盘加载数据时为 true

hit

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

    responses

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

    bytes

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

stale

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

    responses

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

    bytes

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

updating

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

    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

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

ua0:samp:bytes_written

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

在 Angie PRO 中,如果使用 proxy_cache_path 指令启用了 cache sharding, 各个分片将作为 shards 对象的对象成员公开:

shards

对象; 将各个分片列为成员

    <shard>

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

        size

数字; 分片的当前大小

        max_size

数字; 最大分片大小(如果已配置)

        cold

布尔值; 当 cache loader 从磁盘加载数据时为 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>#

每个配置的 http 中的 limit_conn 或 stream 中的 limit_conn 上下文的对象，包含以下字段：

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

passed

数字；通过的连接总数

    handshaked

数字；成功 SSL 握手的总次数

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

数字；使用零长度键或键超过 255 字节而通过的请求总数

delayed

数字；延迟的请求总数

rejected

数字；拒绝的请求总数

exhausted

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

HTTP 上游#

要启用以下指标的收集， 请在 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

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

通过动态配置 API 的 相应子节 设置值时， 您可以指定秒数 或具有毫秒精度的 时间 值。

    backup

布尔值；备份服务器为 true

    weight

数字；配置的 权重

    state

字符串；节点的当前状态以及发送给它的请求：

  • busy：表示发送到服务器的请求数量 已达到 max_conns 设置的限制， 不再向其发送新请求；

  • down：手动禁用，不发送请求；

  • recovering：根据 slow_start 从故障中恢复， 随着时间推移发送越来越多的请求；

  • unavailable：达到 max_fails 限制， 仅在 fail_timeout 定义的间隔内 发送试探性客户端请求；

  • up：正常运行，正常发送请求；

Angie PRO 中的附加状态：

  • checking：配置为 essential 并正在检查中， 仅发送 探测请求；

  • draining：类似于 down， 但来自先前绑定会话的请求 （通过 sticky）仍会发送；

  • unhealthy：不可操作， 仅发送 探测请求。

    selected

对象；节点选择统计信息

        current

数字；当前到节点的连接数

        total

数字；转发到节点的请求总数

        last

字符串或数字；节点最后被选择的时间， 格式为 日期

    max_conns

数字；配置的到节点的同时活动连接的 最大 数量（如果指定）

    responses

对象；响应统计信息

        <code>

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

        xxx

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

    data

对象；数据统计信息

        received

数字；从节点接收的字节总数

        sent

数字；发送到节点的字节总数

    health

对象；健康统计信息

        fails

数字；与节点通信失败的尝试总数

        unavailable

数字；由于达到 max_fails 限制而导致节点变为 unavailable 的次数

        downtime

数字；节点 unavailable 无法选择的总时间（以毫秒为单位）

        downstart

字符串或数字；节点变为 unavailable 的时间， 格式为 日期

        header_time

(PRO 1.3.0+)

数字；从服务器接收响应头的平均时间（以毫秒为单位）； 参见 response_time_factor (PRO)

        response_time

(PRO 1.3.0+)

数字；从服务器接收完整响应的平均时间（以毫秒为单位）； 参见 response_time_factor (PRO)

    sid

字符串；上游组中服务器的 配置 id

keepalive

数字；当前缓存连接数

backup_switch

对象；包含活动备份逻辑的当前状态， 如果为上游配置了 backup_switch (PRO) 则存在

    active

数字；当前用于负载均衡请求的活动组级别。 如果活动组是主组，则值为 0

    timeout

数字；剩余等待时间（以毫秒为单位）， 之后负载均衡器将重新检查较低级别组中的健康节点， 从主组开始，而不检查较高级别的组； 主组（级别 0）不显示

health/probes (PRO)#

在 1.2.0 版本发生变更: PRO

如果上游配置了 upstream_probe (PRO) 探测， health 对象还有一个 probes 子对象 用于存储服务器的健康探测计数器， 而 state 除了上表中列出的值外， 还可以是 checking 和 unhealthy：

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

state 的 checking 值不计入 downtime， 表示配置了 essential 探测的服务器尚未被检查； unhealthy 值表示服务器出现故障。 这两种状态都意味着服务器不包含在负载均衡中。 有关健康探测的详细信息，请参见 upstream_probe。

probes 中的计数器：

count

数字；此服务器的探测总数

fails

数字；失败探测总数

last

字符串或数字；最后探测时间， 格式为 日期

queue (PRO)#

在 1.4.0 版本发生变更: PRO

如果为上游配置了 请求队列， 上游对象还包含一个嵌套的 queue 对象， 其中包含请求队列计数器：

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

计数器值在所有工作进程中求和：

queued

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

waiting

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

dropped

数字；因客户端过早关闭连接而从队列中移除的请求总数

timedout

数字；因超时而从队列中移除的请求总数

overflows

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

Stream 上游#

要启用以下指标的收集， 请在 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

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

通过动态配置 API 的 相应子节 设置该值时， 您可以指定秒数 或具有毫秒精度的 时间 值。

    backup

布尔值；备份服务器为 true

    weight

数字；为对等节点设置的 权重

    state

字符串；对等节点的当前状态以及发送给它的请求：

  • busy：表示发送到服务器的请求数 已达到 max_conns 设置的限制， 不再向其发送新请求

  • down：手动禁用，不发送请求

  • recovering：根据 slow_start 从故障中恢复， 随着时间推移发送越来越多的请求

  • unavailable：达到 max_fails 限制， 仅以 fail_timeout 定义的间隔发送试探性客户端请求

  • up：正常运行，照常发送请求

Angie PRO 中的附加状态：

  • checking：配置为 essential 并正在检查中， 仅发送 探测请求

  • draining：类似于 down， 但来自先前绑定会话的请求 （通过 sticky）仍会发送

  • unhealthy：不可用， 仅发送 探测请求

    selected

对象；选择此对等节点进行连接的统计信息

        current

数字；当前到对等节点的连接数

        total

数字；转发到对等节点的连接总数

        last

字符串或数字；上次选择对等节点的时间， 格式为 日期

    max_conns

数字；到对等节点的同时活动连接的 最大 数量（如果已设置）

    data

对象；数据传输统计信息

        received

数字；从对等节点接收的总字节数

        sent

数字；发送到对等节点的总字节数

    health

对象；对等节点健康统计信息

        fails

数字；尝试到达对等节点失败的总次数

        unavailable

数字；由于达到 max_fails 值，对等节点变为 unavailable 的次数

        downtime

数字；对等节点处于 unavailable 状态（无法被选择）的总时间（以毫秒为单位）

        downstart

字符串或数字；对等节点上次变为 unavailable 的时间， 格式为 日期

        connect_time

数字；与服务器建立连接的平均时间（以毫秒为单位）； 参见 response_time_factor (PRO) 指令

        first_byte_time

数字；从服务器接收第一个字节的平均时间（以毫秒为单位）； 参见 response_time_factor (PRO) 指令

        last_byte_time

数字；从服务器接收完整响应的平均时间（以毫秒为单位）； 参见 response_time_factor (PRO) 指令

backup_switch (PRO 1.10.0+)

对象；包含活动备份逻辑的当前状态， 如果为上游配置了 backup_switch (PRO) 则显示

    active

数字；当前用于负载均衡的活动组的级别。 如果活动组是主组，则值为 0

    timeout

数字；剩余等待时间（以毫秒为单位）， 之后负载均衡器将重新检查较低级别组中的健康节点， 从主组开始， 而不检查较高级别的组； 主组（级别 0）不显示

在 1.4.0 版本发生变更: PRO

在 Angie PRO 中，如果上游配置了 upstream_probe (PRO) 探测， health 对象还包含一个 probes 子对象， 用于存储服务器的健康探测计数器， 而 state 除了上表中列出的值外， 还可以是 checking 和 unhealthy：

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

state 的 checking 值表示配置了 essential 参数探测的服务器尚未被检查； unhealthy 值表示服务器不可用。 这两种状态还意味着服务器不包含在负载均衡中。 有关健康探测的详细信息，请参见 upstream_probe。

probes 中的计数器：

count

数字；此服务器的探测总数

fails

数字；失败的探测数

last

字符串或数字；上次探测时间， 格式为 日期

动态配置 API (PRO)#

该 API 包含一个 /config 节，可通过 PUT、PATCH 和 DELETE HTTP 请求 以 JSON 格式动态更新 Angie 的配置。 所有更新都是原子性的：新设置作为一个整体应用， 或者完全不应用。 出错时，Angie 会报告原因。

/config 的子节#

目前，/config 节中可用于 HTTP 和 stream 模块的上游内各个服务器的配置； 可进行动态配置的设置数量正在稳步增加。

/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 子部分允许设置 weight、max_conns、 max_fails、fail_timeout、backup、down 和 sid 参数，如 server 中所述。

备注

这里没有单独的 drain （PRO）参数； 要启用 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>

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 子部分允许设置 weight、 max_conns、max_fails、fail_timeout、backup 和 down 参数，如 server 中所述。

备注

这里没有单独的 drain （PRO）参数； 要启用 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 上游中的 backend.example.com 服务器 添加之前未指定的 max_fails 参数：

$ curl -X PUT -d '2' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}

验证更改：

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

{
    "max_conns": 5,
    "max_fails": 2
}

DELETE#

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": "Reset",
    "description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}

使用 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_drop、grpc_connection_drop、 fastcgi_connection_drop、scgi_connection_drop 和 uwsgi_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#

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": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

验证更改：

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

{
    "max_conns": 5,
    "down": true
}

请注意，随 PATCH 请求提供的 JSON 对象*被合并*到现有对象中， 而不是像 PUT 那样完全替换它。

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": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

验证更改：

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

{
    "max_conns": 6
}

提供了 null 值的 down 参数已被删除； max_conns 值已更新。