API#

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

API 接受 GET 和 HEAD HTTP 请求；其他请求方法将导致错误：

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

Angie PRO API 具有动态配置功能，允许在不重新加载配置或重启 Angie 的情况下更新设置；目前，它支持配置上游中的各个后端节点。

指令#

api#

语法	`api` path;
默认值	—
上下文	location

在 location 中启用 HTTP RESTful 接口。

path 参数是必需的，类似于 alias 指令，但它作用于 API 树，而不是文件系统层级。

当在前缀位置指定时：

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

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

还可以使用变量：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/"

经过插值后，生成的 API 请求路径为 /status/http/location_zones/bar/data。

备注

在 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.7.0",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2024-09-19T12: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/、resolver、http upstream、http server、location、cache、limit_conn (在 http 中）和 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;

        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 树

{
    "angie": {
        "version":"1.7.0",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2024-09-19T12: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 字符串表示日期值；要改用整数的 epoch 格式，可以在查询字符串中添加 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.7.0",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2024-09-19T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

`version`	字符串；当前运行的 Angie Web 服务器版本
`build`	字符串；在编译时指定的特定构建名称
`address`	字符串；接受 API 请求的服务器地址
`generation`	数字；自上次启动以来配置重载的总次数
`load_time`	字符串或数字；上次配置重载的时间，格式为日期；字符串具有毫秒分辨率
`config_files`	对象；其成员是当前服务器实例加载的所有 Angie 配置文件的绝对路径，它们的值是文件内容的字符串表示，例如： { "/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n" } 小心仅当启用了 api_config_files 指令时，`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;

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

`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;
}

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

`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;
    }
}

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

`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;
}

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

`ssl`	对象；SSL 统计信息。仅在 `server` 设置了 `listen ssl;` 时显示
`handshaked`	数字；成功的 SSL 握手总次数
`reuses`	数字；SSL 握手期间会话重用的总次数
`timedout`	数字；SSL 握手超时的总次数
`failed`	数字；SSL 握手失败的总次数
`connections`	对象；连接统计信息
`total`	数字；客户端连接的总次数
`processing`	数字；当前正在处理的客户端连接数
`discarded`	数字；未创建会话而完成的客户端连接总数
`relayed`	数字；使用 `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 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>`	对象；表示一个分片，其名称为缓存路径
`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>`#

为每个配置在 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`	数字；因键长度为零或超过 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`	数字；配置的权重
`state`	字符串；当前节点状态： `checking` (PRO)：设置为 `essential`，当前正在检查，仅发送探测请求 `down`：手动禁用，不发送请求 `draining` (PRO)：类似于 `down`，但通过 sticky 绑定的会话请求仍然会被发送 `recovering`：故障恢复中，遵循 slow_start，逐步增加请求数 `unavailable`：达到 max_fails 限制，在 fail_timeout 间隔重试 `unhealthy` (PRO)：节点未正常运行，仅发送探测请求 `up`：正常运行，请求正常发送
`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`	数字；当前缓存的连接数

`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": "2024-09-19T09:56:07Z"
            }
        }
    }
}

state 的 checking 值不会计为 downtime，表示配置为 essential 的探测节点尚未被检查； unhealthy 值表示节点运行异常。这两个状态都意味着该节点不会参与负载均衡。有关健康探测的详细信息，请参阅上游探测。

probes 中的计数器：

`count`	数字；此节点的总探测次数
`fails`	数字；失败的探测总次数
`last`	字符串或数字；上次探测时间，格式为日期

`queue`#

在 1.4.0 版本发生变更.

如果为上游配置了请求队列，上游对象还将包含一个嵌套的 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 指令配置的上游的名称。

{
    "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`	字符串；节点的当前状态： `up`：正常运行，请求正常发送 `down`：手动禁用，不发送请求 `draining` (PRO)：类似于 `down`，但通过 sticky 绑定的会话请求仍然发送 `unavailable`：达到 max_fails 限制，在 fail_timeout 间隔尝试重试 `recovering`：故障恢复中，遵循 slow_start，逐步增加请求数 `checking` (PRO)：设置为 `essential`，当前正在检查，仅发送探测请求 `unhealthy` (PRO)：节点运行异常，仅发送探测请求
`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) 指令。

在 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": "2024-09-19T11:03:54Z"
            }
        }
    }
}

state 的 checking 值不会计为 downtime，表示配置为 essential 的探测节点尚未被检查； unhealthy 值表示节点运行异常。这两个状态都意味着节点不会参与负载均衡。有关健康探测的详细信息，请参阅上游探测。

probes 中的计数器：

`count`	数字；此节点的总探测次数
`fails`	数字；失败的探测总次数
`last`	字符串或数字；上次探测时间，格式为日期

动态配置 API（仅限 PRO）#

Added in version 1.2.0.

API 包括一个 /config 部分，允许通过 JSON 进行动态更新 Angie 配置，支持 PUT、PATCH 和 DELETE HTTP 请求。所有更新都是原子性的；新设置要么整体应用，要么完全不应用。发生错误时，Angie 会报告原因。

`/config` 的子部分#

目前，HTTP 和 Stream 模块中的上游服务器配置可通过 /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:8080 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:8080/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1/

此 API 子部分允许设置 weight、max_conns、max_fails、 fail_timeout、backup、down 和 sid 参数，具体说明见 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": ""
}

实际可用的参数受当前上游的负载均衡方法限制。例如，如果上游配置为 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 参数也只能在新节点创建时设置。

删除服务器时，可以使用 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

`/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 子部分允许设置 weight、max_conns、 max_fails、fail_timeout、backup 和 down 参数，具体说明见 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
}

实际可用的参数受当前上游的负载均衡方法限制。例如，如果上游配置为 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 设置已恢复为默认值。

PATCH#

PATCH HTTP 方法在指定路径创建新实体，或通过提供 JSON 定义来部分替换或补充现有实体（参见 RFC 7386）。

该方法的操作方式如下：如果新定义中的实体存在于配置中，它们将被覆盖；否则，将添加新值。

例如，更改 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 已更新。

API#

指令#

api#

api_config_files#

指标#

示例配置#

服务器状态#

/status/angie#

连接全局指标#

/status/connections#

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

/status/slabs/<zone>#

解析器 DNS 查询#

/status/resolvers/<zone>#

HTTP 服务器和位置#

/status/http/server_zones/<zone>#

/status/http/location_zones/<zone>#

流服务器#

/status/stream/server_zones/<zone>#

HTTP 缓存#

/status/http/caches/<cache>#

limit_conn#

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

limit_req#

/status/http/limit_reqs/<zone>#

HTTP 上游#

/status/http/upstreams/<upstream>#

health/probes (PRO)#

queue#

流上游#

/status/stream/upstreams/<upstream>#

动态配置 API（仅限 PRO）#

/config 的子部分#

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

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

HTTP 方法#

GET#

PUT#

DELETE#

PATCH#

`/status/angie`#

`/status/connections`#

`/status/slabs/<zone>`#

`/status/resolvers/<zone>`#

`/status/http/server_zones/<zone>`#

`/status/http/location_zones/<zone>`#

`/status/stream/server_zones/<zone>`#

`/status/http/caches/<cache>`#

`/status/http/limit_conns/<zone>`，`/status/stream/limit_conns/<zone>`#

`/status/http/limit_reqs/<zone>`#

`/status/http/upstreams/<upstream>`#

`health/probes` (PRO)#

`queue`#

`/status/stream/upstreams/<upstream>`#

`/config` 的子部分#

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

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