API#

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

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

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

在Angie PRO中，此接口包含一个:ref:动态配置 <api_config> 部分，允许在不重新加载配置或重启的情况下更改设置；目前，可以配置:ref:u_upstream 中的单个服务器。

指令#

api#

语法

api path;

默认

—

上下文

location

在 location 中启用HTTP RESTful接口。

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

如果在前缀 location 中指定：

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

与前缀 /stats/ 匹配的请求URI部分将被 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_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.1",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-07-17T12: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.1",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-07-17T12: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.1",
    "build_time": "2025-07-17T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-07-17T16: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 服务器和位置#

第二个文件内容： .. code-block:: console

/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

布尔值；当 缓存加载器 从磁盘加载数据时为 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

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

    bytes_written

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

Added in version 1.2.0: PRO

在 Angie PRO 中，如果通过 proxy_cache_path 指令启用了 缓存分片， 各个分片作为 shards 对象的对象成员公开：

shards

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

    <shard>

对象；表示一个单独的分片，以其缓存路径为名称

size

数字；分片的当前大小

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>#

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

{
  "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

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

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

数字；配置的 权重

    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-07-17T09: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

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

流上游#

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

数字；对等节点的 权重

    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

(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) 指令。

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-07-17T11:03:54Z"
            }
        }
    }
}

state 的 checking 值表示配置为 essential 的对等节点尚未被检查； unhealthy 值表示对等节点运行不正常。 这两种状态也意味着对等节点不包括在负载均衡中。 有关健康探测的详细信息，请参见 upstream_probe。

probes 中的计数器：

count

数字；此对等节点的总探测次数

fails

数字；总失败探测次数

last

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

动态配置API（仅PRO版）#

Added in version 1.2.0: 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）参数；要启用 :samp:`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>

指定 <upstream> 中特定服务器的名称；以 <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 子部分允许设置 server 部分中描述的 weight、max_conns、max_fails、fail_timeout、backup 和 down 参数。

备注

没有单独的 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 被更新。