# https://cn.angie.software/index.md # 欢迎！ [所有新闻](https://cn.angie.software/news/) * [Angie 和 Angie PRO 更新至 1.11.6 版本](https://cn.angie.software/news/releases/angie-1-11-6/) - Angie 和 Angie PRO 1.11.6 修复版本已发布，移植了前一日在 nginx 中发现的 rewrite 指令漏洞 CVE-2026-9256 的修复。 (25.05.2026) * [Angie 和 Angie PRO 更新至 1.11.5 版本](https://cn.angie.software/news/releases/angie-1-11-5/) - Angie 和 Angie PRO 1.11.5 修复版本已发布，移植了 nginx 中发现的五个漏洞的修复。这些漏洞涉及 rewrite、ssl_ocsp、scgi_pass、uwsgi_pass 和 charset_map 指令的工作，以及 HTTP/3 协议请求的处理。 (15.05.2026) Angie Software（Web Server, LLC）是一家俄罗斯IT公司，专注于开发高负载系统解决方案。 我们的产品包括：负载均衡系统 [Angie ADC](https://cn.angie.software//adc/index.md) （应用交付控制器）、Web服务器 [Angie PRO](https://cn.angie.software//angie/pro/index.md) 以及 [Angie Ingress Controller (ANIC)](https://cn.angie.software//anic/index.md) ，这是一个用于管理Kubernetes中容器化应用流量的解决方案。 我们特别引以为傲的是 [开源Web服务器Angie](https://cn.angie.software//angie/index.md) ，它是nginx的一个分支，旨在超越原有的功能。 ## 为什么选择我们的解决方案？ 我们团队的核心成员是曾在全球知名的Web服务器和负载均衡市场领导者NGINX工作过的专业人士，并且曾在F5 Networks担任高级工程职位。我们定期在国际行业会议上发表演讲，拥有独特的能力，自2011年以来一直是nginx Web服务器的主要开发者。 我们的产品基于nginx技术，这些技术在安全性、容错性和高负载下的可扩展性方面表现优异。向后兼容性使您能够使用我们的解决方案而无需额外的实施和员工再培训成本。作为原始作者和开发者，我们对我们的产品有深入的理解，能够解决最复杂的问题。 除了具有扩展功能的商业产品外，我们还开发全球水平的开源产品。我们的Angie项目在自由BSD许可证下进一步开发nginx，旨在超越其能力并完全取代它。围绕Angie已经形成了一个紧密的社区，定期发布新功能和高质量标准吸引了越来越多来自世界各地的用户。 我们团队的工程师为全球最大的公司提供支持，包括《财富》500强企业。他们因其工作多次获得国际知名奖项，如2016年销售和客户服务银奖斯蒂维奖和2017年销售和客户服务金奖斯蒂维奖。 我们正式「开箱即用」支持中国的 NTLS 加密标准，并使用 TongSuo TLS 库。这意味着完全兼容性和由 TongSuo 开发者官方推荐的可靠数据保护方案。此解决方案更适合亚洲市场，有助于加强技术合作与睦邻友好关系。 # https://cn.angie.software/404.md # 页面未找到 该页面可能已被移动或删除，或者URL中可能存在拼写错误。 返回 [首页](/) 重新开始，尝试使用 [短链接](https://angie.ws/en/)，或使用 [搜索功能](/search/)。 如果您认为这是一个错误，请通过 [社区论坛](https://forum.angie.support/) 或 [Telegram频道](https://t.me/angie_support) 与我们联系。 # https://cn.angie.software/500.md # 服务器错误 服务器发生了意外错误。请稍候，我们将尽快修复。 [返回首页](https://cn.angie.software//index.md) # https://cn.angie.software/vacancies/UX-UI-designer.md # UX/UI 设计师（Angie ADC） 我们是 Angie Software 团队。公司的核心成员是参与了 nginx 早期开发的资深工程师，他们如今正在打造 nginx 的演进继任者——Angie。我们的产品已经在全球范围内获得越来越多的认可，我们也为自己设定了一个雄心勃勃的目标：超越 F5、Citrix、Radware 这样的行业巨头。 Angie ADC 是一款现代的企业级应用交付控制器。它负责流量路由、负载均衡、SSL 卸载和安全防护——确保应用程序在复杂网络环境中稳定运行所需的一切。我们坚信，制胜的关键不仅在于"引擎"的技术卓越，还在于对市场需求的深刻理解——正是这种理解将复杂的事物转化为真正受欢迎的产品。 我们的文化是非正式的、扁平的：大家平等交流，没有官僚作风，也没有多余的繁文缛节。决策迅速做出，论据比头衔更重要。 ## 您将做什么： - 全面重新思考并发展 Angie ADC 的 UX/UI，把复杂的网络概念（负载均衡、拓扑、安全策略）转化为工程师能直观理解、并且赏心悦目的界面； - 设计用户场景、制作原型和详细的设计稿，开发 UI 组件、图标和规范，构建产品的视觉语言； - 进行可用性测试、用户需求研究，并分析反馈，让我们基于数据而不是猜想去验证假设、持续改善体验； - 与研发团队和技术产品负责人紧密协作：在技术可实现性、商业价值和理想用户体验之间共同寻找平衡。 ## 我们想招的人： - 相信 UX 是战略和竞争优势，而不仅仅是"好看的按钮"； - 拥有 3 年以上 UX/UI 经验，并有为复杂基础设施或 enterprise 产品做设计的经历； - 具备系统思维，能把技术上复杂的领域拆解为清晰的模式和场景，而不是简单跟风； - 熟练使用 Figma 等工具，但更擅长用户调研方法和数据分析，以便向任何受众论证自己的设计决策； - 具备技术背景，或者足够强的好奇心，能快速钻研网络相关细节，与开发人员同频对话； - 希望打造一款被业内顶尖公司工程师使用的产品。 ## 我们提供： - 真正影响一款世界级产品的机会，看到您的决策落地，而不必承受大公司的惯性； - 在一支业内公认的专家团队中工作，团队重视专业能力、主动性和担当； - 扁平结构，您的声音真正被重视，官僚作风不复存在； - 有竞争力的薪资、补充医疗保险、报销培训和会议费用——我们支持您的职业成长； - 已认证的 IT 企业资质和透明的工作条件。 **工作形式：** 混合办公或全坐班（可商议），萨维奥洛夫斯卡娅（Савёловская）地铁站，Factoria 商务中心。 如果您感兴趣，请将英文简历发送至 [hr@wbsrv.ru](mailto:hr@wbsrv.ru)。 #### NOTE 我们仅接受英文简历，请用英文提交您的简历。 # https://cn.angie.software/angie/docs/configuration/acme.md # ACME 配置 Angie 中的 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 模块使用 [ACME 协议](https://datatracker.ietf.org/doc/html/rfc8555) 实现自动证书获取。ACME 协议支持 多种域名验证方法(也称为"验证");本模块实现了 [HTTP 验证](#acme-config-http)、 [DNS 验证](#acme-config-dns)、[ALPN 验证](#acme-config-alpn) 以及通过自定义外部服务进行的 [基于钩子的验证](#acme-config-hooks)。 ## 配置步骤 在配置中启用证书请求的常规步骤: - **配置 ACME 客户端**:在 `http` 块中使用 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) 指令, 指定唯一的客户端名称和其他参数。可以配置多个 ACME 客户端。 - **指定请求证书的域名**:将为所有 `server` 块中 [server_name](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-name) 指令列出的所有域名颁发单个证书,这些块使用指向同一 ACME 客户端的 [acme](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) 指令。 - **设置请求处理和 ACME 回调**:这是验证域名所有权所必需的。设置取决于所选的域名验证方法: | 方法 | 用户要求 | 多域名 | 通配符域名 | |------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------|---------| | [HTTP 验证](#acme-config-http) | 在 Angie 服务器上开放端口 80(或 [acme_http_port](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) 中指定的端口)
以接受传入连接。 | ✔ | | | [DNS 验证](#acme-config-dns) | 在 Angie 服务器上开放端口 53(或 [acme_dns_port](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) 中指定的端口)
以接受传入连接。

为 `_acme-challenge.` 子域设置 NS 记录,
指向您的 Angie 服务器。 | ✔ | ✔ | | [ALPN 验证](#acme-config-alpn) | 在 Angie 服务器上开放端口 443(或您的服务器使用的 TLS 端口)
以接受传入连接。 | ✔ | | | [钩子验证](#acme-config-hooks) | 创建一个外部服务(脚本或应用程序),
可以根据 Angie 的请求更新 DNS 记录
或通过 Web 服务器提供特殊响应。 | ✔ | ✔ | - **使用获取的证书和密钥配置 SSL**:该模块将证书和密钥作为 [嵌入式变量](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables) 提供,可在 [配置](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) 中使用以填充 [ssl_certificate](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) 和 [ssl_certificate_key](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key)。 有关 SSL 设置说明,请参阅 [SSL配置](https://cn.angie.software//angie/docs/configuration/ssl.md#ssl-config)。 ## 实现细节 客户端密钥和证书以 [PEM 编码](https://datatracker.ietf.org/doc/html/rfc7468) 存储在由 `--http-acme-client-path` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 指定的目录的子目录中: ```console $ ls /var/lib/angie/acme/example/ account.key certificate.pem private.key ``` ACME 客户端需要在 CA 服务器上拥有一个账户。为了创建和管理此账户, 客户端使用私钥(`account.key`)。如果不存在密钥,则在启动时生成。 然后客户端使用此密钥向服务器注册账户。 #### NOTE 如果您已经拥有账户密钥,请在启动前将其放置在客户端的子目录中以重用该账户。 或者,使用 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) 中的 `account_key` 参数指定密钥文件。 ACME 客户端还使用单独的密钥(`private.key`)用于证书签名请求(CSR)。 如果需要,此证书密钥会在启动时自动创建。 启动时,如果证书不存在,客户端会请求证书,签名并向 CA 服务器发送包含其管理的所有域名的 CSR。 服务器使用 [HTTP](#acme-config-http) 或 [DNS 验证](#acme-config-dns) 验证域名所有权, 并颁发证书,客户端将其保存在本地(`certificate.pem`)。 如前所述,单个证书涵盖同一 ACME 客户端管理的所有域名,可能产生多域名证书。 证书涵盖的所有名称列表可以在获取的证书的 Subject Alternative Name (SAN)部分中找到。 要从命令行检查: ```console $ openssl x509 -in certificate.pem -noout -text | grep -A5 "Subject Alternative Name" ``` 当证书即将过期或域名列表发生变化时,客户端会签名并向 CA 服务器发送另一个 CSR。 服务器重新验证所有权并颁发新证书,客户端将其安装在本地,替换之前的证书。 在 [配置](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) 中,获取的证书及其对应的密钥可通过前缀变量 [$acme_cert_<名称>](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) 和 [$acme_cert_key_<名称>](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-key-name) 获得。它们的值是相应文件的内容, 应与 [ssl_certificate](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate) 和 [ssl_certificate_key](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-key) 指令一起使用: ```nginx server { listen 443 ssl; server_name example.com www.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } ``` ## 域名收集与证书使用 [acme](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) 指令仅用于收集证书请求的域名, 并不控制证书可在何处使用: 任何 `server` 块都可以通过 [$acme_cert_](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) 变量 引用获取的证书, 无论该块是否包含 `acme` 指令。 例如,如果您有一个已涵盖所有子域名的通配符 `server` 块, 那么针对特定子域名的额外 `server` 块 不需要 `acme` 指令: ```nginx http { resolver 127.0.0.53; acme_client example https://acme-v02.api.letsencrypt.org/directory challenge=dns; # This block lists the domains for the certificate request server { listen 443 ssl; server_name example.com *.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } # This block uses the same certificate but does not # add its server_name to the certificate request server { listen 443 ssl; server_name app.example.com; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } } ``` ### 显式域名列表 为了精确控制证书中的域名集合, 而不依赖于从所有 `server` 块自动收集, 可以创建一个专用的 `server` 块, 其中仅包含 [server_name](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-name) 和 [acme](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) 指令。 为防止此块处理实际流量, 可以将其绑定到 Unix 域套接字: ```nginx # Dedicated block that defines the certificate's domain list server { listen unix:/tmp/acme_example.sock; server_name example.com www.example.com; acme example; } ``` 其他 `server` 块随后可通过 [$acme_cert_](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#v-acme-cert-name) 变量 使用该证书,而不会影响请求的域名。 ## HTTP 验证 验证是自动处理的。该过程涉及 ACME 服务器在收到请求后,\`通过 HTTP 检索特殊令牌文件 <[https://datatracker.ietf.org/doc/html/rfc8555#section-8.3](https://datatracker.ietf.org/doc/html/rfc8555#section-8.3)>\`_, 从客户端地址 `/.well-known/acme-challenge/` 获取。我们的 ACME 模块 会自动跟踪和处理此类请求。当收到包含正确内容的预期响应时,ACME 服务器确认该域名属于客户端。 ### 配置示例 在此示例中,名为 `example` 的 ACME 客户端管理 `example.com` 和 `www.example.com` 的证书(注意 HTTP 验证不支持通配符证书): ```nginx http { resolver 127.0.0.53; # 'acme_client' 指令所需 acme_client example https://acme-v02.api.letsencrypt.org/directory; server { listen 80; # 如果没有服务器监听 HTTP 挑战端口,则可选 # (参见 'acme_http_port' 指令) listen 443 ssl; server_name example.com www.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } } ``` 如前所述,必须开放端口 80 以处理 HTTP ACME 调用。 如果没有配置服务器监听 HTTP 挑战端口, 该模块会在端口 80(或 [acme_http_port](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-http-port) 中设置的端口)上创建专用监听器。不需要单独的 [server](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server) 块。 ## DNS 验证 验证是自动处理的。在处理证书请求时,ACME 服务器会对被验证域名的 `_acme-challenge.` 子域执行 [特殊的 DNS 查询](https://datatracker.ietf.org/doc/html/rfc8555#section-8.4)。一旦收到预期的响应,ACME 服务器确认该域名属于客户端。 我们的 ACME 模块会自动跟踪和处理此类请求,前提是您的 DNS 记录已正确配置,将 Angie 服务器指定为 `_acme-challenge.` 子域的权威名称服务器。 #### NOTE Angie 服务器必须能够通过互联网在 UDP 53 端口(或 [acme_dns_port](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-dns-port) 中指定的端口)上访问。 如果服务器位于防火墙后, 请确保该端口对入站连接开放。 例如,要使用 IP 地址为 `93.184.215.14` 的 Angie 服务器验证域名 `example.com`,您的域名 DNS 配置应包含以下记录: ```none _acme-challenge.example.com. 60 IN NS ns.example.com. ns.example.com. 60 IN A 93.184.215.14 ``` 此配置将 `_acme-challenge.example.com` 的 DNS 解析委托给 `ns.example.com`,并通过将 `ns.example.com` 映射到 IP 地址(`93.184.215.14`)来确保其可访问。 #### WARNING NS 记录的传播可能需要几分钟到 48 小时不等,具体取决于 TTL 和 DNS 提供商。建议在请求证书之前验证配置是否正确。 要验证 DNS 是否配置正确,您可以使用以下命令: ```console $ dig NS _acme-challenge.example.com +short # 检查 _acme-challenge 子域的 NS 记录 ns.example.com. $ dig A ns.example.com +short # 检查名称服务器的 A 记录 93.184.215.14 $ nc -zv 93.184.215.14 53 # 检查 DNS 服务器在端口 53 上的可访问性 ``` 此方法允许请求通配符证书,例如,在 Subject Alternative Name (SAN)部分包含 `*.example.com` 条目的证书。要明确请求子域的证书,例如 `www.example.com`,您必须使用上述方法单独验证该子域。 #### WARNING 此场景的适用性在很大程度上取决于您的 DNS 提供商提供的功能;某些提供商不允许此类配置。 ### 配置示例 总体而言,配置与上一节中的示例类似。不需要 HTTP 特定的设置;只需为 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) 指令设置 `challenge=dns` 即可。 在此示例中,名为 `example` 的 ACME 客户端管理 `example.com` 和 `*.example.com` 的证书: ```nginx http { resolver 127.0.0.53; acme_client example https://acme-v02.api.letsencrypt.org/directory challenge=dns; server { server_name example.com *.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } } ``` ## ALPN 验证 验证是自动处理的。ACME 服务器使用 TLS 连接并通过 ALPN 请求 `acme-tls/1` 协议。该模块为验证请求提供临时证书。 要启用此方法,请在 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) 指令中配置 `challenge=alpn`,并确保您的 TLS 监听器在端口 443(或用于 TLS 的端口)上可访问。 ## 基于钩子的验证 与之前的方法不同,此验证需要额外的工作。ACME 服务器执行标准的 [HTTP 验证](#acme-config-http) 或 [DNS 验证](#acme-config-dns),但它不是直接与 Angie 服务器交互,而是通过钩子调用([acme_hook](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook))与 Angie 服务器管理的外部服务通信。该服务配置一个单独的 DNS 或 HTTP 服务器,ACME 服务器向其发送请求。 一旦 ACME 服务器从配置的 DNS 或 HTTP 服务器收到预期的响应,它就会确认域名所有权。 当证书签发或续订需要进行域名验证时, Angie 会向包含 [acme_hook](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) 指令的命名 `location` 生成一个内部请求。 该请求的处理方式完全取决于同一 `location` 中配置的其他指令。 通用模式如下: 1. 创建一个带有 [acme_hook](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) 指令的命名 `location`。 2. 在同一 `location` 中, 使用适合您环境的模块配置请求处理程序: FastCGI 使用 [fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), HTTP 使用 [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), CGI 脚本使用 `cgi`,等等。 3. 使用处理程序支持的机制, 将 ACME [变量](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme-variables) 传递给处理程序, 例如 FastCGI 使用 `fastcgi_param`, CGI 使用 `cgi_set_var`。 处理程序必须返回 `2xx` 状态码, 可以通过 `Status` 头发送。 任何其他状态码都被视为错误, 证书续订将停止。 处理程序的输出将被忽略。 ### 最小配置 无论使用哪种处理程序, 钩子 `location` 都遵循以下结构: ```nginx location @acme_hook { acme_hook example; # Handler directive (fastcgi_pass, proxy_pass, cgi on, ...) # Pass ACME variables using the handler's mechanism: # ACME_HOOK — $acme_hook_name ("add" or "remove") # ACME_CHALLENGE — $acme_hook_challenge ("dns" or "http") # ACME_DOMAIN — $acme_hook_domain # ACME_TOKEN — $acme_hook_token # ACME_KEYAUTH — $acme_hook_keyauth } ``` 对于 DNS 验证,处理程序必须使用 `ACME_HOOK` 来确定操作: 当其值为 `add` 时, 为 `_acme-challenge.*ACME_DOMAIN*` 创建一条 值为 `ACME_KEYAUTH` 的 TXT 记录; 当其值为 `remove` 时,删除该记录。 ### FastCGI 示例 在此示例中,:ref:acme_client 指令通过 `challenge=dns` 参数 将 ACME 客户端 `example` 配置为使用 DNS 验证。 `server` 块适用于 `example.com` 的所有子域(例如 `*.example.com`), 并通过 [acme](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) 指令使用 ACME 客户端 `example` 来管理证书。 一个命名的 `location` 块负责处理钩子调用。 [acme_hook](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-hook) 指令将其与 ACME 客户端 `example` 关联起来。 钩子请求通过 [fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass) 发送到运行在 9000 端口上的本地 FastCGI 服务器。 `fastcgi_param` 指令将 ACME 变量 传递给外部服务。 ```nginx acme_client example https://acme-v02.api.letsencrypt.org/directory challenge=dns; server { listen 80; server_name *.example.com; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; location @acme_hook_location { acme_hook example; fastcgi_pass localhost:9000; fastcgi_param ACME_CLIENT $acme_hook_client; fastcgi_param ACME_HOOK $acme_hook_name; fastcgi_param ACME_CHALLENGE $acme_hook_challenge; fastcgi_param ACME_DOMAIN $acme_hook_domain; fastcgi_param ACME_TOKEN $acme_hook_token; fastcgi_param ACME_KEYAUTH $acme_hook_keyauth; include fastcgi.conf; } } ``` 以下 Perl 脚本演示了相应的外部 FastCGI 服务: ```perl #!/usr/bin/perl use strict; use warnings; use FCGI; my $socket = FCGI::OpenSocket(":9000", 5); my $request = FCGI::Request(\*STDIN, \*STDOUT, \*STDERR, \%ENV, $socket); while ($request->Accept() >= 0) { print "\r\n"; my $client = $ENV{ACME_CLIENT}; my $hook = $ENV{ACME_HOOK}; my $challenge = $ENV{ACME_CHALLENGE}; my $domain = $ENV{ACME_DOMAIN}; my $token = $ENV{ACME_TOKEN}; my $keyauth = $ENV{ACME_KEYAUTH}; if ($hook eq 'add') { DNS_set_TXT_record("_acme-challenge.$domain.", $keyauth); } elsif ($hook eq 'remove') { DNS_clear_TXT_record("_acme-challenge.$domain."); } }; FCGI::CloseSocket($socket); ``` 这里,:samp:DNS_set_TXT_record() 和 `DNS_clear_TXT_record()` 是假定在外部 DNS 服务器的配置中添加和删除 TXT 记录的函数,ACME 服务器会查询该 DNS 服务器。这些记录必须包含 Angie 服务器提供的数据,以允许外部 DNS 服务器成功通过验证,类似于 [DNS 验证](#acme-config-dns) 中描述的过程。此类函数的实现细节超出了本指南的范围;例如,参数也可以通过请求 URI 传递: ```nginx # ... location @acme_hook_location { acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth; fastcgi_pass localhost:9000; fastcgi_param REQUEST_URI $request_uri; fastcgi_param ACME_CLIENT $acme_hook_client; fastcgi_param ACME_CHALLENGE $acme_hook_challenge; fastcgi_param ACME_TOKEN $acme_hook_token; include fastcgi.conf; } ``` ### PHP-FPM 示例 另一个使用 PHP-FPM 的示例: ```nginx location @acme_hook_location { acme_hook example; root /var/www/dns; fastcgi_pass unix:/run/php-fpm/php-dns.sock; fastcgi_index hook.php; fastcgi_param SCRIPT_FILENAME /var/www/dns/hook.php; include fastcgi_params; fastcgi_param ACME_CLIENT $acme_hook_client; fastcgi_param ACME_HOOK $acme_hook_name; fastcgi_param ACME_CHALLENGE $acme_hook_challenge; fastcgi_param ACME_DOMAIN $acme_hook_domain; fastcgi_param ACME_TOKEN $acme_hook_token; fastcgi_param ACME_KEYAUTH $acme_hook_keyauth; } ``` ```ini [dns] listen = /run/php-fpm/php-dns.sock listen.mode = 0666 user = angie group = angie chdir = /var/www/dns # ... ``` 传递的参数可以在 PHP 中通过 `$_SERVER['...']` 访问。 ## Stream 模块中的 ACME [ACME](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_acme.md#stream-acme) stream 模块可为 TCP 流量启用自动化的 证书签发和使用。 为使其正常工作,您必须首先配置其 HTTP 对应部分: ACME 客户端必须在 `http` 上下文中声明, 并且 `stream` 块本身必须放置在配置文件中 `http` 块\*之后\*。 ### 配置示例 默认情况下,使用 HTTP 验证模式来获取证书。 如 [HTTP 验证](#acme-config-http) 部分所述, 这需要一个监听 80 端口的 HTTP 服务器: ```nginx # HTTP 部分 http { resolver 127.0.0.53; # 用于 stream 部分的 ACME 客户端 acme_client example https://acme-v02.api.letsencrypt.org/directory; # 用于 HTTP 验证的服务器 server { listen 80; return 444; } } # Stream 部分 stream { server { listen 12345 ssl; proxy_pass backend_upstream; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; server_name example.com www.example.com; acme example; # 引用 HTTP 部分中定义的 ACME 客户端 } upstream backend_upstream { server 127.0.0.1:54321; } } ``` 您也可以使用 DNS 验证, 方法是在 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) 指令中配置 `challenge=dns`; 在这种情况下,将不需要该服务器。 ## 从 **certbot** 迁移 如果您之前在 [从 nginx 迁移到 Angie](https://cn.angie.software//angie/docs/configuration/migration.md#migration) 之前 使用 [certbot](https://certbot.eff.org/) 从 Let's Encrypt 获取和续订 SSL 证书, 请按照以下步骤过渡到使用我们的 ACME 模块。 假设您按如下方式配置了证书: ```console $ sudo certbot --nginx -d example.com -d www.example.com ``` 此命令自动创建的配置 通常位于 `/etc/nginx/sites-available/example.conf`, 看起来类似这样: ```nginx server { listen 80; server_name example.com www.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name example.com www.example.com; root /var/www/example; index index.html; ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; } ``` 在上面的示例中,需要修改高亮显示的行。 根据您的情况和偏好,使用 ACME 模块配置 [HTTP 验证](#acme-config-http) 或 [DNS 验证](#acme-config-dns)。 最终的 [Angie 配置](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) 可能如下所示: ```nginx http { resolver 127.0.0.53; acme_client example https://acme-v02.api.letsencrypt.org/directory; server { listen 80; server_name example.com www.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name example.com www.example.com; root /var/www/example; index index.html; acme example; ssl_certificate $acme_cert_example; ssl_certificate_key $acme_cert_key_example; } } ``` 请记住在 [更改后重新加载配置](https://cn.angie.software//angie/docs/configuration/runtime.md#control-config-change): ```console $ sudo kill -HUP $(cat /run/angie.pid) ``` 一旦您验证了此配置可以正常工作, 您可以删除 **certbot** 证书 并禁用或从服务器上完全移除 certbot (如果它不再在其他地方使用), 例如: ```console $ sudo rm -rf /etc/letsencrypt $ sudo systemctl stop certbot.timer $ sudo systemctl disable certbot.timer $ # -- 或 -- $ sudo rm /etc/cron.d/certbot $ sudo apt remove certbot $ # -- 或 -- $ sudo dnf remove certbot ``` # https://cn.angie.software/adc.md # Angie ADC Angie ADC 是一款应用交付控制器级别的软件系统， 集成了负载均衡、DNS 负载均衡，并支持通过外部和内部网关路由协议进行网络请求的路由和均衡。 Angie ADC 是一款综合性的负载均衡和网络流量管理软件， 可帮助构建灵活、高性能和安全的基础设施。 主要特性： - 支持 L4-L7 层负载均衡。 - 支持 L2/L3 协议和技术。 - 全球 DNS 负载均衡（GSLB）。 - 后端服务器健康检查。 - 客户端会话保持。 - TLS 处理与加速。 - 高可用性解决方案。 - 已列入俄罗斯软件注册。 - 提供 Web 界面、命令行（CLI）和 API，便于集成。 - 兼容俄罗斯操作系统。 - 技术支持。 **Angie ADC |adc_pdf_version|** 已于 ``` |adc_release_date| ``` 发布。 新版本计划每月发布，并及时提供安全修复与改进。 ## 为什么选择 Angie ADC？ 支持多种流量分配算法（包括动态：反馈、最短时间、最小带宽、最少包数）。 支持应用层（L7）和传输层（L4）负载均衡。 支持会话管理及第三方存储。 可通过 API 基于应用信息进行负载均衡。 根据应用服务器状态和数据中心性能管理 DNS 响应。 支持地理分布式流量调度。 支持主流协议（BGP、OSPF、VRRP、RIP、PBR、BFD）。 优化入站和出站流量路由。 提供 Angie ADC 控制台用于监控和配置。 命令行（CLI）支持所有变更日志记录。 支持 BGP、OSPF、VRRP，实现主备切换。 可在单数据中心或多数据中心部署高可用方案。 DNS 和负载均衡层灵活配置，保障故障时可靠运行。 基于可用性和性能指标进行服务器状态检测。 支持 ACME 自动证书续签，包括 GOST 证书。 完全兼容本地加密模块和 GOST TLS。 提供 API，便于自动化和 CI/CD 集成。 支持 REST API 和 SNMP，便于采集指标和管理。 以虚拟设备或硬件负载均衡器形式交付。 支持高可用部署场景，包括 Anycast 和多数据中心架构。 ## 技术支持 Angie ADC 产品提供 24/7 全天候技术支持，确保您随时获得帮助。 ## 配套文档 Angie ADC ``` |adc_pdf_version| ``` PDF 文档（俄语）： - [`Angie ADC 安装指南`](https://cn.angie.software//adc/Angie_ADC_|adc_pdf_version|_installation_guide.pdf) - [`Angie ADC 功能说明`](https://cn.angie.software//adc/Angie_ADC_|adc_pdf_version|_functional_description.pdf) - [`Angie ADC 运维手册`](https://cn.angie.software//adc/Angie_ADC_|adc_pdf_version|_operating_guide.pdf) ## 购买许可 本软件产品以商业许可方式分发。 如需了解产品价格、购买方式及许可协议， 请发送邮件至 [info@wbsrv.ru](mailto:info@wbsrv.ru) 咨询。 # https://cn.angie.software/news/all-news.md # 所有新闻 ## [Angie 和 Angie PRO 更新至 1.11.6 版本](https://cn.angie.software//news/releases/angie-1-11-6.md) *25.05.2026* Angie 和 Angie PRO 1.11.6 修复版本已发布，移植了前一日在 nginx 中发现的 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令漏洞 CVE-2026-9256 的修复。 ## [Angie 和 Angie PRO 更新至 1.11.5 版本](https://cn.angie.software//news/releases/angie-1-11-5.md) *15.05.2026* Angie 和 Angie PRO 1.11.5 修复版本已发布，移植了 nginx 中发现的五个漏洞的 修复。这些漏洞涉及 `rewrite`、`ssl_ocsp`、`scgi_pass`、 `uwsgi_pass` 和 `charset_map` 指令的工作，以及 `HTTP/3` 协议请求的处理。 ## [Angie 和 Angie PRO 更新至 1.11.0 版本](https://cn.angie.software//news/releases/angie-1-11-0.md) *24.12.2025* Angie 和 Angie PRO 1.11.0 已发布 — 这是该项目历史上规模最大的更新。 此版本引入了 Metrics 模块，修复了 `HTTP/3` 可靠性问题，扩展了 ACME 和图像过滤器功能；Angie PRO 改进了具有外部存储的粘性会话，并在 API 中添加了许可证详情。 ## [Angie 和 Angie PRO 更新至 1.10.3 版本](https://cn.angie.software//news/releases/angie-1-10-3.md) *13.11.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 1.10.3。 从 nginx 1.29 移植了邮件 SMTP 模块的一个潜在漏洞修复。修复了 ACME 配置 错误，并解决了在 client 块中使用变量访问传入连接时的潜在崩溃问题。 PRO 版本还修复了 UDP 健康检查和 Docker 模块服务器的相关问题。 ## [Angie 和 Angie PRO 更新至 1.10.2 版本](https://cn.angie.software//news/releases/angie-1-10-2.md) *22.08.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 1.10.2。 这些版本修复了在 1.10 版本中引入 client 块实现时出现的问题，该问题 可能会干扰 stream 模块中 ACME、Docker 和 sticky remote 模块的功能。 同时修复了通过 Docker API 更新代理服务器组的问题，并添加了两个新的 第三方模块。 ## [Angie 和 Angie PRO 更新至 1.10.1 版本](https://cn.angie.software//news/releases/angie-1-10-1.md) *17.07.2025* 发布了 Angie 和 Angie PRO 的 1.10.1 修复版本。此次更新修复了 reuseport 和 HTTP/3 的相关问题，改进了 client 配置块的逻辑， 增加了对新版本 GCC 的兼容性，并解决了 Angie PRO 中使用特殊变量时的崩溃问题。 ## [Angie 和 Angie PRO 更新至 1.10.0 版本](https://cn.angie.software//news/releases/angie-1-10-0.md) *04.07.2025* 开源 Web 服务器 Angie 及其商业版 Angie PRO 已发布 1.10.0 版本。 主要更新包括自动代理 Docker 容器、改进流模块中的 ACME 支持、 支持多路径 TCP 和带 CUBIC 的 QUIC，以及集群模式下 Angie PRO 的新功能。 ## [Angie 和 Angie PRO 更新至版本 1.9.1](https://cn.angie.software//news/releases/angie-1-9-1.md) *29.05.2025* 开源 Web 服务器 Angie 及其商业版 Angie PRO 发布了 1.9.1 版本。 本次更新重点提升了对 HTTP/3 的支持，并改进了对非标准 ACME 配置的处理， 同时修复了流模块中的一些问题。 ## [Angie 和 Angie PRO 更新至 1.9.0 版本](https://cn.angie.software//news/releases/angie-1-9-0.md) *11.04.2025* 开源网页服务器 Angie 及其商业版本 Angie PRO 已发布 1.9.0 版本。 主要更新包括将缓存索引保存到磁盘以加快重启速度、 在流模块中支持 TLS 1.3 Early Data，以及 Angie PRO 中 HTTP 负载均衡器的新功能。 ## [Angie 和 Angie PRO 发布了 1.8.3 版本；Console Light 更新至 1.7.0 版本](https://cn.angie.software//news/releases/angie-1-8-3.md) *02.04.2025* 开源版 Angie 网络服务器及其商业版 Angie PRO 发布了 1.8.3 版本，修复了统计功能； Console Light 更新至 1.7.0 版本。 ## [Angie 和 Angie PRO 发布 1.8.2 更新](https://cn.angie.software//news/releases/angie-1-8-2.md) *13.02.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 的 1.8.2 版本包含重要的安全修复，以及其他多项改进。 ## [Angie 和 Angie PRO 升级至 1.8.1 版本](https://cn.angie.software//news/releases/angie-1-8-1.md) *28.12.2024* 开源网络服务器 Angie 和其商业版本 Angie PRO 发布了 1.8.1 版本。 此更新修复了服务器统计区域的问题，改进了 ACME 模块对通配符证书的支持，并包含 HTTP/3 的重要修复。 ## [Angie 和 Angie PRO 更新至版本 1.8.0](https://cn.angie.software//news/releases/angie-1-8-0.md) *19.12.2024* Angie 网络服务器及其商业版本 Angie PRO 的 1.8.0 版本已发布。此更新包括 ACME 模块的新功能、对 WebAssembly 的支持，以及 API 和功能的改进。 ## [Angie 启用 WebAssembly 支持](https://cn.angie.software//news/articles/wasm.md) *29.11.2024* 此次更新使得可以构建 WASM 模块，以便 Angie 加载并在服务器配置中使用它们。 ## [Angie 和 Angie PRO 收到更新 1.7.0](https://cn.angie.software//news/releases/angie-i-angie-pro-poluchili-obnovlenie-1-7-0.md) *20.09.2024* 新版本的开源网页服务器 Angie 1.7.0 和商业版 Angie PRO 1.7.0 现已推出，提供显著的改进和新功能。 ## [Rubytech集团与俄罗斯Web服务器开发商Angie整合资源与专业技术，共同推进产品开发](https://cn.angie.software//news/gruppa-rubytech-i-angie-objedinaiut-resursi.md) *22.08.2024* 俄罗斯高负载系统软件开发商Angie（Web Server有限责任公司）已加入Rubytech集团。 ![Alternative text](../../_images/news/gruppa-rubytech-i-angie-objedinaiut-resursi.webp) ## [Angie 和 Angie PRO 发布 1.6.1 更新](https://cn.angie.software//news/releases/angie-i-angie-pro-poluchili-obnovlenie-1.6.1.md) *08.08.2024* Web Server公司发布了开源网络服务器 Angie 1.6.1 和其商业版本 Angie PRO 1.6.1。 ## [SolidWall Web应用程序防护解决方案兼容Angie PRO](https://cn.angie.software//news/integrations/reshenie-po-zaschite-web-prilojenii-solidwall-sovmestimo-s-angie-pro.md) *15.07.2024* 与Angie PRO的集成增强了SolidWall WAF的功能，例如，实现了对HTTP/3协议的支持。 ## [Angie和Angie PRO Web服务器发布更新](https://cn.angie.software//news/releases/vishli-obnovlenia-web-servera-angie-i-angie-pro.md) *28.06.2024* 新版本显著扩展了负载均衡功能，并继续开发ACME模块。 ## [Web服务器Angie新增ACME支持](https://cn.angie.software//news/releases/veb-server-angie-poluchil-podderzhku-acme.md) *27.03.2024* 新增了http_acme模块，实现了对ACME(自动化证书管理环境)协议的支持，简化了网站数字证书的工作流程， 无需使用像EFF Certbot这样的第三方解决方案。 ## [国产云环境Kubernetes解决方案Angie Ingress Controller (ANIC)发布更新](https://cn.angie.software//news/releases/vishli-obnovleniya-otechestvennogo-reshenia-ANIC.md) *02.03.2024* Web Server公司发布了用于Kubernetes容器化应用流量管理的俄罗斯解决方案Angie Ingress Controller (ANIC) 0.3.0版本。 ## [Angie Web服务器及其专有版本Angie PRO发布更新](https://cn.angie.software//news/releases/vishli-obnovleniya-veb-servera-angie-i-ego-proprietarnoi-versii-angie-pro.md) *15.02.2024* Web Server公司发布了俄罗斯开源Web服务器Angie 1.4.1及其商业版本Angie PRO 1.4.1。 ## [X-Config负责监控Angie PRO配置的安全性](https://cn.angie.software//news/integrations/bezopastnost-configuracii-angie-pro-kontroliruet-x-config.md) *08.02.2024* Angie PRO的安全配置标准将使客户能够自动监控Web服务器设置，接收按优先级排序的漏洞识别报告，并提供修复建议。 ## [Angie Ingress Controller (ANIC) 已加入国产软件名录](https://cn.angie.software//news/integrations/ingress-controller-anic-voshel-v-reestr-otechestvennogo-po.md) *12.01.2024* 大家好！我们用于 Kubernetes 云环境的解决方案 Angie Ingress Controller (ANIC) 已被添加到 [国产软件名录](https://reestr.digital.gov.ru/reestr/2057228/)。 ## [俄罗斯网络服务器Angie PRO更新发布](https://cn.angie.software//news/releases/vishli-obnovleniya-rossiiskogo-veb-servera-Angie-Pro.md) *21.12.2023* Web Server公司宣布发布新版本的俄罗斯网络服务器Angie PRO 1.4.0。 ## [俄罗斯开源Web服务器Angie发布更新](https://cn.angie.software//news/releases/vishli-obnovleniya-rossiiskogo-veb-servera-s-otkrytym-iskhodnym-kodom-Angie.md) *12.12.2023* "Web Server"公司发布了俄罗斯开源Web服务器Angie 1.4.0新版本。 ## [Angie PRO 获得 ROSA Chrome 12 Server 操作系统认证](https://cn.angie.software//news/integrations/angie-pro-sertifitsirovan-dlya-os-rosa-chrome-12-server.md) *01.12.2023* 俄罗斯网络服务器开发商Web Server与 ROSA IT 研究中心已确认 Angie PRO 网络服务器与 ROSA Chrome 12 Server 操作系统的兼容性，这一点已通过双方签发的证书得到证实，凸显了产品的高度兼容性和可靠性。 ## [Angie和Angie PRO发布1.3.2更新](https://cn.angie.software//news/releases/angie-i-angie-pro-poluchili-obnovlenie-1.3.2.md) *24.11.2023* Web Server公司发布了Web服务器Angie及其商业版本Angie PRO的更新。 ## [Angie新增功能助力更好的Web服务器监控](https://cn.angie.software//news/articles/novoe-v-angie-dlya-luchshego-monitoringa.md) *17.11.2023* 2023年9月，我们通过添加Angie Console Light为Angie web服务器引入了新的监控组织方式。 ## [Angie和Angie PRO针对DoS攻击的防护得到增强](https://cn.angie.software//news/releases/angie-i-angie-pro-obnovleni-dlya-uluchsheniya-zashchity-ot-dos-ataki.md) *18.10.2023* Web Server公司宣布发布Angie和Angie PRO的1.3.1版本。 ## [Web服务器Angie PRO发布1.3.0更新](https://cn.angie.software//news/releases/veb-server-angie-pro-poluchil-obnovlenie-1.3.0.md) *03.10.2023* "Web Server"公司宣布发布俄罗斯Web服务器Angie PRO 1.3.0新版本。 ## [开源代码的Web服务器Angie更新至版本1.3.0](https://cn.angie.software//news/releases/veb-server-angie-s-otkritim-ishodnim-kodom-1.3.0.md) *19.09.2023* 公司“Web服务器”宣布发布俄罗斯开源Web服务器Angie 1.3.0的新版本。 ## [WebmonitorEx平台与俄罗斯网络服务器Angie PRO实现兼容](https://cn.angie.software//news/integrations/platforma-vebmonitoreks-sovmestima-s-rossijskim-veb-serverom-Angie-Pro.md) *06.09.2023* WebmonitorEx已确保其平台与俄罗斯网络服务器Angie PRO的兼容性。这为企业提供了更高的可靠性和安全性，以防御网络威胁。 ## [Web服务器Angie PRO发布1.2.0更新](https://cn.angie.software//news/releases/veb-server-angie-pro-poluchil-obnovlenie-1.2.0.md) *19.08.2023* "Web Server"公司宣布发布其俄罗斯Web服务器Angie PRO 1.2.0新版本。 ## [Web Server公司推出Angie入口控制器](https://cn.angie.software//news/releases/kompaniya-veb-server-predstavila-angie-ingress-controller.md) *29.06.2023* Web Server公司推出了新产品Angie入口控制器（ANIC），可实现Kubernetes网络中的高效流量管理。 ## [我们在发展并诚邀专业人才加入我们的团队](https://cn.angie.software//news/mi-rastem-i-priglashaem-na-rabotu-spetsialistov.md) *16.06.2023* 我们在发展并诚邀专业人才加入我们的团队 - 招聘Angie网络服务器的C语言开发工程师和QA专家（Perl） ## [公司Web Server更新开源Web服务器Angie](https://cn.angie.software//news/releases/kompaniya-veb-server-obnovila-veb-server.md) *08.06.2023* 俄罗斯开源Web服务器Angie 1.2.0新版本发布。 ## [Angie Web服务器成为"俄罗斯版GitHub"的参与者](https://cn.angie.software//news/integrations/veb-server-angie-stal-uchastnikom-rossijskogo-GitHub.md) *06.06.2023* 由前nginx团队开发的俄罗斯Web服务器Angie已成为创建俄罗斯代码仓库实验的参与者。俄罗斯数字发展部于2023年5月31日发布了相关命令。 ## [Web服务器Angie PRO被列入国产软件名录](https://cn.angie.software//news/integrations/veb-server-angie-pro-voshel-v-reestr-otechestvennogo-PO.md) *24.05.2023* 由前nginx团队开发的Web服务器Angie PRO已被列入国产软件名录。 ## ["网络服务器"团队推出企业级产品 — Angie PRO](https://cn.angie.software//news/integrations/komanda-veb-servera-predstavlyaet-produkt-dlya-korporativnyh-zakazchikov-Angie-Pro.md) *27.03.2023* Angie已通过RED OS和Astra Linux特别版的兼容性认证。 ## [俄罗斯将推出自主研发的Web服务器Angie](https://cn.angie.software//news/rossiya-poluchit-nezavisimii-veb-server.md) *27.10.2022* 俄罗斯已开发出名为Angie的Web服务器，这将使俄罗斯企业能够替代国外解决方案并确保其基础设施的安全。 ## [Angie正在招聘](https://cn.angie.software//news/angie-priglashaet-na-rabotu.md) *28.05.2024* 大家好！我们想让全世界知道，我们也需要专业人士。 ![替代文本](../../_images/news/angie-priglashaet-na-rabotu.jpeg) ## [我们的团队持续为全球开源事业做贡献！](https://cn.angie.software//news/nasha-komanda-prodolzhaet-delat-vklad-v-mirovoj-open-source.md) *27.12.2023* 我们不仅在开发 Angie — nginx 的一个分支，还偶尔会为 nginx 本身做出贡献。 ![Alternative text](../../_images/news/nasha-komanda-prodolzhaet-delat-vklad-v-mirovoj-open-source.jpeg) ## [备受尊敬的Ivan Panchenko的精彩访谈](https://cn.angie.software//news/interviews/prekrasnoe-intervyu-gluboko-uvazhaemogo-ivana-panchenko.md) *07.02.2024* 从第25分钟开始，Ivan [谈论](https://www.youtube.com/watch?app=desktop&v=d9joPLRULeA) 我们的事情， 虽然他没有直接提到我们的名字。不过，这个一小时长的访谈中其他内容对所有从事开源项目的人来说都同样重要。 ![Alternative text](../../_images/news/prekrasnoe-intervyu-gluboko-uvazhaemogo-ivana-panchenko.jpeg) ## [Angie Console - 我们正在开发新产品！](https://cn.angie.software//news/angie-console-mi-razrabativaem-novii-produkt.md) *09.02.2024* 这是一个用于管理Web服务器集群的集中式系统，具有监控和动态配置功能。 ![Alternative text](../../_images/news/angie-console-mi-razrabativaem-novii-produkt.jpg) ## [扩充第三方模块库：新增ModSecurity](https://cn.angie.software//news/integrations/popolnyaem-kollektsiyu-storonnih-modulei.md) *04.12.2023* 大家好！在我们为即将发布的Angie和Angie PRO网络服务器更新版本进行工作的同时，我们也在持续扩充我们的第三方模块库。 ![Alternative text](../../_images/news/popolnyaem-kollektsiyu-storonnih-modulei.webp) ## [Angie Web服务器一年后：新机遇与未来规划](https://cn.angie.software//news/events/veb-server-angie-god-spustya-novie-vozmozhnosti.md) *27.11.2023* Angie开发负责人Valentin Bartenyev将在HighLoad 2023大会上回顾项目第一年的发展历程。 ![替代文本](../../_images/news/veb-server-angie-god-spustya-novie-vozmozhnosti.jpeg) ## [研发部负责人访谈](https://cn.angie.software//news/interviews/intervyu-s-rukovoditelem-otdela-razrabotki.md) *16.11.2023* 大家好！今天我们在Habr上发布了一篇对研发部负责人Valentin Bartenyev的访谈。 ![Alternative text](../../_images/news/intervyu-s-rukovoditelem-otdela-razrabotki.jpg) ## [获得Alt SP Server操作系统兼容性证书](https://cn.angie.software//news/integrations/poluchili-sertifikat-sovmestimosti-s-os-Alt-SP-Server.md) *10.11.2023* 该证书不仅证实了测试的成功完成，也是我们产品对部分客户实施的必需文件。 ![Alternative text](../../_images/news/poluchili-sertifikat-sovmestimosti-s-os-Alt-SP-Server.jpeg) ## [认识 Console Light](https://cn.angie.software//news/articles/vstrechaite-console-light.md) *27.09.2023* 我们推出了一款用于实时活动监控的轻量级可视化控制台。 ![Alternative text](../../_images/news/vstrechaite-console-light.jpg) ## [三周更新计划](https://cn.angie.software//news/tri-nedeli-obnovleniy.md) *19.09.2023* 在接下来的三周(没错!)中，我们将以更新来庆祝并让用户感到欣喜。 ![Alternative text](../../_images/news/tri-nedeli-obnovleniy.jpeg) ## [在俄罗斯推广开源](https://cn.angie.software//news/articles/populyarizuem-opensource-v-rossii.md) *14.09.2023* 我们与科学出版物N+1的朋友们一起启动了一个在俄罗斯推广开源的特别项目。 ![Alternative text](../../_images/news/populyarizuem-opensource-v-rossii.jpeg) ## [Angie与中国的经验](https://cn.angie.software//news/articles/opyt-raboti-angie-s-kitaem.md) *04.09.2023* 当俄罗斯正在积极制定"本土"开源项目发展计划时，中国也在积极发展其自己的开源项目。 ![Alternative text](../../_images/news/opyt-raboti-angie-s-kitaem.jpeg) ## [在贝加尔测试Angie PRO](https://cn.angie.software//news/integrations/testiruem-angie-pro-na-baikale.md) *31.08.2023* 我们成功地在ARM处理器架构上编译、构建软件包并测试了我们的产品Angie/Angie PRO。 ![Alternative text](../../_images/news/testiruem-angie-pro-na-baikale.jpeg) ## [Angie 与 nginx 的异同点](https://cn.angie.software//news/articles/shodstva-i-razlichiya-angie-i-nginx.md) *25.08.2023* Angie 项目和 Angie PRO 产品与其前身 nginx 及其商业版本 NGINX Plus 的关系。 ![Angie vs. nginx](../../_images/news/shodstva-i-razlichiya-angie-i-nginx.webp) ## [ANIC - Angie Ingress Controller](https://cn.angie.software//news/articles/anic-angie-ingress-controller.md) *11.08.2023* 今天我们将讨论Angie Ingress Controller（ANIC）- Web Server公司为简化Kubernetes中的流量管理而推出的解决方案。 ![Alternative text](../../_images/news/anic-angie-ingress-controller.jpg) ## [Angie 和 N+1 探索俄罗斯开源世界](https://cn.angie.software//news/articles/angie-i-Nplus1-issleduyut-opensors-v-rossii.md) *04.08.2023* 我们将与 N+1 编辑团队一起，用一年时间探索使用开源原则的软件开发世界。 ![Alternative text](../../_images/news/angie-i-Nplus1-issleduyut-opensors-v-rossii.jpg) ## [Angie 一周年！](https://cn.angie.software//news/angie-1-god.md) *21.07.2023* 今天，7月21日，Angie迎来了它的第一个生日。我们正在各大平台上开设博客，向您介绍我们的发展情况。 ![Alternative text](../../_images/news/angie-1-god.jpeg) # https://cn.angie.software/news/releases/angie-1-10-0.md # Angie 和 Angie PRO 更新至 1.10.0 版本 *04.07.2025* 开源 Web 服务器 Angie 及其商业版 Angie PRO 已发布 1.10.0 版本。 主要更新包括自动代理 Docker 容器、改进流模块中的 ACME 支持、 支持多路径 TCP 和带 CUBIC 的 QUIC，以及集群模式下 Angie PRO 的新功能。 我们已将开源 Web 服务器 Angie 及其商业版 Angie PRO 更新至 1.10.0 版本。 此版本的重点功能是内置支持自动代理和负载均衡运行在 Docker 或 Podman 容器中的 Web 服务。带有特定标签的容器会自动添加到配置的上游组中，并实时跟踪其启动/停止生命周期——无需重新加载配置。 ACME 模块现在可以完全在流上下文中工作，扩展了自动配置 TLS 和更新证书的能力。 HTTP 上下文中新增了 `client` 块——类似于 `server` 块，但用于出站请求。这允许灵活配置与 ACME 服务器和 Docker API 的交互。 多路径 TCP 支持已从 freenginx 移植到 http、stream 和 mail 模块。Angie 现在还包括 nginx 1.27.5 版本的所有功能，包括 QUIC 连接中的 CUBIC 拥塞控制。与 nginx 不同，Angie 也可以使用 QUIC 进行到后端的出站连接。 在 Angie PRO 中，集群模式在使用外部存储时增强了新的会话粘性机制。流模块还获得了一种新的回退模式，避免立即返回到主服务器组。 我们还修复了 `drain` 模式统计中服务器停机时间计算的一个小错误。 了解更多变更： - [Angie 1.10.0 变更](https://cn.angie.software/angie/docs/oss_changes/#angie-1-10-0) - [Angie PRO 1.10.0 变更](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-10-0) 我们将很快在 Habr 上发布一篇详细文章，探讨此版本及未来发展。 祝您有美好的一天！😊 # https://cn.angie.software/news/releases/angie-1-10-1.md # Angie 和 Angie PRO 更新至 1.10.1 版本 *17.07.2025* 发布了 Angie 和 Angie PRO 的 1.10.1 修复版本。此次更新修复了 reuseport 和 HTTP/3 的相关问题，改进了 client 配置块的逻辑， 增加了对新版本 GCC 的兼容性，并解决了 Angie PRO 中使用特殊变量时的崩溃问题。 我们发布了开源版 Angie 和商业版 Angie PRO 的修复版本 — 1.10.1。 在 Angie 中，修复了在 `listen` 指令中使用 `reuseport` 参数时， 所有连接都由同一个工作进程处理的问题。同时也解决了使用较新 OpenSSL 版本时 HTTP/3 代理失败的情况。 新版中改进了 `client ` 配置块的逻辑，使其行为更清晰、使用更方便。 此外，更新增加了对新版本 GCC 编译器的兼容性，并修复了在使用 `-O3` 优化等级编译时的构建错误。 在 Angie PRO 中，修复了在非预期上下文中访问仅用于外部会话存储请求的特殊变量时 导致的工作进程崩溃问题。 详细更新内容： - [Angie 1.10.1 的更新说明](https://cn.angie.software/angie/docs/oss_changes/#angie-1-10-1) - [Angie PRO 1.10.1 的更新说明](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-10-1) 感谢大家的反馈与支持！ # https://cn.angie.software/news/releases/angie-1-10-2.md # Angie 和 Angie PRO 更新至 1.10.2 版本 *22.08.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 1.10.2。 这些版本修复了在 1.10 版本中引入 client 块实现时出现的问题，该问题 可能会干扰 stream 模块中 ACME、Docker 和 sticky remote 模块的功能。 同时修复了通过 Docker API 更新代理服务器组的问题，并添加了两个新的 第三方模块。 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 — 1.10.2。 这些版本修复了在 1.10 版本中引入 `client` 块实现时出现的问题，该问题 导致 `http` 块级别的一些代理模块设置可能会干扰 stream 模块中 ACME、 Docker 和 sticky remote 模块的功能。 同时修复了当列表中只有一个服务器时，通过 Docker API 更新代理服务器组的问题。 此外，构建中添加了两个新的第三方模块： - Auth TOTP 用于基于 TOTP 一次性密码的身份验证； - Combined Upstreams 允许将多个代理服务器组合并为一个。 关于更改的详细信息： - [Angie 1.10.2 更改日志](https://cn.angie.software/angie/docs/oss_changes/#angie-1-10-2) - [Angie PRO 1.10.2 更改日志](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-10-2) 祝您度过愉快的一天！ # https://cn.angie.software/news/releases/angie-1-10-3.md # Angie 和 Angie PRO 更新至 1.10.3 版本 *13.11.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 1.10.3。 从 nginx 1.29 移植了邮件 SMTP 模块的一个潜在漏洞修复。修复了 ACME 配置 错误，并解决了在 client 块中使用变量访问传入连接时的潜在崩溃问题。 PRO 版本还修复了 UDP 健康检查和 Docker 模块服务器的相关问题。 开源 Web 服务器 Angie 及其商业版本 Angie PRO 发布了修复版本 — 1.10.3。 这些版本包括： - 从 nginx 1.29 移植了邮件 SMTP 模块的一个潜在漏洞修复。 - 修复了 ACME 配置错误。 - 解决了在 `client` 块中使用变量访问传入连接时的潜在崩溃问题。 在该块中不存在这样的连接。 在商业版本 Angie PRO 中另外： - 解决了活跃 UDP 健康检查的问题。 - 修复了通过 Docker 模块添加的服务器的活跃健康检查问题。 - 修正了配置重新加载后 learn-session 超时的问题。 关于更改的详细信息： - [Angie 1.10.3 更改日志](https://cn.angie.software/angie/docs/oss_changes/#angie-1-10-3) - [Angie PRO 1.10.3 更改日志](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-10-3) 祝您度过愉快的一天！ # https://cn.angie.software/news/releases/angie-1-11-0.md # Angie 和 Angie PRO 更新至 1.11.0 版本 *24.12.2025* Angie 和 Angie PRO 1.11.0 已发布 — 这是该项目历史上规模最大的更新。 此版本引入了 Metrics 模块，修复了 `HTTP/3` 可靠性问题，扩展了 ACME 和图像过滤器功能；Angie PRO 改进了具有外部存储的粘性会话，并在 API 中添加了许可证详情。 Angie 及其商业版本 Angie PRO — 1.11.0 — 现已发布。这是项目历史上规模最大的更新， 每个版本包含数十项改进。 主要亮点： - 新增 Metrics 模块，用于实时数据采集和聚合（移动平均和指数平均、计数器、 直方图等）。Metrics 可从任意变量构建，通过 HTTP API 以 JSON 和 Prometheus 格式暴露，并可通过变量和日志使用。 - 修复了配置重加载和二进制升级时 `HTTP/3` 的可靠性问题；通过 BPF 更新改进了进程间的 QUIC 数据包路由。 - ACME 增强：支持 ALPN 验证、API（及 Prometheus）中的续期状态、简化的 HTTP 挑战配置，以及修复了在没有 `acme` 指令时从 `stream` 块访问证书的问题。 - 图像过滤器更新，支持 AVIF 和 HEIC 格式，以及格式转换。 - 支持 ECH（Encrypted Client Hello）。 - 代理以及 `GET` 和 `HEAD` 请求正确缓存的改进。 - 移植了最新 nginx 版本的功能和 freenginx 的部分改进。 在 Angie PRO 中另外： - 改进了对外部存储的会话绑定，便于构建多个负载均衡器组成的集群。 - 许可证和限制信息现在可通过 API 获取。 PHP 应用运行器作为 PHP-FPM 的替代方案未能纳入本版本 — 工作仍在进行中。 关于更改的详细信息： - [Angie 1.11.0 更改日志](https://cn.angie.software/angie/docs/oss_changes/#angie-1-11-0) - [Angie PRO 1.11.0 更改日志](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-11-0) 祝您度过愉快的一天！ # https://cn.angie.software/news/releases/angie-1-11-5.md # Angie 和 Angie PRO 更新至 1.11.5 版本 *15.05.2026* Angie 和 Angie PRO 1.11.5 修复版本已发布，移植了 nginx 中发现的五个漏洞的 修复。这些漏洞涉及 `rewrite`、`ssl_ocsp`、`scgi_pass`、 `uwsgi_pass` 和 `charset_map` 指令的工作，以及 `HTTP/3` 协议请求的处理。 Angie 及其商业版本 Angie PRO 修复版本 — 1.11.5 — 现已发布，移植了 nginx 中 发现的若干漏洞的修复。 已修复 5 个漏洞： [CVE-2026-42945](https://nvd.nist.gov/vuln/detail/CVE-2026-42945)、 [CVE-2026-40701](https://nvd.nist.gov/vuln/detail/CVE-2026-40701)、 [CVE-2026-40460](https://nvd.nist.gov/vuln/detail/CVE-2026-40460)、 [CVE-2026-42946](https://nvd.nist.gov/vuln/detail/CVE-2026-42946) 和 [CVE-2026-42934](https://nvd.nist.gov/vuln/detail/CVE-2026-42934)。 nginx 中发现的第六个漏洞 [CVE-2026-42926](https://nvd.nist.gov/vuln/detail/CVE-2026-42926) 不影响已发布的 Angie 版本。 这些漏洞涉及 `rewrite`、`ssl_ocsp`、`scgi_pass`、 `uwsgi_pass` 和 `charset_map` 指令的工作，以及 `HTTP/3` 协议请求的处理。 关于更改的详细信息： - [Angie 1.11.5 更改日志](https://cn.angie.software/angie/docs/oss_changes/#angie-1-11-5) - [Angie PRO 1.11.5 更改日志](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-11-5) 祝您度过愉快的一天！ # https://cn.angie.software/news/releases/angie-1-11-6.md # Angie 和 Angie PRO 更新至 1.11.6 版本 *25.05.2026* Angie 和 Angie PRO 1.11.6 修复版本已发布，移植了前一日在 nginx 中发现的 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令漏洞 CVE-2026-9256 的修复。 Angie 及其商业版本 Angie PRO 修复版本 — 1.11.6 — 现已发布，移植了 前一日在 nginx 中发现的漏洞 [CVE-2026-9256](https://nvd.nist.gov/vuln/detail/CVE-2026-9256) 的修复。 当配置中使用 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令以及包含嵌套捕获的正则表达式时， 可能触发该漏洞，例如： `rewrite ^/((.*))$ http://127.0.0.1:8080/?$1$2;`。 关于更改的详细信息： - [Angie 1.11.6 更改日志](https://cn.angie.software/angie/docs/oss_changes/#angie-1-11-6) - [Angie PRO 1.11.6 更改日志](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-11-6) 祝您度过愉快的一天！ # https://cn.angie.software/news/releases/angie-1-8-0.md # Angie 和 Angie PRO 更新至版本 1.8.0 *19.12.2024* Angie 网络服务器及其商业版本 Angie PRO 的 1.8.0 版本已发布。此更新包括 ACME 模块的新功能、对 WebAssembly 的支持，以及 API 和功能的改进。 开源网络服务器 Angie 及其商业版本 Angie PRO 的 1.8.0 版本已发布。这是 2024 年计划中的第四个 Angie 版本。 通过此次发布，用于自动化 TLS 证书设置的 ACME 模块现在支持发行通配符证书。 新的实现允许 Angie 使用自身的功能处理域名验证的 DNS 查询，与现有的自动化工具如 certbot 相比，这大大简化了设置过程。 有关这些功能的更多详细信息，请参阅我们为此次发布准备的 [综合指南](https://cn.angie.software//angie/docs/configuration/acme.md#acme-config)。 1.8.0 版本还包括 [之前宣布的 WASM 模块](https://cn.angie.software//news/articles/wasm.md) 为 Angie。这些模块添加了对 WebAssembly (WASM) 的支持，并提供了一个专用 SDK 用于创建 WASM 模块。Angie 中的 WASM 实现允许开发人员使用服务器 API 和 SDK 在流行的编程语言中编写扩展，为定制和灵活配置开辟了可能性。 此外，此更新还包括： - Angie PRO 中 [粘性学习](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) 模式的新设置，实现会话绑定与外部存储的结合。现在您可以创建具有会话绑定的整个负载均衡器集群！ - API 指标的改进： [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 指令现在支持变量，允许基于任意标准提供详细统计信息。 - 从 freenginx 项目和 nginx 版本 1.27.3 移植的功能。 有关新功能的更多详细信息，请访问以下链接： - [Angie 1.8.0 更改](https://angie.software/angie/docs/oss_changes/#angie-1-8-0) - [Angie PRO 1.8.0 更改](https://angie.software/angie/docs/pro_changes/#angie-pro-1-8-0) # https://cn.angie.software/news/releases/angie-1-8-1.md # Angie 和 Angie PRO 升级至 1.8.1 版本 *28.12.2024* 开源网络服务器 Angie 和其商业版本 Angie PRO 发布了 1.8.1 版本。 此更新修复了服务器统计区域的问题，改进了 ACME 模块对通配符证书的支持，并包含 HTTP/3 的重要修复。 开源网络服务器 Angie 和其商业版本 Angie PRO 已升级至 1.8.1 版本。 此版本修复了在 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 指令中添加对变量的支持后引入的服务器统计区域处理问题。 同时，修复了 [ACME 模块](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 中与获取通配符证书相关的功能问题，提高了证书配置的可靠性。 1.8.1 版本还包含了从未发布的 nginx 1.27.4 版本中移植的 HTTP/3 协议重要问题修复。由于供应商政策的变更（详见 [提交记录](https://github.com/nginx/nginx/commit/c73fb273acc31bff7c4e469efda5f3fd66c48557)），这些修复只会在 nginx 主分支的下一个版本中出现。 我们理解在年末最后一个工作日发布更新并不理想，但这是为了修复已发现的问题并确保稳定性所必须的。 更多有关更新的信息，请访问： - [Angie 1.8.1 版本更新内容](https://cn.angie.software/angie/docs/oss_changes/#angie-1-8-1) - [Angie PRO 1.8.1 版本更新内容](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-8-1) # https://cn.angie.software/news/releases/angie-1-8-2.md # Angie 和 Angie PRO 发布 1.8.2 更新 *13.02.2025* 开源 Web 服务器 Angie 及其商业版本 Angie PRO 的 1.8.2 版本包含重要的安全修复，以及其他多项改进。 我们已将开源 Web 服务器 Angie 及其商业版本 Angie PRO 更新至 1.8.2 版本。 首先，该版本移植了最近在 nginx 1.27.4 中修复的 [CVE-2025-23419](https://www.cve.org/CVERecord?id=CVE-2025-23419) 漏洞。此漏洞源于在不同于创建会话的虚拟主机中重用 TLS 会话， 可能绕过客户端 TLS 证书验证。当多个虚拟主机的客户端证书验证设置不同，而会话恢复机制或会话缓存启用时，该问题就会出现。 此外，本次更新修复了 HTTP/3 协议统计计算问题、API 请求处理错误，以及通过 ACME 协议处理域名时的错误。同时，它还修复了 在流模块中使用主动健康检查时导致的工作进程崩溃问题。 有关更新的更多详细信息，请参阅以下链接： - [Angie 1.8.2 更新说明](https://cn.angie.software/angie/docs/oss_changes/#angie-1-8-2) - [Angie PRO 1.8.2 更新说明](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-8-2) # https://cn.angie.software/news/releases/angie-1-8-3.md # Angie 和 Angie PRO 发布了 1.8.3 版本；Console Light 更新至 1.7.0 版本 *02.04.2025* 开源版 Angie 网络服务器及其商业版 Angie PRO 发布了 1.8.3 版本，修复了统计功能； Console Light 更新至 1.7.0 版本。 我们已将开源版 Angie 网络服务器及其商业版 Angie PRO 更新至 1.8.3 版本。 1.8.3 版本修复了以下问题：在 HTTP 模块的 [server](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server) 块中， [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 的统计信息可能在以下情况下计算不正确： 请求在一个连接中命中多个统计区域，或在请求处理早期阶段发生错误。 该问题首次出现在 1.8.2 版本中，由社区发现。 我们建议当前使用 Angie 1.8.\* 较早版本的用户升级至 1.8.3 版本。 这个错误修复版本发布在即将推出新功能的 1.9.0 版本之前， 确保那些尚未准备好升级到新版本的用户也能获得更新。 作为此次发布的一部分，可视化控制台 Angie Console Light 也已更新至 [1.7.0](https://cn.angie.software//angie/docs/configuration/monitoring.md#monitoring) 版本。它可以帮助实时监控网络服务器指标，包括性能和负载。 更多更新详情请查看： - [Angie 1.8.3 的更改内容](https://cn.angie.software/angie/docs/oss_changes/#angie-1-8-3) - [Angie PRO 1.8.3 的更改内容](https://cn.angie.software/angie/docs/pro_changes/#angie-pro-1-8-3) # https://cn.angie.software/news/releases/angie-1-9-0.md # Angie 和 Angie PRO 更新至 1.9.0 版本 *11.04.2025* 开源网页服务器 Angie 及其商业版本 Angie PRO 已发布 1.9.0 版本。 主要更新包括将缓存索引保存到磁盘以加快重启速度、 在流模块中支持 TLS 1.3 Early Data，以及 Angie PRO 中 HTTP 负载均衡器的新功能。 我们已将开源网页服务器 Angie 和其商业版本 Angie PRO 更新至 1.9.0 版本。 这是 2025 年计划发布的四个主要版本中的第一个。 1.9.0 版本的主要变化是能够将共享内存中的缓存索引保存到磁盘， 并在重启时无需缓存加载器即可立即加载。该创新可在处理大规模缓存时加快服务器恢复速度。 在 Angie PRO 中，HTTP 负载均衡器新增了 [backup_switch (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) 指令。 它允许灵活配置在切换到备用服务器组时的行为，并控制停留的时间。 其他重要更新包括： - 在流模块中支持 TLS 1.3 Early Data (0-RTT)； - 新增服务器连接数耗尽时的状态 `busy`； - 改进 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 模块，简化证书续期管理； - 缓存通过变量设置的「动态」TLS 证书（如 [ssl_certificate_cache](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-certificate-cache) 等指令）。 详细更新内容请见： - [Angie 1.9.0 的更新内容](https://en.angie.software/angie/docs/oss_changes/#angie-1-9-0) - [Angie PRO 1.9.0 的更新内容](https://en.angie.software/angie/docs/pro_changes/#angie-pro-1-9-0) 我们建议您更新至 1.9.0 版本以体验新功能。 在接下来的几天里，我们将发布特别文章，详细介绍 1.9.0 版本的变化， 并部分透露 1.10.0 版本的计划。 祝大家周末愉快！ # https://cn.angie.software/news/releases/angie-1-9-1.md # Angie 和 Angie PRO 更新至版本 1.9.1 *29.05.2025* 开源 Web 服务器 Angie 及其商业版 Angie PRO 发布了 1.9.1 版本。 本次更新重点提升了对 HTTP/3 的支持，并改进了对非标准 ACME 配置的处理， 同时修复了流模块中的一些问题。 我们已将开源 Web 服务器 Angie 及其商业版本 Angie PRO 升级至 1.9.1 版本。 这是一个以提升稳定性和修复已知问题为主的修订版本。 主要更新内容： - 提升了与 HTTP/3 协议交互时的稳定性； - 改进了 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 模块对非标准配置的支持； - 修复了流模块中代理服务器状态显示不正确的问题； - 修复了 `drain` 模式下的一个错误。 详细更新内容请参阅： - [Angie 1.9.1 的变更](https://angie.software/angie/docs/oss_changes/#angie-1-9-1) - [Angie PRO 1.9.1 的变更](https://angie.software/angie/docs/pro_changes/#angie-pro-1-9-1) 我们曾在 Habr 上详细介绍了从 1.9.0 版本开始的新功能： [https://habr.com/zh/articles/900672/](https://habr.com/zh/articles/900672/) # https://cn.angie.software/news/angie-1-god.md # Angie 一周年！ *21.07.2023* 今天，7月21日，Angie迎来了它的第一个生日。我们正在各大平台上开设博客，向您介绍我们的发展情况。 ![Alternative text](../../_images/news/angie-1-god.jpeg)![Alternative text](../../_images/news/angie-1-god.jpeg) 各位同事、客户和合作伙伴们，大家好！ 2022年7月，我们组建了一支由曾参与NGINX Web服务器开发和支持的顶尖工程师组成的团队，创立了Web Server公司，并开始开发俄罗斯开源Web服务器Angie。今天，7月21日，Angie迎来了它的第一个生日。我们正在各大平台上开设博客，向您介绍我们的发展情况。 以下是我们一年来取得的成就简报： 2022年秋季，Web Server团队发布了Angie的开源版本。它是基于NGINX（这是我们最熟悉且最流行的Web服务器）的一个分支，但同时也是一个独立的项目，会定期更新新功能。比如，这款国产Web服务器已经支持HTTP/3协议。 但Angie的本质不在于复制：我们正在使我们的Web服务器变得更可靠、更经济、更快速。统计数据收集功能使我们能够及时应对资源过度使用、错误和攻击；会话绑定和DNS服务器更新有助于在现代基础设施中实现负载均衡。我们目前正在添加均衡服务器的主动检查和配置管理功能，以提高容错能力并简化管理。 Angie团队认为开源版本是其工作中最重要的领域之一——我们也参与了创建俄罗斯代码仓库的实验，与Basalt、Red Soft和T1 Innovations等俄罗斯IT市场巨头共同合作。 我们也为企业客户提供优质服务。2023年春季，我们发布了Angie PRO——这是唯一一款获得与国产操作系统RED OS、Astra Linux Special Edition和Alt Server 10兼容性认证的商业俄罗斯Web服务器。我们的另一个产品——Angie Ingress Controller (ANIC)——是一个使用Ingress Controller管理Kubernetes中容器化应用程序流量的解决方案。 我们的目标是满足俄罗斯市场的技术需求。Web服务器的付费版和开源版都提供俄语文档和支持；我们还计划添加符合GOST标准的加密功能。在我们的代码仓库中，我们发布了适用于各种操作系统和硬件平台（包括国产平台）的现成软件包，以及补充Web服务器核心功能的流行动态模块。 但这仅仅是开始。我们一定会给您带来惊喜。不止一次，也不止两次。 在这个博客中，我们将讨论俄罗斯IT市场如何运作（不仅是运作，还包括失败、卡顿和宕机的情况），分享我们与中国客户合作的经验（是的，我们确实有这样的经验），并分享技术专长——我们不仅会告诉您产品开发的进展，最终还会在这里集成技术支持聊天功能。 我们还将发布职位招聘信息（欢迎开发人员等加入——我们在这个领域拥有很强的专业知识），并讨论我们认为有趣的项目和媒体报道。我们更注重深思熟虑的公关，而不是铺天盖地的宣传。 朋友们，这将会很有趣！ 此致 Angie团队 [我们的网站](https://cn.angie.software) [Telegram频道](https://t.me/angie_software) # https://cn.angie.software/news/angie-console-mi-razrabativaem-novii-produkt.md # Angie Console - 我们正在开发新产品！ *09.02.2024* 这是一个用于管理Web服务器集群的集中式系统，具有监控和动态配置功能。 ![Alternative text](../../_images/news/angie-console-mi-razrabativaem-novii-produkt.jpg)![Alternative text](../../_images/news/angie-console-mi-razrabativaem-novii-produkt.jpg) 我们的目标是创建一个用户友好且直观的负载均衡系统控制台。为此，我们正在开发一个新产品——Angie Console。这是一个用于管理Web服务器集群的集中式系统，具有监控和动态配置功能。产品即将发布，敬请关注！ # https://cn.angie.software/news/articles/angie-i-Nplus1-issleduyut-opensors-v-rossii.md # Angie 和 N+1 探索俄罗斯开源世界 *04.08.2023* 我们将与 N+1 编辑团队一起，用一年时间探索使用开源原则的软件开发世界。 ![Alternative text](../../_images/news/angie-i-Nplus1-issleduyut-opensors-v-rossii.jpg)![Alternative text](../../_images/news/angie-i-Nplus1-issleduyut-opensors-v-rossii.jpg) 大家好！ 近年来，俄罗斯越来越多地思考如何开发开源项目——可信赖的代码仓库正在建立，法规框架正在完善，专门的组织机构也在成立，承诺培育开源项目开发的生态系统。 [Angie 网络服务器](https://wbsrv.ru) 最初就被设计为一个开源项目——我们相信这能确保我们产品的高质量。然而，在发布第一个版本、与合作伙伴对话以及内部讨论期间，我们意识到并非所有人都理解什么是开源软件，以及它为什么如此重要。 我们将与俄罗斯最权威的科技媒体 N+1 的编辑团队一起，用一年时间探索使用开源原则的软件开发世界。我们将讨论这类项目的历史、经济、安全性以及哲学和伦理。我们将研究国家和大型企业的利益如何影响这些项目。当然，我们也将努力理解这些项目在俄罗斯的未来发展。 我们工作的最终目标是创建俄罗斯首个关于开源项目开发文化的研究。我们邀请所有真正关心这个话题的人加入讨论。 在我们准备第一批材料期间（将在9月份开始发布，届时我们会再次公告），您可以在 [N+1 网站](https://nplus1.ru) 上阅读其他新闻。例如关于 [为了科学研究而让人体模型出汗的实验](https://nplus1.ru/news/2023/07/25/sweating-robot)。 # https://cn.angie.software/news/releases/angie-i-angie-pro-obnovleni-dlya-uluchsheniya-zashchity-ot-dos-ataki.md # Angie和Angie PRO针对DoS攻击的防护得到增强 *18.10.2023* Web Server公司宣布发布Angie和Angie PRO的1.3.1版本。 Web Server公司宣布发布Angie和Angie PRO的1.3.1版本。 此次发布包含了多项变更，其中包括对HTTP/2协议数据流的限制，这增强了对"HTTP/2 Rapid Reset" DoS攻击的防护。Web Server公司认为Angie并不受此问题影响，但仍决定采取额外的预防措施。 Angie 1.3.1和Angie PRO 1.3.1代表了俄罗斯Web服务器发展的重要一步。更新后的版本提供了更高水平的安全性和性能。 早些时候，在10月11日，谷歌报告 <[https://www.opennet.ru/opennews/art.shtml?num=59901/](https://www.opennet.ru/opennews/art.shtml?num=59901/)> 其基础设施遭受了最大规模DDoS攻击，攻击强度达到每秒3.98亿次请求。这种新的攻击技术被命名为"Rapid Reset"，它利用了HTTP/2提供的多路复用功能，允许在已建立的连接中形成请求流，无需开启新的网络连接，也无需等待数据包确认。该漏洞被视为HTTP/2协议缺陷的结果，该协议在其规范中指出，当尝试打开过多流时，应该只取消超出限制的流，而不是关闭整个网络连接。 # https://cn.angie.software/news/releases/angie-i-angie-pro-poluchili-obnovlenie-1-7-0.md # Angie 和 Angie PRO 收到更新 1.7.0 *20.09.2024* 新版本的开源网页服务器 Angie 1.7.0 和商业版 Angie PRO 1.7.0 现已推出，提供显著的改进和新功能。 Angie 开源网页服务器及其商业版 Angie PRO 的 1.7.0 版本已发布。此更新包括多个增强功能，以提高服务器的可靠性和弹性，同时从 freenginx 项目移植了一些功能。 基于客户的请求，我们引入了三个关键特性： 1. **DNS 查询统计**：跟踪内置缓存解析器发出的外部 DNS 查询的统计信息。 2. **证书类型变量**：显示所使用证书类型的信息，这在具有多种证书类型的配置中尤为有用。 3. **后端移除时强制断开连接**：类似于 NGINX Plus 中的 proxy_session_drop 的功能，但具有几项改进： - 在流模块和 HTTP 模块中均有效，对于长期 WebSocket 连接特别有帮助。 - 允许配置强制关闭连接前的等待时间。 - 在 Angie PRO 中，可以通过 API 动态为每个服务器启用此模式。 此外，Angie PRO 还引入了增强的流量管理工具，包括新的负载均衡模式和错误修复。 # https://cn.angie.software/news/releases/angie-i-angie-pro-poluchili-obnovlenie-1.3.2.md # Angie和Angie PRO发布1.3.2更新 *24.11.2023* Web Server公司发布了Web服务器Angie及其商业版本Angie PRO的更新。 Web Server公司发布了Web服务器Angie及其商业版本Angie PRO的更新。在新版本1.3.2中，修复了与代理服务器相关的主动检查问题、Prometheus指标统计收集问题以及连接计数问题。 *"我们感谢向我们报告问题的用户，因此我们努力及时解决这些问题，并迅速回应论坛上的问题，"* 公司首席执行官Zaur Abasmirzoev表示。 # https://cn.angie.software/news/releases/angie-i-angie-pro-poluchili-obnovlenie-1.6.1.md # Angie 和 Angie PRO 发布 1.6.1 更新 *08.08.2024* Web Server公司发布了开源网络服务器 Angie 1.6.1 和其商业版本 Angie PRO 1.6.1。 Web Server公司发布了开源网络服务器 [Angie 1.6.1](https://cn.angie.software/oss_changes/#angie-1-6-1) 和其商业版本 [Angie PRO 1.6.1](https://cn.angie.software/pro_changes/#angie-pro-1-6-1)。这些版本针对 nginx 1.27 中新增的功能，改进了 [stream 模块 API](https://cn.angie.software/configuration/modules/http/http_api/#status-stream-server-zones-zone) 中的统计数据收集，同时修复了 [ACME 协议实现](https://cn.angie.software/configuration/modules/http/http_acme/) 中的一个缺陷以及缓存响应处理的一个问题。 这些修复的实现离不开用户的反馈，他们主动分享报告并告知我们所遇到的任何问题。我们努力回应通过 [论坛](https://forum.angie.support) 和 [GitHub](https://github.com/webserver-llc/angie/issues) 提交的所有错误报告和需求，并在规划新版本时参考这些反馈。 我们还采纳了另一个来自社区的建议：现在 Angie 不仅整合了来自原始 [nginx](https://nginx.org/) 的更改，还包含了其最新分支 [freenginx](https://freenginx.org/) 的更改；我们始终将快速响应各种改进并秉持开源精神公正地实施这些改进作为首要任务。 # https://cn.angie.software/news/angie-priglashaet-na-rabotu.md # Angie正在招聘 *28.05.2024* 大家好！我们想让全世界知道，我们也需要专业人士。 ![替代文本](../../_images/news/angie-priglashaet-na-rabotu.jpeg)![替代文本](../../_images/news/angie-priglashaet-na-rabotu.jpeg) 我们是一家年轻的软件供应商公司，我们需要你来征服这个世界。我们每天都在为此努力。 *— 嘿，Brain，我们今晚要做什么？* *— 我们要做的还是跟往常一样，Pinky，试图征服世界。* *© Pinky和Brain⁠⁠.* 你可以阅读和观看关于我们的内容： [Kommersant，nginx正在俄罗斯重建。](https://www.kommersant.ru/doc/5634072) [Vedomosti，首个俄罗斯网络服务器已被纳入国内软件注册。](https://www.vedomosti.ru/technology/articles/2023/05/24/976527-pervii-rossiiskii-veb-server-vnesen-v-reestr-otechestvennogo-po?shared_token=cbe20f6feeee8a5bcf52f077d2d6ad62b66e3917) [Habr，"网络服务器"推出ANIC——Kubernetes网络中的流量管理软件。](https://habr.com/news/744654/) 我们首席执行官Zaur Abasmirzoev在Forbes的一些专栏文章：[开发者市场：如何发展俄罗斯的GitHub。](https://www.forbes.ru/mneniya/491830-marketplejs-dla-razrabotcikov-kak-razvivat-rossijskij-github)，Forbes [开放源代码的封闭区域：中俄如何发展开源。](https://www.forbes.ru/tekhnologii/495635-zakrytye-zony-otkrytogo-koda-kak-kitaj-i-rossia-razvivaut-open-source) [与我们首席开发员Valentin Bartenev在Habr的访谈。](https://habr.com/articles/774274/) [Valentin Bartenev在HighLoad的演讲（YouTube）。](https://www.youtube.com/watch?v=CKHNqMawUiE) ![替代文本](../../_images/news/02-team_1.webp) 例如，在开源产品——Angie网络服务器中——我们的团队继续按照质量和稳定性的传统开发老牌nginx，扩展其功能以满足现代需求。请查看已累积的 [变更日志](https://wbsrv.ru/angie-pro/docs/#index-features-oss)。 对于开源产品，我们提供社区支持。无论我们在公司的角色如何，我们都会尽可能地监控各种平台——Telegram聊天、论坛、GitHub、技术博客的评论。我们不排斥与匿名人士沟通。我们还尝试在每年的HighLoad会上分享关于我们项目的更新。例如，如果开发人员能够做到，今年我们将推出WASM支持，并在会议上讨论这一点。 所有这些都是针对国际市场的长期战略，我们正在逐渐在使用统计中攀升。 下一个产品是基于Angie PRO的ANIC入口控制器的开发，因为这与我们在负载均衡系统（以及客户请求）上的发展方向一致。然后，我们逻辑上得出结论，我们需要将符合企业多样化需求的产品推向市场。具体而言： - 以虚拟设备形式提供的"负载均衡系统"类的盒装解决方案（未来还有硬件-软件解决方案） - 用于配置网络参数的Web面板，支持鼠标点击 - 面向工程师和集成的API/CLI - 全球服务器负载均衡——全球流量负载均衡（例如，在DNS级别，考虑接收流量的服务器状态） - 在L4-L7网络级别操作的高性能负载均衡器 - 一组组件，用于将盒装解决方案集成到L2-L3网络级别的网络拓扑中 最终，我们发展出了应用交付控制器（Angie ADC）——一个满足所有上述客户请求的产品类别。为了理解，你可以参考现有的产品，如Citrix Netscaler（ADC）或F5 Big-IP。该产品既有趣又庞大，我们绝对知道如何使其在俄罗斯和全球市场上具有竞争力。 简而言之，我们有几年的发展战略——我们想要实现什么，追求什么商业结果——并且我们始终遵循这一战略。 现在，让我们谈谈我们的开发过程是如何组织的。 对我们来说，里程碑是季度发布。我们尽量在所有产品中遵循这个时间表。例如，你可以在这里查看开源版本网络服务器的变更历史：[https://angie.software/oss_changes/](https://angie.software/oss_changes/)。公司的开发日程和所有预发布活动都与这些里程碑保持一致。甚至为作者版权的后勤工作也与之保持一致。 除了发布，我们还为公司设定每周几个目标，基本上围绕跨团队互动展开。我们尽量在短时间内专注于这些目标。每周至少一次，开发团队会举行内部状态会议。有时根据会议结果，我们会调整路线图。同时，团队之间没有每日站立会议或电话会议（或者我只是没听说过）。 我们还在公司举行每周一次的总会议（视频通话），每个团队分享他们的成功、失败以及任何帮助人们保持信息灵通的内容。总体而言，开放性和内部透明度相当高。与一些公司相比，这个水平极高。我们甚至要求财务人员以所有其他同事能够理解的方式解释他们的工作，让大家知道这些可怜的人在办公室里做什么。 这就是简单明了的工作和开发过程，然而，这需要同事们具备一定的独立性。哦——这就是责任。 我们的办公室位于莫斯科，维亚茨卡亚街。我们完全采用混合办公模式。偶尔会有勇敢的尝试在工作时间把大家聚在一起，但目前为止，唯一的机会是在公司活动期间。 让我们回到我们的产品在技术栈方面： ![替代文本](../../_images/news/05-portfolio.webp) - 我们用C语言编写Angie，并继续在Perl中进行测试。 - 内部包含Angie Pro的Angie入口控制器使用Go开发。 - Angie控制台作为虚拟设备的一部分，是一个经典的Web应用程序，包含后端和前端。使用Go、Python（测试）、Typescript、React、Next.js、Jest。 - 我们使用Ansible、Jenkins、qemu、Docker、rpm构建来构建一切。 - Angie ADC继承了上述所有内容，另外网络组件再次使用Go和BGP/VRRP等技术。 由此可见，我们正在寻找的专业人员的档案： - 后端和前端开发人员 - 测试工程师 - 技术写作人员 - 技术产品经理 除了技术团队外，我们还对能够区分Web服务器和数据库的经验丰富的销售专家感兴趣。是的，这是一句玩笑。 目前，Angie ADC团队的招聘是我们的优先事项。 我们正在有针对性地寻找加入我们团队的同事。我们甚至愿意考虑招聘一个团结的团队。但我们会谨慎选择——保持内部氛围的舒适性很重要。我们不容忍争吵，也不害怕工作冲突。我们知道如何区分这两者。 我们重视冷静和愿意来工作、创造，并在必要时学习的人，而不是围着咖啡机转（尽管我们办公室里确实有咖啡机）。团队领导是市场上该领域最优秀的专业人士。我们的同事都很出色。 薪资，通常所说，是有竞争力的。公司被列入认可的IT组织名录。 你可以写信至hr@wbsrv.ru。如果你不确定应该将询问发送到哪里，可以直接联系我，邮箱是zaur@wbsrv.ru，或者在Telegram上联系我@izaurio，以便我们互相认识。如果你觉得自己可能适合我们（或者我们适合你），请不要犹豫。无需发送标准简历；最好写1-2段关于你自己、你的经验和你的目标的内容。 总的来说，我想说的是：来和我们一起工作，让我们一起创造伟大的事物。 爱你的，Zaur Abasmirzoev。 # https://cn.angie.software/news/integrations/angie-pro-sertifitsirovan-dlya-os-rosa-chrome-12-server.md # Angie PRO 获得 ROSA Chrome 12 Server 操作系统认证 *01.12.2023* 俄罗斯网络服务器开发商Web Server与 ROSA IT 研究中心已确认 Angie PRO 网络服务器与 ROSA Chrome 12 Server 操作系统的兼容性，这一点已通过双方签发的证书得到证实，凸显了产品的高度兼容性和可靠性。 俄罗斯网络服务器开发商Web Server与 ROSA IT 研究中心已确认 Angie PRO 网络服务器与 ROSA Chrome 12 Server 操作系统的兼容性，这一点已通过双方签发的证书得到证实，凸显了产品的高度兼容性和可靠性。 该认证证书证明 Angie PRO 网络服务器满足 ROSA Chrome 12 Server 操作系统的所有要求，可以在企业环境中使用。这为用户提供了高效且安全工作的新机会。 Web Server在网络服务器开发方面拥有深厚的知识和丰富的经验，而 ROSA IT 研究中心则是操作系统和基础设施软件开发领域的领导者。 ROSA Chrome 是基于其自有仓库 ROSA 2021.1 构建的操作系统，该仓库为服务器、桌面和移动操作系统提供支持。ROSA Chrome 操作系统仓库是世界上最大的仓库之一，包含超过35,000个应用程序和组件。它支持 x86 和 ARMv8 硬件平台、e2k（Elbrus）和 RISC-V。 该操作系统的优势包括：安全性、在俄罗斯完全本地化的开发和支持、为 Windows 用户提供熟悉的工作环境、软件产品的开发和组装环境（ABF）、灵活的技术政策，以及被列入俄罗斯联邦数字发展、通信和大众传媒部维护的统一俄罗斯软件注册表，注册号为1607。 Angie PRO 网络服务器与 ROSA Chrome 12 Server 操作系统的兼容性是俄罗斯技术和产品发展的又一步，表明其可以与国外同类产品竞争。Web Server和 ROSA IT 研究中心将继续致力于产品的开发和功能的扩展。 此前，Angie 已通过了国产操作系统的兼容性认证：Red OS、Astra Linux Special Edition、Alt 及其 FSTEC 版本 Alt SP，并已被列入国产软件注册表（编号17604）。 **参考信息** ROSA IT 研究中心（NTC IT ROSA）是俄罗斯领先的信息技术开发商和供应商。该公司基于自有仓库 ROSA 2021.1 开发系统和基础设施软件。公司的技术栈能够满足国家和大型企业的广泛 IT 需求。产品组合包括操作系统 ROSA Chrome、ROSA Fresh、ROSA Barium、ROSA Cobalt 和 ROSA Mobile，ROSA 虚拟化平台、操作系统管理平台和混合虚拟基础设施。公司的产品已被列入俄罗斯数字发展部的国产软件注册表，并获得了相应的 FSTEC 证书，可处理机密信息。 www.rosalinux.ru # https://cn.angie.software/angie.md # Angie Angie 是 nginx 的一个自由分支，是一个强大且可扩展的 web 服务器。 代码在公共仓库中以 BSD 类型的自由许可证开放。 Angie 是一个强大且可扩展的 web 服务器，发展了 nginx 的理念： - 由前 nginx 开发者创建，旨在朝着一个新方向发展。 - 作为前身的替代品提供， 无需重新配置和模块重开发。 - 包含 [nginx |nginxversion|](https://nginx.org/en/CHANGES) 的所有功能 并增加了一些新功能。 [二进制包](https://cn.angie.software//angie/docs/installation/oss_packages.md) 可用于 各种操作系统和架构，以及 [Docker 镜像](https://cn.angie.software//angie/docs/installation/docker.md)。项目代码在 [公共仓库](https://cn.angie.software//angie/docs/development.md) 中开放，遵循 BSD 类型的自由许可证。 动态模块用于扩展基本功能。 它们经过测试、编译， 也可以在 [我们的仓库](https://cn.angie.software//angie/docs/installation/index.md#install-dynamicmodules) 中获取。 **Angie |angie_version|** 于 **|angie_release_date|** 发布。 新版本每季度发布； 重要修复和改进按时发布。 另见 [版本历史](https://cn.angie.software//angie/docs/oss_changes.md)。 您可以在 [我们的网站](docs/) 上找到完整文档。 ## Why Angie? [HTTP/3 协议](https://cn.angie.software//angie/docs/configuration/modules/http/http_v3.md) 支持客户端连接和与 [代理服务器](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md) 的连接，允许从不同方面独立使用不同的协议 (HTTP/1.x、HTTP/2、HTTP/3)。 通过 REST 风格的 [API 接口](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) 以 JSON 格式访问有关 web 服务器的基本信息、其 [配置](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files) 和 [统计信息](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics)，包括代理服务器、客户端连接、共享内存区等许多其他内容。 支持 [Prometheus 格式](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3) 和 [可自定义模板](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template)。 自动代理和负载均衡运行在 [Docker 容器](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) 中的服务。 通过 `slow_start` 选项实现 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令的功能。 通过内置的 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md) 支持获取 TLS 证书。 用于通过浏览器监控服务器的 [Console Light](https://cn.angie.software//angie/docs/configuration/monitoring.md) 控制台。 在线示例: [https://console.angie.software/](https://console.angie.software/) [会话绑定模式](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)，其中会话中的所有请求都路由到同一代理服务器。 流模块的 [mqtt_preread](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) 指令，扩展 MQTT 协议的授权和负载均衡能力。 为我们自己的模块和第三方模块提供现成的 [包](https://cn.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules)。 ## Support and Development 如果您遇到问题但在 [文档](docs/) 中找不到解决方案，请在 [社区论坛](https://forum.angie.support/) 或在 Telegram 的 [支持聊天](https://t.me/angie_support) 中提问。 通过 [GitHub](https://github.com/webserver-llc/angie/issues) 分享新功能的想法或您自己的改进。 ## Legal Information * [Angie 软件产品许可证](https://cn.angie.software//angie/license-angie.md) * [许可组件存在声明](https://cn.angie.software//angie/doc-license.md) * [贡献者许可协议](https://cn.angie.software//angie/contributor-agreement.md) # https://cn.angie.software/news/articles/anic-angie-ingress-controller.md # ANIC - Angie Ingress Controller *11.08.2023* 今天我们将讨论Angie Ingress Controller（ANIC）- Web Server公司为简化Kubernetes中的流量管理而推出的解决方案。 ![Alternative text](../../_images/news/anic-angie-ingress-controller.jpg)![Alternative text](../../_images/news/anic-angie-ingress-controller.jpg) Kubernetes是一个流行的容器编排系统。它的任务之一是将请求路由到系统内的应用程序。这是通过两个组件来实现的：Ingress和Ingress Controller。Ingress是请求的入口点，有助于路由和负载均衡流量。但是，要使其正常运行，需要Ingress Controller。我们将解释Web Server公司的新产品\*\*Angie Ingress Controller（ANIC）\*\*如何帮助简化Kubernetes中的流量管理。 Ingress Controller允许您根据指定的设置管理代理和负载均衡。当设置发生变化时，Ingress Controller会收到信号并根据新数据重新配置Ingress。这样，我们就可以通过修改设置来管理对运行在Kubernetes集群中的应用程序的外部请求。Ingress可以配置为将外部URL绑定到内部服务、提供流量均衡以及处理SSL/TLS连接。通常，反向代理服务器被用作Ingress。 **Angie Ingress Controller（ANIC）** 支持两种安装方式：DaemonSet和Deployment。 如果您需要安装单个Ingress Controller实例并动态更改实例数量，请使用Deployment。如果您需要在集群的每个节点上安装Ingress Controller，请使用DaemonSet。 ANIC使用Angie PRO网络服务器作为Ingress。它是世界上最强大的网络服务器之一。Angie PRO有效地解决了分配给Ingress的核心任务。大量的设置允许灵活代理，并能够通过REST接口动态管理上游组设置。此外，Angie PRO还可以作为L4-L7负载均衡器。 **除了Angie PRO的标准功能外：** * 它允许创建虚拟服务器并具有众多灵活的设置。 * 它支持HTTP/2协议，使您能够在监听套接字上接受HTTP/2连接。 * 它支持会话持久性（粘性会话），确保客户端会话中的所有请求都绑定到上游组中的单个服务器。 * 流量分割允许进行A/B测试和金丝雀部署。 * 它通过RESTful接口提供广泛的统计信息和实时监控。以JSON格式提供基本服务器信息，以及客户端连接、共享内存区域、DNS查询、HTTP请求、HTTP响应缓存、流模块会话、http_upstream和其他模块区域的统计信息。 * 它允许通过REST接口动态管理上游组设置。 有关更多详细信息，您可以 [访问我们的网站了解](https://wbsrv.ru/anic/)。 # https://cn.angie.software/anic.md # ANIC ANIC 是 NGINX Ingress Controller 的一个分支，集成了 Angie PRO 的功能。 Angie Ingress Controller (ANIC) 是一个用于管理 Kubernetes 中容器化应用流量的解决方案。 ANIC 部署并在集群内运行，管理 Ingress 功能，并能够配置流量处理规则。该产品基于 Angie PRO 的能力，允许构建安全、可扩展、高性能的环境，提供专业迁移服务和俄语技术支持的俄罗斯解决方案。 **ANIC |anic_pdf_version|** 已于 ``` |anic_release_date| ``` 发布。 ## 为什么选择 ANIC？ | 功能 | ANIC | K8S Ingress Controller | NGINX Ingress Controller | Kong Ingress Controller | Traefik | Istio | HAProxy | Contour | |-----------------------|---------|--------------------------|----------------------------|---------------------------|-----------|---------|-----------|-----------| | Prometheus 格式指标 | | | | | | | | | | 粘性会话 | | | | | | | | | | 日志的变量 | | | | | | | | | | 通过注释配置 TLSPassthrough | | | | | | | | | | 对 Ingress 实体使用片段 | backlog | | | | | | | | | OpenID Connect (OIDC) | | | | | | | | | | 路径的 JWT 验证配置 | | | | | | | | | | 通过注释添加上游参数 | backlog | | | | | | | | | 通过注释添加粘性路由参数 | backlog | | | | | | | | | 读取 DOCKER 标签以便在容器中使用 | backlog | | | | | | | | | OpenTelemetry | backlog | | | | | | | | | OpenTracing | backlog | | | | | | | | | HTTP3 | backlog | | | | | | | | ## 系统要求 除了常见的发行版外，还支持俄罗斯操作系统，如 RED OS、Astra Linux、Alt 和 ROSA。完整的列表可以在 [此链接](https://cn.angie.software//angie/docs/installation/oss_packages.md) 找到。 ## 技术支持 我们提供两种技术支持选项：标准的工作时间支持和企业支持——提供 24/7 的支持，确保在您需要时随时可用。 ## 随附文档 PDF 文档（俄语）： - [`ANIC 安装指南`](https://cn.angie.software//anic/ANIC_|anic_pdf_version|_installation_guide.pdf) - [`ANIC 功能规格`](https://cn.angie.software//anic/ANIC_|anic_pdf_version|_functional_description.pdf) - [`ANIC 操作指南`](https://cn.angie.software//anic/ANIC_|anic_pdf_version|_operating_guide.pdf) ## 许可证购买 该软件产品以商业许可证分发。 有关软件价格、购买条件以及许可证协议的信息, 可以通过以下电子邮件地址写信给我们: [info@wbsrv.ru](mailto:info@wbsrv.ru)。 # https://cn.angie.software/news/articles.md # 文章 ## [Angie 启用 WebAssembly 支持](https://cn.angie.software//news/articles/wasm.md) *29.11.2024* 此次更新使得可以构建 WASM 模块，以便 Angie 加载并在服务器配置中使用它们。 ## [Angie新增功能助力更好的Web服务器监控](https://cn.angie.software//news/articles/novoe-v-angie-dlya-luchshego-monitoringa.md) *17.11.2023* 2023年9月，我们通过添加Angie Console Light为Angie web服务器引入了新的监控组织方式。 ## [多方位监控 Angie —— nginx Web 服务器的分支](https://cn.angie.software//news/articles/multifaceted-monitoring.md) *27.09.2023* Angie 监控能力的详细概述：用于统计的内置 API、 用于实时可视化的 Console Light，以及无需第三方模块的 Prometheus 集成。 ## [认识 Console Light](https://cn.angie.software//news/articles/vstrechaite-console-light.md) *27.09.2023* 我们推出了一款用于实时活动监控的轻量级可视化控制台。 ![Alternative text](../../_images/news/vstrechaite-console-light.jpg) ## [在俄罗斯推广开源](https://cn.angie.software//news/articles/populyarizuem-opensource-v-rossii.md) *14.09.2023* 我们与科学出版物N+1的朋友们一起启动了一个在俄罗斯推广开源的特别项目。 ![Alternative text](../../_images/news/populyarizuem-opensource-v-rossii.jpeg) ## [Angie与中国的经验](https://cn.angie.software//news/articles/opyt-raboti-angie-s-kitaem.md) *04.09.2023* 当俄罗斯正在积极制定"本土"开源项目发展计划时，中国也在积极发展其自己的开源项目。 ![Alternative text](../../_images/news/opyt-raboti-angie-s-kitaem.jpeg) ## [Angie 与 nginx 的异同点](https://cn.angie.software//news/articles/shodstva-i-razlichiya-angie-i-nginx.md) *25.08.2023* Angie 项目和 Angie PRO 产品与其前身 nginx 及其商业版本 NGINX Plus 的关系。 ![Angie vs. nginx](../../_images/news/shodstva-i-razlichiya-angie-i-nginx.webp) ## [ANIC - Angie Ingress Controller](https://cn.angie.software//news/articles/anic-angie-ingress-controller.md) *11.08.2023* 今天我们将讨论Angie Ingress Controller（ANIC）- Web Server公司为简化Kubernetes中的流量管理而推出的解决方案。 ![Alternative text](../../_images/news/anic-angie-ingress-controller.jpg) ## [Angie 和 N+1 探索俄罗斯开源世界](https://cn.angie.software//news/articles/angie-i-Nplus1-issleduyut-opensors-v-rossii.md) *04.08.2023* 我们将与 N+1 编辑团队一起，用一年时间探索使用开源原则的软件开发世界。 ![Alternative text](../../_images/news/angie-i-Nplus1-issleduyut-opensors-v-rossii.jpg) # https://cn.angie.software/angie/docs/installation/external-modules/auth-jwt.md # Auth JWT 该模块通过使用指定密钥验证提供的 JSON Web Token (JWT) 来实现客户端授权。 - 支持 JSON Web Signature (JWS)。 - 可用于通过 OpenID Connect 进行身份验证。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-auth-jwt` - Angie PRO：`angie-pro-module-auth-jwt` ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_auth_jwt_module.so; ``` ## 配置示例 ```nginx location / { auth_jwt "closed site"; auth_jwt_key_file conf/keys.json; } ``` 完整配置示例可在以下位置获取： [https://github.com/kjdev/nginx-auth-jwt/tree/main/example](https://github.com/kjdev/nginx-auth-jwt/tree/main/example) ## 其他信息 详细文档和源代码可在以下位置获取： [https://github.com/kjdev/nginx-auth-jwt](https://github.com/kjdev/nginx-auth-jwt) # https://cn.angie.software/angie/docs/installation/external-modules/auth-ldap.md # Auth LDAP LDAP 模块支持跨多个 LDAP 服务器进行身份验证。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-auth-ldap` - Angie PRO：`angie-pro-module-auth-ldap` ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_auth_ldap_module.so; ``` ## 配置示例 ```nginx http { ldap_server test1 { url ldap://192.168.0.1:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person); binddn "TEST\\LDAPUSER"; binddn_passwd LDAPPASSWORD; group_attribute uniquemember; group_attribute_is_dn on; require valid_user; } ldap_server test2 { url ldap://192.168.0.2:3268/DC=test,DC=local?sAMAccountName?sub?(objectClass=person); binddn "TEST\\LDAPUSER"; binddn_passwd LDAPPASSWORD; group_attribute uniquemember; group_attribute_is_dn on; require valid_user; } server { listen 8000; server_name localhost; auth_ldap "Forbidden"; auth_ldap_servers test1; auth_ldap_servers test2; location / { root html; index index.html index.htm; } } } ``` ## 其他信息 详细文档和源代码可在此处获取： [https://github.com/kvspb/nginx-auth-ldap](https://github.com/kvspb/nginx-auth-ldap) # https://cn.angie.software/angie/docs/installation/external-modules/auth-pam.md # Auth PAM 该模块添加了对 PAM 身份验证的支持。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-auth-pam` - Angie PRO：`angie-pro-module-auth-pam` ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_auth_pam_module.so; ``` ## 配置示例 ```nginx location /secure { auth_pam "Secure Zone"; auth_pam_service_name "angie"; } ``` 例如，要在 LDAP 服务器上对用户进行身份验证（使用 `pam_ldap.so` 模块），`/etc/pam.d/angie` 文件可能包含以下内容： ```none auth required /lib/security/pam_ldap.so account required /lib/security/pam_ldap.so ``` ## 附加信息 详细文档和源代码可在以下位置获取： [https://github.com/sto/ngx_http_auth_pam_module](https://github.com/sto/ngx_http_auth_pam_module) # https://cn.angie.software/angie/docs/installation/external-modules/auth-spnego.md # Auth SPNEGO 该模块提供对 SPNEGO 的支持。 目前仅支持通过 GSSAPI 进行 Kerberos 身份验证。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-auth-spnego` - Angie PRO:`angie-pro-module-auth-spnego` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_auth_spnego_module.so; ``` ## 其他信息 详细文档和源代码可在以下位置获取: [https://github.com/stnoonan/spnego-http-auth-nginx-module](https://github.com/stnoonan/spnego-http-auth-nginx-module) # https://cn.angie.software/angie/docs/installation/external-modules/auth-totp.md # Auth TOTP 该模块实现基于时间的一次性密码 (TOTP) 算法，并提供短时有效的一次性密码机制。 特性： - 使用 TOTP 的标准 HTTP 认证。 - 在 TOTP 过期后基于 cookie 跟踪已认证客户端。 - 可配置的密钥、时间基准、时间步长和截断长度，用于生成 TOTP。 - 可配置的 TOTP 校验时间窗口。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-auth-totp` - Angie PRO：`angie-pro-module-auth-totp` ## 加载模块 要使用该模块，请在 `main{}` 上下文中加载它： ```nginx load_module modules/ngx_http_auth_totp_module.so; ``` ## 配置示例 ```nginx server { listen 80; location /protected { auth_totp_realm "Protected"; auth_totp_file /etc/angie/totp.conf; auth_totp_length 8; auth_totp_reuse off; auth_totp_skew 1; auth_totp_step 1m; auth_totp_cookie "totp-session"; auth_totp_expiry 1d; } } ``` ## 其他信息 详细文档和源代码可在以下位置获取： [https://github.com/61131/nginx-http-auth-totp](https://github.com/61131/nginx-http-auth-totp) # https://cn.angie.software/news/integrations/bezopastnost-configuracii-angie-pro-kontroliruet-x-config.md # X-Config负责监控Angie PRO配置的安全性 *08.02.2024* Angie PRO的安全配置标准将使客户能够自动监控Web服务器设置，接收按优先级排序的漏洞识别报告，并提供修复建议。 俄罗斯现代信息安全软件产品开发商Spacebit已将Angie PRO Web服务器添加到其配置安全由X-Config保障的软件列表中。 X-Config系统旨在检测和消除软件配置文件中的漏洞。X-Config允许对系统和应用软件配置的整个管理过程进行结构化，从IT基础设施分析到监控已识别漏洞的实际修复，并使设置符合安全配置的最佳实践和监管要求。 Spacebit开发的Angie PRO安全配置标准将使客户能够自动监控Web服务器设置，接收按优先级排序的漏洞识别报告，并提供修复建议。得益于灵活的配置机制，信息安全专家可以对标准进行修改并制定企业安全配置策略。使用X-Config将显著提高Angie PRO处理、负载均衡和代理事务的基础设施的信息安全水平，这对于具有关键信息基础设施和高负载基础设施的企业尤为重要。 "在Web服务器遭受攻击密度增加的背景下，其配置的安全性已成为组织网络安全的基本要素之一。考虑到采用经认证的俄罗斯基础设施软件替代品的趋势，为Angie PRO Web服务器开发安全配置标准是保护俄罗斯基础设施的重要方面，"Spacebit的X-Config产品经理Valery Ledovskoy如是说。 # https://cn.angie.software/angie/docs/installation/external-modules/brotli.md # Brotli 这是一组两个模块: - `ngx_brotli_filter` — 用于即时压缩响应。 - `ngx_brotli_static` — 用于提供预压缩文件。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-brotli` - Angie PRO:`angie-pro-module-brotli` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_brotli_filter_module.so; load_module modules/ngx_http_brotli_static_module.so; ``` ## 动态压缩的配置示例 ```nginx server { listen 80 default_server; brotli on; brotli_comp_level 1; brotli_types text/plain text/css; location / { root /usr/share/angie/html; index index.html; } } ``` ## 演示准备 首先,让我们放置测试文件 `war-and-peace.txt`: ```console $ ls -l /usr/share/angie/html/ total 3292 -rw-r--r-- 1 root root 497 Feb 13 07:40 50x.html -rw-r--r-- 1 root root 543 Feb 13 07:40 index.html -rw-r--r-- 1 root root 3359405 Feb 26 12:47 war-and-peace.txt ``` ```console $ mkdir tmp ``` 请求压缩文件: ```console $ curl -s -H 'Accept-encoding: br' -o tmp/war-and-peace.br localhost/war-and-peace.txt ``` ```console $ ls -l tmp/ total 1092 -rw-r--r-- 1 asv asv 1115616 Feb 26 16:52 war-and-peace.br ``` ## 提供预压缩文件的配置示例 ```nginx server { listen 80 default_server; brotli_static on; brotli_types text/plain text/css; location / { root /usr/share/angie/html; index index.html; } } ``` ## 移动预压缩文件 ```console $ sudo mv tmp/war-and-peace.br /usr/share/angie/html/war-and-peace.txt.br $ ls -l /usr/share/angie/html/ total 4384 -rw-r--r-- 1 root root 497 Feb 13 07:40 50x.html -rw-r--r-- 1 root root 543 Feb 13 07:40 index.html -rw-r--r-- 1 root root 3359405 Feb 26 12:47 war-and-peace.txt -rw-r--r-- 1 root root 1115616 Feb 26 16:57 war-and-peace.txt.br ``` 请求压缩文件: ```console $ curl -s -H 'Accept-encoding: br' -o tmp/war-and-peace.br localhost/war-and-peace.txt ``` ```console $ ls -l tmp/ total 1092 -rw-r--r-- 1 asv asv 1115616 Feb 26 17:13 war-and-peace.br ``` ## 组合动态和静态压缩 在一个配置中,可以组合使用动态压缩(`brotli on`)和静态选择(`brotli_static on`)。在这种情况下,系统将首先查找相应的静态压缩文件。如果找不到这样的文件,将对请求中指定的文件进行动态压缩。 ## 附加信息 指令的完整文档和源代码可在以下位置获取: [https://github.com/google/ngx_brotli](https://github.com/google/ngx_brotli)。 # https://cn.angie.software/vacancies/business-assistant.md # 商务助理 我们是 Angie Software 团队。公司的核心成员是参与了 nginx 早期开发的资深工程师，他们如今正在打造 nginx 的演进继任者——Angie。我们的产品已经在全球范围内获得越来越多的认可，我们也为自己设定了一个雄心勃勃的目标：超越 F5、Citrix、Radware 这样的行业巨头。 我们的文化是非正式的、扁平的：大家平等交流，没有官僚作风，也没有多余的繁文缛节。决策迅速做出，论据比头衔更重要。 ## 您将做什么： - 参与公司战略项目的落地执行； - 根据总经理的要求收集、分析并整理信息； - 撰写分析简报； - 编写项目进展报告； - 制作演示文稿、报告以及其他材料； - 跟进总经理交办的任务与指示的执行情况； - 保障总经理与各部门之间的高效沟通； - 规划并协调总经理的工作日程； - 组织各类会议和团队活动； - 与公司各层级员工保持有效协作。 ## 我们想招的人： - 拥有至少 3 年商务助理、私人助理或运营经理岗位的工作经验； - 精通文书工作和商务沟通礼仪； - 熟练使用电脑（MS Office: Word, Excel, PowerPoint）； - 善于处理大量信息，并能在多任务并行的状态下高效推进工作； - 具备出色的规划、组织与跟进控制能力； - 善于团队协作，能够与公司不同部门顺畅对接； - 拥有全流程项目协调经验，能够从零搭建流程或对现有流程进行优化改造。 ## 我们提供： - 真正影响一款世界级产品的机会，看到您的决策落地，而不必承受大公司的惯性； - 在一支业内公认的专家团队中工作，团队重视专业能力、主动性和担当； - 扁平结构，您的声音真正被重视，官僚作风不复存在； - 有竞争力的薪资、补充医疗保险、报销培训和会议费用——我们支持您的职业成长； - 已认证的 IT 企业资质和透明的工作条件。 **工作形式：** 混合办公或全坐班（可商议），萨维奥洛夫斯卡娅（Савёловская）地铁站，Factoria 商务中心。 如果您感兴趣，请将英文简历发送至 [hr@wbsrv.ru](mailto:hr@wbsrv.ru)。 #### NOTE 我们仅接受英文简历，请用英文提交您的简历。 # https://cn.angie.software/angie/docs/installation/external-modules/cache-purge.md # 缓存清除 允许清除缓存内容。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie: `angie-module-cache-purge` - Angie PRO: `angie-pro-module-cache-purge` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_cache_purge_module.so; ``` ## 配置示例 ```nginx log_format test_cache '[$time_local] "$request" ' '$status $body_bytes_sent rt="$request_time" ' 'ucs="$upstream_cache_status" us="$upstream_status" ' 'ubr=$upstream_bytes_received'; proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:10m; server { listen 80 default_server; location / { access_log /var/log/angie/cache-access.log test_cache; proxy_pass http://127.0.0.1:8080; proxy_cache cache_zone; proxy_cache_valid 10m; proxy_cache_key $uri$is_args$args; proxy_cache_purge PURGE from 127.0.0.1; } } ``` ## 演示准备 从服务器请求文件: ```console $ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt ``` 检查缓存(MISS — 文件未在缓存中找到): ```console [05/Mar/2025:17:44:24 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.001" ucs="MISS" us="200" ubr=752 ``` 重新请求(HIT — 文件从缓存中提供): ```console $ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt ``` ```console [05/Mar/2025:17:46:02 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.000" ucs="HIT" us="-" ubr=- ``` ## 清除缓存 ```console $ curl -X PURGE http://127.0.0.1/storage/* Successful purge

Successful purge

Key : /storage/*

``` 清除缓存后请求文件(MISS — 文件再次加载): ```console $ curl -s -o testf1.txt http://127.0.0.1/storage/testf1.txt ``` ```console [05/Mar/2025:17:52:05 +0300] "GET /storage/testf1.txt HTTP/1.1" 200 519 rt="0.002" ucs="MISS" us="200" ubr=752 ``` ## 单独缓存清除位置的配置示例 ```nginx proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:10m; map $uri $wpurgeuri { "~/purge(?/.*)" $wpurge; default $uri; } server { listen 80 default_server; location / { access_log /var/log/angie/cache-access.log test_cache; proxy_pass http://127.0.0.1:8080; proxy_cache cache_zone; proxy_cache_valid 10m; proxy_cache_key $uri$is_args$args; } location /purge { allow 127.0.0.1; deny all; proxy_cache_purge cache_zone $wpurgeuri$is_args$args; } } ``` 在这种情况下清除缓存的请求: ```console $ curl -X PURGE http://127.0.0.1/purge/storage/* ``` ## 附加信息 指令的完整文档和源代码可在以下位置获取: [https://github.com/nginx-modules/ngx_cache_purge](https://github.com/nginx-modules/ngx_cache_purge) # https://cn.angie.software/angie/docs/installation/external-modules/cgi.md # CGI 该模块添加了对 CGI 的支持。 需要注意的是,CGI **不** 适用于: - 高 QPS; - 大流量; - 高并发。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-cgi` - Angie PRO:`angie-pro-module-cgi` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_cgi_module.so; ``` ## 配置示例 ```nginx server { listen 80; root /usr/share/angie/html; index index.html index.htm; location /cgi { alias /usr/share/angie/cgi-bin; cgi on; } } ``` ## 测试脚本 一个示例测试可执行脚本 `test.sh`: ```bash #!/bin/sh echo "Content-Type: text/plain" # Add header to the response echo "" # Separator between headers and body of the response # Environment variables echo "query string: $QUERY_STRING" echo "server addr: $SERVER_ADDR" echo "server port: $SERVER_PORT" # Request headers via environment variables echo "http host: $HTTP_HOST" echo "http accept: $HTTP_ACCEPT" echo "http Some-Field: $HTTP_SOME_FIELD" body=$(cat) # Reads the request body into a variable echo "Request body: $body" ``` ## 放置脚本 根据配置,脚本必须放置在 `/usr/share/angie/cgi-bin/` 目录中。 该文件必须具有读取和执行权限。 ## 请求执行示例 ```console $ curl -H 'Some-Field:some text' -d '{"key1":"value1", "key2":"value2"}' -i \ 'http://127.0.0.1/cgi/hello.sh?a=valueA&b=valueB' HTTP/1.1 200 OK Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Transfer-Encoding: chunked Connection: keep-alive Content-Type: text/plain query string: a=valueA&b=valueB server addr: 127.0.0.1 server port: 80 http host: 127.0.0.1 http accept: */* http Some-Field: some text Request body: {"key1":"value1", "key2":"value2"} ``` ## 其他信息 详细文档和源代码可在以下位置获取: [https://github.com/pjincz/nginx-cgi](https://github.com/pjincz/nginx-cgi) # https://cn.angie.software/angie/docs/configuration/cluster.md # Angie 集群设置 本指南介绍了创建具有自动配置同步和虚拟 IP 地址故障转移的容错 Angie 集群的过程。 ## 准备集群节点以进行同步 第一步是通过配置用户账户并确保服务器之间的安全访问来准备所有集群节点。 ### 配置用户和访问权限 在所有节点上创建一个用户(例如,:samp:angie-ha-sync)并赋予 `sudo` 权限: ```console $ sudo adduser angie-ha-sync ``` 如有必要,设置密码: ```console $ sudo passwd angie-ha-sync ``` #### NOTE 在某些操作系统中(例如 Alt Linux), 您应该将用户添加到 `wheel` 组: ```console $ sudo usermod -a -G wheel angie-ha-sync ``` 在 Astra Linux 中启用 MAC 时要使用 `rsync`,请设置 正确的完整性级别: ```console $ sudo pdpl-user -i 63 angie-ha-sync ``` 配置无密码 sudo: ```console $ echo "angie-ha-sync ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers ``` 在主节点上,创建 SSH 密钥并将其复制到备份节点: ```console $ su - angie-ha-sync $ ssh-keygen -t rsa $ ssh-copy-id angie-ha-sync@node2_hostname ``` #### WARNING 在复制 SSH 密钥之前,请确保 `/etc/ssh/sshd_config` 文件中有以下选项: `PasswordAuthentication yes` 设置基于密钥的访问后,将该值设置为 `no` 以提高 安全性。 #### NOTE 对于 Angie 配置的交叉同步,请将用户密钥 复制到所有节点: ```console $ scp -p ~angie-ha-sync/.ssh/id_rsa angie-ha-sync@node2_hostname:.ssh/ ``` ## 安装 Angie 和 angie-ha-sync 准备好节点后,您需要安装主要的集群组件: Angie 和配置同步包。 根据您的系统包的说明在所有节点上配置仓库: - [Angie 说明](https://cn.angie.software//angie/docs/installation/oss_packages.md#oss-packages) - [Angie PRO 说明](https://cn.angie.software//angie/docs/installation/pro_packages.md#pro-packages) ### 安装 angie-ha-sync 配置同步模块在以下包中可用: - Angie:`angie-ha-sync` - Angie PRO:`angie-pro-ha-sync` #### NOTE 在干净的系统上安装此包时, 相应的 `angie` 或 `angie-pro` 包 也将作为依赖项安装。 在所有节点上,使用您的操作系统包管理器安装该包,例如: ```console $ sudo {apk|apt|pkg|yum|zypper} {add|install} angie-pro-ha-sync ``` ## 配置配置同步 下一步是设置集群节点之间配置文件的自动同步。 #### NOTE 同步原则: - 通过 `rsync` 执行同步。 - 仅在 Angie 服务运行时发生。 - 手动执行(命令 `angiehasync -Sd`)。 - 单向工作:从主节点到备份节点。 - `rsync` 以守护进程模式运行。 ### 配置 `rsync` 在节点上创建 `rsync` 配置(`/etc/rsyncd.conf`): ```ini [angie] # Angie 配置目录 path = /etc/angie # 用于同步的用户 uid = angie-ha-sync # 用户组 gid = angie-ha-sync # 允许连接的 IP 或子网 hosts allow = 10.21.8.0/24 # 拒绝所有其他 hosts deny = * ``` 根据操作系统,启动守护进程: ```console $ sudo service rsyncd start # 或 $ sudo service rsync start ``` #### NOTE 对于某些系统,有现成的说明: - [Alt](https://www.altlinux.org/Настройка_rsync-сервера) - [Astra](https://wiki.astralinux.ru/pages/viewpage.action?pageId=41191598#id-Архивированиеивосстановлениефайловссохранениеммандатныхатрибутов-RSYNC) ### 配置同步文件 编辑 `/etc/angiehasync/angiehasync.conf`: ```ini M_NODE="" # 此节点的主机名或 IP TARGET_HOSTS="" # 用于同步的主机/IP 列表(空格分隔)。 # 在备份节点上可以省略。 SSH_USER="user" # 用于同步的用户(具有管理员权限) SSH_ID="/home/$SSH_USER/.ssh/id_rsa" # 私钥路径 ``` #### NOTE 对于交叉同步, 在所有节点上填写 `TARGET_HOSTS` 列表; 但是,不要在列表中包含当前正在配置的节点。 ### 配置 Angie 的健康检查 在 Angie 配置中添加健康检查块 (`/etc/angie/angie.conf`): ```ini server { listen unix:/tmp/angie_hcheck.sock; # 用于检查的 Unix 套接字 access_log off; error_log /dev/null; default_type text/plain; return 200 'ok\n'; } ``` 启动 Angie: ```console $ sudo angie -t && sudo service angie start ``` 启动同步: ```console $ sudo angiehasync -Sd ``` #### NOTE 该脚本将自动检查配置,与所有节点执行同步,并应用它。 ## 配置 Keepalived 为了在集群节点之间实现自动故障转移,使用 Keepalived — 一个用于管理虚拟 IP 地址(VIP)的服务。 #### NOTE 如果未安装 `keepalived` 包 — 请安装它: ```console $ sudo {apk|apt|pkg|yum|zypper} {add|install} keepalived ``` 要将进程绑定到非本地 IP 地址, 允许系统执行相应的操作: ```console $ sudo sysctl -w net.ipv4.ip_nonlocal_bind=1 ``` 更多详情: [https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt#ip_nonlocal_bind) 假设 VIP `10.21.11.230` 分配给主节点(`10.21.8.26`) 或备份节点(`10.21.8.27`)。 如果 Angie 监听此 VIP(`listen 10.21.11.230:80;`) 但地址尚未分配, 没有 `ip_nonlocal_bind` 参数,Angie 将无法启动。 ### Keepalived 配置 在主节点上(`/etc/keepalived/keepalived.conf`): ```ini global_defs { enable_script_security } vrrp_script angie_check { script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script' --no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/" interval 5 user angie } vrrp_instance angie { state MASTER interface enp0s2 virtual_router_id 254 priority 100 advert_int 2 unicast_src_ip 10.21.8.26 unicast_peer { 10.21.8.27 } virtual_ipaddress { 10.21.11.230 } track_script { angie_check } } ``` 在备份节点上: ```ini global_defs { enable_script_security } vrrp_script angie_check { script "/usr/bin/curl -s --connect-timeout 5 -A 'angie_hcheck_script' --no-buffer -XGET --unix-socket /tmp/angie_hcheck.sock http://hcheck/" interval 5 user angie } vrrp_instance angie { state MASTER interface enp0s2 virtual_router_id 254 priority 99 advert_int 2 unicast_src_ip 10.21.8.27 unicast_peer { 10.21.8.26 } virtual_ipaddress { 10.21.11.230 } track_script { angie_check } } ``` #### NOTE 在 `vrrp_instance angie` 部分中,设置以下值: - `unicast_src_ip` — 当前节点的 IP - `unicast_peer` — 相邻节点的 IP - `virtual_ipaddress` — 虚拟 IP(VIP) - `interface` — 网络接口 启动服务: ```console $ sudo keepalived -t && sudo service keepalived start ``` ### Keepalived 配置详解 让我们详细研究 Keepalived 配置的主要元素, 以了解集群的运行原理。 配置包含两个部分: - `global_defs` — 全局设置 - `vrrp_instance` — VRRP 参数(VIP 切换) 主要元素: - `enable_script_security` — 允许执行健康检查脚本 - `vrrp_script` — Angie 健康检查脚本 - `state MASTER` — 初始节点状态 - `priority` — 优先级(MASTER 角色分配给优先级最高的节点) - `advert_int` — VRRP 通告间隔 - `unicast_src_ip` — 当前节点 IP - `unicast_peer` — 邻居节点 IP - `virtual_ipaddress` — VIP 地址 - `track_script` — 通过健康检查脚本进行可用性监控 #### NOTE 如果原主节点恢复, 它将重新获得 MASTER 角色(因为优先级更高)。 要禁用故障恢复,请使用 `nopreempt` 参数: ```none vrrp_instance angie { ... nopreempt } ``` ## 测试集群运行 完成配置后,需要测试集群运行情况 并确保节点之间正确切换。 检查 VIP 状态: ```console $ ip addr show enp0s2 | grep "10.21.11.230" ``` 测试容错能力: 在主节点上停止 Angie: ```console $ sudo service angie stop ``` 检查 VIP 是否转移到备份节点: ```console $ ip addr show enp0s2 | grep "10.21.11.230" ``` 再次在主节点上启动 Angie: ```console $ sudo service angie start ``` 此后,VIP 应该返回到主节点。 # https://cn.angie.software/angie/docs/installation/external-modules/combined-upstreams.md # Combined Upstreams 该模块允许将多个服务器组组合为一个。 它引入了 `add_upstream`、`combine_server_singlets` 和 `extend_single_peers` 指令，这些指令可在 `upstream` 配置块内使用； 同时新增 `upstrand` 配置块，用于创建更高层级的 `upstream` 块。 此外，引入 `dynamic_upstrand` 指令，用于在运行时选择 `upstream` 块。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-combined-upstreams` - Angie PRO：`angie-pro-module-combined-upstreams` ## 加载模块 要使用该模块，请在 `main{}` 上下文中加载它： ```nginx load_module modules/ngx_http_combined_upstreams_module.so; ``` ## 其他信息 详细文档和源代码可在以下位置获取： [https://github.com/lyokha/nginx-combined-upstreams-module](https://github.com/lyokha/nginx-combined-upstreams-module) 模块指令的配置示例与详细说明： - [http://lin-techdet.blogspot.com/2011/10/nginx.html](http://lin-techdet.blogspot.com/2011/10/nginx.html) - [http://lin-techdet.blogspot.com/2015/12/nginx.html](http://lin-techdet.blogspot.com/2015/12/nginx.html) # https://cn.angie.software/company.md # 关于我们 我们是一家俄罗斯IT公司，从事软件开发工作。 我们公司由前NGINX员工创立，开发了Angie—— 一个高性能且可扩展的Web服务器，它是nginx的一个分支， 旨在超越原版的功能，成为集群软件解决方案市场中备受青睐的 Web服务器。 目前，我们正在积极开发基于Angie的一系列解决方案， 根据市场需求添加新功能。 我们的产品： - Angie及其商业版本Angie PRO。与nginx相比，它们显著提高了 容错能力、性能和运行条件，"Web Server"公司的 [技术支持](https://cn.angie.software//service.md) 专家将协助设置基于Angie的 解决方案和nginx的不间断运行。 - Angie Ingress Controller（ANIC）。这是一个用于管理 Kubernetes中容器化应用程序流量的解决方案。 ANIC基于Angie PRO的功能，允许使用俄罗斯解决方案构建安全、 可扩展、高性能的环境，并提供专业的迁移服务和俄语技术支持。 - Angie Application Delivery Controller（Angie ADC）目前正在开发中。 它是一个"负载均衡系统"类别的盒装解决方案，以虚拟设备的形式提供 （未来将提供硬件-软件解决方案），解决俄罗斯市场在这一领域的 多样化企业需求。 Angie PRO、ANIC和Angie ADC已被列入俄罗斯电子计算机和数据库软件统一注册表。 公司的产品正在与国产系统Astra Linux、Alt、RED OS和ROSA进行 兼容性测试。 我们的服务： - [标准技术支持](https://cn.angie.software//support/index.md)； - [企业技术支持](https://cn.angie.software//support/enterprise.md)； - 高素质的 [专业服务](https://cn.angie.software//professional-service.md)， 用于在客户基础设施中进行我们产品的迁移、 适配和优化。 我们与合作伙伴一起开发培训课程和认证项目， 用于我们产品的使用。 关于我们的媒体报道： - [Kommersant，nginx在俄罗斯重建。](https://www.kommersant.ru/doc/5634072) - [Vedomosti，第一个俄罗斯Web服务器被列入国产软件注册表。](https://www.vedomosti.ru/technology/articles/2023/05/24/976527-pervii-rossiiskii-veb-server-vnesen-v-reestr-otechestvennogo-po?shared_token=cbe20f6feeee8a5bcf52f077d2d6ad62b66e3917) - [Habr，"Web Server"推出ANIC——Kubernetes网络流量管理软件。](https://habr.com/news/744654/) - [开发者市场：如何发展俄罗斯的GitHub。](https://www.forbes.ru/mneniya/491830-marketplejs-dla-razrabotcikov-kak-razvivat-rossijskij-github) - [开源代码的封闭区域：中国和俄罗斯如何发展开源。](https://www.forbes.ru/tekhnologii/495635-zakrytye-zony-otkrytogo-koda-kak-kitaj-i-rossia-razvivaut-open-source) - [我们的首席开发者Valentin Bartenev在Habr上的采访。](https://habr.com/articles/774274/) - [Valentin Bartenev在HighLoad的演讲（YouTube）。](https://www.youtube.com/watch?v=CKHNqMawUiE) # https://cn.angie.software/angie/docs/configuration/configfile.md # 配置文件 Angie 使用基于文本的配置文件。默认情况下，该文件名为 `angie.conf`，根据 [--conf-path](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths) 构建参数的位置，通常位于 `/etc/angie` 目录下。 配置文件通常由以下上下文组成： - [events](https://cn.angie.software//angie/docs/configuration/modules/core.md#events) – 一般连接处理 - [http](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#d-http) – HTTP 流量 - [mail](https://cn.angie.software//angie/docs/configuration/modules/mail/index.md#m-mail) – 邮件流量 - [stream](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-stream) – TCP 和 UDP 流量 - [wasm_modules](https://cn.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules) – WASM 运行时 放置在这些上下文之外的指令被视为在 `main` 上下文中： ```nginx user angie; # 在 'main' 上下文中的指令 events { # 连接处理的配置 } http { # 特定于 HTTP 的配置，影响所有虚拟服务器 server { # HTTP 虚拟服务器 1 的配置 location /one { # 处理以 '/one' 开头的 URI 的配置 } location /two { # 处理以 '/two' 开头的 URI 的配置 } } server { # HTTP 虚拟服务器 2 的配置 } } stream { # 特定于 TCP/UDP 的配置，影响所有虚拟服务器 server { # TCP 虚拟服务器 1 的配置 } } ``` 为了简化配置管理，我们建议在主 `angie.conf` 文件中使用 [include](https://cn.angie.software//angie/docs/configuration/modules/core.md#include) 指令引用特定功能文件的内容： ```nginx include /etc/angie/http.d/*.conf; include /etc/angie/stream.d/*.conf; ``` ## 继承 一般来说，子上下文（包含在另一个上下文中的上下文，被视为其父上下文）继承在父级定义的指令设置。一些指令可以出现在多个上下文中；在这种情况下，您可以通过在子上下文中包含该指令来覆盖从父级继承的设置。 ## 语法 ### 测量单位 可以使用以下单位来指定大小： | 无后缀 | 字节 | |----------|------| | `k`, `K` | 千字节 | | `m`, `M` | 兆字节 | | `g`, `G` | 吉字节 | 例如：`1024`、`8k`、`1m`、`16g`。 时间间隔可以以毫秒、秒、分钟、小时、天等来指定，使用以下后缀： | `ms` | 毫秒 | |--------|---------------| | `s` | 秒 | | `m` | 分钟 | | `h` | 小时 | | `d` | 天 | | `w` | 周 | | `M` | 月（假定等于 30 天） | | `y` | 年（假定等于 365 天） | 多个单位可以通过按顺序从最重要到最不重要指定它们来组合成一个值，选用空格分隔。例如，`"1h 30m"` 指定的持续时间与 `"90m"` 或 `"5400s"` 相同。没有后缀的值被解释为秒。建议始终指定后缀。 某些时间间隔只能以秒级精度指定。 ### 指令 每个指令由一个名称和一组参数组成。 如果指令的任何部分需要包含空格， 它应被引号括起来或转义空格： ```nginx add_header X-MyHeader "foo bar"; add_header X-MyHeader foo\ bar; ``` 如果命名参数需要空格，并且您使用了引号， 则其名称也必须用引号括起来： ```nginx server example.com "sid=server 1"; ``` ## 设置哈希 为了有效处理静态数据集，例如服务器名称、[map](https://cn.angie.software//angie/docs/configuration/modules/http/http_map.md#id3) 指令值、MIME 类型和请求头名称，Angie 使用哈希表。在启动和每次重新配置时，Angie 确定这些哈希表的最佳大小，以确保存储具有相同哈希值的键的桶大小不超过配置参数（hash bucket size）。表的大小以桶为单位测量，并调整直到超过 hash max size 参数。大多数哈希表都有相应的指令来调整这些参数，例如 [server_names_hash_max_size](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-max-size) 和 [server_names_hash_bucket_size](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-bucket-size) 用于服务器名称。 hash bucket size 参数与处理器的缓存行大小对齐。这种对齐提高了现代处理器上键搜索的效率，减少了内存访问的次数。如果 hash bucket size 等于一个缓存行大小，则在键搜索期间的最大内存访问次数将为两个：一个用于计算桶地址，另一个用于在桶内搜索。因此，如果 Angie 指示应该增加 hash max size 或 hash bucket size，则首先增加 hash max size。 ### 重新加载配置 要应用对配置文件的更改，必须重新加载它。您可以先通过配置语法检查重启 Angie 进程： ```console $ sudo angie -t && sudo service angie restart ``` 或者，您可以重新加载服务，以在不中断当前请求处理的情况下应用新配置： ```console $ sudo angie -t && sudo service angie reload ``` # https://cn.angie.software/angie/docs/configuration.md # 配置 本页面包含用于配置 Angie 的文章、参考、索引和说明。 ## 一般信息 这些文章涵盖 Angie 的安装和配置、 启动和停止 Web 服务器、管理服务器, 以及请求处理和与其他服务器交互的各个方面。 * [配置](https://cn.angie.software//angie/docs/configuration/configfile.md) * [管理](https://cn.angie.software//angie/docs/configuration/runtime.md) * [连接、会话、请求、日志](https://cn.angie.software//angie/docs/configuration/processing.md) ## 参考和索引 这些摘要部分提供有关内置模块的参考信息、 它们的配置示例以及支持的指令和变量。 * [模块](https://cn.angie.software//angie/docs/configuration/modules/index.md) * [指令](https://cn.angie.software//genindex.md) * [变量](https://cn.angie.software//angie/docs/configuration/varindex.md) * [NJS API 参考](https://cn.angie.software//angie/docs/configuration/njs-reference.md) 您还可以使用 [https://angie.ws/](https://angie.ws/) 上的短链接服务 快速查找单个指令和变量: * [快速访问](https://cn.angie.software//angie/docs/configuration/quickaccess.md) ## 面向 AI 助手的文档 本站为每个文档页面提供机器可读的副本,以便 Claude Code、Cursor、 ChatGPT 等基于 LLM 的代理工具可以直接获取内容,而无需抓取渲染后的 HTML。 ### llms.txt 与 llms-full.txt 每个语言子域名都提供一份 [llms.txt](https://llmstxt.org/) 索引 文件,其中包含项目的简短描述以及全部页面的列表(标题、绝对 URL、 摘要)。配套的 `llms-full.txt` 将所有页面的完整 Markdown 内容 拼接为一个文件,适合一次性加载到模型中: - [https://cn.angie.software/llms.txt](https://cn.angie.software/llms.txt) - [https://cn.angie.software/llms-full.txt](https://cn.angie.software/llms-full.txt) 上述 URL 也通过 `Llms:` 指令在 [robots.txt](https://cn.angie.software/robots.txt) 中声明, LLM 爬虫可以自动发现它们。 ### 页面的 Markdown 版本 每个 HTML 页面都有对应的 Markdown 版本。将文档页面 URL 末尾的斜杠 替换为 `.md` 即可获取其 Markdown 版本: - HTML: [https://cn.angie.software/angie/docs/configuration/](https://cn.angie.software/angie/docs/configuration/) - Markdown: [https://cn.angie.software/angie/docs/configuration.md](https://cn.angie.software/angie/docs/configuration.md) Markdown 版本与 HTML 版本由相同的 reStructuredText 源文件构建, 因此内容始终保持同步。 ### Context7 Angie 文档已收录于 [Context7](https://context7.com/) —— 一个 通过 MCP 服务器为 AI 代码编辑器提供最新库文档的目录。中文版 Angie 在 Context7 的页面位于 [https://context7.com/websites/cn_angie_software_angie](https://context7.com/websites/cn_angie_software_angie)。 ## 说明 此处提供了配置 Angie 特定方面的分步说明。 * [配置 ACME](https://cn.angie.software//angie/docs/configuration/acme.md) * [配置集群](https://cn.angie.software//angie/docs/configuration/cluster.md) * [配置 OIDC](https://cn.angie.software//angie/docs/configuration/oidc.md) * [配置 SSL](https://cn.angie.software//angie/docs/configuration/ssl.md) * [Console Light 面板](https://cn.angie.software//angie/docs/configuration/monitoring.md) * [自定义指标](https://cn.angie.software//angie/docs/configuration/custom-metrics.md) * [从 nginx 迁移](https://cn.angie.software//angie/docs/configuration/migration.md) * [Grafana 面板](https://cn.angie.software//angie/docs/configuration/grafana.md) ## 社区材料 我们收集了社区资源,这些资源将帮助您更好地理解 Angie 的配置和使用。 ### 文章 - [Angie: A New NGINX Fork Developed by Some of Its Former Devs](https://linuxiac.com/angie-web-server-is-a-new-nginx-fork/) on Linuxiac - [What's New in the Angie 1.9 Web Server (an nginx fork) and What to Expect from 1.10?](https://habr.com/en/articles/911444/) on Habr ### 课程 目前没有英文的 Angie 课程。 请参阅官方 Angie 文档和下面的实用指南。 ### 实用指南 - [Migrating from Nginx to Angie: A Real-World Journey from Certbot to Built-in ACME](https://dev.to/stan-breaks/migrating-from-nginx-to-angie-a-real-world-journey-from-certbot-to-built-in-acme-7a3) on DEV Community ### 访谈和播客 - "NGINX is Dead? // Angie Web Server Migration Guide" by DevOps Toolbox ([YouTube](https://www.youtube.com/watch?v=HFCtaiJMDGg), 27.03.2026) - "Nginx Has a BIG Problem..." by DevOps Toolbox ([YouTube](https://www.youtube.com/watch?v=acJBNVTW42I), 30.01.2026) # https://cn.angie.software/contacts.md # 联系方式 电话：+7 (495) 120 50 33
邮箱：[info@wbsrv.ru](mailto:info@wbsrv.ru)
地址：127015，莫斯科，维亚茨卡亚街，27号，7栋
[在Telegram上支持](https://t.me/angie_support) (俄语、英语)
[在Telegram上查看新闻](https://t.me/angie_software) (俄语)
# https://cn.angie.software/angie/contributor-agreement.md # 贡献者许可协议 本协议管理公司与贡献者之间的关系，双方承担协议文本中规定的权利和义务，以下称为协议： **术语和定义**： **贡献** 是智力活动的结果（包括但不限于源代码、设计实体、文本和文档），这些都是程序的元素。 **程序** 是公司拥有独占权的软件（计算机程序），以及此类程序的所有新（后续）版本。 **贡献者** 是，（1）如果贡献是由个人以其自身名义作出的，则是具有必要法律能力并已接受本协议所有条款的个人；（2）如果贡献是由个人代表法人实体或个体企业家作为其雇主作出的，则是适用的法人实体或个体企业家。 **公司** 是Web Server, LLC，一个根据俄罗斯联邦法律注册的法人实体（OGRN: 1227700436578），注册地址为：俄罗斯莫斯科，127015，Vyatskaya St., 27, bld. 7。 **当事方** 是协议的其中一方，即贡献者或公司。 1. 本协议的主题是贡献者授予公司在非独占、免版税、不可撤销的许可条款下使用贡献的权利，包括本协议中明确规定和说明的所有手段。 该许可的授权期限为贡献的独占权的整个持续时间，允许的地域为世界各国。 贡献可以由贡献者以任何方式（在有形媒介上、通过电子邮件的电子形式、以变更请求的形式，或使用在GitHub、GitLab或其他类似网站上使用的贡献转移系统）提供给公司。贡献应被视为在公司收到它们的日期作出。 在实际提交贡献给公司的日期，贡献者表示完全无条件地同意本协议的所有条款。 1. **公司对贡献的使用**。公司有权以以下方式使用贡献： 2.1. 在任何程序中（包括开放源代码和闭源代码）出于商业和非商业目的使用贡献；在公司拥有权利的任何其他智力活动成果中使用贡献； 2.2. 对贡献进行任何更改、删节和补充，在使用贡献时添加评论、图片或解释； 2.3. 基于贡献创建任何其他（衍生）智力活动成果； 2.4. 将贡献翻译成其他语言，包括其他编程语言； 2.5. 以任何方式分发贡献，包括直接向第三方提供贡献，以及作为任何程序的一部分，以"现状"基础提供，且不需要对其可操作性/无缺陷和错误提供任何保证； 2.6. 进行公开展示，将贡献提供给公众； 2.7. 拆解、反编译（将目标代码转换为源代码）、对贡献进行工程分析。 2.8. 在不提及作者姓名和/或笔名（匿名）的情况下使用贡献。 1. 贡献者授予公司在全球所有国家的非独占、免版税、永久、不可撤销的许可，涵盖贡献者的专利权。该许可包括贡献者持有的所有专利权。 2. **陈述**。贡献者向公司提供以下陈述，涉及公司认为对协议的执行和签订重要的事项： 4.1. 贡献者拥有签署协议所需的所有权利； 4.2. 贡献者提供给公司的贡献是由贡献者个人开发的，除非贡献的独占权由其他人（权利人）拥有，但在这些权利人的同意下，无需与权利人协调且无需向他们支付报酬即可分发，且贡献者在合法基础上使用这些贡献； 4.3. 贡献不受任何第三方权利的限制； 4.4. 贡献者已获得贡献中包含的知识产权所有者的同意（如有）以便公司按照协议中规定的所有方式使用； 4.5. 公司进一步使用贡献的形式不侵犯任何第三方知识产权或其他合法利益和权利。 1. **责任**。如果公司因使用贡献者的贡献而面临任何索赔或诉讼，贡献者同意赔偿公司可能因这些索赔或诉讼而产生的所有损失。 2. **责任限制**。贡献者向公司提供的所有贡献均为"现状"基础，且不提供任何保证。 3. **商标**。贡献者仅在获得公司事先书面同意的情况下使用公司的徽标和商标。为获得书面同意，贡献者必须向公司的电子邮箱发送信件：[legal@wbsrv.ru](mailto:legal@wbsrv.ru)。 4. **争议解决和适用法律**。本协议应根据俄罗斯联邦的法律进行管辖和解释。如果各方未能就争议问题达成一致，则该争议应受公司所在地法院的管辖，法律另有直接规定的除外。 5. 公司没有义务向贡献者提供关于贡献使用的报告。 6. **协议语言**。本协议以俄语和英语书写。 俄文版本的协议可在以下地址获取： [https://angie.software/angie/contributor-agreement/](https://angie.software/angie/contributor-agreement/) 中文版本的协议可在以下地址获取： [https://cn.angie.software/angie/contributor-agreement/](https://cn.angie.software/angie/contributor-agreement/) 如俄文和英文版本的协议之间存在任何不一致，以俄文条款为准。 1. **协议生效**。本协议在公司收到来自贡献者的以本协议第1条中提到的任何形式和方式的贡献时被视为生效并已由双方签署。这包括但不限于，接收贡献到公司在GitHub和/或GitLab网站上的企业账户。 Web Server, LLC. OGRN: 1227700436578. 地址：俄罗斯莫斯科，127015，Vyatskaya St., 27, bldg. 7. 电话：+7 (495) 120 50 33. 电子邮件：[legal@wbsrv.ru](mailto:legal@wbsrv.ru). 发布日期：2023年11月08日。 # https://cn.angie.software/angie/docs/configuration/modules/core.md # 核心模块 该模块提供服务器基本运行所需的核心功能和配置指令, 并处理关键任务,如管理工作进程、 配置事件驱动模型、 以及处理传入的连接和请求。 它包含用于设置主进程、错误 日志记录以及在底层控制服务器行为的关键指令。 ## 配置示例 ```nginx user www www; worker_processes 2; error_log /var/log/error.log info; events { use kqueue; worker_connections 2048; } ``` ## 指令 ### accept_mutex | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `accept_mutex` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `accept_mutex off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 当启用 `accept_mutex` 时, 工作进程将轮流接受新连接。 如果不设置此项,所有工作进程都会收到新连接的通知, 这可能导致系统资源的低效使用, 特别是在新连接数量较少的情况下。 #### NOTE 在支持 `EPOLLEXCLUSIVE` 标志的系统上 或使用 [reuseport](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#listen) 指令时, 无需启用 `accept_mutex`。 ### accept_mutex_delay | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `accept_mutex_delay` time; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `accept_mutex_delay 500ms;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 如果启用了 [accept_mutex](#accept-mutex), 此指令指定工作进程在另一个工作进程正在处理新连接时, 等待继续接受新连接的最长时间。 ### daemon | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `daemon` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | `daemon on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 确定 Angie 是否应作为守护进程运行。 这主要在开发过程中使用。 ### debug_connection | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `debug_connection` address | CIDR | `unix:`; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 为特定客户端连接启用调试日志。 其他连接将使用 [error_log](#error-log) 指令设置的日志级别。 您可以通过 IPv4 或 IPv6 地址、网络或主机名指定连接。 对于使用 UNIX 域套接字的连接, 使用 `unix:` 参数启用调试日志。 ```nginx events { debug_connection 127.0.0.1; debug_connection localhost; debug_connection 192.0.2.0/24; debug_connection ::1; debug_connection 2001:0db8::/32; debug_connection unix:; # ... } ``` #### NOTE 要使此指令生效, 必须在构建 Angie 时启用 [调试日志](https://cn.angie.software//angie/docs/troubleshooting.md#debug-logging)。 ### debug_points | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `debug_points` `abort` | `stop`; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 此指令用于调试。 当发生内部错误时, 例如在工作进程重启期间发生套接字泄漏, 启用 `debug_points` 将创建核心文件 (`abort`) 或停止进程 (`stop`) 以便使用系统调试器进行进一步分析。 ### env | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `env` variable[=value]; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | `env TZ;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 默认情况下, Angie 会删除从其父进程继承的所有环境变量, 但 `TZ` 变量除外。 此指令允许您保留某些继承的变量、 修改它们的值或创建新的环境变量。 这些变量随后: - 在 [可执行文件的实时升级](https://cn.angie.software//angie/docs/configuration/runtime.md#service-upgrade) 期间被继承 - 被 [Perl](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) 模块使用 - 对工作进程可用 请注意,以这种方式控制系统库可能并不总是有效, 因为库通常仅在初始化期间检查变量, 而初始化发生在此指令生效之前。 `TZ` 变量始终被继承 并可供 [Perl](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) 模块访问, 除非明确配置为其他方式。 示例: ```nginx env MALLOC_OPTIONS; env PERL5LIB=/data/site/modules; env OPENSSL_ALLOW_PROXY_CERTS=1; ``` #### NOTE `ANGIE` 环境变量由 Angie 内部使用, 不应由用户直接设置。 ### error_log | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log` file [level] [[`filter=`type:value] ...]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `error_log logs/error.log error;`
(路径取决于 `--error-log-path` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main, http, mail, stream, server, location | 配置日志记录, 允许在同一配置级别指定多个日志。 如果在 `main` 配置级别未明确定义日志文件, 将使用默认文件。 第一个参数指定存储日志的文件。 特殊值 `stderr` 选择标准错误流。 要配置到 [syslog](https://cn.angie.software//angie/docs/configuration/processing.md#syslog-logging) 的日志记录, 使用 `"syslog:"` 前缀。 要记录到 [循环内存缓冲区](https://cn.angie.software//angie/docs/troubleshooting.md#cyclic-memory-buffer), 使用 `"memory:"` 前缀后跟缓冲区大小; 这通常用于调试。 第二个参数设置日志级别,可以是以下之一: `debug`、`info`、`notice`、`warn`、`error`、 `crit`、`alert` 或 `emerg`。 这些级别按严重性递增的顺序列出。 设置日志级别将捕获相同和更高严重性的消息: | 设置 | 捕获的级别 | |----------|--------------------------------------------------------------------| | `debug` | `debug`、`info`、`notice`、`warn`、`error`、
`crit`、`alert`、`emerg` | | `info` | `info`、`notice`、`warn`、`error`、
`crit`、`alert`、`emerg` | | `notice` | `notice`、`warn`、`error`、
`crit`、`alert`、`emerg` | | `warn` | `warn`、`error`、`crit`、`alert`、`emerg` | | `error` | `error`、`crit`、`alert`、`emerg` | | `crit` | `crit`、`alert`、`emerg` | | `alert` | `alert`、`emerg` | | `emerg` | `emerg` | 如果省略此参数, 将使用 `error` 作为默认日志级别。 可选的 `filter=` 参数限制将哪些消息写入日志。 支持的过滤器有: - `filter=file:`prefix 匹配源文件前缀(例如, `ngx_http_access_module.c`); - `filter=event:`prefix 匹配事件 ID 前缀(例如, `http.upstream.peer`); - `filter=tag:`tag 匹配附加到日志条目的标签。 多个 `filter=file:` 或 `filter=event:` 参数通过前缀匹配, 任何匹配都允许消息通过。多个 `filter=tag:` 参数要求所有标签都存在。 标签可以由模块自动添加(例如, `http`、`stream`、`mail`、`upstream`、 `peer`、`subrequest`),也可以通过 [error_log_user_tag](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#error-log-user-tag) 指令添加。 #### NOTE 要使 `debug` 日志级别生效, 必须在构建 Angie 时启用 [调试日志](https://cn.angie.software//angie/docs/troubleshooting.md#debug-logging)。 错误日志中的每个条目具有以下格式: ```text timestamp [level] PID#TID: *request_id message ``` 其中: - `timestamp` — 事件的日期和时间 - `level` — 事件的日志级别 - `PID#TID` — 进程和线程标识符 - `*request_id` — 唯一的请求标识符(如果适用) - `message` — 错误或事件消息文本 ### events | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `events` { ... }; | |--------------------------------------------------------------------------------------|---------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 为影响连接处理的指令 提供配置文件上下文。 ### include | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `include` file | mask; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | any | 将另一个文件或与指定 mask 匹配的文件 包含到配置中。 包含的文件必须包含语法正确的指令和块。 示例: ```nginx include mime.types; include vhosts/*.conf; ``` ### load_module | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `load_module` file; | |--------------------------------------------------------------------------------------|-----------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 从指定文件加载动态模块。 如果提供的是相对路径,则基于 `--prefix` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 进行解释。要验证路径: ```console $ sudo angie -V ``` 示例: ```nginx load_module modules/ngx_mail_module.so; ``` 如果动态模块是为不同的 Angie 构建版本构建的,加载将失败并显示类似以下的错误:"module "..." was built for "..." but you are running "Angie""。 ### lock_file | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lock_file` file; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `lock_file logs/angie.lock;`
(路径取决于 `--lock-path` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Angie 使用锁机制来实现 [accept_mutex](#accept-mutex) 并序列化对共享内存的访问。 在大多数系统上,锁是使用原子操作管理的, 因此不需要此指令。 但是,在某些系统上,会使用替代的 lock file 机制。 此指令设置锁文件名的前缀。 ### master_process | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `master_process` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `master_process on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 决定是否启动工作进程。 此指令供 Angie 开发人员使用。 ### multi_accept | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `multi_accept` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `multi_accept off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | | `on` | 工作进程将同时接受所有新连接。 | |--------|-------------------| | `off` | 工作进程每次接受一个新连接。 | #### NOTE 如果使用 [kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 连接处理方法, 则忽略此指令, 因为它会提供准备接受的新连接数量。 ### pcre_jit | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `pcre_jit` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `pcre_jit off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 为配置解析时已知的正则表达式 启用或禁用"即时编译"(PCRE JIT)。 PCRE JIT 可以显著加速正则表达式处理。 #### NOTE JIT 在 PCRE 库 8.20 版本及以上可用, 前提是使用 `--enable-jit` 配置选项构建。 当使用 PCRE 库构建 Angie 时 (`--with-pcre=`), 使用 `--with-pcre-jit` 选项启用 JIT 支持。 ### pid | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `pid` file | `off`; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `pid logs/angie.pid;`
(路径取决于 `--pid-path` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths)) | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 指定将存储 Angie 主进程 ID 的 file。 该文件以原子方式创建,这确保其内容始终正确。 `off` 设置禁用创建此文件。 #### NOTE 如果在重新配置期间修改了 file 设置, 但它指向先前 PID 文件的符号链接, 则不会重新创建该文件。 ### ssl_engine | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_engine` 设备; | |--------------------------------------------------------------------------------------|--------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 指定硬件 SSL 加速器的名称。 ### ssl_object_cache_inheritable | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_object_cache_inheritable` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | `ssl_object_cache_inheritable on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 如果启用,SSL 对象(SSL 证书、私钥、受信任的 CA 证书、 CRL 列表)在配置重新加载时会被继承。 如果从文件加载的 SSL 对象的修改时间和文件 索引自上次配置加载以来没有更改,则会被继承。指定为 `engine:name:id` 的私钥 永远不会被继承,而指定为 `data:value` 的私钥 始终会被继承。 从变量加载的 SSL 对象无法被继承。 示例: ```nginx ssl_object_cache_inheritable on; http { server { ssl_certificate example.com.crt; ssl_certificate_key example.com.key; } } ``` ### thread_pool | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `thread_pool` name `threads=`number [`max_queue=`number]; | |--------------------------------------------------------------------------------------|-------------------------------------------------------------| | 默认值 | `thread_pool default threads=32 max_queue=65536;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 定义线程池的 name 和参数, 用于多线程读取和发送文件, [不阻塞](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#aio) 工作进程。 `threads` 参数定义池中的线程数。 如果池中的所有线程都忙于执行任务,新任务将在队列中等待。 `max_queue` 参数限制允许在队列中等待的任务数量。 默认情况下,队列中最多可以有 65536 个任务。 当队列溢出时,任务将以错误完成。 ### timer_resolution | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `timer_resolution` interval; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 降低工作进程中的计时器分辨率, 从而减少 `gettimeofday()` 系统调用的次数。 默认情况下,每次接收到内核事件时都会调用 `gettimeofday()`。 降低分辨率后,:samp:gettimeofday() 仅在指定间隔内调用一次。 示例: ```nginx timer_resolution 100ms; ``` 间隔的内部实现取决于所使用的方法: - 如果使用 [kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue),则使用 `EVFILT_TIMER` 过滤器; - 如果使用 [eventport](https://cn.angie.software//angie/docs/configuration/processing.md#eventport),则使用 `timer_create()`; - 否则使用 `setitimer()`。 ### use | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `use` method; | |--------------------------------------------------------------------------------------|-----------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 指定用于 [连接处理](https://cn.angie.software//angie/docs/configuration/processing.md#methods-use) 的 method。 通常不需要显式指定, 因为 Angie 默认会使用最高效的方法。 ### user | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `user` user [group]; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `user <构建参数 --user> <构建参数 --group>;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 定义工作进程使用的 user 和 group 凭据 (另请参阅 [构建参数](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure))。 如果省略 group,则使用与 user 同名的组。 ### worker_aio_requests | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_aio_requests` number; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `worker_aio_requests 32;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 当使用 [aio](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#aio) 和 [epoll](https://cn.angie.software//angie/docs/configuration/processing.md#epoll) 连接处理方法时, 设置单个工作进程的最大未完成异步 I/O 操作数。 ### worker_connections | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_connections` number; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `worker_connections 512;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | events | 设置工作进程可以打开的最大同时连接数。 应该记住,此数字包括所有连接 (例如与代理服务器的连接等), 而不仅仅是与客户端的连接。 另一个考虑因素是,实际的同时连接数 不能超过当前打开文件数的最大限制, 该限制可以通过 [worker_rlimit_nofile](#worker-rlimit-nofile) 更改。 ### worker_cpu_affinity | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_cpu_affinity` cpumask ...;

`worker_cpu_affinity` auto [cpumask]; | |--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 将工作进程绑定到 CPU 集合。 每个 CPU 集合由允许的 CPU 位掩码表示。 应该为每个工作进程定义一个单独的集合。 默认情况下,工作进程不绑定到任何特定的 CPU。 例如: ```nginx worker_processes 4; worker_cpu_affinity 0001 0010 0100 1000; ``` 此配置将每个工作进程绑定到单独的 CPU。 或者: ```nginx worker_processes 2; worker_cpu_affinity 0101 1010; ``` 这将第一个工作进程绑定到 CPU0 和 CPU2, 将第二个工作进程绑定到 CPU1 和 CPU3。 此设置适用于超线程。 特殊值 `auto` 允许自动将工作进程绑定到可用的 CPU: ```nginx worker_processes auto; worker_cpu_affinity auto; ``` 可选的掩码参数可用于限制 可用于自动绑定的 CPU: ```nginx worker_cpu_affinity auto 01010101; ``` #### NOTE 该指令仅在 FreeBSD 和 Linux 上可用。 ### worker_priority | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_priority` number; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `worker_priority 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 定义工作进程的调度优先级,类似于 **nice** 命令的做法:负数 number 表示更高的优先级。 允许的范围通常从 -20 到 20。 示例: ```nginx worker_priority -10; ``` ### worker_processes | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_processes` number | `auto`; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `worker_processes 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 定义工作进程的数量。 最佳值取决于许多因素,包括(但不限于) CPU 核心数、存储数据的硬盘驱动器数量 以及负载模式。 如果不确定,将其设置为可用 CPU 核心数 是一个不错的起点(值"`auto`"将尝试自动检测)。 ### worker_rlimit_core | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_rlimit_core` size; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 更改工作进程的核心文件最大大小限制(`RLIMIT_CORE`)。 用于在不重启主进程的情况下增加限制。 ### worker_rlimit_nofile | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_rlimit_nofile` number; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 更改工作进程的最大打开文件数限制(`RLIMIT_NOFILE`)。 用于在不重启主进程的情况下增加限制。 ### worker_shutdown_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `worker_shutdown_timeout` time; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 配置工作进程优雅关闭的超时时间(以秒为单位)。 当指定的时间到期时, Angie 将尝试关闭当前打开的所有连接 以便于关闭。 优雅关闭通过向主进程发送 [QUIT 信号](https://cn.angie.software//angie/docs/configuration/runtime.md#control-signals) 来启动,该信号指示工作进程 停止接受新连接并允许现有连接完成。 工作进程继续处理活动请求直到完成, 然后优雅地关闭。如果连接保持打开的时间 超过 `worker_shutdown_timeout`,Angie 将强制关闭这些 连接以完成关闭。 此外,客户端保持活动连接仅在空闲时间 至少达到 [lingering_timeout](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#lingering-timeout) 指定的时间时才会关闭。 ### working_directory | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `working_directory` directory; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 定义工作进程的当前工作目录。 它主要在写入核心文件时使用, 在这种情况下,工作进程应该对 指定的目录具有写入权限。 # https://cn.angie.software/angie/docs/configuration/custom-metrics.md # 自定义指标配置 Angie 可以在共享内存中收集自定义数值指标，并通过实时 [统计 API](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) 在 `/status/http/metric_zones/` 公开它们。这由 [Metric](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#http-metric) 模块提供。 ## 配置步骤 1. 在 `http` 块中定义指标区域： - [metric_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) 创建具有单个指标模式的区域。 - [metric_complex_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) 创建具有多个命名指标的区域。 2. 使用 [metric](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#id5) 指令在请求处理中更新指标。 使用 `key=value` 对（两者都是 [复杂值](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)），并使用 `on=` 选择更新阶段（`request`、`response` 或 `end`）。 3. 使用 `location` 公开 API： ```nginx location /status/ { api /status/http/metric_zones/; } ``` ## 示例 统计每个主机的请求数并在 API 中公开指标： ```nginx http { metric_zone requests:128k count; server { listen 80; location / { metric requests $host=1; } location /status/ { api /status/http/metric_zones/; } } } ``` ## 注意事项 - 如果在区域上设置了 `expire=on` 且共享内存已满，则最近最少使用的条目将过期。如果设置了 `expire=off`，新的更新将被丢弃，`discarded` 计数器会增长。 - 如果设置了 `discard_key`，过期条目的指标将在 API 输出中聚合到该键下。 - 键和值限制为 255 字节；较长的键在 API 中会被截断。 - 空值被视为 `0`，没有前导数字的非空值被视为 `1`。 # https://cn.angie.software/angie/docs/installation/external-modules/dav-ext.md # DAV-Ext 此模块通过 PROPFIND、OPTIONS、LOCK 和 UNLOCK 方法扩展了 WebDAV 支持。 标准 [DAV](https://cn.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) 模块提供了 WebDAV 的部分实现, 仅支持 GET、HEAD、PUT、DELETE、MKCOL、COPY 和 MOVE 方法。 要获得完整的 WebDAV 支持,您需要启用标准的 `http_dav_module` 模块,以及此模块来支持缺失的方法。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-dav-ext` - Angie PRO:`angie-pro-module-dav-ext` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_dav_ext_module.so; ``` ## 配置示例 ```nginx dav_ext_lock_zone zone=lock_zone:10m; server { listen 80 default_server; location / { root /usr/share/angie/html; dav_methods PUT DELETE MKCOL COPY MOVE; dav_ext_methods PROPFIND OPTIONS LOCK UNLOCK; dav_ext_lock zone=lock_zone; } } ``` ## 请求执行示例 将文件上传到服务器: ```console $ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt HTTP/1.1 201 Created Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Content-Length: 0 Location: http://127.0.0.1/testf1.txt Connection: keep-alive ``` 覆盖同一文件: ```console $ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt HTTP/1.1 204 No Content Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Connection: keep-alive ``` 锁定文件防止被覆盖: ```console $ curl -i -X LOCK http://127.0.0.1/testf1.txt HTTP/1.1 200 OK Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Content-Type: text/xml; charset=utf-8 Content-Length: 392 Connection: keep-alive Lock-Token: ``` 尝试覆盖文件: ```console $ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt HTTP/1.1 423 Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Content-Length: 0 Connection: keep-alive ``` 文件已被锁定。解锁文件: ```console $ curl -i -X UNLOCK -H 'Lock-Token: ' http://127.0.0.1/testf1.txt HTTP/1.1 204 No Content Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Connection: keep-alive ``` 覆盖文件: ```console $ curl -i -X PUT -d @testf1.txt http://127.0.0.1/testf1.txt HTTP/1.1 204 No Content Server: Angie/|angie_version| Date: |sampledatelong| 19:15:35 GMT Connection: keep-alive ``` 文件已成功解锁并覆盖。 ## 附加信息 详细文档和源代码可在以下位置获取: [https://github.com/arut/nginx-dav-ext-module](https://github.com/arut/nginx-dav-ext-module) # https://cn.angie.software/angie/docs/developer_guide.md # 开发者指南 ## 编码约定 源代码遵循以下结构和约定。 ### 代码布局 * `auto` — 构建脚本 * `src` * `core` — 基本类型和函数 — 字符串、数组、日志、 池等。 * `event` — 事件核心 * `modules` — 事件通知模块: `epoll`、`kqueue`、`select` 等。 * `http` — 核心 HTTP 模块和通用代码 * `modules` — 其他 HTTP 模块 * `v2` — HTTP/2 * `mail` — 邮件模块 * `os` — 平台特定代码 * `unix` * `win32` * `stream` — 流模块 ### 包含文件 以下两个 `#include` 语句必须出现在 每个 Angie 文件的开头: ```c #include #include ``` 除此之外,HTTP 代码应包含 ```c #include ``` 邮件代码应包含 ```c #include ``` 流代码应包含 ```c #include ``` ### 整数 对于一般用途,Angie 代码使用两种整数类型, `ngx_int_t` 和 `ngx_uint_t`,它们分别是 `intptr_t` 和 `uintptr_t` 的类型定义。 ### 常见返回码 Angie 中的大多数函数返回以下代码: * `NGX_OK` — 操作成功。 * `NGX_ERROR` — 操作失败。 * `NGX_AGAIN` — 操作未完成;再次调用该函数。 * `NGX_DECLINED` — 操作被拒绝,例如,因为它在 配置中被禁用。这永远不是错误。 * `NGX_BUSY` — 资源不可用。 * `NGX_DONE` — 操作完成或在其他地方继续。 也用作替代成功代码。 * `NGX_ABORT` — 函数被中止。 也用作替代错误代码。 ### 错误处理 `ngx_errno` 宏返回最后一个系统错误代码。 它在 POSIX 平台上映射到 `errno`,在 Windows 中映射到 `GetLastError()` 调用。 `ngx_socket_errno` 宏返回最后一个套接字错误 编号。 与 `ngx_errno` 宏一样,它在 POSIX 平台上映射到 `errno`。 它在 Windows 中映射到 `WSAGetLastError()` 调用。 连续多次访问 `ngx_errno` 或 `ngx_socket_errno` 的值可能会导致 性能问题。 如果错误值可能被多次使用,请将其存储在 `ngx_err_t` 类型的局部变量中。 要设置错误,请使用 `ngx_set_errno(errno)` 和 `ngx_set_socket_errno(errno)` 宏。 `ngx_errno` 和 `ngx_socket_errno` 的值可以传递给日志函数 `ngx_log_error()` 和 `ngx_log_debugX()`, 在这种情况下,系统错误文本会添加到日志消息中。 使用 `ngx_errno` 的示例: ```c ngx_int_t ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo) { ngx_err_t err; if (kill(pid, signo) == -1) { err = ngx_errno; ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo); if (err == NGX_ESRCH) { return 2; } return 1; } return 0; } ``` ### 字符串 #### 概述 对于 C 字符串,Angie 使用无符号字符类型指针 `u_char *`。 Angie 字符串类型 `ngx_str_t` 定义如下: ```c typedef struct { size_t len; u_char *data; } ngx_str_t; ``` `len` 字段保存字符串长度, `data` 保存字符串数据。 `ngx_str_t` 中保存的字符串在 `len` 字节之后 可能以 null 结尾,也可能不以 null 结尾。 在大多数情况下不是。 但是,在代码的某些部分(例如,解析配置时), `ngx_str_t` 对象已知以 null 结尾,这 简化了字符串比较,并使将字符串传递给 系统调用变得更容易。 Angie 中的字符串操作在 `src/core/ngx_string.h` 中声明。 其中一些是标准 C 函数的包装器: * `ngx_strcmp()` * `ngx_strncmp()` * `ngx_strstr()` * `ngx_strlen()` * `ngx_strchr()` * `ngx_memcmp()` * `ngx_memset()` * `ngx_memcpy()` * `ngx_memmove()` 其他字符串函数是 Angie 特定的: * `ngx_memzero()` — 用零填充内存。 * `ngx_explicit_memzero()` — 与 `ngx_memzero()` 相同,但此调用永远不会被 编译器的死存储消除优化删除。 此函数可用于清除敏感数据,如密码和密钥。 * `ngx_cpymem()` — 与 `ngx_memcpy()` 相同,但返回最终目标地址。 这对于连续追加多个字符串很方便。 * `ngx_movemem()` — 与 `ngx_memmove()` 相同,但返回最终目标地址。 * `ngx_strlchr()` — 在字符串中搜索字符, 由两个指针分隔。 以下函数执行大小写转换和比较: * `ngx_tolower()` * `ngx_toupper()` * `ngx_strlow()` * `ngx_strcasecmp()` * `ngx_strncasecmp()` 以下宏简化了字符串初始化: * `ngx_string(text)` — 从 C 字符串字面量 `text` 为 `ngx_str_t` 类型的静态初始化器 * `ngx_null_string` — `ngx_str_t` 类型的静态空字符串初始化器 * `ngx_str_set(str, text)` — 使用 C 字符串 字面量 `text` 初始化 `ngx_str_t *` 类型的字符串 `str` * `ngx_str_null(str)` — 使用空字符串初始化 `ngx_str_t *` 类型的字符串 `str` #### 格式化 以下格式化函数支持 Angie 特定类型: * `ngx_sprintf(buf, fmt, ...)` * `ngx_snprintf(buf, max, fmt, ...)` * `ngx_slprintf(buf, last, fmt, ...)` * `ngx_vslprintf(buf, last, fmt, args)` * `ngx_vsnprintf(buf, max, fmt, args)` 这些函数支持的格式化选项的完整列表在 `src/core/ngx_string.c` 中。其中一些是: * `%O` — `off_t` * `%T` — `time_t` * `%z` — `ssize_t` * `%i` — `ngx_int_t` * `%p` — `void *` * `%V` — `ngx_str_t *` * `%s` — `u_char *` (以 null 结尾) * `%*s` — `size_t + u_char *` 您可以在大多数类型前加上 `u` 以使其无符号。 要将输出转换为十六进制,请使用 `X` 或 `x` 。 ### 数值转换 Angie 中实现了几个数值转换函数。 前四个函数各自将给定长度的字符串转换为指定类型的正整数。 它们在出错时返回 `NGX_ERROR`。 * `ngx_atoi(line, n)` — `ngx_int_t` * `ngx_atosz(line, n)` — `ssize_t` * `ngx_atoof(line, n)` — `off_t` * `ngx_atotm(line, n)` — `time_t` 还有两个额外的数值转换函数。 与前四个一样,它们在出错时返回 `NGX_ERROR`。 * `ngx_atofp(line, n, point)` — 将给定长度的定点数 转换为 `ngx_int_t` 类型的正整数。 结果向左移动 `point` 个十进制 位置。 数字的字符串表示预期不超过 `point` 个小数位。 例如,:samp:ngx_atofp("10.5", 4, 2) 返回 `1050`。 * `ngx_hextoi(line, n)` — 将正整数的十六进制表示 转换为 `ngx_int_t`。 ### 正则表达式 Angie 中的正则表达式接口是 [PCRE](http://www.pcre.org) 库的包装器。 相应的头文件是 `src/core/ngx_regex.h`。 要使用正则表达式进行字符串匹配，首先需要 编译它，这通常在配置阶段完成。 请注意，由于 PCRE 支持是可选的，所有使用该接口的代码必须 由周围的 `NGX_PCRE` 宏保护： ```c #if (NGX_PCRE) ngx_regex_t *re; ngx_regex_compile_t rc; u_char errstr[NGX_MAX_CONF_ERRSTR]; ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?\\w+)'"); ngx_memzero(&rc, sizeof(ngx_regex_compile_t)); rc.pattern = value; rc.pool = cf->pool; rc.err.len = NGX_MAX_CONF_ERRSTR; rc.err.data = errstr; /* rc.options 可以设置为 NGX_REGEX_CASELESS */ if (ngx_regex_compile(&rc) != NGX_OK) { ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err); return NGX_CONF_ERROR; } re = rc.regex; #endif ``` 成功编译后，`ngx_regex_compile_t` 结构中的 `captures` 和 `named_captures` 字段分别包含在正则表达式中找到的所有捕获和命名捕获的计数。 然后可以使用编译后的正则表达式来匹配字符串： ```c ngx_int_t n; int captures[(1 + rc.captures) * 3]; ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'."); n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3); if (n >= 0) { /* string matches expression */ } else if (n == NGX_REGEX_NO_MATCHED) { /* no match was found */ } else { /* some error */ ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n); } ``` `ngx_regex_exec()` 的参数是编译后的正则 表达式 `re`、要匹配的字符串 `input`、 一个可选的整数数组来保存找到的任何 `captures`, 以及数组的 `size`。 `captures` 数组的大小必须是三的倍数, 如 [PCRE API](http://www.pcre.org/original/doc/html/pcreapi.html) 所要求的。 在示例中,大小是根据捕获总数加上 匹配字符串本身的一个计算得出的。 如果有匹配,可以按如下方式访问捕获: ```c u_char *p; size_t size; ngx_str_t name, value; /* all captures */ for (i = 0; i < n * 2; i += 2) { value.data = input.data + captures[i]; value.len = captures[i + 1] - captures[i]; } /* accessing named captures */ size = rc.name_size; p = rc.names; for (i = 0; i < rc.named_captures; i++, p += size) { /* capture name */ name.data = &p[2]; name.len = ngx_strlen(name.data); n = 2 * ((p[0] << 8) + p[1]); /* captured value */ value.data = &input.data[captures[n]]; value.len = captures[n + 1] - captures[n]; } ``` `ngx_regex_exec_array()` 函数接受一个 `ngx_regex_elt_t` 元素数组(它们只是带有关联名称的编译正则 表达式)、要匹配的字符串和日志。 该函数将数组中的表达式应用于字符串,直到 找到匹配或没有更多表达式为止。 当有匹配时返回值为 `NGX_OK`, 否则为 `NGX_DECLINED`,或在出错时为 `NGX_ERROR`。 ### 时间 `ngx_time_t` 结构用三个独立的类型表示时间：秒、毫秒和 GMT 偏移： ```c typedef struct { time_t sec; ngx_uint_t msec; ngx_int_t gmtoff; } ngx_time_t; ``` `ngx_tm_t` 结构是 UNIX 平台上 `struct tm` 和 Windows 上 `SYSTEMTIME` 的别名。 要获取当前时间，通常只需访问一个可用的全局变量，这些变量以所需格式表示缓存的时间值。 可用的字符串表示形式有： * `ngx_cached_err_log_time` — 用于错误日志条目： `"1970/09/28 12:00:00"` * `ngx_cached_http_log_time` — 用于 HTTP 访问日志条目： `"28/Sep/1970:12:00:00 +0600"` * `ngx_cached_syslog_time` — 用于 syslog 条目： `"Sep 28 12:00:00"` * `ngx_cached_http_time` — 用于 HTTP 头： `"Mon, 28 Sep 1970 06:00:00 GMT"` * `ngx_cached_http_log_iso8601` — ISO 8601 标准格式： `"1970-09-28T12:00:00+06:00"` `ngx_time()` 和 `ngx_timeofday()` 宏返回当前时间值（以秒为单位），是访问缓存时间值的首选方式。 要显式获取时间，请使用 `ngx_gettimeofday()`，它会更新其参数（指向 `struct timeval` 的指针）。 当 Angie 从系统调用返回到事件循环时，时间总是会更新。 要立即更新时间，请调用 `ngx_time_update()`，或者如果在信号处理程序上下文中更新时间，请调用 `ngx_time_sigsafe_update()`。 以下函数将 `time_t` 转换为指定的分解时间表示形式。 每对中的第一个函数将 `time_t` 转换为 `ngx_tm_t`，第二个函数（带有 `_libc_` 中缀）转换为 `struct tm`： * `ngx_gmtime(), ngx_libc_gmtime()` — 以 UTC 表示的时间 * `ngx_localtime(), ngx_libc_localtime()` — 相对于本地时区表示的时间 `ngx_http_time(buf, time)` 函数返回适合在 HTTP 头中使用的字符串表示形式（例如，`"Mon, 28 Sep 1970 06:00:00 GMT"`）。 `ngx_http_cookie_time(buf, time)` 函数返回适合 HTTP cookie 的字符串表示形式（`"Thu, 31-Dec-37 23:55:55 GMT"`）。 ## 容器 ### 数组 Angie 数组类型 `ngx_array_t` 定义如下 ```c typedef struct { void *elts; ngx_uint_t nelts; size_t size; ngx_uint_t nalloc; ngx_pool_t *pool; } ngx_array_t; ``` 数组的元素在 `elts` 字段中可用。 `nelts` 字段保存元素的数量。 `size` 字段保存单个元素的大小，并在数组初始化时设置。 使用 `ngx_array_create(pool, n, size)` 调用在内存池中创建数组，使用 `ngx_array_init(array, pool, n, size)` 调用初始化已分配的数组对象。 ```c ngx_array_t *a, b; /* 创建一个字符串数组，为 10 个元素预分配内存 */ a = ngx_array_create(pool, 10, sizeof(ngx_str_t)); /* 初始化 10 个元素的字符串数组 */ ngx_array_init(&b, pool, 10, sizeof(ngx_str_t)); ``` 使用以下函数向数组添加元素： * `ngx_array_push(a)` 添加一个尾部元素并返回指向它的指针 * `ngx_array_push_n(a, n)` 添加 `n` 个尾部元素并返回指向第一个元素的指针 如果当前分配的内存量不足以容纳新元素，则会分配一个新的内存块并将现有元素复制到其中。 新内存块通常是现有内存块的两倍大。 ```c s = ngx_array_push(a); ss = ngx_array_push_n(&b, 3); ``` ### 列表 在 Angie 中，列表是一系列数组，针对插入可能大量的项目进行了优化。 `ngx_list_t` 列表类型定义如下： ```c typedef struct { ngx_list_part_t *last; ngx_list_part_t part; size_t size; ngx_uint_t nalloc; ngx_pool_t *pool; } ngx_list_t; ``` 实际项目存储在列表部分中，定义如下： ```c typedef struct ngx_list_part_s ngx_list_part_t; struct ngx_list_part_s { void *elts; ngx_uint_t nelts; ngx_list_part_t *next; }; ``` 在使用之前，必须通过调用 `ngx_list_init(list, pool, n, size)` 初始化列表，或通过调用 `ngx_list_create(pool, n, size)` 创建列表。 这两个函数都将单个项目的大小和每个列表部分的项目数作为参数。 要向列表添加项目，请使用 `ngx_list_push(list)` 函数。 要遍历项目，请直接访问列表字段，如示例所示： ```c ngx_str_t *v; ngx_uint_t i; ngx_list_t *list; ngx_list_part_t *part; list = ngx_list_create(pool, 100, sizeof(ngx_str_t)); if (list == NULL) { /* error */ } /* 向列表添加项目 */ v = ngx_list_push(list); if (v == NULL) { /* error */ } ngx_str_set(v, "foo"); v = ngx_list_push(list); if (v == NULL) { /* error */ } ngx_str_set(v, "bar"); /* 遍历列表 */ part = &list->part; v = part->elts; for (i = 0; /* void */; i++) { if (i >= part->nelts) { if (part->next == NULL) { break; } part = part->next; v = part->elts; i = 0; } ngx_do_smth(&v[i]); } ``` 列表主要用于 HTTP 输入和输出头。 列表不支持项目删除。 但是，在需要时，可以在内部将项目标记为缺失，而无需实际从列表中删除。 例如，要将 HTTP 输出头（存储为 `ngx_table_elt_t` 对象）标记为缺失，请将 `ngx_table_elt_t` 中的 `hash` 字段设置为零。 在遍历头时，会显式跳过以这种方式标记的项目。 ### 队列 在 Angie 中，队列是一个侵入式双向链表，每个节点定义如下： ```c typedef struct ngx_queue_s ngx_queue_t; struct ngx_queue_s { ngx_queue_t *prev; ngx_queue_t *next; }; ``` 头队列节点不与任何数据链接。 在使用之前，使用 `ngx_queue_init(q)` 调用初始化列表头。 队列支持以下操作： * `ngx_queue_insert_head(h, x)`、`ngx_queue_insert_tail(h, x)` — 插入新节点 * `ngx_queue_remove(x)` — 删除队列节点 * `ngx_queue_split(h, q, n)` — 在节点处拆分队列，在单独的队列中返回队列尾部 * `ngx_queue_add(h, n)` — 将第二个队列添加到第一个队列 * `ngx_queue_head(h)`、`ngx_queue_last(h)` — 获取第一个或最后一个队列节点 * `ngx_queue_sentinel(h)` — 获取队列哨兵对象以结束迭代 * `ngx_queue_data(q, type, link)` — 获取对队列节点数据结构开头的引用，考虑其中队列字段的偏移量 示例： ```c typedef struct { ngx_str_t value; ngx_queue_t queue; } ngx_foo_t; ngx_foo_t *f; ngx_queue_t values, *q; ngx_queue_init(&values); f = ngx_palloc(pool, sizeof(ngx_foo_t)); if (f == NULL) { /* error */ } ngx_str_set(&f->value, "foo"); ngx_queue_insert_tail(&values, &f->queue); /* 在此处插入更多节点 */ for (q = ngx_queue_head(&values); q != ngx_queue_sentinel(&values); q = ngx_queue_next(q)) { f = ngx_queue_data(q, ngx_foo_t, queue); ngx_do_smth(&f->value); } ``` ### 红黑树 `src/core/ngx_rbtree.h` 头文件提供对红黑树的有效实现的访问。 ```c typedef struct { ngx_rbtree_t rbtree; ngx_rbtree_node_t sentinel; /* 此处为自定义的每棵树数据 */ } my_tree_t; typedef struct { ngx_rbtree_node_t rbnode; /* 自定义的每个节点数据 */ foo_t val; } my_node_t; ``` 要将树作为一个整体处理，您需要两个节点：根节点和哨兵节点。 通常，它们被添加到自定义结构中，允许您将数据组织到树中，其中叶子包含指向您的数据的链接或嵌入您的数据。 要初始化树： ```c my_tree_t root; ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function); ``` 要遍历树并插入新值，请使用 "`insert_value`" 函数。 例如，`ngx_str_rbtree_insert_value` 函数处理 `ngx_str_t` 类型。 其参数是指向插入的根节点的指针、要添加的新创建节点以及树哨兵。 ```c void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp, ngx_rbtree_node_t *node, ngx_rbtree_node_t *sentinel) ``` 遍历非常简单，可以用以下查找函数模式演示： ```c my_node_t * my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash) { ngx_int_t rc; my_node_t *n; ngx_rbtree_node_t *node, *sentinel; node = rbtree->root; sentinel = rbtree->sentinel; while (node != sentinel) { n = (my_node_t *) node; if (hash != node->key) { node = (hash < node->key) ? node->left : node->right; continue; } rc = compare(val, node->val); if (rc < 0) { node = node->left; continue; } if (rc > 0) { node = node->right; continue; } return n; } return NULL; } ``` `compare()` 函数是一个经典的比较器函数，返回小于、等于或大于零的值。 为了加快查找速度并避免比较可能很大的用户对象，使用了整数哈希字段。 要向树添加节点，请分配一个新节点，对其进行初始化并调用 `ngx_rbtree_insert()`： ```c my_node_t *my_node; ngx_rbtree_node_t *node; my_node = ngx_palloc(...); init_custom_data(&my_node->val); node = &my_node->rbnode; node->key = create_key(my_node->val); ngx_rbtree_insert(&root->rbtree, node); ``` 要删除节点，请调用 `ngx_rbtree_delete()` 函数： ```c ngx_rbtree_delete(&root->rbtree, node); ``` ### 哈希 哈希表函数在 `src/core/ngx_hash.h` 中声明。 支持精确匹配和通配符匹配。 后者需要额外的设置，并在下面的单独部分中描述。 在初始化哈希之前，您需要知道它将包含的元素数量，以便 Angie 可以最佳地构建它。 需要配置的两个参数是 `max_size` 和 `bucket_size`，详见单独的 [文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。 它们通常由用户配置。 哈希初始化设置使用 `ngx_hash_init_t` 类型存储，哈希本身是 `ngx_hash_t`： ```c ngx_hash_t foo_hash; ngx_hash_init_t hash; hash.hash = &foo_hash; hash.key = ngx_hash_key; hash.max_size = 512; hash.bucket_size = ngx_align(64, ngx_cacheline_size); hash.name = "foo_hash"; hash.pool = cf->pool; hash.temp_pool = cf->temp_pool; ``` `key` 是指向从字符串创建哈希整数键的函数的指针。 有两个通用的键创建函数：`ngx_hash_key(data, len)` 和 `ngx_hash_key_lc(data, len)`。 后者将字符串转换为全小写字符，因此传递的字符串必须是可写的。 如果不是这样，请将 `NGX_HASH_READONLY_KEY` 标志传递给函数，初始化键数组（见下文）。 哈希键存储在 `ngx_hash_keys_arrays_t` 中，并使用 `ngx_hash_keys_array_init(arr, type)` 初始化： 第二个参数（`type`）控制为哈希预分配的资源量，可以是 `NGX_HASH_SMALL` 或 `NGX_HASH_LARGE`。 如果您预计哈希将包含数千个元素，则后者是合适的。 ```c ngx_hash_keys_arrays_t foo_keys; foo_keys.pool = cf->pool; foo_keys.temp_pool = cf->temp_pool; ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL); ``` 要将键插入哈希键数组，请使用 `ngx_hash_add_key(keys_array, key, value, flags)` 函数： ```c ngx_str_t k1 = ngx_string("key1"); ngx_str_t k2 = ngx_string("key2"); ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY); ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY); ``` 要构建哈希表，请调用 `ngx_hash_init(hinit, key_names, nelts)` 函数： ```c ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts); ``` 如果 `max_size` 或 `bucket_size` 参数不够大，该函数将失败。 构建哈希后，使用 `ngx_hash_find(hash, key, name, len)` 函数查找元素： ```c my_data_t *data; ngx_uint_t key; key = ngx_hash_key(k1.data, k1.len); data = ngx_hash_find(&foo_hash, key, k1.data, k1.len); if (data == NULL) { /* 未找到键 */ } ``` #### 通配符匹配 要创建使用通配符的哈希，请使用 `ngx_hash_combined_t` 类型。 它包括上述哈希类型，并有两个额外的键数组：`dns_wc_head` 和 `dns_wc_tail`。 基本属性的初始化类似于常规哈希： ```c ngx_hash_init_t hash ngx_hash_combined_t foo_hash; hash.hash = &foo_hash.hash; hash.key = ...; ``` 可以使用 `NGX_HASH_WILDCARD_KEY` 标志添加通配符键： ```c /* k1 = ".example.org"; */ /* k2 = "foo.*"; */ ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY); ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY); ``` 该函数识别通配符并将键添加到相应的数组中。 有关通配符语法和匹配算法的描述，请参阅 [Map](https://cn.angie.software//angie/docs/configuration/modules/http/http_map.md#http-map) 模块文档。 根据添加的键的内容，您可能需要初始化最多三个键数组：一个用于精确匹配（如上所述），另外两个用于启用从字符串的头部或尾部开始的匹配： ```c if (foo_keys.dns_wc_head.nelts) { ngx_qsort(foo_keys.dns_wc_head.elts, (size_t) foo_keys.dns_wc_head.nelts, sizeof(ngx_hash_key_t), cmp_dns_wildcards); hash.hash = NULL; hash.temp_pool = pool; if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts, foo_keys.dns_wc_head.nelts) != NGX_OK) { return NGX_ERROR; } foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash; } ``` 键数组需要排序，初始化结果必须添加到组合哈希中。 `dns_wc_tail` 数组的初始化方式类似。 组合哈希中的查找由 `ngx_hash_find_combined(chash, key, name, len)` 处理： ```c /* key = "bar.example.org"; - 将匹配 ".example.org" */ /* key = "foo.example.com"; - 将匹配 "foo.*" */ hkey = ngx_hash_key(key.data, key.len); res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len); ``` ## 内存管理 ### 堆 要从系统堆分配内存,请使用以下函数: * `ngx_alloc(size, log)` — 从系统堆分配内存。 这是 `malloc()` 的包装器,支持日志记录。 分配错误和调试信息会记录到 `log`。 * `ngx_calloc(size, log)` — 从系统堆分配内存, 类似于 `ngx_alloc()`,但在分配后将内存填充为零。 * `ngx_memalign(alignment, size, log)` — 从系统堆分配对齐的内存。 在提供该函数的平台上,这是 `posix_memalign()` 的包装器。 否则实现会回退到 `ngx_alloc()`,它提供最大对齐。 * `ngx_free(p)` — 释放已分配的内存。 这是 `free()` 的包装器。 ### 内存池 大多数 Angie 分配都在内存池中完成。 在 Angie 内存池中分配的内存会在内存池销毁时自动释放。 这提供了良好的分配性能并使内存控制变得容易。 内存池在内部以连续的内存块分配对象。 一旦一个块满了,就会分配一个新块并添加到内存池的内存块列表中。 当请求的分配太大而无法放入块中时,请求会转发到系统分配器, 返回的指针会存储在内存池中以便后续释放。 Angie 内存池的类型是 `ngx_pool_t`。 支持以下操作: * `ngx_create_pool(size, log)` — 创建具有指定块大小的内存池。 返回的内存池对象也在内存池中分配。 `size` 应至少为 `NGX_MIN_POOL_SIZE` 且是 `NGX_POOL_ALIGNMENT` 的倍数。 * `ngx_destroy_pool(pool)` — 释放所有内存池内存,包括内存池对象本身。 * `ngx_palloc(pool, size)` — 从指定的内存池分配对齐的内存。 * `ngx_pcalloc(pool, size)` — 从指定的内存池分配对齐的内存并用零填充。 * `ngx_pnalloc(pool, size)` — 从指定的内存池分配未对齐的内存。 主要用于分配字符串。 * `ngx_pfree(pool, p)` — 释放先前在指定内存池中分配的内存。 只有转发到系统分配器的分配请求才能被释放。 ```c u_char *p; ngx_str_t *s; ngx_pool_t *pool; pool = ngx_create_pool(1024, log); if (pool == NULL) { /* error */ } s = ngx_palloc(pool, sizeof(ngx_str_t)); if (s == NULL) { /* error */ } ngx_str_set(s, "foo"); p = ngx_pnalloc(pool, 3); if (p == NULL) { /* error */ } ngx_memcpy(p, "foo", 3); ``` 链接节点(`ngx_chain_t`)在 Angie 中被积极使用, 因此 Angie 内存池实现提供了一种重用它们的方法。 `ngx_pool_t` 的 `chain` 字段保存了一个先前分配的链接节点列表,可供重用。 要在内存池中高效分配链接节点,请使用 `ngx_alloc_chain_link(pool)` 函数。 此函数在内存池列表中查找空闲的链接节点,如果内存池列表为空则分配新的链接节点。 要释放链接节点,请调用 `ngx_free_chain(pool, cl)` 函数。 可以在内存池中注册清理处理程序。 清理处理程序是一个带参数的回调函数,在内存池销毁时调用。 内存池通常与特定的 Angie 对象(如 HTTP 请求)绑定,并在对象到达其生命周期结束时销毁。 注册内存池清理是释放资源、关闭文件描述符或对与主对象关联的共享数据进行最终调整的便捷方式。 要注册内存池清理,请调用 `ngx_pool_cleanup_add(pool, size)`,它返回一个 `ngx_pool_cleanup_t` 指针供调用者填充。 使用 `size` 参数为清理处理程序分配上下文。 ```c ngx_pool_cleanup_t *cln; cln = ngx_pool_cleanup_add(pool, 0); if (cln == NULL) { /* error */ } cln->handler = ngx_my_cleanup; cln->data = "foo"; ... static void ngx_my_cleanup(void *data) { u_char *msg = data; ngx_do_smth(msg); } ``` ### 共享内存 Angie 使用共享内存在进程之间共享公共数据。 `ngx_shared_memory_add(cf, name, size, tag)` 函数向周期添加一个新的共享内存条目 `ngx_shm_zone_t`。 该函数接收区域的 `name` 和 `size`。 每个共享区域必须有唯一的名称。 如果具有提供的 `name` 和 `tag` 的共享区域条目已存在,则重用现有的区域条目。 如果具有相同名称的现有条目具有不同的标签,该函数将失败并返回错误。 通常,模块结构的地址作为 `tag` 传递,这使得可以在一个 Angie 模块内按名称重用共享区域。 共享内存条目结构 `ngx_shm_zone_t` 具有以下字段: * `init` — 初始化回调,在共享区域映射到实际内存后调用 * `data` — 数据上下文,用于将任意数据传递给 `init` 回调 * `noreuse` — 禁用从旧周期重用共享区域的标志 * `tag` — 共享区域标签 * `shm` — 类型为 `ngx_shm_t` 的平台特定对象,至少具有以下字段: * `addr` — 映射的共享内存地址,初始为 NULL * `size` — 共享内存大小 * `name` — 共享内存名称 * `log` — 共享内存日志 * `exists` — 指示共享内存是否从主进程继承的标志(Windows 特定) 共享区域条目在配置解析后在 `ngx_init_cycle()` 中映射到实际内存。 在 POSIX 系统上,使用 `mmap()` 系统调用创建共享匿名映射。 在 Windows 上,使用 `CreateFileMapping()`/`MapViewOfFileEx()` 对。 为了在共享内存中分配,Angie 提供了 slab 池 `ngx_slab_pool_t` 类型。 用于分配内存的 slab 池会自动在每个 Angie 共享区域中创建。 该池位于共享区域的开头,可以通过表达式 `(ngx_slab_pool_t *) shm_zone->shm.addr` 访问。 要在共享区域中分配内存,请调用 `ngx_slab_alloc(pool, size)` 或 `ngx_slab_calloc(pool, size)`。 要释放内存,请调用 `ngx_slab_free(pool, p)`。 slab 池将所有共享区域划分为页面。 每个页面用于分配相同大小的对象。 指定的大小必须是 2 的幂,且大于最小大小 8 字节。 不符合的值会向上舍入。 每个页面的位掩码跟踪哪些块正在使用,哪些块可供分配。 对于大于半页(通常为 2048 字节)的大小,分配一次完成整个页面。 要保护共享内存中的数据免受并发访问,请使用 `ngx_slab_pool_t` 的 `mutex` 字段中可用的互斥锁。 互斥锁最常用于 slab 池在分配和释放内存时,但它也可用于保护在共享区域中分配的任何其他用户数据结构。 要锁定或解锁互斥锁,请分别调用 `ngx_shmtx_lock(&shpool->mutex)` 或 `ngx_shmtx_unlock(&shpool->mutex)`。 ```c ngx_str_t name; ngx_foo_ctx_t *ctx; ngx_shm_zone_t *shm_zone; ngx_str_set(&name, "foo"); /* allocate shared zone context */ ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t)); if (ctx == NULL) { /* error */ } /* add an entry for 64k shared zone */ shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module); if (shm_zone == NULL) { /* error */ } /* register init callback and context */ shm_zone->init = ngx_foo_init_zone; shm_zone->data = ctx; ... static ngx_int_t ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data) { ngx_foo_ctx_t *octx = data; size_t len; ngx_foo_ctx_t *ctx; ngx_slab_pool_t *shpool; value = shm_zone->data; if (octx) { /* reusing a shared zone from old cycle */ ctx->value = octx->value; return NGX_OK; } shpool = (ngx_slab_pool_t *) shm_zone->shm.addr; if (shm_zone->shm.exists) { /* initialize shared zone context in Windows Angie worker */ ctx->value = shpool->data; return NGX_OK; } /* initialize shared zone */ ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t)); if (ctx->value == NULL) { return NGX_ERROR; } shpool->data = ctx->value; return NGX_OK; } ``` ### 日志 Angie 使用 `ngx_log_t` 对象进行日志记录。 Angie 日志记录器支持多种输出类型: * stderr — 记录到标准错误(stderr) * file — 记录到文件 * syslog — 记录到 syslog * memory — 记录到内部内存存储以用于开发目的;可以稍后使用调试器访问内存 日志记录器实例可以是日志记录器链,通过 `next` 字段相互链接。 在这种情况下,每条消息都会写入链中的所有日志记录器。 对于每个日志记录器,严重性级别控制将哪些消息写入日志(仅记录分配了该级别或更高级别的事件)。 支持以下严重性级别: * `NGX_LOG_EMERG` * `NGX_LOG_ALERT` * `NGX_LOG_CRIT` * `NGX_LOG_ERR` * `NGX_LOG_WARN` * `NGX_LOG_NOTICE` * `NGX_LOG_INFO` * `NGX_LOG_DEBUG` 对于调试日志记录,还会检查调试掩码。 调试掩码包括: * `NGX_LOG_DEBUG_CORE` * `NGX_LOG_DEBUG_ALLOC` * `NGX_LOG_DEBUG_MUTEX` * `NGX_LOG_DEBUG_EVENT` * `NGX_LOG_DEBUG_HTTP` * `NGX_LOG_DEBUG_MAIL` * `NGX_LOG_DEBUG_STREAM` 通常,日志记录器由现有的 Angie 代码从 `error_log` 指令创建, 并在周期、配置、客户端连接和其他对象的几乎每个阶段都可用。 Angie 提供以下日志记录宏: * `ngx_log_error(level, log, err, fmt, ...)` — 错误日志记录 * `ngx_log_debug0(level, log, err, fmt)`, `ngx_log_debug1(level, log, err, fmt, arg1)` 等 — 调试日志记录, 最多支持八个格式化参数 日志消息在栈上大小为 `NGX_MAX_ERROR_STR`(当前为 2048 字节)的缓冲区中格式化。 消息前面会加上严重性级别、进程 ID(PID)、连接 ID(存储在 :samp:`log->connection` 中)和系统错误文本。 对于非调试消息,还会调用 `log->handler` 以在日志消息前添加更多特定信息。 HTTP 模块将 `ngx_http_log_error()` 函数设置为日志处理程序, 以记录客户端和服务器地址、当前操作(存储在 `log->action` 中)、客户端请求行、服务器名称等。 ```c /* specify what is currently done */ log->action = "sending mp4 to client"; /* error and debug log */ ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely closed connection"); ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0, "mp4 start:%ui, length:%ui", mp4->start, mp4->length); ``` 上面的示例会产生如下日志条目: ```text 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1" 2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000 ``` ### 周期 周期对象存储从特定配置创建的 Angie 运行时上下文。 其类型为 `ngx_cycle_t`。 当前周期由 `ngx_cycle` 全局变量引用, 并在 Angie worker 启动时被继承。 每次重新加载 Angie 配置时,都会从新的 Angie 配置创建一个新周期; 旧周期通常在新周期成功创建后被删除。 周期由 `ngx_init_cycle()` 函数创建, 该函数将前一个周期作为其参数。 该函数定位前一个周期的配置文件并尽可能多地从前一个周期继承资源。 在 Angie 启动时会创建一个名为"init cycle"的占位符周期, 然后被从配置构建的实际周期替换。 周期的成员包括: * `pool` — 周期池。 为每个新周期创建。 * `log` — 周期日志。 最初从旧周期继承,在读取配置后设置为指向 `new_log`。 * `new_log` — 周期日志,由配置创建。 受根作用域 `error_log` 指令影响。 * `connections`, `connection_n` — 类型为 `ngx_connection_t` 的连接数组, 由事件模块在初始化每个 Angie worker 时创建。 Angie 配置中的 `worker_connections` 指令设置连接数 `connection_n`。 * `free_connections`, `free_connection_n` — 当前可用连接的列表和数量。 如果没有可用连接,Angie worker 将拒绝接受新客户端或连接到上游服务器。 * `files`, `files_n` — 用于将文件描述符映射到 Angie 连接的数组。 此映射由具有 `NGX_USE_FD_EVENT` 标志的事件模块使用 (当前为 `poll` 和 `devpoll`)。 * `conf_ctx` — 核心模块配置数组。 配置在读取 Angie 配置文件时创建和填充。 * `modules`, `modules_n` — 类型为 `ngx_module_t` 的模块数组, 包括当前配置加载的静态和动态模块。 * `listening` — 类型为 `ngx_listening_t` 的监听对象数组。 监听对象通常由调用 `ngx_create_listening()` 函数的不同模块的 `listen` 指令添加。 监听套接字基于监听对象创建。 * `paths` — 类型为 `ngx_path_t` 的路径数组。 路径由将要操作某些目录的模块调用 `ngx_add_path()` 函数添加。 如果缺少这些目录,Angie 会在读取配置后创建它们。 此外,可以为每个路径添加两个处理程序: * path loader — 在启动或重新加载 Angie 后 60 秒内仅执行一次。 通常,加载器读取目录并将数据存储在 Angie 共享内存中。 该处理程序从专用的 Angie 进程"cache loader"调用。 * path manager — 定期执行。 通常,管理器从目录中删除旧文件并更新 Angie 内存以反映更改。 该处理程序从专用的"cache manager"进程调用。 * `open_files` — 类型为 `ngx_open_file_t` 的打开文件对象列表, 通过调用 `ngx_conf_open_file()` 函数创建。 目前,Angie 将这种打开文件用于日志记录。 读取配置后,Angie 打开 `open_files` 列表中的所有文件, 并将每个文件描述符存储在对象的 `fd` 字段中。 文件以追加模式打开,如果缺失则创建。 列表中的文件在 Angie worker 收到重新打开信号(最常见的是 `USR1`)时重新打开。 在这种情况下,:samp:fd 字段中的描述符会更改为新值。 * `shared_memory` — 共享内存区域列表, 每个通过调用 `ngx_shared_memory_add()` 函数添加。 共享区域在所有 Angie 进程中映射到相同的地址范围, 用于共享公共数据,例如 HTTP 缓存内存树。 ### Buffer 对于输入/输出操作,Angie 提供了缓冲区类型 `ngx_buf_t`。 通常,它用于保存要写入目标或从源读取的数据。 缓冲区可以引用内存中的数据或文件中的数据,从技术上讲,缓冲区可以同时引用两者。 缓冲区的内存是单独分配的,与缓冲区结构 `ngx_buf_t` 无关。 `ngx_buf_t` 结构具有以下字段: * `start`、`end` — 为缓冲区分配的内存块的边界。 * `pos`、`last` — 内存缓冲区的边界;通常是 `start` .. `end` 的子范围。 * `file_pos`、`file_last` — 文件缓冲区的边界,表示为从文件开头的偏移量。 * `tag` — 用于区分缓冲区的唯一值;由不同的 Angie 模块创建,通常用于缓冲区重用。 * `file` — 文件对象。 * `temporary` — 标志,指示缓冲区引用可写内存。 * `memory` — 标志,指示缓冲区引用只读内存。 * `in_file` — 标志,指示缓冲区引用文件中的数据。 * `flush` — 标志,指示需要刷新缓冲区之前的所有数据。 * `recycled` — 标志,指示缓冲区可以重用,需要尽快消费。 * `sync` — 标志,指示缓冲区不携带数据或特殊信号,如 `flush` 或 `last_buf`。 默认情况下,Angie 将此类缓冲区视为错误条件,但此标志告诉 Angie 跳过错误检查。 * `last_buf` — 标志,指示缓冲区是输出中的最后一个。 * `last_in_chain` — 标志,指示请求或子请求中没有更多数据缓冲区。 * `shadow` — 对与当前缓冲区相关的另一个("影子")缓冲区的引用,通常意味着缓冲区使用来自影子的数据。 当缓冲区被消费时,影子缓冲区通常也会被标记为已消费。 * `last_shadow` — 标志,指示缓冲区是引用特定影子缓冲区的最后一个。 * `temp_file` — 标志,指示缓冲区位于临时文件中。 对于输入和输出操作,缓冲区以链的形式链接。 链是类型为 `ngx_chain_t` 的链节点序列,定义如下: ```c typedef struct ngx_chain_s ngx_chain_t; struct ngx_chain_s { ngx_buf_t *buf; ngx_chain_t *next; }; ``` 每个链节点保存对其缓冲区的引用和对下一个链节点的引用。 使用缓冲区和链的示例: ```c ngx_chain_t * ngx_get_my_chain(ngx_pool_t *pool) { ngx_buf_t *b; ngx_chain_t *out, *cl, **ll; /* first buf */ cl = ngx_alloc_chain_link(pool); if (cl == NULL) { /* error */ } b = ngx_calloc_buf(pool); if (b == NULL) { /* error */ } b->start = (u_char *) "foo"; b->pos = b->start; b->end = b->start + 3; b->last = b->end; b->memory = 1; /* read-only memory */ cl->buf = b; out = cl; ll = &cl->next; /* second buf */ cl = ngx_alloc_chain_link(pool); if (cl == NULL) { /* error */ } b = ngx_create_temp_buf(pool, 3); if (b == NULL) { /* error */ } b->last = ngx_cpymem(b->last, "foo", 3); cl->buf = b; cl->next = NULL; *ll = cl; return out; } ``` ## 网络 ### 连接 连接类型 `ngx_connection_t` 是套接字描述符的包装器。 它包括以下字段: * `fd` — 套接字描述符 * `data` — 任意连接上下文。 通常,它是指向构建在连接之上的更高级别对象的指针,例如 HTTP 请求或 Stream 会话。 * `read`、`write` — 连接的读和写事件。 * `recv`、`send`、 `recv_chain`、`send_chain` — 连接的 I/O 操作。 * `pool` — 连接池。 * `log` — 连接日志。 * `sockaddr`、`socklen`、 `addr_text` — 二进制和文本形式的远程套接字地址。 * `local_sockaddr`、`local_socklen` — 二进制形式的本地套接字地址。 最初,这些字段为空。 使用 `ngx_connection_local_sockaddr()` 函数获取本地套接字地址。 * `proxy_protocol_addr`、`proxy_protocol_port` — PROXY protocol 客户端地址和端口,如果为连接启用了 PROXY protocol。 * `ssl` — 连接的 SSL 上下文。 * `reusable` — 标志,指示连接处于使其有资格重用的状态。 * `close` — 标志,指示连接正在被重用,需要关闭。 Angie 连接可以透明地封装 SSL 层。 在这种情况下,连接的 `ssl` 字段保存指向 `ngx_ssl_connection_t` 结构的指针,该结构保存连接的所有 SSL 相关数据,包括 `SSL_CTX` 和 `SSL`。 `recv`、`send`、 `recv_chain` 和 `send_chain` 处理程序也设置为支持 SSL 的函数。 Angie 配置中的 `worker_connections` 指令限制每个 Angie worker 的连接数。 所有连接结构在 worker 启动时预先创建,并存储在 cycle 对象的 `connections` 字段中。 要检索连接结构,使用 `ngx_get_connection(s, log)` 函数。 它将套接字描述符作为其 `s` 参数,该描述符需要包装在连接结构中。 由于每个 worker 的连接数有限,Angie 提供了一种获取当前正在使用的连接的方法。 要启用或禁用连接的重用,调用 `ngx_reusable_connection(c, reusable)` 函数。 调用 `ngx_reusable_connection(c, 1)` 在连接结构中设置 `reuse` 标志,并将连接插入到 cycle 的 `reusable_connections_queue` 中。 每当 `ngx_get_connection()` 发现 cycle 的 `free_connections` 列表中没有可用连接时,它会调用 `ngx_drain_connections()` 来释放特定数量的可重用连接。 对于每个这样的连接,设置 `close` 标志并调用其读处理程序,该处理程序应该通过调用 `ngx_close_connection(c)` 释放连接并使其可供重用。 要退出连接可以重用的状态,调用 `ngx_reusable_connection(c, 0)`。 HTTP 客户端连接是 Angie 中可重用连接的一个示例;它们被标记为可重用,直到从客户端接收到第一个请求字节。 ## 事件 ### 事件 Angie 中的事件对象 `ngx_event_t` 提供了一种机制,用于通知特定事件已发生。 `ngx_event_t` 中的字段包括: * `data` — 事件处理程序中使用的任意事件上下文,通常作为指向与事件相关的连接的指针。 * `handler` — 事件发生时要调用的回调函数。 * `write` — 标志,指示写事件。 缺少该标志表示读事件。 * `active` — 标志,指示事件已注册以接收 I/O 通知,通常来自通知机制,如 `epoll`、`kqueue`、`poll`。 * `ready` — 标志,指示事件已收到 I/O 通知。 * `delayed` — 标志,指示由于速率限制而延迟 I/O。 * `timer` — 用于将事件插入定时器树的红黑树节点。 * `timer_set` — 标志,指示事件定时器已设置且尚未过期。 * `timedout` — 标志,指示事件定时器已过期。 * `eof` — 标志,指示读取数据时发生 EOF。 * `pending_eof` — 标志,指示套接字上挂起 EOF,即使可能在它之前有一些可用数据。 该标志通过 `EPOLLRDHUP` `epoll` 事件或 `EV_EOF` `kqueue` 标志传递。 * `error` — 标志,指示在读取(对于读事件)或写入(对于写事件)期间发生错误。 * `cancelable` — 定时器事件标志,指示在关闭 worker 时应忽略该事件。 优雅的 worker 关闭会延迟,直到没有计划的不可取消定时器事件。 * `posted` — 标志,指示事件已发布到队列。 * `queue` — 用于将事件发布到队列的队列节点。 ### I/O 事件 通过调用 `ngx_get_connection()` 函数获得的每个连接都附加了两个事件,:samp:c->read 和 `c->write`,用于接收套接字准备好读取或写入的通知。 所有此类事件都在边缘触发模式下运行,这意味着它们仅在套接字状态更改时触发通知。 例如,在套接字上执行部分读取不会使 Angie 在更多数据到达套接字之前传递重复的读通知。 即使底层 I/O 通知机制本质上是水平触发(`poll`、`select` 等),Angie 也会将通知转换为边缘触发。 为了使 Angie 事件通知在不同平台上的所有通知系统中保持一致,必须在处理 I/O 套接字通知或在该套接字上调用任何 I/O 函数后调用函数 `ngx_handle_read_event(rev, flags)` 和 `ngx_handle_write_event(wev, lowat)`。 通常,这些函数在每个读或写事件处理程序结束时调用一次。 ### 定时器事件 可以将事件设置为在超时到期时发送通知。 事件使用的定时器从某个未指定的点开始计算毫秒数,截断为 `ngx_msec_t` 类型。 其当前值可以从 `ngx_current_msec` 变量获得。 函数 `ngx_add_timer(ev, timer)` 为事件设置超时,:samp:ngx_del_timer(ev) 删除先前设置的超时。 全局超时红黑树 `ngx_event_timer_rbtree` 存储当前设置的所有超时。 树中的键类型为 `ngx_msec_t`,是事件发生的时间。 树结构支持快速插入和删除操作,以及访问最近的超时,Angie 使用它来确定等待 I/O 事件的时间以及使超时事件过期。 ### 发布的事件 事件可以被发布,这意味着其处理程序将在当前事件循环迭代中的某个时刻稍后调用。 发布事件是简化代码和避免栈溢出的良好做法。 发布的事件保存在发布队列中。 `ngx_post_event(ev, q)` 宏将事件 `ev` 发布到发布队列 `q`。 `ngx_delete_posted_event(ev)` 宏从其当前发布的队列中删除事件 `ev`。 通常,事件被发布到 `ngx_posted_events` 队列,该队列在事件循环的后期处理 — 在所有 I/O 和定时器事件都已处理之后。 调用函数 `ngx_event_process_posted()` 来处理事件队列。 它调用事件处理程序,直到队列为空。 这意味着发布的事件处理程序可以发布更多事件,以便在当前事件循环迭代中处理。 示例: ```c void ngx_my_connection_read(ngx_connection_t *c) { ngx_event_t *rev; rev = c->read; ngx_add_timer(rev, 1000); rev->handler = ngx_my_read_handler; ngx_my_read(rev); } void ngx_my_read_handler(ngx_event_t *rev) { ssize_t n; ngx_connection_t *c; u_char buf[256]; if (rev->timedout) { /* timeout expired */ } c = rev->data; while (rev->ready) { n = c->recv(c, buf, sizeof(buf)); if (n == NGX_AGAIN) { break; } if (n == NGX_ERROR) { /* error */ } /* process buf */ } if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ } } ``` ### 事件循环 除了 Angie 主进程外,所有 Angie 进程都执行 I/O,因此都有事件循环。 (Angie 主进程大部分时间都花在 `sigsuspend()` 调用中等待信号到达。) Angie 事件循环在 `ngx_process_events_and_timers()` 函数中实现,该函数会重复调用,直到进程退出。 事件循环具有以下阶段: * 通过调用 `ngx_event_find_timer()` 查找最接近过期的超时。 此函数查找定时器树中最左边的节点,并返回节点过期前的毫秒数。 * 通过调用特定于事件通知机制的处理程序来处理 I/O 事件,该处理程序由 Angie 配置选择。 此处理程序至少等待一个 I/O 事件发生,但仅等到下一个超时到期。 当发生读或写事件时,设置 `ready` 标志并调用事件的处理程序。 对于 Linux,通常使用 `ngx_epoll_process_events()` 处理程序,它调用 `epoll_wait()` 等待 I/O 事件。 * 通过调用 `ngx_event_expire_timers()` 使定时器过期。 从最左边的元素到右边迭代定时器树,直到找到未过期的超时。 对于每个过期的节点,设置 `timedout` 事件标志,重置 `timer_set` 标志,并调用事件处理程序。 * 通过调用 `ngx_event_process_posted()` 处理发布的事件。 该函数重复从发布的事件队列中删除第一个元素并调用该元素的处理程序,直到队列为空。 所有 Angie 进程也处理信号。 信号处理程序仅设置全局变量,这些变量在 `ngx_process_events_and_timers()` 调用后检查。 ### 进程 Angie 中有几种类型的进程。 进程的类型保存在 `ngx_process` 全局变量中，可以是以下值之一： * `NGX_PROCESS_MASTER` — master 进程，读取 NGINX 配置，创建 cycle，并启动和控制子进程。 它不执行任何 I/O，仅响应信号。 其 cycle 函数是 `ngx_master_process_cycle()`。 * `NGX_PROCESS_WORKER` — worker 进程，处理客户端 连接。 它由 master 进程启动，并响应其信号和 channel 命令。 其 cycle 函数是 `ngx_worker_process_cycle()`。 可以有多个 worker 进程，由 `worker_processes` 指令配置。 * `NGX_PROCESS_SINGLE` — single 进程，仅存在于 `master_process off` 模式下，是该模式下运行的唯一进程。 它创建 cycle（像 master 进程一样）并处理客户端连接 （像 worker 进程一样）。 其 cycle 函数是 `ngx_single_process_cycle()`。 * `NGX_PROCESS_HELPER` — helper 进程，目前 有两种类型：cache manager 和 cache loader。 两者的 cycle 函数都是 `ngx_cache_manager_process_cycle()`。 Angie 进程处理以下信号： * `NGX_SHUTDOWN_SIGNAL`（在大多数系统上是 :samp:`SIGQUIT`）— 优雅关闭。 收到此信号后，master 进程向所有 子进程发送关闭信号。 当没有子进程剩余时，master 销毁 cycle 池并退出。 当 worker 进程收到此信号时，它关闭所有监听套接字并 等待直到没有不可取消的事件被调度，然后销毁 cycle 池并退出。 当 cache manager 或 cache loader 进程收到此信号时，它 立即退出。 当进程收到此信号时，`ngx_quit` 变量被设置为 `1`， 并在处理后立即重置。 当 worker 进程处于关闭状态时，`ngx_exiting` 变量被设置为 `1`。 * `NGX_TERMINATE_SIGNAL`（在大多数系统上是 :samp:`SIGTERM`）— 终止。 收到此信号后，master 进程向所有 子进程发送终止信号。 如果子进程在 1 秒内未退出，master 进程发送 `SIGKILL` 信号来杀死它。 当没有子进程剩余时，master 进程销毁 cycle 池并 退出。 当 worker 进程、cache manager 进程或 cache loader 进程 收到此信号时，它销毁 cycle 池并退出。 收到此信号时，变量 `ngx_terminate` 被设置为 `1`。 * `NGX_NOACCEPT_SIGNAL`（在大多数系统上是 :samp:`SIGWINCH`）— 关闭所有 worker 和 helper 进程。 收到此信号后，master 进程关闭其子进程。 如果先前启动的新 Angie 二进制文件退出，旧 master 的子进程将再次启动。 当 worker 进程收到此信号时，它在由 `debug_points` 指令设置的调试模式下关闭。 * `NGX_RECONFIGURE_SIGNAL`（在大多数系统上是 :samp:`SIGHUP`）— 重新配置。 收到此信号后，master 进程重新读取配置并 基于它创建一个新的 cycle。 如果新 cycle 创建成功，旧 cycle 被删除并启动新的 子进程。 同时，旧的子进程接收 `NGX_SHUTDOWN_SIGNAL` 信号。 在 single-process 模式下，Angie 创建一个新 cycle，但保留旧的 cycle， 直到不再有客户端与其绑定的活动连接。 worker 和 helper 进程忽略此信号。 * `NGX_REOPEN_SIGNAL`（在大多数系统上是 :samp:`SIGUSR1`）— 重新打开文件。 master 进程将此信号发送给 worker，worker 重新打开所有 与 cycle 相关的 `open_files`。 * `NGX_CHANGEBIN_SIGNAL`（在大多数系统上是 :samp:`SIGUSR2`）— 更改 Angie 二进制文件。 master 进程启动一个新的 Angie 二进制文件并传入所有监听 套接字的列表。 在 `"NGINX"` 环境变量中传递的文本格式列表， 由用分号分隔的描述符编号组成。 新的 Angie 二进制文件读取 `"NGINX"` 变量并将 套接字添加到其 init cycle。 其他进程忽略此信号。 虽然所有 Angie worker 进程都能够接收并正确处理 POSIX 信号，但 master 进程不使用标准 `kill()` 系统调用来向 worker 和 helper 传递信号。 相反，Angie 使用进程间套接字对，允许在所有 Angie 进程之间发送消息。 但是，目前消息仅从 master 发送到其子进程。 消息携带标准信号。 ### 线程 可以将原本会阻塞 Angie worker 进程的任务卸载到单独的线程中。 例如，Angie 可以配置为使用线程执行 [文件 I/O](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#aio)。 另一个用例是没有异步接口的库， 因此无法正常与 Angie 一起使用。 请记住，线程接口是现有异步方法处理客户端连接的辅助工具， 绝不是替代品。 为了处理同步，提供了以下对 `pthreads` 原语的包装： * `typedef pthread_mutex_t ngx_thread_mutex_t;` * `ngx_int_t ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log);` * `ngx_int_t ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log);` * `ngx_int_t ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log);` * `ngx_int_t ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log);` * `typedef pthread_cond_t ngx_thread_cond_t;` * `ngx_int_t ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log);` * `ngx_int_t ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log);` * `ngx_int_t ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log);` * `ngx_int_t ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx, ngx_log_t *log);` Angie 实现了 [thread_pool](https://cn.angie.software//angie/docs/configuration/modules/core.md#thread-pool) 策略， 而不是为每个任务创建一个新线程。 可以为不同的目的配置多个线程池 （例如，在不同的磁盘集上执行 I/O）。 每个线程池在启动时创建，包含有限数量的线程， 这些线程处理任务队列。 当任务完成时，会调用预定义的完成处理程序。 `src/core/ngx_thread_pool.h` 头文件包含 相关定义： ```c struct ngx_thread_task_s { ngx_thread_task_t *next; ngx_uint_t id; void *ctx; void (*handler)(void *data, ngx_log_t *log); ngx_event_t event; }; typedef struct ngx_thread_pool_s ngx_thread_pool_t; ngx_thread_pool_t *ngx_thread_pool_add(ngx_conf_t *cf, ngx_str_t *name); ngx_thread_pool_t *ngx_thread_pool_get(ngx_cycle_t *cycle, ngx_str_t *name); ngx_thread_task_t *ngx_thread_task_alloc(ngx_pool_t *pool, size_t size); ngx_int_t ngx_thread_task_post(ngx_thread_pool_t *tp, ngx_thread_task_t *task); ``` 在配置时，希望使用线程的模块必须通过调用 `ngx_thread_pool_add(cf, name)` 获得对线程池的引用， 该函数要么创建一个具有给定 `name` 的新线程池， 要么返回对该名称的池的引用（如果它已经存在）。 要在运行时将 `task` 添加到指定线程池 `tp` 的队列中，使用 `ngx_thread_task_post(tp, task)` 函数。 要在线程中执行函数，传递参数并设置完成 处理程序，使用 `ngx_thread_task_t` 结构： ```c typedef struct { int foo; } my_thread_ctx_t; static void my_thread_func(void *data, ngx_log_t *log) { my_thread_ctx_t *ctx = data; /* this function is executed in a separate thread */ } static void my_thread_completion(ngx_event_t *ev) { my_thread_ctx_t *ctx = ev->data; /* executed in Angie event loop */ } ngx_int_t my_task_offload(my_conf_t *conf) { my_thread_ctx_t *ctx; ngx_thread_task_t *task; task = ngx_thread_task_alloc(conf->pool, sizeof(my_thread_ctx_t)); if (task == NULL) { return NGX_ERROR; } ctx = task->ctx; ctx->foo = 42; task->handler = my_thread_func; task->event.handler = my_thread_completion; task->event.data = ctx; if (ngx_thread_task_post(conf->thread_pool, task) != NGX_OK) { return NGX_ERROR; } return NGX_OK; } ``` ## 模块 ### 添加新模块 每个独立的 Angie 模块都位于一个单独的目录中，该目录至少包含两个文件： `config` 和一个包含模块源代码的文件。 `config` 文件包含 Angie 集成模块所需的所有信息，例如： ```bash ngx_module_type=CORE ngx_module_name=ngx_foo_module ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c" . auto/module ngx_addon_name=$ngx_module_name ``` `config` 文件是一个 POSIX shell 脚本，可以设置 和访问以下变量： * `ngx_module_type` — 要构建的模块类型。 可能的值是 `CORE`、`HTTP`、 `HTTP_FILTER`、`HTTP_INIT_FILTER`、 `HTTP_AUX_FILTER`、`MAIL`、 `STREAM` 或 `MISC`。 * `ngx_module_name` — 模块名称。 要从一组源文件构建多个模块，请指定一个 以空格分隔的名称列表。 第一个名称表示动态模块的输出二进制文件的名称。 列表中的名称必须与源代码中使用的名称匹配。 * `ngx_addon_name` — 模块的名称，显示在 configure 脚本的控制台输出中。 * `ngx_module_srcs` — 用于编译模块的源 文件的空格分隔列表。 `$ngx_addon_dir` 变量可用于表示模块目录的路径。 * `ngx_module_incs` — 构建模块所需的包含路径 * `ngx_module_deps` — 模块依赖项的空格分隔列表。 通常，它是头文件的列表。 * `ngx_module_libs` — 要与模块链接的库的空格分隔列表。 例如，使用 `ngx_module_libs=-lpthread` 来链接 `libpthread` 库。 以下宏可用于链接与 Angie 相同的库： `LIBXSLT`、`LIBGD`、`GEOIP`、 `PCRE`、`OPENSSL`、`MD5`、 `SHA1`、`ZLIB` 和 `PERL`。 * `ngx_module_link` — 由构建系统设置为 `DYNAMIC`（用于动态模块）或 :samp:`ADDON` （用于静态模块）的变量，用于根据链接类型确定要执行的不同操作。 * `ngx_module_order` — 模块的加载顺序； 对 `HTTP_FILTER` 和 `HTTP_AUX_FILTER` 模块类型很有用。 此选项的格式是一个以空格分隔的模块列表。 列表中当前模块名称之后的所有模块在 全局模块列表中排在它之后，这设置了模块初始化的顺序。 对于过滤器模块，较晚的初始化意味着较早的执行。 以下模块通常用作参考。 `ngx_http_copy_filter_module` 为其他过滤器模块读取数据， 并放置在列表的底部附近，因此它是最先执行的模块之一。 `ngx_http_write_filter_module` 将数据写入客户端套接字， 并放置在列表的顶部附近，是最后执行的模块。 默认情况下，过滤器模块放置在模块列表中 `ngx_http_copy_filter` 之前，因此过滤器处理程序在复制过滤器处理程序之后执行。 对于其他模块类型，默认值是空字符串。 要将模块静态编译到 Angie 中，使用 `--add-module=/path/to/module` 参数传递给 configure 脚本。 要将模块编译为稍后动态加载到 Angie 中，使用 `--add-dynamic-module=/path/to/module` 参数。 ### 核心模块 模块是 Angie 的构建块,其大部分功能都是作为模块实现的。 模块源文件必须包含一个 `ngx_module_t` 类型的全局变量,其定义如下: ```c struct ngx_module_s { /* 省略私有部分 */ void *ctx; ngx_command_t *commands; ngx_uint_t type; ngx_int_t (*init_master)(ngx_log_t *log); ngx_int_t (*init_module)(ngx_cycle_t *cycle); ngx_int_t (*init_process)(ngx_cycle_t *cycle); ngx_int_t (*init_thread)(ngx_cycle_t *cycle); void (*exit_thread)(ngx_cycle_t *cycle); void (*exit_process)(ngx_cycle_t *cycle); void (*exit_master)(ngx_cycle_t *cycle); /* 省略未来扩展的存根 */ }; ``` 省略的私有部分包括模块版本和签名,使用预定义的宏 `NGX_MODULE_V1` 填充。 每个模块在 `ctx` 字段中保存其私有数据, 识别在 `commands` 数组中指定的配置指令,并可在 Angie 生命周期的特定阶段被调用。 模块生命周期包含以下事件: * 配置指令处理程序在配置文件中出现时被调用,在主进程的上下文中。 * 配置成功解析后,在主进程的上下文中调用 `init_module` 处理程序。 每次加载配置时,都会在主进程中调用 `init_module` 处理程序。 * 主进程创建一个或多个工作进程,并在每个工作进程中调用 `init_process` 处理程序。 * 当工作进程从主进程接收到关闭或终止命令时,它调用 `exit_process` 处理程序。 * 主进程在退出前调用 `exit_master` 处理程序。 由于线程在 Angie 中仅用作具有自己 API 的辅助 I/O 设施,因此 `init_thread` 和 `exit_thread` 处理程序目前不会被调用。 也没有 `init_master` 处理程序,因为这会是不必要的开销。 模块 `type` 准确定义了 `ctx` 字段中存储的内容。 其值为以下类型之一: * `NGX_CORE_MODULE` * `NGX_EVENT_MODULE` * `NGX_HTTP_MODULE` * `NGX_MAIL_MODULE` * `NGX_STREAM_MODULE` `NGX_CORE_MODULE` 是最基本的,因此也是最通用和最低级的模块类型。 其他模块类型在其之上实现,并提供更便捷的方式来处理相应的领域,如处理事件或 HTTP 请求。 核心模块集包括 `ngx_core_module`、 `ngx_errlog_module`、`ngx_regex_module`、 `ngx_thread_pool_module` 和 `ngx_openssl_module` 模块。 HTTP 模块、stream 模块、mail 模块和 event 模块也是核心模块。 核心模块的上下文定义为: ```c typedef struct { ngx_str_t name; void *(*create_conf)(ngx_cycle_t *cycle); char *(*init_conf)(ngx_cycle_t *cycle, void *conf); } ngx_core_module_t; ``` 其中 `name` 是模块名称字符串, `create_conf` 和 `init_conf` 是指向创建和初始化模块配置的函数的指针。 对于核心模块,Angie 在解析新配置之前调用 `create_conf`,在所有配置成功解析后调用 `init_conf`。 典型的 `create_conf` 函数为配置分配内存并设置默认值。 例如，一个名为 `ngx_foo_module` 的简单模块可能如下所示： ```c /* * Copyright (C) Author. */ #include #include typedef struct { ngx_flag_t enable; } ngx_foo_conf_t; static void *ngx_foo_create_conf(ngx_cycle_t *cycle); static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf); static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data); static ngx_conf_post_t ngx_foo_enable_post = { ngx_foo_enable }; static ngx_command_t ngx_foo_commands[] = { { ngx_string("foo_enabled"), NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG, ngx_conf_set_flag_slot, 0, offsetof(ngx_foo_conf_t, enable), &ngx_foo_enable_post }, ngx_null_command }; static ngx_core_module_t ngx_foo_module_ctx = { ngx_string("foo"), ngx_foo_create_conf, ngx_foo_init_conf }; ngx_module_t ngx_foo_module = { NGX_MODULE_V1, &ngx_foo_module_ctx, /* module context */ ngx_foo_commands, /* module directives */ NGX_CORE_MODULE, /* module type */ NULL, /* init master */ NULL, /* init module */ NULL, /* init process */ NULL, /* init thread */ NULL, /* exit thread */ NULL, /* exit process */ NULL, /* exit master */ NGX_MODULE_V1_PADDING }; static void * ngx_foo_create_conf(ngx_cycle_t *cycle) { ngx_foo_conf_t *fcf; fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t)); if (fcf == NULL) { return NULL; } fcf->enable = NGX_CONF_UNSET; return fcf; } static char * ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf) { ngx_foo_conf_t *fcf = conf; ngx_conf_init_value(fcf->enable, 0); return NGX_CONF_OK; } static char * ngx_foo_enable(ngx_conf_t *cf, void *post, void *data) { ngx_flag_t *fp = data; if (*fp == 0) { return NGX_CONF_OK; } ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled"); return NGX_CONF_OK; } ``` ### 配置指令 `ngx_command_t` 类型定义单个配置指令。 每个支持配置的模块都提供一个此类结构的数组,描述如何处理参数以及调用哪些处理程序: ```c typedef struct ngx_command_s ngx_command_t; struct ngx_command_s { ngx_str_t name; ngx_uint_t type; char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); ngx_uint_t conf; ngx_uint_t offset; void *post; }; ``` 使用特殊值 `ngx_null_command` 终止数组。 `name` 是指令在配置文件中出现的名称,例如 "worker_processes" 或 "listen"。 `type` 是标志的位字段,指定指令接受的参数数量、其类型以及它出现的上下文。 标志包括: * `NGX_CONF_NOARGS` — 指令不接受参数。 * `NGX_CONF_1MORE` — 指令接受一个或多个参数。 * `NGX_CONF_2MORE` — 指令接受两个或多个参数。 * `NGX_CONF_TAKE1` .. `NGX_CONF_TAKE7` — 指令恰好接受指定数量的参数。 * `NGX_CONF_TAKE12`、`NGX_CONF_TAKE13`、 `NGX_CONF_TAKE23`、`NGX_CONF_TAKE123`、 `NGX_CONF_TAKE1234` — 指令可以接受不同数量的参数。 选项限于指定的数字。 例如,:samp:NGX_CONF_TAKE12 表示它接受一个或两个参数。 指令类型的标志: * `NGX_CONF_BLOCK` — 指令是一个块,即它可以在其开闭大括号内包含其他指令,甚至实现自己的解析器来处理内部内容。 * `NGX_CONF_FLAG` — 指令接受布尔值, `on` 或 `off`。 指令上下文定义它可以出现在配置中的位置: * `NGX_MAIN_CONF` — 在顶级上下文中。 * `NGX_HTTP_MAIN_CONF` — 在 `http` 块中。 * `NGX_HTTP_SRV_CONF` — 在 `http` 块内的 `server` 块中。 * `NGX_HTTP_LOC_CONF` — 在 `http` 块内的 `location` 块中。 * `NGX_HTTP_UPS_CONF` — 在 `http` 块内的 `upstream` 块中。 * `NGX_HTTP_SIF_CONF` — 在 `http` 块的 `server` 块内的 `if` 块中。 * `NGX_HTTP_LIF_CONF` — 在 `http` 块的 `location` 块内的 `if` 块中。 * `NGX_HTTP_LMT_CONF` — 在 `http` 块内的 `limit_except` 块中。 * `NGX_STREAM_MAIN_CONF` — 在 `stream` 块中。 * `NGX_STREAM_SRV_CONF` — 在 `stream` 块内的 `server` 块中。 * `NGX_STREAM_UPS_CONF` — 在 `stream` 块内的 `upstream` 块中。 * `NGX_MAIL_MAIN_CONF` — 在 `mail` 块中。 * `NGX_MAIL_SRV_CONF` — 在 `mail` 块内的 `server` 块中。 * `NGX_EVENT_CONF` — 在 `events` 块中。 * `NGX_DIRECT_CONF` — 由不创建上下文层次结构且只有单个全局配置的模块使用。 此配置作为 `conf` 参数传递给处理程序。 配置解析器使用这些标志为放错位置的指令抛出错误,并使用适当的配置指针调用指令处理程序,以便相同的指令在不同位置可以将其值存储在不同的位置。 `set` 字段定义一个处理程序,用于处理指令并将解析的值存储到相应的配置中。 有许多函数执行常见的转换: * `ngx_conf_set_flag_slot` — 将字面字符串 `on` 和 `off` 转换为值为 1 或 0 的 `ngx_flag_t` 值。 * `ngx_conf_set_str_slot` — 将字符串存储为 `ngx_str_t` 类型的值。 * `ngx_conf_set_str_array_slot` — 将值追加到字符串 `ngx_str_t` 的数组 `ngx_array_t` 中。 如果数组不存在则创建它。 * `ngx_conf_set_keyval_slot` — 将键值对追加到键值对 `ngx_keyval_t` 的数组 `ngx_array_t` 中。 第一个字符串成为键,第二个成为值。 如果数组不存在则创建它。 * `ngx_conf_set_num_slot` — 将指令的参数转换为 `ngx_int_t` 值。 * `ngx_conf_set_size_slot` — 将 [大小](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax) 转换为以字节表示的 `size_t` 值。 * `ngx_conf_set_off_slot` — 将 [偏移量](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax) 转换为以字节表示的 `off_t` 值。 * `ngx_conf_set_msec_slot` — 将 [时间](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax) 转换为以毫秒表示的 `ngx_msec_t` 值。 * `ngx_conf_set_sec_slot` — 将 [时间](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax) 转换为以秒表示的 `time_t` 值。 * `ngx_conf_set_bufs_slot` — 将提供的两个参数转换为包含缓冲区数量和 [大小](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax) 的 `ngx_bufs_t` 对象。 * `ngx_conf_set_enum_slot` — 将提供的参数转换为 `ngx_uint_t` 值。 在 `post` 字段中传递的以 null 结尾的 `ngx_conf_enum_t` 数组定义可接受的字符串和相应的整数值。 * `ngx_conf_set_bitmask_slot` — 将提供的参数转换为 `ngx_uint_t` 值。 每个参数的掩码值进行 OR 运算产生结果。 在 `post` 字段中传递的以 null 结尾的 `ngx_conf_bitmask_t` 数组定义可接受的字符串和相应的掩码值。 * `ngx_conf_set_path_slot` — 将提供的参数转换为 `ngx_path_t` 值并执行所有必要的初始化。 有关详细信息,请参阅 [proxy_temp_path](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-temp-path) 指令的文档。 * `ngx_conf_set_access_slot` — 将提供的参数转换为文件权限掩码。 有关详细信息,请参阅 [proxy_store_access](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-store-access) 指令的文档。 `conf` 字段定义将哪个配置结构传递给指令处理程序。 核心模块只有全局配置并设置 `NGX_DIRECT_CONF` 标志来访问它。 HTTP、Stream 或 Mail 等模块创建配置层次结构。 例如,为 `server`、`location` 和 `if` 作用域创建模块的配置。 * `NGX_HTTP_MAIN_CONF_OFFSET` — `http` 块的配置。 * `NGX_HTTP_SRV_CONF_OFFSET` — `http` 块内 `server` 块的配置。 * `NGX_HTTP_LOC_CONF_OFFSET` — `http` 块内 `location` 块的配置。 * `NGX_STREAM_MAIN_CONF_OFFSET` — `stream` 块的配置。 * `NGX_STREAM_SRV_CONF_OFFSET` — `stream` 块内 `server` 块的配置。 * `NGX_MAIL_MAIN_CONF_OFFSET` — `mail` 块的配置。 * `NGX_MAIL_SRV_CONF_OFFSET` — `mail` 块内 `server` 块的配置。 `offset` 字段定义模块配置结构中保存此特定指令值的字段的偏移量。 典型用法是使用 `offsetof()` 宏。 `post` 字段有两个用途:它可用于定义在主处理程序完成后调用的处理程序,或将额外数据传递给主处理程序。 在第一种情况下,需要使用指向处理程序的指针初始化 `ngx_conf_post_t` 结构,例如: ```c static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data); static ngx_conf_post_t ngx_foo_post = { ngx_do_foo }; ``` `post` 参数是 `ngx_conf_post_t` 对象本身,:samp:data 是指向值的指针,由主处理程序使用适当的类型从参数转换而来。 ## HTTP ### 连接 每个 HTTP 客户端连接都会经历以下阶段： * `ngx_event_accept()` 接受客户端 TCP 连接。 此处理程序在监听套接字上收到读通知时被调用。 在此阶段会创建一个新的 `ngx_connection_t` 对象 来封装新接受的客户端套接字。 每个 Angie 监听器都提供一个处理程序来传递新的连接对象。 对于 HTTP 连接，它是 `ngx_http_init_connection(c)`。 * `ngx_http_init_connection()` 执行 HTTP 连接的早期初始化。 在此阶段会为连接创建一个 `ngx_http_connection_t` 对象， 并将其引用存储在连接的 `data` 字段中。 稍后它将被 HTTP 请求对象替换。 PROXY 协议解析器和 SSL 握手也在此阶段启动。 * `ngx_http_wait_request_handler()` 读事件处理程序 在客户端套接字上有数据可用时被调用。 在此阶段会创建一个 HTTP 请求对象 `ngx_http_request_t` 并设置到连接的 `data` 字段。 * `ngx_http_process_request_line()` 读事件处理程序 读取客户端请求行。 该处理程序由 `ngx_http_wait_request_handler()` 设置。 数据被读入连接的 `buffer`。 缓冲区的大小最初由 [client_header_buffer_size](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#client-header-buffer-size) 指令设置。 整个客户端头部应该能够放入该缓冲区。 如果初始大小不够，则会分配一个更大的缓冲区， 其容量由 [large_client_header_buffers](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers) 指令设置。 * `ngx_http_process_request_headers()` 读事件处理程序， 在 `ngx_http_process_request_line()` 之后设置， 用于读取客户端请求头。 * `ngx_http_core_run_phases()` 在请求头完全读取和解析后被调用。 此函数运行从 `NGX_HTTP_POST_READ_PHASE` 到 `NGX_HTTP_CONTENT_PHASE` 的请求阶段。 最后一个阶段旨在生成响应并沿过滤器链传递。 响应不一定在此阶段发送到客户端。 它可能保持缓冲状态并在最终化阶段发送。 * `ngx_http_finalize_request()` 通常在请求生成所有输出 或产生错误时被调用。 在后一种情况下，会查找适当的错误页面并将其用作响应。 如果此时响应尚未完全发送到客户端， 则会激活 HTTP 写入器 `ngx_http_writer()` 来完成发送未完成的数据。 * `ngx_http_finalize_connection()` 在完整响应已发送到客户端 且请求可以被销毁时被调用。 如果启用了客户端连接保持活动功能， 则会调用 `ngx_http_set_keepalive()`，它会销毁当前请求 并等待连接上的下一个请求。 否则，`ngx_http_close_request()` 会同时销毁请求和连接。 ### 请求 对于每个客户端 HTTP 请求，都会创建 `ngx_http_request_t` 对象。 此对象的一些字段包括： * `connection` — 指向 `ngx_connection_t` 客户端连接对象的指针。 多个请求可以同时引用同一个连接对象 - 一个主请求及其子请求。 请求被删除后，可以在同一连接上创建新请求。 请注意，对于 HTTP 连接，`ngx_connection_t` 的 `data` 字段会指回请求。 这样的请求称为活动请求，与绑定到连接的其他请求相对。 活动请求用于处理客户端连接事件，并被允许将其响应输出到客户端。 通常，每个请求在某个时刻都会变为活动状态，以便它可以发送其输出。 * `ctx` — HTTP 模块上下文数组。 每个类型为 `NGX_HTTP_MODULE` 的模块都可以在请求中存储任何值 （通常是指向结构的指针）。 该值存储在 `ctx` 数组中模块的 `ctx_index` 位置。 以下宏提供了获取和设置请求上下文的便捷方式： * `ngx_http_get_module_ctx(r, module)` — 返回 `module` 的上下文 * `ngx_http_set_ctx(r, c, module)` — 将 `c` 设置为 `module` 的上下文 * `main_conf`、`srv_conf`、 `loc_conf` — 当前请求配置的数组。 配置存储在模块的 `ctx_index` 位置。 * `read_event_handler`、`write_event_handler` - 请求的读和写事件处理程序。 通常，HTTP 连接的读和写事件处理程序都设置为 `ngx_http_request_handler()`。 此函数为当前活动请求调用 `read_event_handler` 和 `write_event_handler` 处理程序。 * `cache` — 用于缓存上游响应的请求缓存对象。 * `upstream` — 用于代理的请求上游对象。 * `pool` — 请求池。 请求对象本身在此池中分配，该池在请求被删除时销毁。 对于需要在整个客户端连接生命周期内可用的分配， 请改用 `ngx_connection_t` 的池。 * `header_in` — 读入客户端 HTTP 请求头的缓冲区。 * `headers_in`、`headers_out` — 输入和输出 HTTP 头对象。 两个对象都包含类型为 `ngx_list_t` 的 `headers` 字段， 用于保存原始头列表。 除此之外，特定的头可以作为单独的字段进行获取和设置， 例如 `content_length_n`、`status` 等。 * `request_body` — 客户端请求体对象。 * `start_sec`、`start_msec` — 请求创建时的时间点， 用于跟踪请求持续时间。 * `method`、`method_name` — 客户端 HTTP 请求方法的数字和文本表示。 方法的数字值在 `src/http/ngx_http_request.h` 中定义， 使用宏 `NGX_HTTP_GET`、`NGX_HTTP_HEAD`、 `NGX_HTTP_POST` 等。 * `http_protocol` — 客户端 HTTP 协议版本的原始文本形式 （"HTTP/1.0"、"HTTP/1.1" 等）。 * `http_version` — 客户端 HTTP 协议版本的数字形式 （`NGX_HTTP_VERSION_10`、`NGX_HTTP_VERSION_11` 等）。 * `http_major`、`http_minor` — 客户端 HTTP 协议版本的数字形式， 分为主版本号和次版本号。 * `request_line`、`unparsed_uri` — 原始客户端请求中的请求行和 URI。 * `uri`、`args`、`exten` — 当前请求的 URI、参数和文件扩展名。 这里的 URI 值可能与客户端发送的原始 URI 不同， 因为进行了规范化。 在整个请求处理过程中，这些值可能会随着内部重定向的执行而改变。 * `main` — 指向主请求对象的指针。 此对象是为处理客户端 HTTP 请求而创建的，与子请求相对， 子请求是为在主请求中执行特定子任务而创建的。 * `parent` — 指向子请求的父请求的指针。 * `postponed` — 输出缓冲区和子请求的列表， 按照它们被发送和创建的顺序排列。 该列表由 postpone 过滤器使用，以便在部分输出由子请求创建时 提供一致的请求输出。 * `post_subrequest` — 指向处理程序及其上下文的指针， 在子请求完成时调用。 对主请求未使用。 * `posted_requests` — 要启动或恢复的请求列表， 通过调用请求的 `write_event_handler` 来完成。 通常，此处理程序保存请求的主函数， 该函数首先运行请求阶段，然后生成输出。 请求通常通过 `ngx_http_post_request(r, NULL)` 调用来发布。 它总是被发布到主请求的 `posted_requests` 列表。 函数 `ngx_http_run_posted_requests(c)` 运行所有 在传递的连接的活动请求的主请求中发布的请求。 所有事件处理程序都会调用 `ngx_http_run_posted_requests`， 这可能导致新的发布请求。 通常，它在调用请求的读或写处理程序后被调用。 * `phase_handler` — 当前请求阶段的索引。 * `ncaptures`、`captures`、 `captures_data` — 请求最后一次正则表达式匹配产生的正则捕获。 正则匹配可能在请求处理期间的多个地方发生： map 查找、通过 SNI 或 HTTP Host 进行服务器查找、rewrite、proxy_redirect 等。 查找产生的捕获存储在上述字段中。 字段 `ncaptures` 保存捕获的数量， `captures` 保存捕获的边界， `captures_data` 保存与正则表达式匹配的字符串， 用于提取捕获。 每次新的正则匹配后，请求捕获都会重置以保存新值。 * `count` — 请求引用计数器。 该字段仅对主请求有意义。 增加计数器通过简单的 `r->main->count++` 完成。 要减少计数器，调用 `ngx_http_finalize_request(r, rc)`。 创建子请求和运行请求体读取过程都会增加计数器。 * `subrequests` — 当前子请求嵌套级别。 每个子请求继承其父级的嵌套级别，减一。 如果该值达到零，则会生成错误。 主请求的值由 `NGX_HTTP_MAX_SUBREQUESTS` 常量定义。 * `uri_changes` — 请求剩余的 URI 更改次数。 请求可以更改其 URI 的总次数受 `NGX_HTTP_MAX_URI_CHANGES` 常量限制。 每次更改时，该值都会递减，直到达到零，此时会生成错误。 重写和内部重定向到普通或命名位置都被视为 URI 更改。 * `blocked` — 请求上持有的阻塞计数器。 当此值非零时，请求无法被最终化。 目前，此值因待处理的 AIO 操作（POSIX AIO 和线程操作） 和活动缓存锁而增加。 * `buffered` — 位掩码，显示哪些模块缓冲了请求产生的输出。 许多过滤器可以缓冲输出；例如，sub_filter 可能因部分字符串匹配而缓冲数据， copy 过滤器可能因缺少空闲输出缓冲区而缓冲数据，等等。 只要此值非零，请求就不会被最终化，等待刷新。 * `header_only` — 标志，指示输出不需要正文。 例如，此标志用于 HTTP HEAD 请求。 * `keepalive` — 标志，指示是否支持客户端连接保持活动。 该值从 HTTP 版本和 "Connection" 头的值推断。 * `header_sent` — 标志，指示请求已发送输出头。 * `internal` — 标志，指示当前请求是内部的。 要进入内部状态，请求必须经过内部重定向或是子请求。 内部请求被允许进入内部位置。 * `allow_ranges` — 标志，指示可以根据 HTTP Range 头的请求 向客户端发送部分响应。 * `subrequest_ranges` — 标志，指示在处理子请求时 可以发送部分响应。 * `single_range` — 标志，指示只能向客户端发送单个连续范围的输出数据。 此标志通常在发送数据流时设置，例如从代理服务器， 并且整个响应在单个缓冲区中不可用。 * `main_filter_need_in_memory`、 `filter_need_in_memory` — 标志， 请求在内存缓冲区而不是文件中生成输出。 这是对 copy 过滤器的信号，即使启用了 sendfile， 也要从文件缓冲区读取数据。 这两个标志之间的区别在于设置它们的过滤器模块的位置。 在过滤器链中 postpone 过滤器之前调用的过滤器设置 `filter_need_in_memory`，请求只有当前请求的输出 进入内存缓冲区。 在过滤器链中稍后调用的过滤器设置 `main_filter_need_in_memory`，请求主请求和所有子请求 在发送输出时将文件读入内存。 * `filter_need_temporary` — 标志，请求在临时缓冲区中生成请求输出， 但不在只读内存缓冲区或文件缓冲区中。 这由可能直接在发送缓冲区中更改输出的过滤器使用。 ### HTTP 模块配置 每个 HTTP 模块可以有三种类型的配置： * 主配置 — 应用于整个 `http` 块。 作为模块的全局设置。 * 服务器配置 — 应用于单个 `server` 块。 作为模块的服务器特定设置。 * 位置配置 — 应用于单个 `location`、 `if` 或 `limit_except` 块。 作为模块的位置特定设置。 配置结构在 Angie 配置阶段通过调用分配结构、初始化结构和合并结构的函数来创建。 以下示例展示了如何为模块创建简单的位置配置。 该配置有一个设置 `foo`，类型为无符号整数。 ```c typedef struct { ngx_uint_t foo; } ngx_http_foo_loc_conf_t; static ngx_http_module_t ngx_http_foo_module_ctx = { NULL, /* preconfiguration */ NULL, /* postconfiguration */ NULL, /* create main configuration */ NULL, /* init main configuration */ NULL, /* create server configuration */ NULL, /* merge server configuration */ ngx_http_foo_create_loc_conf, /* create location configuration */ ngx_http_foo_merge_loc_conf /* merge location configuration */ }; static void * ngx_http_foo_create_loc_conf(ngx_conf_t *cf) { ngx_http_foo_loc_conf_t *conf; conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t)); if (conf == NULL) { return NULL; } conf->foo = NGX_CONF_UNSET_UINT; return conf; } static char * ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child) { ngx_http_foo_loc_conf_t *prev = parent; ngx_http_foo_loc_conf_t *conf = child; ngx_conf_merge_uint_value(conf->foo, prev->foo, 1); } ``` 如示例所示，`ngx_http_foo_create_loc_conf()` 函数创建一个新的配置结构， `ngx_http_foo_merge_loc_conf()` 将配置与更高级别的配置合并。 实际上,服务器和位置配置不仅存在于服务器和位置级别， 还会在它们之上的所有级别创建。 具体来说，服务器配置也会在主级别创建， 位置配置会在主级别、服务器级别和位置级别创建。 这些配置使得可以在 Angie 配置文件的任何级别指定服务器和位置特定的设置。 最终配置会向下合并。 提供了许多宏，如 `NGX_CONF_UNSET` 和 `NGX_CONF_UNSET_UINT`， 用于指示缺失的设置并在合并期间忽略它。 标准的 Angie 合并宏，如 `ngx_conf_merge_value()` 和 `ngx_conf_merge_uint_value()`，提供了一种便捷的方式来合并设置， 并在所有配置都未提供显式值时设置默认值。 有关不同类型的完整宏列表，请参见 `src/core/ngx_conf_file.h`。 以下宏可用于在配置时访问 HTTP 模块的配置。 它们都将 `ngx_conf_t` 引用作为第一个参数。 * `ngx_http_conf_get_module_main_conf(cf, module)` * `ngx_http_conf_get_module_srv_conf(cf, module)` * `ngx_http_conf_get_module_loc_conf(cf, module)` 以下示例获取标准 [核心 HTTP 模块](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#http-core) 的位置配置指针， 并替换存储在结构的 `handler` 字段中的位置内容处理器。 ```c static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r); static ngx_command_t ngx_http_foo_commands[] = { { ngx_string("foo"), NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS, ngx_http_foo, 0, 0, NULL }, ngx_null_command }; static char * ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) { ngx_http_core_loc_conf_t *clcf; clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module); clcf->handler = ngx_http_bar_handler; return NGX_CONF_OK; } ``` 以下宏可用于在运行时访问 HTTP 模块的配置。 * `ngx_http_get_module_main_conf(r, module)` * `ngx_http_get_module_srv_conf(r, module)` * `ngx_http_get_module_loc_conf(r, module)` 这些宏接收对 HTTP 请求 `ngx_http_request_t` 的引用。 请求的主配置永远不会改变。 服务器配置可能会在为请求选择虚拟服务器后从默认值改变。 为处理请求而选择的位置配置可能会因重写操作或内部重定向而多次改变。 以下示例展示了如何在运行时访问模块的 HTTP 配置。 ```c static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r) { ngx_http_foo_loc_conf_t *flcf; flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module); ... } ``` ### 阶段 每个 HTTP 请求都会经历一系列阶段。 在每个阶段，对请求执行不同类型的处理。 模块特定的处理器可以在大多数阶段注册， 许多标准 Angie 模块将其阶段处理器注册为在请求处理的特定阶段被调用的方式。 阶段按顺序处理，一旦请求到达该阶段，就会调用阶段处理器。 以下是 Angie HTTP 阶段的列表。 * `NGX_HTTP_POST_READ_PHASE` — 第一个阶段。 [RealIP](https://cn.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) 模块在此阶段注册其处理器， 以便在调用任何其他模块之前替换客户端地址。 * `NGX_HTTP_SERVER_REWRITE_PHASE` — 处理在 `server` 块中定义的重写指令 （但在 `location` 块之外）的阶段。 [Rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) 模块在此阶段安装其处理器。 * `NGX_HTTP_FIND_CONFIG_PHASE` — 根据请求 URI 选择位置的特殊阶段。 在此阶段之前，相关虚拟服务器的默认位置被分配给请求， 任何请求位置配置的模块都会接收默认服务器位置的配置。 此阶段为请求分配新位置。 此阶段不能注册额外的处理器。 * `NGX_HTTP_REWRITE_PHASE` — 与 `NGX_HTTP_SERVER_REWRITE_PHASE` 相同， 但用于在前一阶段选择的位置中定义的重写规则。 * `NGX_HTTP_POST_REWRITE_PHASE` — 如果请求的 URI 在重写期间发生更改， 则将请求重定向到新位置的特殊阶段。 这是通过请求再次经过 `NGX_HTTP_FIND_CONFIG_PHASE` 来实现的。 此阶段不能注册额外的处理器。 * `NGX_HTTP_PREACCESS_PHASE` — 用于不同类型处理器的通用阶段， 与访问控制无关。 标准 Angie 模块 [Limit Conn](https://cn.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn) 和 [Limit Req](https://cn.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) 在此阶段注册其处理器。 * `NGX_HTTP_ACCESS_PHASE` — 验证客户端是否有权发出请求的阶段。 标准 Angie 模块如 [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) 和 [Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 在此阶段注册其处理器。 默认情况下，客户端必须通过此阶段注册的所有处理器的授权检查， 请求才能继续到下一阶段。 [satisfy](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 指令可用于允许在任何阶段处理器授权客户端时继续处理。 * `NGX_HTTP_POST_ACCESS_PHASE` — 处理 [satisfy](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 指令的特殊阶段。 如果某些访问阶段处理器拒绝访问且没有明确允许，则请求被最终化。 此阶段不能注册额外的处理器。 * `NGX_HTTP_PRECONTENT_PHASE` — 在生成内容之前调用处理器的阶段。 标准模块如 [try_files](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#try-files) 和 [Mirror](https://cn.angie.software//angie/docs/configuration/modules/http/http_mirror.md#http-mirror) 在此阶段注册其处理器。 * `NGX_HTTP_CONTENT_PHASE` — 通常生成响应的阶段。 多个标准 Angie 模块在此阶段注册其处理器， 包括 [Index](https://cn.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index)。 它们按顺序调用，直到其中一个产生输出。 也可以按位置设置内容处理器。 如果 [HTTP 模块](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#http-core) 模块的位置配置设置了 `handler`， 它将作为内容处理器被调用，并且忽略此阶段安装的处理器。 * `NGX_HTTP_LOG_PHASE` — 执行请求日志记录的阶段。 目前，只有 [Log](https://cn.angie.software//angie/docs/configuration/modules/http/http_log.md#http-log) 模块在此阶段注册其处理器以进行访问日志记录。 日志阶段处理器在请求处理的最后被调用，就在释放请求之前。 以下是预访问阶段处理器的示例。 ```c static ngx_http_module_t ngx_http_foo_module_ctx = { NULL, /* preconfiguration */ ngx_http_foo_init, /* postconfiguration */ NULL, /* create main configuration */ NULL, /* init main configuration */ NULL, /* create server configuration */ NULL, /* merge server configuration */ NULL, /* create location configuration */ NULL /* merge location configuration */ }; static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r) { ngx_table_elt_t *ua; ua = r->headers_in.user_agent; if (ua == NULL) { return NGX_DECLINED; } /* reject requests with "User-Agent: foo" */ if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) { return NGX_HTTP_FORBIDDEN; } return NGX_DECLINED; } static ngx_int_t ngx_http_foo_init(ngx_conf_t *cf) { ngx_http_handler_pt *h; ngx_http_core_main_conf_t *cmcf; cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module); h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers); if (h == NULL) { return NGX_ERROR; } *h = ngx_http_foo_handler; return NGX_OK; } ``` 阶段处理器应返回特定的代码： * `NGX_OK` — 继续到下一阶段。 * `NGX_DECLINED` — 继续到当前阶段的下一个处理器。 如果当前处理器是当前阶段的最后一个，则移至下一阶段。 * `NGX_AGAIN`、`NGX_DONE` — 暂停阶段处理， 直到某个未来事件，例如异步 I/O 操作或只是延迟。 假定稍后通过调用 `ngx_http_core_run_phases()` 恢复阶段处理。 * 阶段处理器返回的任何其他值都被视为请求最终化代码， 特别是 HTTP 响应代码。 请求以提供的代码最终化。 对于某些阶段，返回代码的处理方式略有不同。 在内容阶段，除 `NGX_DECLINED` 之外的任何返回代码都被视为最终化代码。 位置内容处理器的任何返回代码都被视为最终化代码。 在访问阶段，在 [satisfy any](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 模式下， 返回除 `NGX_OK`、`NGX_DECLINED`、`NGX_AGAIN`、 `NGX_DONE` 之外的代码被视为拒绝。 如果没有后续访问处理器允许或使用不同代码拒绝访问， 则拒绝代码将成为最终化代码。 ### 示例 [nginx-dev-examples](https://github.com/nginx/nginx-dev-examples) 仓库提供了适用于 Angie 的 nginx 模块示例。 ## 代码风格 ### 通用规则 * 最大文本宽度为 80 个字符 * 缩进为 4 个空格 * 不使用制表符，不使用尾随空格 * 同一行上的列表元素用空格分隔 * 十六进制字面量为小写 * 文件名、函数和类型名称以及全局变量具有 `ngx_` 前缀或更具体的前缀， 如 `ngx_http_` 和 `ngx_mail_` ```c size_t ngx_utf8_length(u_char *p, size_t n) { u_char c, *last; size_t len; last = p + n; for (len = 0; p < last; len++) { c = *p; if (c < 0x80) { p++; continue; } if (ngx_utf8_decode(&p, last - p) > 0x10ffff) { /* invalid UTF-8 */ return n; } } return len; } ``` ### 文件 典型的源文件可能包含以下部分，用两个空行分隔： * 版权声明 * 包含文件 * 预处理器定义 * 类型定义 * 函数原型 * 变量定义 * 函数定义 版权声明如下所示： ```c /* * Copyright (C) Author Name * Copyright (C) Organization, Inc. */ ``` 如果文件被大幅修改，应更新作者列表，新作者添加到顶部。 始终首先包含 `ngx_config.h` 和 `ngx_core.h` 文件， 然后是 `ngx_http.h`、`ngx_stream.h` 或 `ngx_mail.h` 之一。 然后是可选的外部头文件： ```c #include #include #include #include #include #include #if (NGX_HAVE_EXSLT) #include #endif ``` 头文件应包含所谓的"头文件保护"： ```c #ifndef _NGX_PROCESS_CYCLE_H_INCLUDED_ #define _NGX_PROCESS_CYCLE_H_INCLUDED_ ... #endif /* _NGX_PROCESS_CYCLE_H_INCLUDED_ */ ``` ### 注释 * 不使用 `//` 注释 * 文本使用英语，首选美式拼写 * 多行注释格式如下： ```c /* * The red-black tree code is based on the algorithm described in * the "Introduction to Algorithms" by Cormen, Leiserson and Rivest. */ ``` ```c /* find the server configuration for the address:port */ ``` ### 预处理器 宏名称以 `ngx_` 或 `NGX_` 前缀开头（或更具体的前缀）。 常量的宏名称为大写。 参数化宏和初始化器宏为小写。 宏名称和值之间至少用两个空格分隔： ```c #define NGX_CONF_BUFFER 4096 #define ngx_buf_in_memory(b) (b->temporary || b->memory || b->mmap) #define ngx_buf_size(b) \ (ngx_buf_in_memory(b) ? (off_t) (b->last - b->pos): \ (b->file_last - b->file_pos)) #define ngx_null_string { 0, NULL } ``` 条件在括号内，否定在外部： ```c #if (NGX_HAVE_KQUEUE) ... #elif ((NGX_HAVE_DEVPOLL && !(NGX_TEST_BUILD_DEVPOLL)) \ || (NGX_HAVE_EVENTPORT && !(NGX_TEST_BUILD_EVENTPORT))) ... #elif (NGX_HAVE_EPOLL && !(NGX_TEST_BUILD_EPOLL)) ... #elif (NGX_HAVE_POLL) ... #else /* select */ ... #endif /* NGX_HAVE_KQUEUE */ ``` ### 类型 类型名称以 `_t` 后缀结尾。 定义的类型名称至少用两个空格分隔： ```c typedef ngx_uint_t ngx_rbtree_key_t; ``` 结构类型使用 `typedef` 定义。 在结构内部，成员类型和名称对齐： ```c typedef struct { size_t len; u_char *data; } ngx_str_t; ``` 在文件中的不同结构之间保持相同的对齐。 指向自身的结构的名称以 `_s` 结尾。 相邻的结构定义用两个空行分隔： ```c typedef struct ngx_list_part_s ngx_list_part_t; struct ngx_list_part_s { void *elts; ngx_uint_t nelts; ngx_list_part_t *next; }; typedef struct { ngx_list_part_t *last; ngx_list_part_t part; size_t size; ngx_uint_t nalloc; ngx_pool_t *pool; } ngx_list_t; ``` 每个结构成员在单独的行上声明： ```c typedef struct { ngx_uint_t hash; ngx_str_t key; ngx_str_t value; u_char *lowcase_key; } ngx_table_elt_t; ``` 结构内部的函数指针具有以 `_pt` 结尾的定义类型： ```c typedef ssize_t (*ngx_recv_pt)(ngx_connection_t *c, u_char *buf, size_t size); typedef ssize_t (*ngx_recv_chain_pt)(ngx_connection_t *c, ngx_chain_t *in, off_t limit); typedef ssize_t (*ngx_send_pt)(ngx_connection_t *c, u_char *buf, size_t size); typedef ngx_chain_t *(*ngx_send_chain_pt)(ngx_connection_t *c, ngx_chain_t *in, off_t limit); typedef struct { ngx_recv_pt recv; ngx_recv_chain_pt recv_chain; ngx_recv_pt udp_recv; ngx_send_pt send; ngx_send_pt udp_send; ngx_send_chain_pt udp_send_chain; ngx_send_chain_pt send_chain; ngx_uint_t flags; } ngx_os_io_t; ``` 枚举类型以 `_e` 结尾： ```c typedef enum { ngx_http_fastcgi_st_version = 0, ngx_http_fastcgi_st_type, ... ngx_http_fastcgi_st_padding } ngx_http_fastcgi_state_e; ``` ### 变量 变量声明按基本类型的长度排序，然后按字母顺序排序。 类型名称和变量名称对齐。 类型和名称"列"用两个空格分隔。 大型数组放在声明块的末尾： ```c u_char *rv, *p; ngx_conf_t *cf; ngx_uint_t i, j, k; unsigned int len; struct sockaddr *sa; const unsigned char *data; ngx_peer_connection_t *pc; ngx_http_core_srv_conf_t **cscfp; ngx_http_upstream_srv_conf_t *us, *uscf; u_char text[NGX_SOCKADDR_STRLEN]; ``` 静态和全局变量可以在声明时初始化： ```c static ngx_str_t ngx_http_memcached_key = ngx_string("memcached_key"); ``` ```c static ngx_uint_t mday[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }; ``` ```c static uint32_t ngx_crc32_table16[] = { 0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac, ... 0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c }; ``` 有一些常用的类型/名称组合： ```c u_char *rv; ngx_int_t rc; ngx_conf_t *cf; ngx_connection_t *c; ngx_http_request_t *r; ngx_peer_connection_t *pc; ngx_http_upstream_srv_conf_t *us, *uscf; ``` ### 函数 所有函数（即使是静态函数）都应有原型。 原型包含参数名称。 长原型在续行上使用单个缩进换行： ```c static char *ngx_http_block(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); static ngx_int_t ngx_http_init_phases(ngx_conf_t *cf, ngx_http_core_main_conf_t *cmcf); static char *ngx_http_merge_servers(ngx_conf_t *cf, ngx_http_core_main_conf_t *cmcf, ngx_http_module_t *module, ngx_uint_t ctx_index); ``` 定义中的函数名称从新行开始。 函数体的左右花括号在单独的行上。 函数体缩进。 函数之间有两个空行： ```c static ngx_int_t ngx_http_find_virtual_server(ngx_http_request_t *r, u_char *host, size_t len) { ... } static ngx_int_t ngx_http_add_addresses(ngx_conf_t *cf, ngx_http_core_srv_conf_t *cscf, ngx_http_conf_port_t *port, ngx_http_listen_opt_t *lsopt) { ... } ``` 函数名称和左括号之间没有空格。 长函数调用换行，使续行从第一个函数参数的位置开始。 如果这不可能，则格式化第一个续行，使其在第 79 列结束： ```c ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "http header: \"%V: %V\"", &h->key, &h->value); hc->busy = ngx_palloc(r->connection->pool, cscf->large_client_header_buffers.num * sizeof(ngx_buf_t *)); ``` 应使用 `ngx_inline` 宏而不是 `inline`： ```c static ngx_inline void ngx_cpuid(uint32_t i, uint32_t *buf); ``` ### 表达式 二元运算符（除 `.` 和 `->` 外） 应与其操作数用一个空格分隔。 一元运算符和下标与其操作数之间没有空格： ```c width = width * 10 + (*fmt++ - '0'); ``` ```c ch = (u_char) ((decoded << 4) + (ch - '0')); ``` ```c r->exten.data = &r->uri.data[i + 1]; ``` 类型转换与被转换的表达式用一个空格分隔。 类型转换内的星号与类型名称用空格分隔： ```c len = ngx_sock_ntop((struct sockaddr *) sin6, p, len, 1); ``` 如果表达式不适合单行，则换行。 首选的换行点是二元运算符。 续行与表达式的开头对齐： ```c if (status == NGX_HTTP_MOVED_PERMANENTLY || status == NGX_HTTP_MOVED_TEMPORARILY || status == NGX_HTTP_SEE_OTHER || status == NGX_HTTP_TEMPORARY_REDIRECT || status == NGX_HTTP_PERMANENT_REDIRECT) { ... } ``` ```c p->temp_file->warn = "an upstream response is buffered " "to a temporary file"; ``` 作为最后的手段，可以换行表达式，使续行在第 79 列结束： ```c hinit->hash = ngx_pcalloc(hinit->pool, sizeof(ngx_hash_wildcard_t) + size * sizeof(ngx_hash_elt_t *)); ``` 上述规则也适用于子表达式， 其中每个子表达式都有自己的缩进级别： ```c if (((u->conf->cache_use_stale & NGX_HTTP_UPSTREAM_FT_UPDATING) || c->stale_updating) && !r->background && u->conf->cache_background_update) { ... } ``` 有时在类型转换后换行表达式很方便。 在这种情况下，续行缩进： ```c node = (ngx_rbtree_node_t *) ((u_char *) lr - offsetof(ngx_rbtree_node_t, color)); ``` 指针显式与 `NULL`（而不是 :samp:`0`）比较： ```c if (ptr != NULL) { ... } ``` ### 条件和循环 `if` 关键字与条件用一个空格分隔。 左花括号位于同一行，或者如果条件占用多行，则位于单独的行上。 右花括号位于单独的行上，可选地后跟 `else if` / `else`。 通常，在 `else if` / `else` 部分之前有一个空行： ```c if (node->left == sentinel) { temp = node->right; subst = node; } else if (node->right == sentinel) { temp = node->left; subst = node; } else { subst = ngx_rbtree_min(node->right, sentinel); if (subst->left != sentinel) { temp = subst->left; } else { temp = subst->right; } } ``` 类似的格式规则适用于 `do` 和 `while` 循环： ```c while (p < last && *p == ' ') { p++; } ``` ```c do { ctx->node = rn; ctx = ctx->next; } while (ctx); ``` `switch` 关键字与条件用一个空格分隔。 左花括号位于同一行。 右花括号位于单独的行上。 `case` 关键字与 `switch` 对齐： ```c switch (ch) { case '!': looked = 2; state = ssi_comment0_state; break; case '<': copy_end = p; break; default: copy_end = p; looked = 0; state = ssi_start_state; break; } ``` 大多数 `for` 循环格式如下： ```c for (i = 0; i < ccf->env.nelts; i++) { ... } ``` ```c for (q = ngx_queue_head(locations); q != ngx_queue_sentinel(locations); q = ngx_queue_next(q)) { ... } ``` 如果省略 `for` 语句的某些部分， 则用 `/* void */` 注释表示： ```c for (i = 0; /* void */ ; i++) { ... } ``` 空循环体也用 `/* void */` 注释表示， 该注释可以放在同一行上： ```c for (cl = *busy; cl->next; cl = cl->next) { /* void */ } ``` 无限循环如下所示： ```c for ( ;; ) { ... } ``` ### 标签 标签周围有空行，并在前一级别缩进： ```c if (i == 0) { u->err = "host not found"; goto failed; } u->addrs = ngx_pcalloc(pool, i * sizeof(ngx_addr_t)); if (u->addrs == NULL) { goto failed; } u->naddrs = i; ... return NGX_OK; failed: freeaddrinfo(res); return NGX_ERROR; ``` ## 调试内存问题 要调试内存问题，如缓冲区溢出或释放后使用错误，可以使用 [AddressSanitizer](https://en.wikipedia.org/wiki/AddressSanitizer) (ASan)，某些现代编译器支持该工具。 要在 `gcc` 和 `clang` 中启用 ASan， 请使用 `-fsanitize=address` 编译器和链接器选项。 在构建 Angie 时，可以通过将该选项添加到 `configure` 脚本的 `--with-cc-opt` 和 `--with-ld-opt` 参数来完成。 由于 Angie 中的大多数分配都是从 Angie 内部 [池](#pool) 进行的，启用 ASan 可能并不总是足以调试 内存问题。 内部池从系统分配一大块内存，并从中切割较小的分配。 但是，可以通过将 `NGX_DEBUG_PALLOC` 宏设置为 `1` 来禁用此机制。 在这种情况下，分配直接传递给系统分配器，使其完全控制缓冲区边界。 以下配置行总结了上述信息。 建议在开发第三方模块和在不同平台上测试 Angie 时使用。 ```bash auto/configure --with-cc-opt='-fsanitize=address -DNGX_DEBUG_PALLOC=1' --with-ld-opt=-fsanitize=address ``` ## 常见陷阱 ### 编写 C 模块 最常见的陷阱是在可以避免的情况下尝试编写完整的 C 模块。 在大多数情况下，您的任务可以通过创建适当的配置来完成。 如果编写模块不可避免，请尝试使其尽可能小而简单。 例如，模块可以只导出一些 [变量](#http_variables)。 在开始编写模块之前，请考虑以下问题： * 是否可以使用已经 [可用的模块](https://cn.angie.software//angie/docs/configuration/modules/index.md#modules) 实现所需的功能？ * 是否可以使用内置的脚本语言解决问题， 例如 [Perl](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) 或 [NJS](https://cn.angie.software//angie/docs/installation/external-modules/njs.md#external-njs)？ ### C 字符串 Angie 中最常用的字符串类型 [ngx_str_t](#string_overview) 不是 C 风格的 以零结尾的字符串。 您不能将数据传递给标准 C 库函数， 例如 `strlen()` 或 `strstr()`。 相反，应使用接受 `ngx_str_t` 或指向数据和长度的指针的 Angie [对应函数](#string_overview)。 但是，有一种情况 `ngx_str_t` 持有 指向以零结尾的字符串的指针：作为配置文件解析结果的字符串是以零结尾的。 ### 全局变量 避免在模块中使用全局变量。 使用全局变量很可能是一个错误。 任何全局数据都应绑定到 [配置周期](#cycle) 并从相应的 [内存池](#pool) 分配。 这允许 Angie 执行优雅的配置重新加载。 尝试使用全局变量可能会破坏此功能， 因为不可能同时拥有两个配置并摆脱它们。 有时需要全局变量。 在这种情况下，需要特别注意正确管理重新配置。 另外，检查您的代码使用的库是否具有可能在重新加载时损坏的隐式全局状态。 ### 手动内存管理 不要使用容易出错的 malloc/free 方法， 而是学习如何使用 Angie [池](#pool)。 池被创建并绑定到对象 - [配置](#http_conf)、 [周期](#cycle)、 连接 <#http_connection> 或 [HTTP 请求](#http_request)。 当对象被销毁时，关联的池也被销毁。 因此，在处理对象时，可以从相应的池中分配所需的数量， 而不必担心释放内存，即使在出现错误的情况下也是如此。 ### 线程 建议避免在 Angie 中使用线程，因为这肯定会破坏事物：大多数 Angie 函数不是线程安全的。 预期线程只执行系统调用和线程安全的库函数。 如果您需要运行与客户端请求处理无关的代码， 正确的方法是在 `init_process` 模块处理器中安排一个定时器， 并在定时器处理器中执行所需的操作。 在内部，Angie 使用 [线程](#dev_threads) 来 提升 IO 相关操作，但这是一个特殊情况，有很多限制。 ### 阻塞库 一个常见的错误是使用内部阻塞的库。 大多数库本质上是同步和阻塞的。 换句话说，它们一次执行一个操作，并浪费时间等待来自其他对等方的响应。 因此，当使用此类库处理请求时，整个 Angie worker 被阻塞，从而破坏性能。 仅使用提供异步接口且不阻塞整个进程的库。 ### 向外部服务发送 HTTP 请求 模块通常需要对某些外部服务执行 HTTP 调用。 一个常见的错误是使用某些外部库(例如 libcurl) 来执行 HTTP 请求。 为了完成 Angie 本身就能完成的任务, 引入大量外部(可能是 [阻塞的](#using_libraries)!)代码 是完全没有必要的。 当需要外部请求时,有两种基本使用场景: * 在处理客户端请求的上下文中(例如,在内容处理程序中) * 在 worker 进程的上下文中(例如,定时器处理程序) 在第一种情况下,最好使用 [子请求 API](#http_subrequests)。 您不是直接访问外部服务,而是在 Angie 配置中声明一个 location, 并将子请求定向到此 location。 此 location 不限于 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) 请求,还可以包含其他 Angie 指令。 这种方法的一个例子是 [Auth Request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 中实现的 [auth_request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) 指令。 对于第二种情况,可以使用 Angie 中可用的基本 HTTP 客户端功能。 例如, [OCSP 模块](https://github.com/nginx/nginx/blob/master/src/event/ngx_event_openssl_stapling.c) 实现了简单的 HTTP 客户端。 # https://cn.angie.software/angie/docs/development.md # 开发 Angie 是一个开源项目, 欢迎所有贡献者。 ## 源代码 您可以从我们的公共仓库克隆 Angie 源代码: [Mercurial](https://hg.angie.software/angie), [Git](https://git.angie.software/web-server/angie)。 ## 编码风格 您的更改应与 Angie 其余代码保持一致; [编码约定](https://cn.angie.software//angie/docs/developer_guide.md#developer-guide) 是一个很好的起点。 ### 提交消息 从历史上看,提交日志使用英语维护。 以一行总结所做的工作开始。 它可以有一个前缀,提交日志将其用于受影响的代码部分。 总结最多可以有 67 个字符, 后面可以跟一个空行和更多详细信息。 一个好的消息会说明是什么导致了更改、对此做了什么, 以及现在的情况如何: ```none API: bad things removed, good things added. As explained elsewhere[1], the original API was bad because stuff; this change was introduced to improve that aspect locally. Levels of goodness have been implemented to mitigate the badness; this is now the preferred way to work. Also, the badness is gone. [1] https://example.com ``` 可能会被忽略的细节: - 总结以句号结尾,并以大写字母开头。 - 如果使用前缀,则后面跟小写字母。 - 双空格分隔单行内的句子。 ## 最终检查 - 尽最大努力验证更改在 *所有* 目标平台上都能正常工作。 - 对于每个平台,运行测试套件以确保没有回归: ```sh $ cd tests $ prove . ``` 详细信息请参阅 `tests/README` 文件。 - 确保您对 [法律条款](https://cn.angie.software//legal/index.md#legal) 感到满意。 ## 提交贡献 要提交补丁,请在我们的 [GitHub 镜像](https://github.com/webserver-llc/angie/) 上创建拉取请求。 如有问题和建议,请通过 [GitHub Issues](https://github.com/webserver-llc/angie/issues) 联系开发人员。 # https://cn.angie.software/angie/doc-license.md # 许可组件存在声明 本站发布的 Angie 软件产品 [文档](https://cn.angie.software//angie/docs/index.md) 是 Web Server, LLC 的知识产权；该文档是通过修改（修订）Nginx 软件产品文档而创建的。未经更改而使用的 Angie 软件产品文档的某些部分是根据 [http://nginx.org/LICENSE](http://nginx.org/LICENSE) 提供的许可证授权的；此类文档部分的使用必须符合该许可证的条款。 # https://cn.angie.software/angie/docs/installation/docker.md # Angie Docker 镜像 要在 [Docker](https://docs.docker.com/engine/reference/commandline/cli/) 容器中运行 Angie, 请使用我们注册表中的镜像:`docker.angie.software`。 这些镜像基于我们的 [二进制软件包](https://cn.angie.software//angie/docs/installation/oss_packages.md#oss-packages) 和几个操作系统的官方基础镜像构建。 #### NOTE 另请注意 [Docker](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) 模块, 该模块基于 Docker 容器标签实现上游服务器组的动态更新。 ## 最小化镜像 - `angie:minimal`: 基于 Alpine 3.22 的 版本。 - `angie:-minimal`: 基于 Alpine 3.22 的指定版本。 这些镜像仅包含 `angie` 软件包。 ## 模板化镜像 - `angie:templated`: 基于 Alpine 3.22 的 版本。 - `angie:-templated`: 基于 Alpine 3.22 的指定版本。 这些镜像设置了以下环境变量: ```docker ENV ANGIE_BINARY="angie" ENV ANGIE_CONFIG_TEMPLATE="/etc/angie/angie.conf.t" ENV ANGIE_ERROR_LOG_SEVERITY="notice" ENV ANGIE_FEATURE_RELOAD="on" ENV ANGIE_FEATURE_TEMPLATE="on" ENV ANGIE_LOAD_MODULES="" ENV ANGIE_PID_FILE="/run/angie/angie.pid" ENV ANGIE_WORKER_CONNECTIONS="65536" ENV ANGIE_WORKER_RLIMIT_NOFILE="65536" ``` 这些变量可用于自定义容器行为: - `ANGIE_BINARY`: 允许运行 [调试版本](https://cn.angie.software//angie/docs/troubleshooting.md#debug-logging)。 - `ANGIE_ERROR_LOG_SEVERITY`: 设置主 [错误日志](https://cn.angie.software//angie/docs/configuration/processing.md#logging) 文件中条目的严重级别。 - `ANGIE_LOAD_MODULES`: 加载一个或多个可用模块(镜像中包含所有模块)。 指定以逗号分隔的模块列表,不含空格。 - `ANGIE_PID_FILE`: 设置进程标识符 (PID) 文件的替代位置。 - `ANGIE_FEATURE_TEMPLATE`: 在容器启动时使用 [gomplate](https://docs.gomplate.ca/) 工具生成 [Angie 配置](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)。使用的参数: `--input-dir /etc/angie/templates` 和 `--output-dir /etc/angie`。 - `ANGIE_FEATURE_RELOAD`: 启用对 `SIGHUP`、`SIGQUIT` 和 `SIGTERM` 信号的处理。 这些镜像包含以下 [软件包](https://cn.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) (如果它们已针对构建镜像所用的 [Angie 版本](https://cn.angie.software//angie/docs/oss_changes.md#oss-changes) 发布): ### 软件包列表 - `angie-console-light` - `angie-module-auth-jwt` - `angie-module-auth-ldap` - `angie-module-auth-pam` - `angie-module-auth-spnego` - `angie-module-auth-totp` - `angie-module-brotli` - `angie-module-cache-purge` - `angie-module-cgi` - `angie-module-combined-upstreams` - `angie-module-dav-ext` - `angie-module-dynamic-limit-req` - `angie-module-echo` - `angie-module-enhanced-memcached` - `angie-module-eval` - `angie-module-geoip2` - `angie-module-headers-more` - `angie-module-http-auth-radius` - `angie-module-image-filter` - `angie-module-keyval` - `angie-module-lua` - `angie-module-modsecurity` - `angie-module-ndk` - `angie-module-njs` - `angie-module-opentracing` - `angie-module-otel` - `angie-module-perl` - `angie-module-postgres` - `angie-module-redis2` - `angie-module-rtmp` - `angie-module-set-misc` - `angie-module-subs` - `angie-module-testcookie` - `angie-module-unbrotli` - `angie-module-upload` - `angie-module-vod` - `angie-module-vts` - `angie-module-wasm` - `angie-module-wasmtime` - `angie-module-xslt` - `angie-module-zip` - `angie-module-zstd` ### 示例 模板化镜像中使用的配置大致按以下方式应用变量: ```none ... {{- if has $modules "zstd"}} # package: angie-module-zstd load_module modules/ngx_http_zstd_filter_module.so; load_module modules/ngx_http_zstd_static_module.so; {{end}} user angie; worker_processes auto; worker_rlimit_nofile {{.Env.ANGIE_WORKER_RLIMIT_NOFILE}}; error_log /var/log/angie/error.log {{.Env.ANGIE_ERROR_LOG_SEVERITY}}; pid {{.Env.ANGIE_PID_FILE}}; events { worker_connections {{.Env.ANGIE_WORKER_CONNECTIONS}}; } http { include /etc/angie/mime.types; default_type application/octet-stream; log_format main ... ``` 运行具有 shell 访问权限的容器: ```console $ docker run -it --pull always --rm --entrypoint=sh \ docker.angie.software/angie:templated ``` 使用自定义连接参数和模块运行 Angie (命令 **angie -T** 将输出完整配置): ```console $ docker run -it --rm -e ANGIE_WORKER_CONNECTIONS=4 \ -e ANGIE_LOAD_MODULES="auth-jwt,vod" \ docker.angie.software/angie:templated angie -T ``` 启动具有指定名称和附加模块的容器: ```console $ docker run -it --rm --name angie-test \ -e ANGIE_WORKER_CONNECTIONS=4 \ -e ANGIE_LOAD_MODULES="auth-jwt,vod" \ docker.angie.software/angie:templated ``` 重新加载正在运行的容器的配置: ```console $ docker kill -s HUP angie-test ``` ## 包含额外模块的镜像 - `angie:latest`: 基于 Alpine 3.22 的 版本。 - `angie:`, `angie:-alpine`: 基于 Alpine 3.22 的指定版本。 - `angie:-debian`: 基于 Debian 13 的指定版本。 - `angie:-rocky`: 基于 Rocky Linux 9 的指定版本。 - `angie:-ubuntu`: 基于 Ubuntu 24.04 LTS 的指定版本。 这些镜像包含以下 [软件包](https://cn.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules) (如果它们已针对构建镜像所用的 [Angie 版本](https://cn.angie.software//angie/docs/oss_changes.md#oss-changes) 发布): ### 软件包列表 - `angie-console-light` - `angie-module-auth-jwt` - `angie-module-auth-ldap` - `angie-module-auth-pam` - `angie-module-auth-spnego` - `angie-module-auth-totp` - `angie-module-brotli` - `angie-module-cache-purge` - `angie-module-cgi` - `angie-module-combined-upstreams` - `angie-module-dav-ext` - `angie-module-dynamic-limit-req` - `angie-module-echo` - `angie-module-enhanced-memcached` - `angie-module-eval` - `angie-module-geoip2` - `angie-module-headers-more` - `angie-module-http-auth-radius` - `angie-module-image-filter` - `angie-module-keyval` - `angie-module-lua` - `angie-module-modsecurity` - `angie-module-ndk` - `angie-module-njs` - `angie-module-opentracing` - `angie-module-otel` - `angie-module-perl` - `angie-module-postgres` - `angie-module-redis2` - `angie-module-rtmp` - `angie-module-set-misc` - `angie-module-subs` - `angie-module-testcookie` - `angie-module-unbrotli` - `angie-module-upload` - `angie-module-vod` - `angie-module-vts` - `angie-module-wasm` - `angie-module-wasmtime` - `angie-module-xslt` - `angie-module-zip` - `angie-module-zstd` ## 运行 要在端口 8080 上启动带有 Angie 的容器, 提供对静态文件目录 `/var/www/` 的只读访问 以及位于当前工作目录中的配置文件 `angie.conf`: ```console $ docker run --rm --name angie -v /var/www:/usr/share/angie/html:ro \ -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 8080:80 -d docker.angie.software/angie:latest $ curl -I localhost:8080 HTTP/1.1 200 OK Server: Angie/|version| Date: |sampledatelong| 10:42:54 GMT Content-Type: text/html Content-Length: 543 Last-Modified: |sampledatelong| 09:12:23 GMT Connection: keep-alive ETag: "64c3ccc7-21f" Accept-Ranges: bytes ``` 此类配置适用于本地开发和配置。 ## 构建自定义镜像 您也可以基于支持的发行版构建自己的镜像, 从 [软件包](https://cn.angie.software//angie/docs/installation/oss_packages.md#oss-packages) 或 [源代码](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 添加 Angie 层。 相应的 `Dockerfile` 文件示例: ```dockerfile FROM debian:13 LABEL org.opencontainers.image.authors="Release Engineering Team " ARG DEBIAN_FRONTEND=noninteractive RUN set -x \ && apt-get update \ && apt-get install --no-install-recommends --no-install-suggests -y \ ca-certificates curl \ && curl -o /etc/apt/trusted.gpg.d/angie-signing.gpg \ https://angie.software/keys/angie-signing.gpg \ && echo "deb https://download.angie.software/angie/$(. /etc/os-release && echo "$ID/$VERSION_ID $VERSION_CODENAME") main" \ > /etc/apt/sources.list.d/angie.list \ && apt-get update \ && apt-get install --no-install-recommends --no-install-suggests -y \ angie angie-module-geoip2 angie-module-njs \ && rm -Rf /var/lib/apt/lists \ /etc/apt/sources.list.d/angie.list \ /etc/apt/trusted.gpg.d/angie-signing.gpg \ && ln -sf /dev/stdout /var/log/angie/access.log \ && ln -sf /dev/stderr /var/log/angie/error.log EXPOSE 80 CMD ["angie", "-g", "daemon off;"] ``` ```dockerfile FROM alpine:3.22 LABEL org.opencontainers.image.authors="Release Engineering Team " RUN set -x \ && apk add --no-cache ca-certificates curl \ && curl -o /etc/apk/keys/angie-signing.rsa https://angie.software/keys/angie-signing.rsa \ && echo "https://download.angie.software/angie/alpine/v$(egrep -o \ '[0-9]+\.[0-9]+' /etc/alpine-release)/main" >> /etc/apk/repositories \ && apk add --no-cache angie angie-module-geoip2 angie-module-njs \ && rm /etc/apk/keys/angie-signing.rsa \ && ln -sf /dev/stdout /var/log/angie/access.log \ && ln -sf /dev/stderr /var/log/angie/error.log EXPOSE 80 CMD ["angie", "-g", "daemon off;"] ``` 要在包含此类 `Dockerfile` 的目录中构建 `myangie` 镜像 并按上述方式启动容器: ```console $ docker build -t myangie . $ docker run --rm --name myangie -v /var/www:/usr/share/angie/html:ro \ -v $(pwd)/angie.conf:/etc/angie/angie.conf:ro -p 8080:80 -d myangie ``` # https://cn.angie.software/angie/docs.md # 关于 Angie Angie /[andʒi](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet)/ 是一个高效、强大且可扩展的 Web 服务器， 从 nginx 分支而来： * 由原始团队的前开发人员构思， 旨在超越早期愿景， 作为 [直接替代品](https://cn.angie.software//angie/docs/configuration/migration.md#migration)， 无需对模块设置或配置进行重大更改。 * 包含 [nginx |nginxversion|](https://nginx.org/en/CHANGES) 的大部分功能 以及许多 [新特性](#index-features-oss)。 我们为多种 [系统和架构](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 构建二进制包， 以及 [Docker 镜像](https://cn.angie.software//angie/docs/installation/docker.md#docker-images)。 源代码在我们的 [公共仓库](https://cn.angie.software//angie/docs/development.md#development) 中开放， 采用 [类 BSD 许可证](https://cn.angie.software//angie/license-angie.md#license-angie)。 此外，具有 [附加功能](#index-features-pro) 的商业版本以 Angie PRO 的名义销售。 可选择现成的 Angie 软件包、 Docker 镜像和源代码构建选项。 启动和运行时控制； 配置、模块、指令和变量。 解决 Angie 的技术问题， 可用的反馈渠道。 为想要为项目做出贡献的 开发人员提供的信息。 ## 当前版本 **Angie |angie_version|** 和 **Angie PRO |angie_pro_version|** 于 **|angie_release_date|** 发布。 新版本每季度发布一次； 在此期间，我们会发布紧急修复和重要更新。 另请参阅 [Angie](https://cn.angie.software//angie/docs/oss_changes.md#oss-changes) 和 [Angie PRO](https://cn.angie.software//angie/docs/pro_changes.md#pro-changes) 的完整版本历史。 ## 特性 相对于 nginx 的核心优势， 在 Angie 的免费开源版本中可用： - 支持客户端连接的 [HTTP/3](https://cn.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3)， 以及 [代理服务器](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) 连接， 能够在两端独立使用不同的协议版本 （HTTP/1.x、HTTP/2、HTTP/3）。 - 自动 HTTPS 通过内置的 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#id4) 协议支持提供 TLS 证书。 - 简化配置：`location` 指令 可以一次定义多个匹配表达式，从而实现 具有共享设置的块的 [组合](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#combined-locations)。 - 通过 RESTful [API](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api) 接口以 JSON 格式 公开有关 Web 服务器、 其 [配置](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api-config-files) 以及代理服务器、客户端连接、 共享内存区域等的 [指标](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#metrics) 的基本信息。 - 以 [Prometheus](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3) 格式导出统计信息， 支持 [可自定义模板](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#prometheus-template)。 - 通过 [Console Light](https://cn.angie.software//angie/docs/configuration/monitoring.md#monitoring) 可视化监控工具 在浏览器中监控服务器。 查看在线演示：[https://console.angie.software/](https://console.angie.software/) - 基于 [Docker 容器](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) （或类似工具如 Podman）的事件和标签 动态更新上游组，无需 服务器重载。 - 将 [proxy_cache_path](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) 中的共享内存区域刷新到磁盘 可在重启和更新之间保留缓存索引内容， 从而消除缓存加载延迟并使服务器更快上线。 - [会话绑定](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky) 模式，将一个会话内的所有请求 定向到同一代理服务器。 - 使用 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令的 `slow_start` 选项 在故障后平滑地重新启用上游服务器。 - 按比特率成比例地 [限制 MP4 文件传输速率](https://cn.angie.software//angie/docs/configuration/modules/http/http_mp4.md#mp4-limit-rate)， 从而减少带宽负载。 - 通过 `stream` 下的 [mqtt_preread](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_mqtt_preread.md#s-mqtt-preread) 指令 扩展 MQTT 协议的授权和均衡功能。 - 通过 `stream` 下的 [rdp_preread](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_rdp_preread.md#s-rdp-preread) 指令 使用 RDP 协议的会话 cookie 为均衡决策提供信息。 - 使用 [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS 库时的 NTLS [服务器](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-ntls) 和 [客户端](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ssl-ntls) 支持， 在 [构建时](https://cn.angie.software//angie/docs/installation/sourcebuild.md#install-source-features) 启用。 - 为许多流行的第三方模块预构建的 [二进制包](https://cn.angie.software//angie/docs/installation/external-modules/index.md#install-thirdpartymodules)。 --- 商业 Angie PRO 在 [公开可用功能](#index-features-oss) 的基础上增加了以下内容： - 通过 RESTful 动态配置 [API](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config) 管理代理服务器； 可视化监控控制台 [Console Light](https://cn.angie.software//angie/docs/configuration/monitoring.md#monitoring) 也可用于在浏览器中管理服务器。 - 通过发送定期 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 主动检查代理服务器的状态。 - 基于代理服务器的 [平均响应时间](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-time) 进行负载均衡，支持 [可自定义的平滑因子](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor)。 - [基于反馈](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-feedback) 的负载均衡， 根据变量值选择对等节点； 假设它来自对等节点本身， 报告其 CPU 负载或其他指标。 - 请求等待队列， 使用 `upstream` 块中的 [queue](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) 指令配置。 - 附加绑定模式 [sticky learn](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)， 支持在共享内存或外部存储中检测和存储客户端会话， 从而允许在集群中加入多个均衡器。 - 在 HTTP 模块的 `upstream` 块中使用 [backup_switch](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) 指令 允许备份服务器 在主服务器再次可访问时继续处理请求。 - 条件性地 [将客户端连接绑定](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-bind-conn) 到代理服务器连接，这也支持代理 NTLM。 - 代理模块中的缓存分片，支持根据响应的属性 在 [位置](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) 之间分配缓存。 - 错误页面和 `Server` 头字段中的服务器签名 可以使用 [server_tokens](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-tokens) 指令隐藏或覆盖。 # https://cn.angie.software/angie/docs/installation/external-modules/dynamic-limit-req.md # Dynamic Limit Req 该模块在请求超出速率限制时动态封禁 IP 地址，并在指定时间后自动解封。 ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_dynamic_limit_req_module.so; ``` ## 配置示例 ```nginx http { include mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; dynamic_limit_req_zone $binary_remote_addr zone=one:10m rate=100r/s redis=127.0.0.1 block_second=300; dynamic_limit_req_zone $binary_remote_addr zone=two:10m rate=50r/s redis=127.0.0.1 block_second=600; dynamic_limit_req_zone $binary_remote_addr zone=sms:5m rate=5r/m redis=127.0.0.1 block_second=1800; server { listen 80; server_name localhost; location / { if ($http_x_forwarded_for) { return 400; } root html; index index.html index.htm; dynamic_limit_req zone=one burst=100 nodelay; dynamic_limit_req_status 403; } error_page 403 500 502 503 504 /50x.html; location = /50x.html { root html; } } server { listen 80; server_name localhost2; location / { root html; index index.html index.htm; set $flag 0; if ($document_uri ~* "regist") { set $flag "${flag}1"; } if ($request_method = POST) { set $flag "${flag}2"; } if ($flag = "012") { dynamic_limit_req zone=sms burst=3 nodelay; dynamic_limit_req_status 403; } if ($document_uri ~* "getSmsVerifyCode.do") { dynamic_limit_req zone=sms burst=5 nodelay; dynamic_limit_req_status 444; } dynamic_limit_req zone=two burst=50 nodelay; dynamic_limit_req_status 403; } error_page 403 502 503 504 /50x.html; location = /50x.html { root html; } } } ``` ## 更多信息 详细文档和源代码可在以下链接获取： [https://github.com/limithit/ngx_dynamic_limit_req_module](https://github.com/limithit/ngx_dynamic_limit_req_module) # https://cn.angie.software/angie/docs/installation/external-modules/echo.md # Echo 该模块添加了 `echo`、`sleep`、`time`、`exec` 以及其他 shell 风格的函数。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-echo` - Angie PRO：`angie-pro-module-echo` ## 加载模块 要使用该模块，必须在 `main{}` 上下文中加载它： ```nginx load_module modules/ngx_http_echo_module.so; ``` ## 配置示例 ```nginx server { listen 80; server_name localhost; location /echo { echo_before_body '这些行是由'; echo_before_body 'echo_before_body 指令插入的'; echo_after_body '这些行是由'; echo_after_body 'echo_after_body 指令添加的'; proxy_pass $scheme://127.0.0.1:$server_port$request_uri/more; } location /echo/more { set $val 'value'; echo '======== 后端响应开始 ========='; echo '后端响应主体'; echo "val 被设置为 $val"; echo '======== 后端响应结束 ==========='; } location /echo_with_sleep { echo hello; echo_flush; echo_sleep 2.5; echo world; } location /dup { echo_duplicate 3 "--"; echo_duplicate 1 " END "; echo_duplicate 3 "--"; echo; } location /subr { echo_reset_timer; echo_location /sub1; echo_location /sub2; echo "took $echo_timer_elapsed sec for total."; } location /subr_async { echo_reset_timer; echo_location_async /sub1; echo_location_async /sub2; echo "took $echo_timer_elapsed sec for total."; } location /sub1 { echo_sleep 2; echo hello; } location /sub2 { echo_sleep 1; echo world; } } ``` ## 演示 让我们发起几个请求来演示该模块的功能。 ```console $ curl localhost/echo 这些行是由 echo_before_body 指令插入的 ======== 后端响应开始 ========= 后端响应主体 val 被设置为 value ======== 后端响应结束 =========== 这些行是由 echo_after_body 指令添加的 ``` ```console $ curl localhost/echo_with_sleep hello world ``` 字符串 "hello" 和 "world" 将以 2.5 秒的间隔出现。 ```console $ curl localhost/dup ------ END ------ ``` ```console $ time curl localhost/subr hello world took 3.004 sec for total. real 0m3.027s user 0m0.015s sys 0m0.007s ``` ```console $ time curl localhost/subr_async hello world took 0.000 sec for total. real 0m2.023s user 0m0.001s sys 0m0.020s ``` ## 附加信息 详细文档和源代码可在以下位置获取： [https://github.com/openresty/echo-nginx-module](https://github.com/openresty/echo-nginx-module). # https://cn.angie.software/angie/docs/installation/external-modules/enhanced-memcached.md # 增强型 Memcached 此模块扩展了内置 [Memcached](https://cn.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached) 模块的功能,允许您在 memcached 服务器上添加和删除键值数据。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-enhanced-memcached` - Angie PRO:`angie-pro-module-enhanced-memcached` ## 加载模块 在 `main{}` 上下文中加载模块: ```nginx load_module modules/ngx_http_enhanced_memcached_module.so; ``` ## 配置示例 ```nginx upstream memcached_upstream { server 127.0.0.1:11211; } server { listen 80; server_name localhost; location / { set $enhanced_memcached_key "$request_uri"; enhanced_memcached_allow_put on; enhanced_memcached_allow_delete on; enhanced_memcached_pass memcached_upstream; } location /stats { enhanced_memcached_stats on; enhanced_memcached_pass memcached_upstream; access_log off; } location /flush { enhanced_memcached_flush on; enhanced_memcached_pass memcached_upstream; } } ``` ## 请求示例 添加键 `key1`,值为 `key1 value`: ```console $ curl -X PUT -d 'key1 value' http://127.0.0.1/key1 STORED ``` 检索 `key1` 的值: ```console $ curl http://127.0.0.1/key1 key1 value ``` 删除键为 `key1` 的数据: ```console $ curl -X DELETE http://127.0.0.1/key1 DELETED ``` 输出 memcached 统计信息: ```console $ curl http://127.0.0.1/stats ``` 清除所有数据: ```console $ curl http://127.0.0.1/flush ``` ## 其他信息 详细文档和源代码可在以下位置获取: [https://github.com/bpaquet/ngx_http_enhanced_memcached_module](https://github.com/bpaquet/ngx_http_enhanced_memcached_module) # https://cn.angie.software/support/enterprise.md # 企业技术支持 企业技术支持为关键基础设施组件提供高水平的服务。企业技术支持服务包含标准技术支持的所有功能，此外还包括： - 保证初始响应时间——最长2小时； - 24/7全天候支持。 完整的服务条款可以在 [`这里`](https://cn.angie.software//support/Angie_enterprise.pdf) 找到。 ## 标准技术支持与企业技术支持条款对比 | | 标准 | 企业 | |--------------------------|------|------| | 基于单独的技术支持协议提供 | | | | 通过电子邮件和在线表单提供支持请求 | | | | 通过电话提供支持请求 | | | | 支持时间：工作日莫斯科时间10:00至20:00 | | | | 支持时间：24/7全天候 | | | | 请求的初始响应时间：最长2小时 | | | ## 企业技术支持提供的服务 - 解决软件功能问题。 - 就软件使用提供咨询并对文档进行说明。 - 就软件运行期间的HTTP和TCP协议操作提供咨询。 - 就修改用户操作系统设置以提升软件性能提供咨询。 - 就软件与用户安装的其他解决方案之间的交互优化机会提供咨询。 - 为满足用户个性化需求提供配置文件定制支持。 - 在技术支持服务期限内提供更新。 # https://cn.angie.software/legal/eula.md # End-User License Agreement #### NOTE The legally binding End-User License Agreement is published in Russian. The Russian original is the authoritative version; this page provides an English-language reference. Please consult the Russian original or contact [info@wbsrv.ru](mailto:info@wbsrv.ru) for assistance. The current End-User License Agreement (EULA) governs the use of Angie Software products distributed by Web Server, LLC (the Rights Holder) either directly to End Users or via the Rights Holder's Partners, including as part of integrated hardware-software solutions. To review the current and previous versions of the EULA, refer to the Russian-language source on the Angie website. # https://cn.angie.software/angie/docs/installation/external-modules/eval.md # Eval 该模块允许将子请求响应体保存到变量中。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-eval` - Angie PRO：`angie-pro-module-eval` ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_eval_module.so; ``` ## 配置示例 ```nginx server { listen 80; server_name localhost; location / { eval_subrequest_in_memory off; eval_override_content_type text/plain; eval_buffer_size 4k; eval $res { rewrite ^(/eval_.*/)(.*)$ /$2 break; proxy_pass http://127.0.0.1:8081; } if ($res ~ "access denied") { return 403 $res\n; } proxy_pass http://127.0.0.1:8082; } } server { listen 8081; if ($arg_user != 'Legal') { return 403 "access denied"; } return 200 OK; } server { listen 8082; location / { root /usr/share/angie/html; } } ``` ## 其他信息 详细文档和源代码可在以下位置获取： [https://github.com/openresty/nginx-eval-module](https://github.com/openresty/nginx-eval-module) # https://cn.angie.software/news/events.md # 活动 ## [Angie Web服务器一年后：新机遇与未来规划](https://cn.angie.software//news/events/veb-server-angie-god-spustya-novie-vozmozhnosti.md) *27.11.2023* Angie开发负责人Valentin Bartenyev将在HighLoad 2023大会上回顾项目第一年的发展历程。 ![替代文本](../../_images/news/veb-server-angie-god-spustya-novie-vozmozhnosti.jpeg) # https://cn.angie.software/angie/docs/installation/external-modules.md # 第三方模块 除了我们自己为 [Angie](https://cn.angie.software//angie/docs/installation/oss_packages.md#install-dynamicmodules-oss) 和 [Angie PRO](https://cn.angie.software//angie/docs/installation/pro_packages.md#install-dynamicmodules-pro) 开发的动态模块外， 我们还在仓库中收集并发布了一些流行的 nginx 兼容第三方模块的软件包， 这些模块由我们公司之外的开发者开发。 ## 安装和配置 第三方模块软件包的安装方式与我们自己的软件包相同，都是从我们的仓库安装： - [Angie](https://cn.angie.software//angie/docs/installation/oss_packages.md#oss-packages) - [Angie PRO](https://cn.angie.software//angie/docs/installation/pro_packages.md#pro-packages) 要在 [配置](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) 中使用已安装的模块， 请在 `main` 上下文中使用 [load_module](https://cn.angie.software//angie/docs/configuration/modules/core.md#load-module) 指令加载它： ```nginx load_module modules/.so; ``` #### NOTE 我们不审查这些模块的源代码， 也不对安装它们的后果负责； 这些软件包的编译完全基于大量用户请求， *仅仅* 为了用户的便利。 ## 模块列表 | 模块 | 版本 | 软件包 | 描述 | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | [Auth JWT](https://cn.angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) | 0.9.0 | `angie-module-auth-jwt` `angie-pro-module-auth-jwt` | 为客户端添加 JWT 身份验证。 | | [Auth LDAP](https://cn.angie.software//angie/docs/installation/external-modules/auth-ldap.md#external-ldap) | 241200e | `angie-module-auth-ldap` `angie-pro-module-auth-ldap` | 添加对多服务器 LDAP 身份验证的支持。 | | [Auth PAM](https://cn.angie.software//angie/docs/installation/external-modules/auth-pam.md#external-auth-pam) | v1.5.5 | `angie-module-auth-pam` `angie-pro-module-auth-pam` | 添加对 PAM 身份验证的支持。 | | [Auth SPNEGO](https://cn.angie.software//angie/docs/installation/external-modules/auth-spnego.md#external-auth-spnego) | v1.1.3 | `angie-module-auth-spnego` `angie-pro-module-auth-spnego` | 添加对 SPNEGO 和 GSSAPI 的支持。 | | [Auth TOTP](https://cn.angie.software//angie/docs/installation/external-modules/auth-totp.md#external-auth-totp) | 1.1.0 | `angie-module-auth-totp` `angie-pro-module-auth-totp` | 添加基于 TOTP 的一次性密码身份验证。 | | [Brotli](https://cn.angie.software//angie/docs/installation/external-modules/brotli.md#external-brotli) | v1.0.0rc | `angie-module-brotli` `angie-pro-module-brotli` | 为响应添加静态和动态 Brotli 压缩。 | | [Cache Purge](https://cn.angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge) | 2.5.3 | `angie-module-cache-purge` `angie-pro-module-cache-purge` | 允许从 FastCGI、proxy、SCGI 和 uWSGI 缓存中清除内容。 | | [CGI](https://cn.angie.software//angie/docs/installation/external-modules/cgi.md#external-cgi) | v0.13 | `angie-module-cgi` `angie-pro-module-cgi` | 添加对 CGI 的支持。 | | [Combined Upstreams](https://cn.angie.software//angie/docs/installation/external-modules/combined-upstreams.md#external-combined-upstreams) | 2.3.1 | `angie-module-combined-upstreams` `angie-pro-module-combined-upstreams` | 允许将多个服务器组合并为一个。 | | [DAV Ext](https://cn.angie.software//angie/docs/installation/external-modules/dav-ext.md#external-dav-ext) | v3.0.0 | `angie-module-dav-ext` `angie-pro-module-dav-ext` | 通过 PROPFIND 和 OPTIONS 方法扩展 WebDAV 支持。 | | [Dynamic Limit Req](https://cn.angie.software//angie/docs/installation/external-modules/dynamic-limit-req.md#external-dynamic-limit-req) | 1.9.3 | `angie-module-dynamic-limit-req` `angie-pro-module-dynamic-limit-req` | 用于动态阻止 IP 地址并定期解除阻止。 | | [Echo](https://cn.angie.software//angie/docs/installation/external-modules/echo.md#external-echo) | v0.63 | `angie-module-echo` `angie-pro-module-echo` | 允许在配置文件中调用 `echo`、`sleep`、`time`、`exec`
和其他 shell 命令。 | | [Enhanced Memcached](https://cn.angie.software//angie/docs/installation/external-modules/enhanced-memcached.md#external-enhanced-memcached) | v0.3 | `angie-module-enhanced-memcached` `angie-pro-module-enhanced-memcached` | 扩展内置 [Memcached](https://cn.angie.software//angie/docs/configuration/modules/http/http_memcached.md#http-memcached) 模块的功能。 | | [Eval](https://cn.angie.software//angie/docs/installation/external-modules/eval.md#external-eval) | 2016.06.10 | `angie-module-eval` `angie-pro-module-eval` | 允许将子请求的响应体保存到变量中。 | | [GeoIP2](https://cn.angie.software//angie/docs/installation/external-modules/geoip2.md#external-geoip2) | 3.4 | `angie-module-geoip2` `angie-pro-module-geoip2` | 在 MaxMind GeoIP2 数据库中添加地理位置搜索。 | | [Headers More](https://cn.angie.software//angie/docs/installation/external-modules/headers-more.md#external-headers-more) | v0.39 | `angie-module-headers-more` `angie-pro-module-headers-more` | 允许设置和清除请求和响应头。 | | [HTTP Auth Radius](https://cn.angie.software//angie/docs/installation/external-modules/http-auth-radius.md#external-http-auth-radius) | 458af16 | `angie-module-http-auth-radius` `angie-pro-module-http-auth-radius` | 添加对 Radius 的支持。 | | [JWT](https://cn.angie.software//angie/docs/installation/external-modules/jwt.md#external-jwt) | v3.4.3 | `angie-module-jwt` `angie-pro-module-jwt` | [Auth JWT](https://cn.angie.software//angie/docs/installation/external-modules/auth-jwt.md#external-auth-jwt) 的轻量级替代方案。 | | [Keyval](https://cn.angie.software//angie/docs/installation/external-modules/keyval.md#external-keyval) | 0.3.0 | `angie-module-keyval` `angie-pro-module-keyval` | 允许使用来自键值对的值的变量。 | | [Lua](https://cn.angie.software//angie/docs/installation/external-modules/lua.md#external-lua)：
[http_lua_module](https://github.com/openresty/lua-nginx-module)、
[stream_lua_module](https://github.com/openresty/stream-lua-nginx-module) | 0.10.28 / v0.0.16 | `angie-module-lua` `angie-pro-module-lua` | 分别允许在 Angie 配置的 `http` 和 `stream` 上下文中
使用 Lua 语言。 | | [ModSecurity](https://cn.angie.software//angie/docs/installation/external-modules/modsecurity.md#external-modsec) | v1.0.4 | `angie-module-modsecurity` `angie-pro-module-modsecurity` | 添加用于使用 ModSecurity 规则的连接器。 | | [NJS](https://cn.angie.software//angie/docs/installation/external-modules/njs.md#external-njs)：
[http_js](https://cn.angie.software//angie/docs/installation/external-modules/http_js.md#http-js)、
[stream_js](https://cn.angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js) | 0.9.1 | `angie-module-njs` `angie-pro-module-njs` | 分别允许在 Angie 配置的 `http` 和 `stream` 上下文中
使用 njs（JavaScript 语言的子集）。

还提供名为 `...-njs-light` 的轻量级版本软件包；
但是，它与常规版本不兼容，不能同时使用。 | | [NDK](https://cn.angie.software//angie/docs/installation/external-modules/ndk.md#external-ndk) | v0.3.4 | `angie-module-ndk` `angie-pro-module-ndk` | 添加 Nginx 开发工具包（NDK）用于开发新模块。 | | [OpenTracing](https://cn.angie.software//angie/docs/installation/external-modules/opentracing.md#external-opentracing) | v0.41.0 | `angie-module-opentracing` `angie-pro-module-opentracing` | 在 Angie 中添加分布式 OpenTracing 请求跟踪；
包含用于将数据导出到 Zipkin 和 DataDog 的插件。 | | [OpenTelemetry](https://cn.angie.software//angie/docs/installation/external-modules/otel.md#external-otel) | v0.1.2 | `angie-module-otel` `angie-pro-module-otel` | 允许将遥测数据发送到 OpenTelemetry 收集器。 | | [PostgreSQL](https://cn.angie.software//angie/docs/installation/external-modules/postgres.md#external-postgres) | 1.0rc7 | `angie-module-postgres` `angie-pro-module-postgres` | 包含对 PostgreSQL 数据库的直接支持。 | | [Redis2](https://cn.angie.software//angie/docs/installation/external-modules/redis2.md#external-redis2) | v0.15 | `angie-module-redis2` `angie-pro-module-redis2` | 包含对 HTTP 上游的 Redis 2.0 支持。 | | [RTMP](https://cn.angie.software//angie/docs/installation/external-modules/rtmp.md#external-rtmp) | v1.2.2 | `angie-module-rtmp` `angie-pro-module-rtmp` | 包含对用于流媒体和点播广播的 RTMP 支持。 | | [Set Misc](https://cn.angie.software//angie/docs/installation/external-modules/set-misc.md#external-set-misc) | v0.33 | `angie-module-set-misc` `angie-pro-module-set-misc` | 向 [Rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite) 模块添加各种 set_xxx 指令。 | | [Subs](https://cn.angie.software//angie/docs/installation/external-modules/subs.md#external-subs) | e12e965 | `angie-module-subs` `angie-pro-module-subs` | 允许使用正则表达式替换 HTTP 响应体中的字符串。 | | [TestCookie](https://cn.angie.software//angie/docs/installation/external-modules/testcookie.md#external-testcookie) | 64137c2 | `angie-module-testcookie` `angie-pro-module-testcookie` | 使用基于 cookie 的"质询-响应"机制帮助对抗机器人。 | | [UnBrotli](https://cn.angie.software//angie/docs/installation/external-modules/unbrotli.md#external-unbrotli) | 60bed63 | `angie-module-unbrotli` `angie-pro-module-unbrotli` | 为不支持 Brotli 编码的客户端解压 `Content-Encoding: br` 的响应。 | | [Upload](https://cn.angie.software//angie/docs/installation/external-modules/upload.md#external-upload) | 2.3.0 | `angie-module-upload` `angie-pro-module-upload` | 为来自客户端的文件上传添加 `multipart/form-data` （RFC 1867）编码，
包括断点续传功能。 | | [VOD](https://cn.angie.software//angie/docs/installation/external-modules/vod.md#external-vod) | 1.33 | `angie-module-vod` `angie-pro-module-vod` | 允许重新打包 MP4 文件以通过 HLS、HDS、MSS 和 DASH 进行流式传输。 | | [VTS](https://cn.angie.software//angie/docs/installation/external-modules/vts.md#external-vts)：
[module-vts](https://github.com/vozlt/nginx-module-vts)、
[module-sts](https://github.com/vozlt/nginx-module-sts)、
[module-stream-sts](https://github.com/vozlt/nginx-module-stream-sts) | v0.2.4 / v0.1.1 / v0.1.1 | `angie-module-vts` `angie-pro-module-vts` | 包含上述三个用于流量监控的模块。 | | [ZIP](https://cn.angie.software//angie/docs/installation/external-modules/zip.md#external-zip) | 1.3.0 | `angie-module-zip` `angie-pro-module-zip` | 包含动态 ZIP 归档打包。 | | [Zstd](https://cn.angie.software//angie/docs/installation/external-modules/zstd.md#external-zstd) | f4ba115 | `angie-module-zstd` `angie-pro-module-zstd` | 包含 Zstandard 压缩。 | # https://cn.angie.software/genindex.md # https://cn.angie.software/angie/docs/installation/external-modules/geoip2.md # GeoIP2 GeoIP2 模块通过客户端的 IP 地址(默认)或特定变量的值在 MaxMind GeoIP2 数据库中实现查找。它同时支持 IPv4 和 IPv6。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie: `angie-module-geoip2` - Angie PRO: `angie-pro-module-geoip2` ## 加载模块 要使用该模块,必须在 `main{}` 上下文中加载它: ```nginx load_module modules/ngx_http_geoip2_module.so; # 用于 http{} 块 load_module modules/ngx_stream_geoip2_module.so; # 用于 stream{} 上下文 ``` 在下面的配置示例中,除了模块本身的指令外,还使用了 [echo](https://cn.angie.software//angie/docs/installation/external-modules/echo.md#external-echo) 模块的指令: ```nginx load_module modules/ngx_http_echo_module.so; ``` ## 配置示例 ```nginx http { geoip2 /var/lib/GeoIP/GeoLite2-Country.mmdb { auto_reload 1h; $geoip2_country_code default=RU source=$http_x_forwarded_for country iso_code; $geoip2_country_name source=$http_x_forwarded_for country names ru; } log_format with_geoip '$server_port $remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for" "$http_host" ' 'country="$geoip2_country_code"'; map $geoip2_country_code $denied { PL "1"; QA "1"; } server { listen 80; root /usr/share/angie/html; index index.html index.htm; access_log /var/log/angie/geoip_access.log with_geoip; if ($denied) { return 403; } location / { echo "ip = $http_x_forwarded_for"; echo "code = $geoip2_country_code"; echo "name = $geoip2_country_name"; } } } ``` ## 请求执行示例 ```console $ curl -H'X-Forwarded-For: 51.68.138.153' http://127.0.0.1 403 Forbidden

403 Forbidden

Angie/|angie_version|
``` ```console $ curl -H'X-Forwarded-For: 8.8.8.8' http://127.0.0.1 ip = 8.8.8.8 code = US name = United States ``` ```console $ curl -H'X-Forwarded-For: 77.88.44.242' http://127.0.0.1 ip = 77.88.44.242 code = RU name = Russia ``` ## 其他信息 详细文档和源代码可在以下位置获取: [https://github.com/leev/ngx_http_geoip2_module](https://github.com/leev/ngx_http_geoip2_module) # https://cn.angie.software/angie/docs/configuration/modules/google_perftools.md # Google PerfTools 模块 使用 [Google Performance Tools](https://github.com/gperftools/gperftools) 对 Angie 工作进程进行性能分析。该模块面向 Angie 开发人员，通过提供有关内存使用、CPU 负载和其他性能指标的详细信息，帮助他们分析和优化服务器性能。 在 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时，默认不构建此模块；需要使用 `--with-google_perftools_module` [构建参数](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 启用。 #### NOTE 此模块需要 [gperftools](https://github.com/gperftools/gperftools) 库。 ## 配置示例 ```nginx google_perftools_profiles /var/log/angie/perftools; ``` 性能分析文件将存储在类似 `/var/log/angie/perftools.<工作进程 PID>` 的文件中。 ## 指令 ### google_perftools_profiles | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `google_perftools_profiles` 文件前缀; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 设置文件名前缀，用于存储 Angie 工作进程的性能分析信息。工作进程 ID 会附加在文件名末尾的点号之后，例如：`/var/log/angie/perftools.1234`。 # https://cn.angie.software/angie/docs/configuration/grafana.md # 配置 Grafana 仪表板 要在 Grafana 中配置 [Angie 的仪表板](https://grafana.com/grafana/dashboards/20719-angie-dashboard/)，请按照以下步骤操作： 1. 使用 [Prometheus](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#http-prometheus) 模块， 添加以下 [include](https://cn.angie.software//angie/docs/configuration/modules/core.md#include) 指令到 [配置文件](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) 的 `http` 块中： ```nginx http { include prometheus_all.conf; # ... } ``` 以及在一个使用指定 IP 地址和端口组合的单独 `server` 块中的 `location` 内添加相应的 [prometheus](https://cn.angie.software//angie/docs/configuration/modules/http/http_prometheus.md#id3) 指令，例如： ```nginx server { listen 192.168.1.100:80; location =/p8s { prometheus all; } # ... } ``` 它们在 `location` 指定的端点以 Prometheus 格式导出 Angie 指标。 2. 将以下配置添加到 Prometheus 中， 指定在前面步骤中设置的 `server` 的 IP 地址和端口： ```yaml scrape_configs: - job_name: "angie" scrape_interval: 15s metrics_path: "/p8s" static_configs: - targets: ["192.168.1.100:80"] ``` 它每 15 秒收集一次指标， 使用在上一步中配置的 `/p8s` 路径。 #### NOTE 确保全局 `scrape_interval` 的值不大于此处的值。 3. 将 [Angie 的仪表板](https://grafana.com/grafana/dashboards/20719-angie-dashboard/) 导入到 Grafana 中。 # https://cn.angie.software/news/gruppa-rubytech-i-angie-objedinaiut-resursi.md # Rubytech集团与俄罗斯Web服务器开发商Angie整合资源与专业技术，共同推进产品开发 *22.08.2024* 俄罗斯高负载系统软件开发商Angie（Web Server有限责任公司）已加入Rubytech集团。 ![Alternative text](../../_images/news/gruppa-rubytech-i-angie-objedinaiut-resursi.webp)![Alternative text](../../_images/news/gruppa-rubytech-i-angie-objedinaiut-resursi.webp) *俄罗斯高负载系统软件开发商Angie（Web Server有限责任公司）已加入Rubytech集团。这一战略合作伙伴关系将扩大和丰富集团的产品组合，同时为开发商提供稳定的产品开发前景，以满足企业领域最迫切的需求。* 自2022年以来，Angie一直在开发其旗舰产品——基于世界知名的nginx（一个开源产品）分支开发的Web服务器。短短几年内，Angie的产品在集群软件解决方案领域建立了强大的声誉，并在俄罗斯市场上赢得了领导者地位。公司的产品已被列入国产软件登记册。 通过此次合作，集团的客户将有机会使用Angie的高性能和可扩展产品来构建和发展自己的IT基础设施，同时由Rubytech的专家、工程师和系统架构师团队提供实施和可靠的技术支持。而Angie的开发团队将继续开发现有产品组合，并为当前客户和合作伙伴保持一贯的解决方案和服务支持水平。Angie的两款旗舰产品——Angie PRO Web服务器和Kubernetes云环境解决方案Angie Ingress Controller（ANIC），以及Angie Web服务器的开源版本都将获得更集中的开发资源。 *"通过与Rubytech的合作，我们的商业能力将得到集团销售团队多年经验和实践的加强。这不仅使我们能够支持和发展自己的合作伙伴销售渠道，还能达到质的新高度。* *这将使我们作为开发商能够快速且自信地将新解决方案推向市场——Angie Application Delivery Controller（Angie ADC）流量平衡系统，它将替代Citrix ADC/Netscaler、Radware和F5 BIG-IP等西方软件产品，"* Angie（Web Server有限责任公司）总经理\*\*Zaur Abasmirzoev\*\*如是评论。 *"在做出合作决定时，我们主要看重Angie开发团队的独特专业技术，他们是世界级Web服务器nginx的创始团队。* *我相信产品、商业和管理经验的整合将使双方受益。Angie的开发人员将有机会显著扩大业务规模并实现可持续增长和发展：推出新产品并使其在企业客户中备受欢迎。而Rubytech集团将能够为客户提供更广泛的技术和解决方案栈，用于构建、发展和扩展IT基础设施。* *我相信这种联盟将是一项成功且互惠互利的投资，有助于在长期战略框架内发展集团业务，"* Rubytech集团首席执行官\*\*Igor Vedekhin\*\*分享了对未来的计划。 # https://cn.angie.software/angie/docs/installation/external-modules/headers-more.md # Headers-More headers-more 模块允许您添加、设置或删除任何传出或传入的头。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块,请使用以下软件包之一: - Angie:`angie-module-headers-more` - Angie PRO:`angie-pro-module-headers-more` ## 加载模块 要使用该模块,必须在 `main{}` 上下文中加载它: ```nginx load_module modules/ngx_http_headers_more_filter_module.so; ``` 在下面的配置示例中,除了该模块自己的指令外,还使用了 echo 模块的指令。 加载 echo 模块: ```nginx load_module modules/ngx_http_echo_module.so; ``` ## 配置示例 ```nginx http { server { listen 80; root /usr/share/angie/html; index index.html index.htm; location /clear { more_clear_headers 'Content-Type'; proxy_pass http://127.0.0.1:8081; } location /settype { more_set_headers 'Content-Type: text/plain'; proxy_pass http://127.0.0.1:8081; } location /changetype { more_set_headers -t 'text/plain text/css' 'Content-Type: text/newtype'; proxy_pass http://127.0.0.1:8081; } location /newheader { more_set_headers -t 'text/plain text/css' 'New-Header: foo'; proxy_pass http://127.0.0.1:8081; } location /404 { more_set_headers -s '400 404 500 503' 'Upstream-Status: $upstream_status'; proxy_pass http://127.0.0.1:8081; } location /input { set $my_host 'my.host'; more_set_input_headers 'Host: $my_host'; more_set_input_headers -t 'text/plain' 'X-Foo: bar'; echo "Host: $host"; echo "X-foo: $http_x_foo"; } } server { listen 8081; default_type text/css; location / { return 200 "OK\n"; } location /404 { return 404 "Done\n"; } } } ``` ## 其他信息 详细文档和源代码可在以下位置获取: [https://github.com/openresty/headers-more-nginx-module/](https://github.com/openresty/headers-more-nginx-module/) # https://cn.angie.software/angie/docs/installation/external-modules/http-auth-radius.md # HTTP Auth RADIUS 此模块使用 RADIUS 协议提供 HTTP 身份验证。 ## 安装 要 [安装](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 该模块，请使用以下软件包之一： - Angie：`angie-module-http-auth-radius` - Angie PRO：`angie-pro-module-http-auth-radius` ## 加载模块 在 `main{}` 上下文中加载模块： ```nginx load_module modules/ngx_http_auth_radius_module.so; ``` ## 配置示例 ```nginx http { radius_server "radius_server1" { auth_timeout 5; resend_limit 3; url "127.0.0.1:1812"; share_secret "secret"; } server { listen 80; server_name localhost; location = / { root html; index index.html index.htm; # RADIUS 服务器配置 # 第三个参数定义身份验证方法： # PAP CHAP MSCHAP MSCHAP2 EAPMD5 auth_radius_server "radius_server1" "PAP"; # 参数值： # Restricted、"Close Content"、off auth_radius "Restricted"; } } } ``` ## 其他信息 详细文档和源代码可在以下位置获取： [https://github.com/ten0s/ngx_http_auth_radius_module/](https://github.com/ten0s/ngx_http_auth_radius_module/) # https://cn.angie.software/angie/docs/configuration/modules/http.md # HTTP 模块 核心 HTTP 模块实现了 HTTP 服务器的基本功能：包括定义服务器块、配置用于请求路由的位置、提供静态文件和控制访问、配置重定向、支持 keep-alive 连接以及管理请求和响应标头。 本节中的其他模块扩展了此功能，允许您针对各种场景和需求灵活配置和优化 HTTP 服务器。 ## 指令 ### absolute_redirect | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `absolute_redirect` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `absolute_redirect on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果禁用,Angie 发出的重定向将是相对的。 另请参阅 [server_name_in_redirect](#server-name-in-redirect) 和 [port_in_redirect](#port-in-redirect) 指令。 ### aio | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio` `on` | `off` | `threads` [=pool]; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | `aio off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在 FreeBSD 和 Linux 上启用或禁用异步文件 I/O (AIO) 的使用: ```nginx location /video/ { aio on; output_buffers 1 64k; } ``` 在 FreeBSD 上,从 FreeBSD 4.3 开始可以使用 AIO。在 FreeBSD 11.0 之前,AIO 可以静态链接到内核中: ```nginx options VFS_AIO ``` 或作为内核可加载模块动态加载: ```nginx kldload aio ``` 在 Linux 上,从内核版本 2.6.22 开始可以使用 AIO。此外,还需要启用 [directio](#directio),否则读取将会阻塞: ```nginx location /video/ { aio on; directio 512; output_buffers 1 128k; } ``` 在 Linux 上,:ref:directio 只能用于读取按 512 字节边界对齐的块(对于 XFS 为 4K)。文件的未对齐末尾以阻塞模式读取。对于字节范围请求和非从文件开头开始的 FLV 请求也是如此:在文件开头和末尾读取未对齐的数据将会阻塞。 当在 Linux 上同时启用 AIO 和 [sendfile](#sendfile) 时,对于大于或等于 [directio](#directio) 指令中指定大小的文件使用 AIO,而对于较小的文件或禁用 [directio](#directio) 时使用 [sendfile](#sendfile): ```nginx location /video/ { sendfile on; aio on; directio 8m; } ``` 最后,可以使用多线程读取和 [发送](#sendfile) 文件,而不会阻塞工作进程: ```nginx location /video/ { sendfile on; aio threads; } ``` 读取和发送文件操作被卸载到指定 [池](https://cn.angie.software//angie/docs/configuration/modules/core.md#thread-pool) 的线程。如果省略池名称,则使用名为 "default" 的池。池名称也可以使用变量设置: ```nginx aio threads=pool$disk; ``` 使用 `aio on` 需要使用 `--with-file-aio` 配置参数进行构建。使用 `aio threads` 需要使用 `--with-threads` 参数进行构建。 目前,多线程仅与 [epoll](https://cn.angie.software//angie/docs/configuration/processing.md#epoll)、[kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 和 [eventport](https://cn.angie.software//angie/docs/configuration/processing.md#eventport) 方法兼容。多线程发送文件仅在 Linux 上受支持。 另请参阅 [sendfile](#sendfile) 指令。 ### aio_write | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio_write` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `aio_write off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果启用了 [aio](#aio),指定是否将其用于写入文件。目前,这仅在使用 `aio threads` 时有效,并且仅限于写入包含从代理服务器接收的数据的临时文件。 ### alias | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `alias` path; | |--------------------------------------------------------------------------------------|-----------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 为指定的位置定义替换路径。例如,使用以下配置: ```nginx location /i/ { alias /data/w3/images/; } ``` 对于 `/i/top.gif` 的请求,将发送文件 /data/w3/images/top.gif。 path 值可以包含变量,但不包括 [$document_root](#v-document-root) 和 [$realpath_root](#v-realpath-root)。 如果在使用正则表达式定义的位置内使用 `alias`,则该正则表达式应包含捕获组,并且 `alias` 应引用这些捕获组,例如: ```nginx location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { alias /data/w3/images/$1; } ``` 当位置匹配指令值的最后部分时: ```nginx location /images/ { alias /data/w3/images/; } ``` 最好使用 [root](#root) 指令: ```nginx location /images/ { root /data/w3; } ``` ### auth_delay | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_delay` time; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | `auth_delay 0s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 延迟处理返回 401 响应代码的未授权请求,以防止在通过 [密码](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 或 [子请求结果](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 限制访问时的时序攻击。 ### auto_redirect | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auto_redirect` [`on` | `off` | `default`]; | |--------------------------------------------------------------------------------------|-----------------------------------------------| | 默认值 | `auto_redirect default;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 控制当前缀位置以斜杠结尾时的 [重定向](#location-redirect) 行为: ```nginx location /prefix/ { auto_redirect on; } ``` 在这里,对 `/prefix` 的请求会导致重定向到 `/prefix/`。 值 `on` 显式启用重定向,而 `off` 禁用它。当设置为 `default` 时,仅当位置使用 [api](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api)、[proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)、[fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass)、[uwsgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass)、[scgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass)、[memcached_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass) 或 [grpc_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass) 处理请求时才启用重定向。 ### chunked_transfer_encoding | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `chunked_transfer_encoding` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `chunked_transfer_encoding on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许在 HTTP/1.1 中禁用分块传输编码。当使用的软件尽管标准要求但不支持分块编码时,这可能会派上用场。 ### client | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client` { ... } | |--------------------------------------------------------------------------------------|--------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 创建一个特殊的 `client` 上下文,用于处理 Angie 自行执行的内部 HTTP 请求,而无需外部客户端参与。 `client` 上下文将来自各种 Angie 模块的服务流量与用户流量隔离,允许对其进行额外控制。在此上下文中,只能定义命名位置(带有 `@` 前缀);它们无法被外部 HTTP 请求访问,只能通过内部服务器机制以编程方式调用。 `client` 上下文用于: - 在 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 模块中通过预定义的 `location @acme` 向证书颁发机构发送请求,可以使用 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块的指令进行额外配置; - 在 [Docker](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) 模块中通过预定义的 `location @docker_events` 和 `@docker_containers` 向 Docker API 发送请求,可以使用 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块的指令进行额外配置; - 通过 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 对代理服务器进行健康探测; - 在流 [Upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) 模块中使用 `remote_action` 的 [sticky learn](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) 模式。 支持多个 `client` 块允许在每个块内为多个 `location` 块分组通用设置,这有助于避免配置重复。 在每个 `client` 块中指定的指令仅由在其中显式声明的 `location` 块继承。特别是,这就是为什么它们不会影响隐式使用 `client` 块进行出站请求的其他模块的配置(例如 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 或 [Docker](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker))。 使用多个 `client` 块并继承设置的示例: ```nginx client { proxy_set_header Host docker.example.com; proxy_set_header Authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="; location @docker_events { } location @docker_containers { } } client { proxy_method GET; proxy_set_header Host backend.example.com; proxy_set_header X-Real-IP $remote_addr; location @health_check { proxy_pass http://upstream-server/health; } } ``` #### NOTE 这里允许使用与常规 `location` 块中相同的指令, 但实际上只有内容处理器 (如 [js_content](https://cn.angie.software//angie/docs/installation/external-modules/http_js.md#js-content) 或 [autoindex](https://cn.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id3)) 和变量处理器(如 [map](https://cn.angie.software//angie/docs/configuration/modules/http/http_map.md#id3)), 以及自身生成请求的指令 (如 `upstream_probe`)才会生效。 在其他 [请求处理阶段](https://cn.angie.software//angie/docs/configuration/processing.md#http-sessions) 操作的指令 (如 [limit_req](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-req)、[auth_request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3)、 [try_files](#try-files)、图像过滤器、XSLT 等) 在这里不起作用。 ### client_body_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_buffer_size` size; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `client_body_buffer_size 8k|16k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置读取客户端请求体的缓冲区大小。如果请求体大于缓冲区,则将整个请求体或仅其部分写入 [临时文件](#client-body-temp-path)。默认情况下,缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上,这是 8K。在其他 64 位平台上,通常是 16K。 ### client_body_in_file_only | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_file_only` `on` | `clean` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------------------| | 默认值 | `client_body_in_file_only off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定是否将整个客户端请求体保存到文件中。此指令可在调试期间使用,或在使用 [$request_body_file](#v-request-body-file) 变量或 [Perl](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) 模块的 [$r->request_body_file](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#p-r-request-body-file) 方法时使用。 | `on` | 请求处理后不删除临时文件 | |---------|------------------| | `clean` | 允许删除请求处理后留下的临时文件 | ### client_body_in_single_buffer | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_single_buffer` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | `client_body_in_single_buffer off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定是否将整个客户端请求体保存在单个缓冲区中。建议在使用 [$request_body](#v-request-body) 变量时使用此指令,以减少涉及的复制操作数量。 ### client_body_temp_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_temp_path` path [level1 [level2 [level3]]]; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `client_body_temp_path client_body_temp;`
(路径取决于 [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-client-body-temp-path`) | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义用于存储客户端请求体临时文件的目录。在指定目录下最多可以使用三级子目录层次结构。例如,在以下配置中 ```nginx client_body_temp_path /spool/angie/client_temp 1 2; ``` 临时文件的路径可能如下所示: ```nginx /spool/angie/client_temp/7/45/00000123457 ``` ### client_body_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_timeout` time; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `client_body_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义读取客户端请求体的超时时间。超时仅针对两次连续读取操作之间的时间段设置,而不是针对整个请求体的传输。如果客户端在此时间内未传输任何内容,则请求将以 408 (Request Time-out) 错误终止。 ### client_header_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_buffer_size` size; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `client_header_buffer_size 1k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置读取客户端请求头的缓冲区大小。对于大多数请求,1K 字节的缓冲区就足够了。但是,如果请求包含长 cookie,或来自 WAP 客户端,则可能无法容纳在 1K 中。如果请求行或请求头字段无法容纳在此缓冲区中,则会分配由 [large_client_header_buffers](#large-client-header-buffers) 指令配置的更大缓冲区。 如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。详情请参阅 [虚拟服务器选择](https://cn.angie.software//angie/docs/configuration/processing.md#request-processing) 部分。 ### client_header_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_timeout` time; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `client_header_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 定义读取客户端请求头的超时时间。如果客户端在此时间内未传输整个请求头,则请求将以 408 (Request Time-out) 错误终止。 ### client_max_body_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_max_body_size` size; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `client_max_body_size 1m;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置客户端请求体的最大允许大小。如果请求中的大小超过配置的值,则向客户端返回 413 (Request Entity Too Large) 错误。请注意,浏览器无法正确显示此错误。 | `0` | 禁用检查客户端请求体大小 | |-------|----------------| ### connection_pool_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `connection_pool_size` size; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `connection_pool_size 256` | `512;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许精确调整每个连接的内存分配。此指令对性能的影响很小,通常不应使用。默认情况下: | `256` (字节) | 在 32 位平台上 | |--------------|-------------| | `512` (字节) | 在 64 位平台上 | ### default_type | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `default_type` mime-type; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `default_type text/plain;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义响应的默认 MIME 类型。文件扩展名到 MIME 类型的映射可以使用 [types](#types) 指令设置。 ### directio | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio` size | `off`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `directio off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在读取大于或等于指定大小的文件时,启用 `O_DIRECT` 标志(FreeBSD、Linux)、`F_NOCACHE` 标志(macOS)或 `directio()` 函数(Solaris)的使用。该指令会自动禁用给定请求的 [sendfile](#sendfile) 使用。建议用于提供大文件: ```nginx directio 4m; ``` 或在 Linux 上使用 [aio](#aio) 时。 ### directio_alignment | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio_alignment` size; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `directio_alignment 512;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置 [directio](#directio) 的对齐方式。在大多数情况下,512 字节对齐就足够了。但是,在 Linux 下使用 XFS 时,需要将其增加到 4K。 ### disable_symlinks | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `disable_symlinks` `off`;

`disable_symlinks` `on` | `if_not_owner` [`from=`part]; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| | 默认值 | `disable_symlinks off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定在打开文件时应如何处理符号链接: | `off` | 允许路径中的符号链接且不进行检查。这是默认行为。 | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `on` | 如果路径的任何组成部分是符号链接,则拒绝访问该文件。 | | `if_not_owner` | 如果路径的任何组成部分是符号链接,且该链接与其指向的对象具有不同的所有者,则拒绝访问该文件。 | | `from=`part | 在检查符号链接时(参数 `on` 和 `if_not_owner`),通常会检查所有路径组成部分。可以通过额外指定 `from=part` 参数来跳过对路径初始部分中符号链接的检查。在这种情况下,仅从指定初始部分之后的路径组成部分开始检查符号链接。如果该值不是被检查路径的初始部分,则会完整检查路径,就像根本没有指定此参数一样。如果该值与文件名完全匹配,则不检查符号链接。参数值中可以使用变量。 | 示例: ```nginx disable_symlinks on from=$document_root; ``` 此指令仅在具有 `openat()` 和 `fstatat()` 接口的系统上可用。此类系统包括现代版本的 FreeBSD、Linux 和 Solaris。 #### WARNING `on` 和 `if_not_owner` 参数会增加处理开销。 在不支持仅为搜索而打开目录的系统上,使用这些参数需要工作进程对所有被检查的目录具有读取权限。 #### NOTE [AutoIndex](https://cn.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex)、[Random Index](https://cn.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) 和 [DAV](https://cn.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) 模块目前忽略此指令。 ### early_hints | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `early_hints` string ...; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义将 "103 Early Hints" 响应传递给客户端的条件。如果字符串参数的至少一个值不为空且不等于 `0`,则将传递响应: ```nginx map $http_sec_fetch_mode $early_hints { navigate $http2$http3; } server { ... location / { early_hints $early_hints; proxy_pass http://example.com; } } ``` ### error_page | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_page` code ... [=[response]] uri; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 定义针对指定错误显示的 URI。uri 值可以使用变量。 示例: ```nginx error_page 404 /404.html; error_page 500 502 503 504 /50x.html; ``` 这会导致内部重定向到指定的 uri,并将客户端请求方法更改为 "GET"(对于除 "GET" 和 "HEAD" 之外的所有方法)。 此外,可以使用类似 `=response` 的语法将响应代码更改为另一个代码,例如: ```nginx error_page 404 =200 /empty.gif; ``` 如果错误响应由代理服务器或 FastCGI/uwsgi/SCGI/gRPC 服务器处理,并且该服务器可能返回不同的响应代码(例如 200、302、401 或 404),则可以传递它返回的代码: ```nginx error_page 404 = /404.php; ``` 如果在内部重定向期间不需要更改 URI 和方法,可以将错误处理传递到命名的 `location`: ```nginx location / { error_page 404 = @fallback; } location @fallback { proxy_pass http://backend; } ``` #### NOTE 如果在处理 uri 期间发生错误,则会将最后发生的错误代码的响应返回给客户端。 也可以使用 URL 重定向进行错误处理: ```nginx error_page 403 http://example.com/forbidden.html; error_page 404 =301 http://example.com/notfound.html; ``` 在这种情况下,默认情况下会向客户端返回响应代码 302。它只能更改为重定向响应代码之一(301、302、303、307 和 308)。 ### etag | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `etag` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | `etag on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用为静态资源自动生成 `ETag` 响应头字段。 ### http | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http` { ... } | |--------------------------------------------------------------------------------------|------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main | 提供配置文件上下文,在其中指定 HTTP 服务器指令。 ### if_modified_since | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `if_modified_since` `off` | `exact` | `before`; | |--------------------------------------------------------------------------------------|---------------------------------------------------| | 默认值 | `if_modified_since exact;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定如何将响应的修改时间与 `If-Modified-Since` 请求头字段中的时间进行比较: | `off` | 响应始终被视为已修改 | |----------|--------------------------------------------| | `exact` | 精确匹配 | | `before` | 响应的修改时间小于或等于 `If-Modified-Since` 请求头字段中的时间 | ### ignore_invalid_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ignore_invalid_headers` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `ignore_invalid_headers on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 控制 Angie 是否忽略具有无效名称的头字段。有效名称由英文字母、数字、连字符组成,可能还包括下划线(由 [underscores_in_headers](#underscores-in-headers) 指令控制)。 如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。 ### internal | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `internal;` | |--------------------------------------------------------------------------------------|---------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 指定给定的 `location` 只能用于内部请求。对于外部请求,将向客户端返回 404 (Not Found) 错误。内部请求包括以下几种: * 由 [error_page](#error-page)、[index](https://cn.angie.software//angie/docs/configuration/modules/http/http_index.md#id3)、[random_index](https://cn.angie.software//angie/docs/configuration/modules/http/http_random_index.md#id3) 和 [try_files](#try-files) 指令重定向的请求; * 由上游服务器的 `X-Accel-Redirect` 响应头字段重定向的请求; * 由 [SSI](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) 模块的 `include virtual` 命令、[Addition](https://cn.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition) 模块指令以及 [auth_request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) 和 [mirror](https://cn.angie.software//angie/docs/configuration/modules/http/http_mirror.md#id3) 指令形成的子请求; * 由 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令更改的请求。 示例: ```nginx error_page 404 /404.html; location = /404.html { internal; } ``` 由于 404 错误是在带有 `internal` 指令的 `location` 上下文中返回的,外部请求可以重定向到不同的 location。这允许对外部和内部请求使用相同的前缀,但进行不同的处理,例如: ```nginx location /path { internal; error_page 404 =@external; proxy_pass https://internal; } location @external { proxy_pass https://external; } ``` 在这里,外部请求 `GET /path` 将被代理到 `https://external/path`,而相同的内部请求将被代理到 `https://internal/path`。 #### NOTE 为了防止错误配置可能导致的循环,内部重定向的次数限制为十次。当达到此限制时,将返回 500 (Internal Server Error) 错误。在这种情况下,可以在错误日志中看到 `rewrite or internal redirection cycle` 消息。 ### keepalive_disable | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_disable` `none` | browser ...; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `keepalive_disable msie6;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 禁用与行为异常的浏览器的保持连接。browser 参数指定将受影响的浏览器。 | `none` | 对所有浏览器启用保持连接 | |----------|-----------------------------------------------------| | `msie6` | 一旦收到 POST 请求,禁用与旧版本 MSIE 的保持连接 | | `safari` | 禁用与 macOS 和类 macOS 操作系统上的 Safari 和类 Safari 浏览器的保持连接 | ### keepalive_requests | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_requests` number; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `keepalive_requests 1000;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置通过一个保持连接可以处理的最大请求数。在达到最大请求数后,连接将被关闭。 定期关闭连接对于释放每个连接的内存分配是必要的。因此,使用过高的最大请求数可能会导致过度的内存使用,不建议这样做。 ### keepalive_time | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_time` time; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | `keepalive_time 1h;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制通过一个保持连接处理请求的最长时间。达到此时间后,连接将在后续请求处理完成后关闭。 ### keepalive_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_timeout` timeout [header_timeout]; | |--------------------------------------------------------------------------------------|-------------------------------------------------| | 默认值 | `keepalive_timeout 75s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | | timeout | 设置保持连接的客户端连接在服务器端保持打开的超时时间 | |-----------|------------------------------| | `0` | 禁用保持连接的客户端连接 | 第二个 *可选* 参数在响应中设置 `Keep‑Alive: timeout=time` 头字段的值。这两个参数可以不同。 `Keep-Alive: timeout=time` 头字段被 Mozilla 和 Konqueror 识别。MSIE 会在大约 60 秒后自行关闭保持连接。 ### large_client_header_buffers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `large_client_header_buffers` number size; | |--------------------------------------------------------------------------------------|----------------------------------------------| | 默认值 | `large_client_header_buffers 4 8k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置用于读取大型客户端请求头的缓冲区的最大数量和大小。请求行不能超过一个缓冲区的大小,否则将向客户端返回 414 (Request-URI Too Large) 错误。请求头字段也不能超过一个缓冲区的大小,否则将向客户端返回 400 (Bad Request) 错误。缓冲区仅在需要时分配。默认情况下,缓冲区大小等于 8K 字节。如果在请求处理结束后连接转换为保持连接状态,这些缓冲区将被释放。 如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。 ### limit_except | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_except` method1 [method2...] { ... }; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 限制 location 内允许的 HTTP 方法。method 参数可以是以下之一:`GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`MKCOL`、`COPY`、`MOVE`、`OPTIONS`、`PROPFIND`、`PROPPATCH`、`LOCK`、`UNLOCK` 或 `PATCH`。允许 `GET` 方法也会使 `HEAD` 方法被允许。可以使用 [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) 和 [Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 模块指令限制对其他方法的访问: ```nginx limit_except GET { allow 192.168.1.0/32; deny all; } ``` #### NOTE 此示例中的限制适用于 **除** `GET` 和 `HEAD` **之外** 的所有方法。 ### limit_rate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate` rate; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `limit_rate 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 限制向客户端传输响应的速率。速率以每秒字节数指定。零值禁用速率限制。限制是针对每个请求设置的,因此如果客户端同时打开两个连接,总速率将是指定限制的两倍。 参数值可以包含变量。在需要根据特定条件限制速率的情况下,这可能很有用: ```nginx map $slow $rate { 1 4k; 2 8k; } limit_rate $rate; ``` 速率限制也可以在 [$limit_rate](#v-limit-rate) 变量中设置,但不建议使用此方法: ```nginx server { if ($slow) { set $limit_rate 4k; } } ``` 速率限制也可以在代理服务器响应的 `X-Accel-Limit-Rate` 头字段中设置。可以使用 [proxy_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers)、[fastcgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers)、[uwsgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers) 和 [scgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) 指令禁用此功能。 ### limit_rate_after | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate_after` size; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `limit_rate_after 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 设置初始数量,在此之后向客户端传输响应的速率将受到限制。参数值可以包含变量。 示例: ```nginx location /flv/ { flv; limit_rate_after 500k; limit_rate 50k; } ``` ### lingering_close | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_close` `on` | `always` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------------| | 默认值 | `lingering_close on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 控制 Angie 如何关闭客户端连接。 | `on` | Angie 将 [等待](#lingering-timeout) 并 [处理](#lingering-time) 来自客户端的额外数据,然后完全关闭连接,但仅当启发式方法表明客户端可能正在发送更多数据时。 | |----------|----------------------------------------------------------------------------------------------------------| | `always` | Angie 将始终等待并处理额外的客户端数据。 | | `off` | Angie 不会等待更多数据,将立即关闭连接。此行为会破坏协议,在正常情况下不应使用。 | 要控制 HTTP/2 连接的关闭,必须在 [server](#server) 级别指定该指令。 ### lingering_time | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_time` time; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | `lingering_time 30s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 当 [lingering_close](#lingering-close) 生效时,此指令指定 Angie 处理(读取并忽略)来自客户端的额外数据的最长时间。在此之后,连接将被关闭,即使还有更多数据。 ### lingering_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_timeout` time; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `lingering_timeout 5s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 当 [lingering_close](#lingering-close) 生效时,此指令指定等待更多客户端数据到达的最长等待时间。如果在此时间内未收到数据,连接将被关闭。否则,数据将被读取并忽略,Angie 再次开始等待更多数据。"等待-读取-忽略"循环会重复,但不会超过 [lingering_time](#lingering-time) 指令指定的时间。 在优雅关闭期间,客户端保持连接仅在空闲时间至少达到 `lingering_timeout` 中指定的时间时才会关闭。 #### NOTE 在 nginx 中,类似的指令称为 [keepalive_min_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout)。 ### listen | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` address[:port] [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];

`listen` port [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];

`listen` unix:path [`default_server`] [`ssl`] [http2 | `quic`] [`proxy_protocol`] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; | |--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `listen *:80` | `*:8000;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 设置监听套接字的 address 和 port，或服务器接受请求的 UNIX 域套接字的路径。address 也可以是主机名，例如： ```nginx listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000; ``` IPv6 地址用方括号指定： ```nginx listen [::]:8000; listen [::1]; ``` UNIX 域套接字使用 `unix:` 前缀指定： ```nginx listen unix:/var/run/angie.sock; ``` 可以同时指定 address 和 port，或仅指定 address 或仅指定 port。 当省略某些部分时，适用以下规则： - 如果仅给出 address，则使用端口 80。 - 如果仅给出 port， Angie 将监听所有可用的 IPv4（以及 IPv6，如果已启用）接口。 该端口的第一个 `server` 块 将成为具有不匹配 `Host` 头的请求的默认服务器。 - 如果完全省略该指令，Angie 在以超级用户权限运行时使用 `*:80`， 否则使用 `*:8000`。 | `default_server` | 指定了此参数的服务器
将成为给定 address:port 对的默认服务器
（它们共同构成一个 *监听套接字*）。

如果没有带 `default_server` 参数的指令，
该监听套接字的默认服务器
将是配置中为该套接字提供服务的第一个服务器。 | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `ssl` | 表示在此监听套接字上接受的所有连接都应在 SSL 模式下工作。这允许为同时处理 HTTP 和 HTTPS 请求的服务器提供更 [紧凑的配置](https://cn.angie.software//angie/docs/configuration/ssl.md#compact-server)。 | | `http2` | 配置端口接受 HTTP/2 连接。通常，为了使其工作，还应指定 `ssl` 参数，但 Angie 也可以配置为接受不带 SSL 的 HTTP/2 连接。

#### Deprecated
自 1.2.0 版本弃用.

请改用 [http2](https://cn.angie.software//angie/docs/configuration/modules/http/http_v2.md#http2) 指令。 | | `quic` | 配置端口接受 QUIC 连接。
要使用此选项，
Angie 必须启用并配置 [HTTP3 模块](https://cn.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3)。
设置 `quic` 后，
您还可以指定 `reuseport`
以便可以使用多个工作进程。 | | `proxy_protocol` | 表示在此监听套接字上接受的所有连接都应使用 PROXY 协议。 | `listen` 指令还可以指定几个特定于套接字相关系统调用的附加参数。这些参数可以在任何 `listen` 指令中指定，但对于给定的监听套接字只能指定一次： | `setfib=`number | 为监听套接字设置路由表 FIB（`SO_SETFIB` 选项）。目前仅在 FreeBSD 上有效。 | |--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fastopen=`number | 为监听套接字启用"TCP Fast Open"，并限制尚未完成三次握手的连接队列的最大长度。

#### WARNING
除非服务器能够处理多次接收带有数据的相同 SYN 数据包，否则不要启用"TCP Fast Open"。 | | `backlog=`number | 设置 `listen()` 调用中的 `backlog` 参数，
该参数限制待处理连接队列的最大长度。默认情况下，
在 FreeBSD、DragonFly BSD 和 macOS 上 backlog 设置为 -1，
在其他平台上设置为 511。 | | `rcvbuf=`size | 为监听套接字设置接收缓冲区大小（`SO_RCVBUF` 选项）。 | | `sndbuf=`size | 为监听套接字设置发送缓冲区大小（`SO_SNDBUF` 选项）。 | | `accept_filter=`filter | 为监听套接字设置接受过滤器的名称（`SO_ACCEPTFILTER` 选项），
该过滤器在将传入连接传递给 `accept()` 之前对其进行过滤。
这仅在 FreeBSD 和 NetBSD 5.0+ 上有效。
可能的值为 `dataready` 和 `httpready`。 | | `deferred` | 指示在 Linux 上使用延迟 `accept()`
（`TCP_DEFER_ACCEPT` 套接字选项）。 | | `bind` | 指示为给定的 address:port 对进行单独的 `bind()` 调用。
这很有用，因为如果有多个具有相同端口但不同地址的 `listen`
指令，并且其中一个 `listen` 指令监听给定 `port`
的所有地址（`*:port`），Angie 将只 `bind()` 到
`*:port`。应该注意的是，在这种情况下将进行 `getsockname()`
系统调用以确定接受连接的地址。如果使用了 `setfib`、`fastopen`、
`backlog`、`rcvbuf`、`sndbuf`、`accept_filter`、
`deferred`、`ipv6only`、`reuseport` 或 `so_keepalive`
参数，那么对于给定的 `address:port` 对将始终进行单独的 `bind()` 调用。 | | `ipv6only=on` | `off` | 确定（通过 `IPV6_V6ONLY` 套接字选项）
监听通配符地址 [::] 的 IPv6 套接字是否只接受
IPv6 连接或同时接受 IPv6 和 IPv4 连接。此参数
默认开启。它只能在启动时设置一次。 | | `reuseport` | 指示为每个工作进程创建单独的监听套接字
（在 Linux 3.9+ 和 DragonFly BSD 上使用 `SO_REUSEPORT` 套接字选项，
或在 FreeBSD 12+ 上使用 `SO_REUSEPORT_LB`），
允许内核在工作进程之间分配传入连接。目前仅在 Linux 3.9+、
DragonFly BSD 和 FreeBSD 12+ 上有效。

#### WARNING
不当使用 `reuseport` 参数
可能会带来安全隐患。 | | `multipath` | 启用通过 [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP) 接受连接，
自 Linux 内核版本 5.6 起支持。
此参数与 `quic` **不兼容**。 | | `so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`] | 为监听套接字配置"TCP keepalive"行为。

| `''` | 如果省略此参数，则套接字将使用操作系统的设置 |
|--------|--------------------------|
| `on` | 为套接字开启 `SO_KEEPALIVE` 选项 |
| `off` | 为套接字关闭 `SO_KEEPALIVE` 选项 | | 某些操作系统支持使用 `TCP_KEEPIDLE`、`TCP_KEEPINTVL` 和 `TCP_KEEPCNT` 套接字选项在每个套接字的基础上设置 TCP keepalive 参数。在这些系统上（目前包括 Linux、NetBSD、 Dragonfly、FreeBSD 和 macOS），可以使用 `keepidle`、`keepintvl` 和 `keepcnt` 参数进行配置。可以省略一个或两个 参数，在这种情况下，相应套接字选项的系统默认设置将生效。例如， ```nginx so_keepalive=30m::10 ``` 将空闲超时（`TCP_KEEPIDLE`）设置为 30 分钟，将探测间隔（`TCP_KEEPINTVL`）保留为系统默认值，并将探测次数（`TCP_KEEPCNT`）设置为 10 次探测。 示例： ```nginx listen 127.0.0.1 default_server accept_filter=dataready backlog=1024; ``` ### location | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `location` ([ = | ~ | ~\* | ^~ ] uri | `@name`)+ { ... } | |--------------------------------------------------------------------------------------|------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location | 根据请求 URI 是否匹配任何匹配表达式来设置配置。 匹配是针对规范化的 URI 执行的，在解码以"%XX"形式编码的文本、解析对相对路径组件"."和".."的引用，以及可能将两个或多个相邻斜杠 [压缩](#merge-slashes) 为单个斜杠之后进行。 `location` 可以由前缀字符串定义，也可以由正则表达式定义。 正则表达式使用前置修饰符指定： | `~*` | 不区分大小写的匹配 | |--------|-------------| | `~` | 区分大小写的匹配 | 为了找到与请求匹配的 location，Angie 首先检查使用前缀字符串定义的 location（前缀 location）。在这些 location 中，选择并记住具有最长匹配前缀的 location。 #### NOTE 对于不区分大小写的操作系统（如 macOS），前缀字符串匹配不区分大小写。 但是，匹配仅限于单字节区域设置。 然后按照正则表达式在配置文件中出现的顺序检查正则表达式。在第一次匹配后停止搜索，并使用相应的配置。如果没有找到与正则表达式的匹配，则使用之前记住的前缀 location 的配置。 除了下面提到的一些例外情况，`location` 块可以嵌套。 正则表达式可以创建捕获组，这些捕获组稍后可以与其他指令一起使用。 如果最长匹配前缀 location 具有 `^~` 修饰符，则不检查正则表达式。 此外，使用 `=` 修饰符，可以定义 URI 和 location 的精确匹配。如果找到精确匹配，则搜索终止。例如，如果 `/` 请求频繁发生，定义 `location =/` 将加快这些请求的处理速度，因为搜索在第一次比较后终止。这样的 location 不能包含嵌套的 location，因为它定义了精确匹配。 示例： ```nginx location =/ { #configuration A } location / { #configuration B } location /documents/ { #configuration C } location ^~/images/ { #configuration D } location ~*\.(gif|jpg|jpeg)$ { #configuration E } ``` - `/` 请求将匹配配置 A， - `/index.html` 请求将匹配配置 B， - `/documents/document.html` 请求将匹配配置 C， - `/images/1.gif` 请求将匹配配置 D， - `/documents/1.jpg` 请求将匹配配置 E。 #### NOTE 如果前缀 `location` 以斜杠字符结尾且 [auto_redirect](#auto-redirect) 已启用,则会发生以下情况: 当请求到达时,其 URI 没有尾部斜杠 但在其他方面与前缀完全匹配,则会返回 代码为 301 的永久重定向,指向附加了斜杠的请求 URI。 对于精确 URI 匹配的 location,不会应用重定向: ```nginx location /user/ { proxy_pass http://user.example.com; } location =/user { proxy_pass http://login.example.com; } ``` `@` 前缀定义了一个 *命名* `location`。此类 location 不用于常规请求处理, 而是仅用于请求重定向。 它们不能嵌套,也不能包含嵌套 location。 #### 组合位置 多个定义相同配置块的 `location` 上下文可以通过在单个 `location` 中列出所有匹配表达式并使用单个配置块来压缩。这称为\*组合\* `location`。 假设前面示例中的配置 A、D 和 E 定义了相同的配置;您可以将它们组合成一个 `location`: ```nginx location =/ ^~/images/ ~*\.(gif|jpg|jpeg)$ { # 通用配置 } ``` 命名的 `location` 也可以是组合的一部分: ```nginx location =/ @named_combined { #... } ``` #### WARNING 组合 `location` 的匹配表达式修饰符和表达式本身之间不能有空格。 正确形式: `location ~*/match(ing|es|er)$ *...*`。 #### NOTE 目前,组合 `location` 不能\*\*直接\*\*包含设置了 URI 的 `proxy_pass` 指令,也不能包含 `api` 或 `alias`。 但是,这些指令可以在嵌套于组合位置内的位置中使用。 ### log_not_found | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_not_found` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `log_not_found on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用将未找到文件的错误记录到 [error_log](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log) 中。 ### log_subrequest | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_subrequest` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `log_subrequest off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用将子请求记录到 [access_log](https://cn.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) 中。 ### max_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_headers` number; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | `max_headers 1000;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置允许的客户端请求头字段的最大数量。 如果超过此限制,将返回 `400 (Bad Request)` 错误。 当此指令在 [server](#server) 级别设置时, 可能会应用默认服务器的值。 有关更多信息,请参阅 [虚拟服务器选择](https://cn.angie.software//angie/docs/configuration/processing.md#virtual-server-selection) 部分。 ### max_ranges | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_ranges` number; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制字节范围请求中允许的最大范围数量。超过限制的请求将被视为未指定字节范围。默认情况下,范围数量不受限制。 | `0` | 完全禁用字节范围支持 | |-------|--------------| ### merge_slashes | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `merge_slashes` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `merge_slashes on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用或禁用将 URI 中两个或多个相邻斜杠压缩为单个斜杠。 请注意,压缩对于正确匹配前缀字符串和正则表达式位置至关重要。如果没有压缩,:samp://scripts/one.php 请求将不会匹配 ```nginx location /scripts/ { } ``` 并且可能被作为静态文件处理。因此它会被转换为 `/scripts/one.php`。 如果 URI 包含 base64 编码的名称,则可能需要关闭压缩,因为 base64 在内部使用 "/" 字符。但是,出于安全考虑,最好避免关闭压缩。 如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。 ### msie_padding | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_padding` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `msie_padding on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用为状态大于 400 的 MSIE 客户端响应添加注释,以将响应大小增加到 512 字节。 ### msie_refresh | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_refresh` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `msie_refresh off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用为 MSIE 客户端发出刷新而不是重定向。 ### open_file_cache | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache` `off`;

`open_file_cache` `max=`N [`inactive=`time]; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | 默认值 | `open_file_cache off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 配置可以存储以下内容的缓存: * 打开的文件描述符、它们的大小和修改时间; * 目录存在性信息; * 文件查找错误,例如"文件未找到"、"无读取权限"等。 错误缓存应通过 [open_file_cache_errors](#open-file-cache-errors) 指令单独启用。 | `max` | 设置缓存中元素的最大数量;缓存溢出时,将删除最近最少使用 (LRU) 的元素 | |------------|--------------------------------------------------| | `inactive` | 定义一个时间,如果在此时间内未访问元素,则将其从缓存中删除;

默认为 60 秒 | | `off` | 禁用缓存 | 示例: ```nginx open_file_cache max=1000 inactive=20s; open_file_cache_valid 30s; open_file_cache_min_uses 2; open_file_cache_errors on; ``` ### open_file_cache_errors | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_errors` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `open_file_cache_errors off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用通过 [open_file_cache](#open-file-cache) 缓存文件查找错误。 ### open_file_cache_min_uses | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_min_uses` number; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `open_file_cache_min_uses 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置在 [open_file_cache](#open-file-cache) 指令的 `inactive` 参数配置的期间内,文件描述符在缓存中保持打开所需的最小文件访问次数。 ### open_file_cache_valid | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_valid` time; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `open_file_cache_valid 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置应验证 [open_file_cache](#open-file-cache) 元素的时间。 ### output_buffers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `output_buffers` number size; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `output_buffers 2 32k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置用于从磁盘读取响应的缓冲区数量和大小。 ### port_in_redirect | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `port_in_redirect` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `port_in_redirect on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在 Angie 发出的 [绝对](#absolute-redirect) 重定向中指定端口。 在重定向中使用主服务器名称由 [server_name_in_redirect](#server-name-in-redirect) 指令控制。 ### postpone_output | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `postpone_output` size; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | `postpone_output 1460;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果可能,客户端数据的传输将被推迟,直到 Angie 至少有指定数量的字节要发送。 | `0` | 禁用推迟数据传输 | |-------|------------| ### read_ahead | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `read_ahead` size; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | `read_ahead 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置在处理文件时内核的预读取量。 在 Linux 上,使用 `posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)` 系统调用,因此 size 参数会被忽略。 在 FreeBSD 上,使用 `fcntl(O_READAHEAD,` size ) 系统调用,该调用从 FreeBSD 9.0-CURRENT 开始支持。 ### recursive_error_pages | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `recursive_error_pages` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | `recursive_error_pages off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用使用 [error_page](#error-page) 指令进行多次重定向。此类重定向的次数是 [有限的](#internal)。 ### request_pool_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `request_pool_size` size; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `request_pool_size 4k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 允许精确调整每个请求的内存分配。此指令对性能的影响很小,通常不应使用。 ### reset_timedout_connection | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `reset_timedout_connection` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `reset_timedout_connection off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用重置超时连接和使用非标准代码 444 关闭的连接。重置按如下方式执行。在关闭套接字之前,为其设置 `SO_LINGER` 选项,超时值为 0。当套接字关闭时,TCP RST 被发送到客户端,并释放与此套接字关联的所有内存。这有助于避免长时间保持已关闭的套接字处于 FIN_WAIT1 状态且缓冲区已满。 #### NOTE keep-alive 连接在超时时会正常关闭。 ### resolver | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` address ... [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone]; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream | 配置用于将上游服务器名称解析为地址的名称服务器，例如： ```nginx resolver 127.0.0.53 [::1]:5353; ``` 地址可以指定为域名或 IP 地址，并可选端口。如果未指定端口，则使用端口 53。名称服务器以轮询方式查询。 #### NOTE 建议使用本地可信解析器，例如 `127.0.0.53` (systemd-resolved)，而非 公共解析器（如 `8.8.8.8`）。公共解析器会将 DNS 查询暴露给第三方， 并增加缓存投毒攻击的风险。 #### NOTE 该指令值会被嵌套块继承， 并可在其中根据需要覆盖。 在单个块内，该指令只能指定一次。 如果重复指定，则最后的定义生效。 默认情况下，Angie 使用响应的 TTL 值缓存答案。如果未指定 `resolver` 指令且不执行动态 DNS 查询（例如，在 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 中使用固定名称而不使用变量时），则不需要指定解析器：名称将在启动时使用系统解析器进行解析。可选的 `valid` 参数允许覆盖此行为： | `valid` | *可选* 参数允许覆盖响应缓存的有效期 | |-----------|------------------------| ```nginx resolver 127.0.0.53 [::1]:5353 valid=30s; ``` 默认情况下，Angie 在解析时会同时查找 IPv4 和 IPv6 地址。 | `ipv4=off` | 禁用查找 IPv4 地址 | |--------------|----------------| | `ipv6=off` | 禁用查找 IPv6 地址 | | `status_zone` | *可选* 参数;
启用在指定区域中收集 DNS 服务器请求和响应指标
([/status/resolvers/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers)) | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### resolver_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` time; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `resolver_timeout 30s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream | 设置名称解析的超时时间,例如: ```nginx resolver_timeout 5s; ``` ### error_log_user_tag | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log_user_tag` value; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | 向错误日志记录添加特定于请求的标签。value 是一个 [复杂值](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax), 可以使用变量。该指令可以多次指定以添加多个标签。 标签可以在 [error_log](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log) 中使用 `filter=tag:` 进行匹配。 ### root | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `root` path; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `root html;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 设置请求的根目录。例如,使用以下配置 ```nginx location /i/ { root /data/w3; } ``` 将发送 `/data/w3/i/top.gif` 文件来响应 `/i/top.gif` 请求。 path 值可以包含变量,但 [$document_root](#v-document-root) 和 [$realpath_root](#v-realpath-root) 除外。 文件路径的构造仅仅是将 URI 添加到 root 指令的值。如果需要修改 URI,应使用 [alias](#alias) 指令。 ### satisfy | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `satisfy` `all` | `any`; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `satisfy all;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果所有 (`all`) 或至少一个 (`any`) [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access)、[Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 或 [Auth Request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 模块允许访问,则允许访问。 ```nginx location / { satisfy any; allow 192.168.1.0/32; deny all; auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } ``` ### send_lowat | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_lowat` size; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | `send_lowat 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果该指令设置为非零值,Angie 将尝试通过使用 [kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 方法的 `NOTE_LOWAT` 标志或 `SO_SNDLOWAT` 套接字选项来最小化客户端套接字上的发送操作次数。在这两种情况下都使用指定的大小。 ### send_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_timeout` time; | |--------------------------------------------------------------------------------------|------------------------| | 默认值 | `send_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置向客户端传输响应的超时时间。超时仅在两次连续的写操作之间设置,而不是用于整个响应的传输。如果客户端在此时间内没有收到任何内容,连接将被关闭。 ### sendfile | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `sendfile off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 启用或禁用 `sendfile()` 的使用。 [aio](#aio) 可用于为 `sendfile()` 预加载数据: ```nginx location /video/ { sendfile on; tcp_nopush on; aio on; } ``` 在此配置中,:samp:sendfile() 使用 `SF_NODISKIO` 标志调用,这使其不会在磁盘 I/O 上阻塞,而是报告数据不在内存中。然后 Angie 通过读取一个字节来启动异步数据加载。在第一次读取时,FreeBSD 内核将文件的前 128K 字节加载到内存中,但后续读取将仅以 16K 块加载数据。这可以使用 [read_ahead](#read-ahead) 指令更改。 ### sendfile_max_chunk | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile_max_chunk` size; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `sendfile_max_chunk 2m;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制单次 `sendfile()` 调用中可以传输的数据量。如果没有限制,一个快速连接可能会完全占用工作进程。 ### server | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } | |--------------------------------------------------------------------------------------|--------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置虚拟服务器的配置。基于 IP(基于 IP 地址)和基于名称(基于 "Host" 请求头字段)的虚拟服务器之间没有明确的分隔。相反,:ref:listen 指令描述应该接受服务器连接的所有地址和端口,:ref:server_name 指令列出所有服务器名称。 [Angie 如何处理请求](https://cn.angie.software//angie/docs/configuration/processing.md#request-processing) 文档中提供了配置示例。 ### server_name | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` name ...; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | `server_name ""`; | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 设置虚拟服务器的名称,例如: ```nginx server { server_name example.com www.example.com; } ``` 第一个名称成为主服务器名称。 服务器名称可以包含星号("\*")来替换名称的第一部分或最后部分: ```nginx server { server_name example.com *.example.com www.example.*; } ``` 这样的名称称为通配符名称。 上述提到的前两个名称可以合并为一个: ```nginx server { server_name .example.com; } ``` 也可以在服务器名称中使用正则表达式,在名称前加上波浪号("~"): ```nginx server { server_name ~^www\d+\.example\.com$ www.example.com; } ``` 正则表达式可以包含捕获,这些捕获可以在其他指令中使用: ```nginx server { server_name ~^(www\.)?(.+)$; location / { root /sites/$2; } } server { server_name _; location / { root /sites/default; } } ``` 正则表达式中的命名捕获会创建变量,这些变量可以在其他指令中使用: ```nginx server { server_name ~^(www\.)?(?.+)$; location / { root /sites/$domain; } } server { server_name _; location / { root /sites/default; } } ``` #### NOTE 如果指令的参数设置为 [$hostname](#v-hostname), 则使用机器名称。 也可以指定空服务器名称: ```nginx server { server_name www.example.com ""; } ``` 按名称搜索虚拟服务器时, 如果名称匹配多个指定的变体 (例如,通配符名称和正则表达式都匹配), 将按以下优先级顺序选择第一个匹配的变体: - 精确名称; - 以星号开头的最长通配符名称,例如 `*.example.com`; - 以星号结尾的最长通配符名称,例如 `mail.*`; - 第一个匹配的正则表达式(按配置文件中出现的顺序), 包括空名称。 #### WARNING 要在 TLS 中使用 `server_name`, 需要 TLS 连接终止。 此指令匹配 HTTP 请求中的 `Host`, 因此必须完成握手并解密连接。 ### server_name_in_redirect | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name_in_redirect` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | `server_name_in_redirect off`; | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在 Angie 发出的 [绝对](#absolute-redirect) 重定向中使用由 [server_name](#server-name) 指令指定的主服务器名称。 | `on` | 使用由 [server_name](#server-name) 指令设置的主服务器名称 | |--------|-----------------------------------------------| | `off` | 使用 "Host" 请求头字段中的名称。如果此字段不存在,则使用服务器的 IP 地址。 | 重定向中端口的使用由 [port_in_redirect](#port-in-redirect) 指令控制。 ### server_names_hash_bucket_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_bucket_size` size; | |--------------------------------------------------------------------------------------|----------------------------------------------------| | 默认值 | `server_names_hash_bucket_size 32` | `64` | `128;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置服务器名称哈希表的桶大小。默认值取决于处理器缓存行的大小。有关设置哈希表的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。 ### server_names_hash_max_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_max_size` size; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `server_names_hash_max_size 512`; | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置服务器名称哈希表的最大大小。有关设置哈希表的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。 ### server_tokens | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_tokens` `on` | `off` | `build` | string; | |--------------------------------------------------------------------------------------|----------------------------------------------------| | 默认值 | `server_tokens on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在错误页面和 `Server` 响应头字段中显示 Angie 版本。 `build` 参数启用显示构建名称, 该名称由相应的 [configure](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 参数设置, 与版本一起显示。 在 Angie PRO 中,如果指令设置了一个 string,该字符串也可以包含变量, 错误页面和 `Server` 响应头字段 将使用该字符串的变量插值后的值 来代替服务器名称、版本和构建名称。 空 string 将禁用 `Server` 字段的显示。 ### status_zone | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `status_zone` `off` | zone | key `zone=`zone[:number]; | |--------------------------------------------------------------------------------------|----------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if in location | 分配一个共享内存区域用于收集 [/status/http/location_zones/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones) 和 [/status/http/server_zones/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones) 指标。 多个 `server` 上下文 可以共享同一个区域进行数据收集; 特殊值 `off` 在嵌套的 `location` 块中禁用数据收集。 使用单个 zone 值的语法 将当前上下文的所有指标合并到一个共享内存区域中: ```nginx server { listen 80; server_name *.example.com; status_zone single; # ... } ``` 替代语法允许设置以下参数: | key | 包含变量的字符串,其值决定区域中请求的分组。
所有在替换后产生相同值的请求
被分组在一起。如果替换产生空值,
则不更新指标。 | |-------------|------------------------------------------------------------------------------| | zone | 共享内存区域的名称。 | | number (可选) | 用于收集指标的独立组的最大数量。
如果新的 key 值超过此限制,它们将被分组到 `zone` 下。

默认值为 1。 | 在以下示例中, 所有共享相同 `$host` 值的请求 被分组到 `host_zone` 中。 为每个唯一的 `$host` 单独跟踪指标, 直到有 10 个指标组。 一旦达到此限制, 任何额外的 `$host` 值都将包含在 `host_zone` 下: ```nginx server { listen 80; server_name *.example.com; status_zone $host zone=host_zone:10; location / { proxy_pass http://example.com; } } ``` 因此,生成的指标在 API 输出中按各个主机分割。 ### subrequest_output_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `subrequest_output_buffer_size` size; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | `subrequest_output_buffer_size 4k` | `8k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置用于存储子请求响应体的缓冲区大小。 默认情况下,缓冲区大小等于一个内存页。这是 `4K` 或 `8K`,取决于平台。它可以设置得更小。 #### NOTE 该指令仅适用于响应体保存在内存中的子请求。例如,这样的子请求由 [SSI](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssi.md#ssi-include-set) 创建。 ### tcp_nodelay | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nodelay` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `tcp_nodelay on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用 `TCP_NODELAY` 选项的使用。当连接转换到保持活动状态时启用该选项。此外,它在 SSL 连接、无缓冲代理和 [WebSocket 代理](https://cn.angie.software//angie/docs/configuration/processing.md#websocket-proxy) 中也被启用。 ### tcp_nopush | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nopush` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `tcp_nopush off`; | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在 FreeBSD 上使用 `TCP_NOPUSH` 套接字选项或在 Linux 上使用 `TCP_CORK` 套接字选项。这些选项仅在使用 [sendfile](#sendfile) 时启用。启用该选项允许 * 在 Linux 和 FreeBSD 4.\* 上,在一个数据包中发送响应头和文件的开头; * 以完整数据包发送文件。 ### try_files | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `try_files` file ... uri;

`try_files` file ... =code; | |--------------------------------------------------------------------------------------|------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location | 按指定顺序检查文件是否存在,并使用第一个找到的文件进行请求处理;处理在当前 location 的上下文中执行。文件的路径根据 file 参数按照 [root](#root) 和 [alias](#alias) 指令构造。可以通过在名称末尾指定斜杠来检查目录是否存在,例如 `$uri/`。如果没有找到任何文件,则进行内部重定向到最后一个参数中指定的 uri。 例如: ```nginx location /images/ { try_files $uri /images/default.gif; } location = /images/default.gif { expires 30s; } ``` 最后一个参数可以是用于内部重定向的 URI、 对命名 location 的引用(例如 `@drupal`)、 或以 `=code` 形式的响应码(例如 `=404`): ```nginx location / { try_files $uri $uri/index.html $uri.html =404; } ``` 应该注意的是,过度使用 `try_files` 指令 会增加系统调用的数量, 这可能会对性能产生负面影响。 因此,:samp:try_files 不应该用于复制 实际上是默认行为的行为,例如: ```nginx location /bad_pattern { # try_files $uri $uri/ =404; # 不推荐! } ``` 此外,:samp:try_files 不应该 仅用于在文件不存在时进行重定向。 原因是 `try_files` 指令有两个特点: - 首先,它检查每个文件是否存在, 这会增加系统负载。 - 其次,任何文件打开错误(例如 `打开文件过多`、 权限错误)也被视为文件不存在并触发回退 到备用处理程序,这可能会用成功响应掩盖 5xx 错误 并导致错误的缓存。 因此,在实践中,可能会遇到以下有问题的结构: ```nginx location / { try_files $uri $uri/ @drupal; # 不推荐! } ``` 这里的问题是唯一的目的是重定向。 使用 `try_files` 会导致上述缺点, 但没有任何好处, 因为不需要检查文件是否存在。 正确的解决方案是使用 [error_page](#error-page) 指令, 它没有这些缺点: ```nginx error_page 404 = @drupal; log_not_found off; ``` 相比之下,在以下示例中: ```nginx location ~ \.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; # ... } ``` `try_files` 指令在将请求传递给同一块中配置的 FastCGI 服务器之前 检查 PHP 文件是否存在; 这里使用 `try_files` 是合理的。 ### 代理到 Mongrel 时的使用示例: ```nginx location / { try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel; } location @mongrel { proxy_pass http://mongrel; } ``` ### 与 Drupal/FastCGI 一起使用的示例: ```nginx location / { error_page 404 = @drupal; } location ~ \.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; fastcgi_param SCRIPT_NAME $fastcgi_script_name; fastcgi_param QUERY_STRING $args; # ... 其他 fastcgi_param } location @drupal { fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to/index.php; fastcgi_param SCRIPT_NAME /index.php; fastcgi_param QUERY_STRING q=$uri&$args; # ... 其他 fastcgi_param } ``` ### 与 Wordpress 和 Joomla 一起使用的示例: ```nginx location / { error_page 404 = @wordpress; } location ~ \.php$ { try_files $uri @wordpress; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; # ... 其他 fastcgi_param } location @wordpress { fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to/index.php; # ... 其他 fastcgi_param } ``` ### types | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types` { ... } | |--------------------------------------------------------------------------------------|------------------------------------------------------------| | 默认值 | `types *text/html html; image/gif gif; image/jpeg jpg;* ` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 将文件扩展名映射到响应的 MIME 类型。扩展名不区分大小写。多个扩展名可以映射到一个类型,例如: ```nginx types { application/octet-stream bin exe dll; application/octet-stream deb; application/octet-stream dmg; } ``` Angie 随附了一个足够完整的映射表,位于 `conf/mime.types` 文件中。 要使特定的 location 对所有响应返回 "application/octet-stream" MIME 类型,可以使用以下配置: ```nginx location /download/ { types { } default_type application/octet-stream; } ``` ### types_hash_bucket_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_bucket_size` size; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `types_hash_bucket_size 64;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置类型哈希表的桶大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。 ### types_hash_max_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_max_size` size; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `types_hash_max_size 1024;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置类型哈希表的最大大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。 ### underscores_in_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `underscores_in_headers` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `underscores_in_headers off`; | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 启用或禁用在客户端请求头字段中使用下划线。当禁用下划线的使用时,名称包含下划线的请求头字段将被标记为无效,并受 [ignore_invalid_headers](#ignore-invalid-headers) 指令的约束。 如果该指令在 [server](#server) 级别指定,则可以使用默认服务器的值。 ### variables_hash_bucket_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_bucket_size` size; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `variables_hash_bucket_size 64;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置变量哈希表的桶大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。 ### variables_hash_max_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_max_size` size; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `variables_hash_max_size 2048;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置变量哈希表的最大大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。 ## 内置变量 `http_core` 模块支持与 Apache Server 变量名称匹配的内置变量。首先,这些是表示客户端请求头字段的变量,例如 `$http_user_agent`、`$http_cookie` 等。此外,还有其他变量: ### `$angie_version` Angie 版本 ### `$arg_` 请求行中的参数 name ### `$args` 请求行中的参数 ### `$binary_remote_addr` 二进制形式的客户端地址,对于 IPv4 地址,值的长度始终为 4 字节,对于 IPv6 地址则为 16 字节 ### `$body_bytes_sent` 发送给客户端的字节数,不包括响应头;此变量与 `mod_log_config` Apache 模块的 "%B" 参数兼容 ### `$bytes_sent` 发送给客户端的字节数 ### `$connection` 连接序列号 ### `$connection_requests` 通过一个连接发出的当前请求数 ### `$connection_time` 连接时间(以秒为单位),具有毫秒分辨率 ### `$content_length` `Content-Length` 请求头字段 ### `$content_type` `Content-Type` 请求头字段 ### `$cookie_` 具有指定 name 的 cookie ### `$document_root` 当前请求的 [root](#root) 或 [alias](#alias) 指令的值 ### `$document_uri` 与 [$uri](#v-uri) 相同 ### `$host` 按以下优先顺序:请求行中的主机名,或 "Host" 请求头字段中的主机名,或与请求匹配的服务器名称 ### `$hostname` 主机名 ### `$http_` 任意请求头字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称 ### `$https` 如果连接在 SSL 模式下运行,则为 `on`,否则为空字符串 ### `$is_args` 如果请求行有参数,则为 `?`,否则为空字符串 ### `$is_request_port` 如果 [$request_port](#v-request-port) 值非空,则为 `:`,否则为空字符串 ### `$limit_rate` 设置此变量可启用响应速率限制;参见 [limit_rate](#limit-rate) ### `$msec` 当前时间(以秒为单位),具有毫秒分辨率 ### `$nginx_version` nginx 版本 ### `$pid` 工作进程的 PID ### `$pipe` 如果请求是流水线式的,则为 `p`,否则为 `.` ### `$proxy_protocol_addr` 来自 PROXY 协议头的客户端地址 必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 ### `$proxy_protocol_port` 来自 PROXY 协议头的客户端端口 必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 ### `$proxy_protocol_server_addr` 来自 PROXY 协议头的服务器地址 必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 ### `$proxy_protocol_server_port` 来自 PROXY 协议头的服务器端口 必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 ### `$proxy_protocol_tlv_` 来自 PROXY 协议头的 TLV。name 可以是 TLV 类型名称或其数值。在后一种情况下,该值为十六进制,应以 `0x` 为前缀: ```none $proxy_protocol_tlv_alpn $proxy_protocol_tlv_0x01 ``` SSL TLV 也可以通过 TLV 类型名称或其数值访问,两者都以 `ssl_` 为前缀: ```none $proxy_protocol_tlv_ssl_version $proxy_protocol_tlv_ssl_0x21 ``` 支持以下 TLV 类型名称: * `alpn (0x01)` - 连接上使用的上层协议 * `authority (0x02)` - 客户端传递的主机名值 * `unique_id (0x05)` - 唯一连接 ID * `netns (0x30)` - 命名空间的名称 * `ssl (0x20)` - 二进制 SSL TLV 结构 支持以下 SSL TLV 类型名称: * `ssl_version (0x21)` - 客户端连接中使用的 SSL 版本 * `ssl_cn (0x22)` - SSL 证书通用名称 * `ssl_cipher (0x23)` - 使用的密码名称 * `ssl_sig_alg (0x24)` - 用于签署证书的算法 * `ssl_key_alg (0x25)` - 公钥算法 此外,还支持以下特殊 SSL TLV 类型名称: * `ssl_verify` - 客户端 SSL 证书验证结果:如果客户端提供了证书并且验证成功,则为 `0`,否则为非零值 必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 ### `$query_string` 与 [$args](#v-args) 相同 ### `$realpath_root` 与当前请求的 [root](#root) 或 [alias](#alias) 指令的值对应的绝对路径名,所有符号链接都解析为实际路径 ### `$remote_addr` 客户端地址 ### `$remote_port` 客户端端口 ### `$remote_user` 通过基本身份验证提供的用户名 ### `$request` 完整的原始请求行 ### `$request_body` 请求体 当请求体被读取到 [内存缓冲区](#client-body-buffer-size) 时,该变量的值在由 [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)、[fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass)、[uwsgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) 和 [scgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) 指令处理的位置中\*可用\*。 ### `$request_body_file` 包含请求体的临时文件名 在处理结束时,需要删除该文件。要始终将请求体写入文件,请启用 [client_body_in_file_only](#client-body-in-file-only)。在代理请求或向 FastCGI/uwsgi/SCGI 服务器发送请求时传递临时文件名时,应分别使用 [proxy_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-body)、[fastcgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass-request-body)、[uwsgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass-request-body) 或 [scgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass-request-body) 指令禁用请求体本身的传递。 ### `$request_completion` 如果请求已完成,则为 `OK`,否则为空字符串 ### `$request_filename` 当前请求的文件路径,基于 [root](#root) 或 [alias](#alias) 指令以及请求 URI ### `$request_id` 从 16 个随机字节生成的唯一请求标识符,以十六进制表示 ### `$request_length` 请求长度(包括请求行、头和请求体) ### `$request_method` 请求方法,通常为 `GET` 或 `POST` ### `$request_port` 按以下优先顺序:请求 URI 的 authority 组件中的端口号,或 "Host" 请求头字段中的端口号 ### `$request_time` 请求处理时间(以秒为单位),具有毫秒分辨率;从客户端读取第一个字节以来经过的时间 ### `$request_uri` 完整的原始请求 URI（带参数），在请求处理过程中不会被修改；参阅 [$uri](#v-uri) 了解当前（可能已重写的）URI ### `$scheme` 请求方案,"http" 或 "https" ### `$sent_body` 子请求或外部请求的响应体(当其存储在内存中时);否则为空字符串 ### `$sent_http_` 任意响应头字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称 ### `$sent_trailer_` 在响应末尾发送的任意字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称 ### `$server_addr` 接受请求的服务器地址 计算此变量的值通常需要一次系统调用。为避免系统调用,:ref:listen 指令必须指定地址并使用 `bind` 参数。 ### `$server_name` 接受请求的服务器名称 ### `$server_port` 接受请求的服务器端口 ### `$server_protocol` 请求协议,通常为 "HTTP/1.0"、"HTTP/1.1" 或 "HTTP/2.0" ### `$status` 响应状态 ### `$time_iso8601` ISO 8601 标准格式的本地时间 ### `$time_local` 通用日志格式的本地时间 ### `$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space` 关于客户端 TCP 连接的信息;在支持 `TCP_INFO` 套接字选项的系统上可用 ### `$uri` 请求中的当前 URI,已 [规范化](#location) `$uri` 的值可能在请求处理过程中发生变化,例如在使用 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 进行重写时、执行内部重定向时,或在使用索引文件时。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_access.md # Access 该模块基于客户端 IP 地址或网络控制对服务器资源的访问。它允许对特定 IP 地址、IP 范围或 UNIX 域套接字允许或阻止访问,通过限制对网站或应用程序敏感区域的访问来增强安全性。 还可以通过使用 [Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 模块的密码或基于 [Auth Request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 模块的子请求结果来限制访问。要同时应用地址和密码限制,请使用 [satisfy](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 指令。 ## 配置示例 ```nginx location / { deny 192.168.1.1; allow 192.168.1.0/24; allow 10.1.1.0/16; allow 2001:0db8::/32; deny all; } ``` 规则按顺序评估,直到找到匹配项。在此示例中,仅允许 IPv4 网络 `10.1.1.0/16` 和 `192.168.1.0/24` (不包括特定地址 `192.168.1.1`)以及 IPv6 网络 `2001:0db8::/32` 访问。当有许多规则时,最好使用 [Geo](https://cn.angie.software//angie/docs/configuration/modules/http/http_geo.md#http-geo) 模块中的变量。 ## 指令 ### allow | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `allow` address | CIDR | `unix:` | `all`; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | 允许指定网络或地址的访问。 特殊值 `all` 表示所有客户端 IP 地址。 特殊值 `unix:` 允许任何 UNIX 域套接字的访问。 ### deny | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `deny` address | CIDR | `unix:` | `all`; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | 拒绝指定网络或地址的访问。 特殊值 `all` 表示所有客户端 IP 地址。 特殊值 `unix:` 拒绝任何 UNIX 域套接字的访问。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_acme.md # ACME 提供使用 [ACME 协议](https://datatracker.ietf.org/doc/html/rfc8555) 自动获取证书的功能。 在 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时,默认不会构建此模块; 需要使用 [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) `--with-http_acme_module` 启用它。 在来自 [我们的软件仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的包和镜像中, 该模块已包含在构建中。 ## 配置示例 有关配置示例和设置说明,请参阅 [ACME 配置](https://cn.angie.software//angie/docs/configuration/acme.md#acme-config) 部分。 ## 指令 ### acme | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` 名称; | |--------------------------------------------------------------------------------------|--------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server | 对于所有引用名为 名称 的 [ACME 客户端](#acme-client) 的 [server](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server) 块中的 [server_name](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-name) 指令指定的所有域名, 将获得单个证书; 如果 `server_name` 配置更改, 证书将更新以反映这些更改。 每次 Angie 启动时,都会为所有缺少有效证书的域名请求新证书。 可能的原因包括证书已过期、 文件丢失或不可读、 证书配置发生更改等。 #### NOTE 该指令仅控制证书请求中包含的域名, 并不影响证书可在何处使用。 任何 `server` 块都可以通过 [$acme_cert_](#v-acme-cert-name) 变量 引用该证书, 无论该块是否包含 `acme` 指令。 从 `server` 块中移除 `acme` 仅会将该块的 [server_name](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server-name) 值 排除在后续的证书请求之外, 但不会阻止该块使用证书。 #### NOTE 目前,不支持使用正则表达式指定的域名, 这些域名将被忽略。 通配符域名仅在 `acme_client` 中设置了 `challenge=dns` 时才受支持。 此指令可以多次指定以加载不同类型的证书,例如 RSA 和 ECDSA: ```nginx server { listen 443 ssl; server_name example.com www.example.com; ssl_certificate $acme_cert_rsa; ssl_certificate_key $acme_cert_key_rsa; ssl_certificate $acme_cert_ecdsa; ssl_certificate_key $acme_cert_key_ecdsa; acme rsa; acme ecdsa; } ``` ### acme_client | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client` 名称 uri [`enabled=``on` | `off`] [`key_type=`类型] [`key_bits=`数字] [`email=`email] [`max_cert_size=`数字] [`renew_before_expiry=`时间] [`renew_on_load`] [`retry_after_error=`off|时间] [`challenge=``dns` | `http` | `alpn`] [`account_key=`文件]; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 定义一个全局唯一的名为 名称 的 ACME 客户端。 该名称必须对目录有效, 是一个包含变量的字符串, 并且将被视为不区分大小写。 第二个必需参数是 ACME 目录的 uri。 例如,Let's Encrypt ACME 目录的 URI [列出](https://letsencrypt.org/getting-started/) 为 [https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory)。 #### NOTE ACME 模块会在 [client](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#client) 上下文中添加一个名为 `location @acme` 的位置, 可用于配置对 ACME 目录的请求; 默认情况下,此 `location` 包含一个带有目录 uri 的 [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) 指令, 可以向其添加来自 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块的其他设置。 为了使此指令生效, 必须在相同上下文中配置 [resolver](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver)。 #### NOTE 出于测试目的, 证书颁发机构通常提供单独的测试环境。 例如,\`Let's Encrypt 的测试环境 <[https://letsencrypt.org/docs/staging-environment/](https://letsencrypt.org/docs/staging-environment/)>\`_ 为 [https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory)。 | `enabled` | 启用或禁用客户端证书的更新;
例如,在不从配置中删除客户端的情况下临时暂停时,这很有用。

默认值:`on`。 | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `key_type` | 证书的私钥算法类型。
有效值:`rsa`,:samp:ecdsa。

默认值:`ecdsa`。 | | `key_bits` | 证书密钥的位数。
默认值:`ecdsa` 为 256,:samp:rsa 为 2048。 | | `email` | 用于反馈的可选电子邮件地址;
在 CA 服务器上创建账户时使用。 | | `max_cert_size` | 指定新证书文件的最大允许大小(以字节为单位),
以在共享内存中为新证书保留空间;
请求的域名越多,需要的空间越大。
此参数不限制 ACME 服务器响应的大小;
请使用 [acme_max_response_size](#acme-max-response-size) 来限制响应大小。

如果未设置该参数,Angie 会根据配置的域名列表计算大致大小,
并将其用于共享内存分配。

如果启动时已存在证书但其大小超过 `max_cert_size` 值,
则 `max_cert_size` 值会动态增加以匹配现有证书文件的大小。

如果更新过程中获得的证书大小超过 `max_cert_size`,
则更新过程将失败并报错。

默认值:自动计算。 | | `renew_before_expiry` | 证书到期前应开始更新的 [时间](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)。

默认值:`30d`。 | | `renew_on_load` | 指定在每次加载配置时强制更新证书。 | | `retry_after_error` | 在证书获取失败时重试前等待的 [时间](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)。
如果设置为 `off`,
客户端不会在失败后重试获取证书。

默认值:`2h`。 | | `challenge` | 指定 ACME 客户端的验证类型。
有效值:`dns`,:samp:http,:samp:alpn。

`alpn` 值启用 [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) 验证,需要
Angie 使用支持 ALPN 的 OpenSSL 构建
(不支持 BoringSSL 或 AWS-LC 构建)。

默认值:`http`。 | | `account_key` | 指定包含 PEM 格式密钥的文件的完整路径。
如果您想使用现有账户密钥而不是自动生成一个,
或者需要为多个 ACME 客户端使用同一个密钥,这很有用。

支持的密钥类型:

- RSA 密钥,长度为 8 的倍数,范围从 2048 到 8192 位。
- ECDSA 密钥,长度为 256、384 或 521 位。

指定 `account_key` 参数时,
应确保密钥文件确实存在。
如果文件不存在,
Angie 将尝试在指定路径创建它。

请注意,ACME 客户端的密钥是按照它们在配置中
通过 [acme_client](#acme-client)、[acme](#id4) 或 [acme_hook](#acme-hook) 指令提及的顺序创建的。
因此,如果一个客户端应该使用为另一个客户端创建的密钥,
那么另一个客户端必须在配置中更早出现。

此外,密钥仅为设置了 `enabled=on` 参数的客户端创建。 | ### acme_max_response_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` 大小; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `acme_max_response_size 32k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 限制 ACME 服务器响应正文的最大大小。如果响应超过此限制,请求将失败并报错。 如果您看到类似 `too big subrequest response while sending to client` 的错误,请增加该值。 ### acme_client_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` 路径; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 覆盖用于存储证书和密钥的目录的 路径, 该路径在构建时由 [构建参数](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) `--http-acme-client-path` 设置。 ### acme_dns_port | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` 端口 | ip[:端口] | [ip6][:端口]; | |--------------------------------------------------------------------------------------|----------------------------------------------| | 默认值 | `acme_dns_port 53;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 指定模块通过 UDP 处理来自 ACME 服务器的 DNS 查询所使用的端口。 端口号必须在 1 到 65535 之间。 也支持同时指定 IP 地址和可选端口。 可以使用 `ip:端口` 格式的 IPv4 地址 和 `[ip6]:端口` 格式的 IPv6 地址: ```nginx acme_dns_port 8053; acme_dns_port 127.0.0.1; acme_dns_port [::1]; ``` 要使用 1024 或更低的端口号, Angie 必须以 [超级用户](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 权限运行。 ### acme_http_port | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` 端口 | ip[:端口] | [ip6][:端口]; | |--------------------------------------------------------------------------------------|-----------------------------------------------| | 默认值 | `acme_http_port 80;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 指定模块用于处理 HTTP ACME 验证请求的端口。 端口号必须在 1 到 65535 之间。 也支持同时指定 IP 地址和可选端口。 可以使用 `ip:端口` 格式的 IPv4 地址 和 `[ip6]:端口` 格式的 IPv6 地址: ```nginx acme_http_port 8080; acme_http_port 127.0.0.1; acme_http_port [::1]; ``` 如果没有服务器配置为监听指定的地址和端口, 模块会为 HTTP 验证创建专用监听器。 要使用 1024 或更低的端口号, Angie 必须以 [超级用户](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 权限运行。 ### acme_hook | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` 名称 [uri]; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 为由 名称 指定的 [ACME 客户端](#acme-client) 启用基于钩子的域名验证。 当证书签发或续订需要进行域名验证时, Angie 会向放置该指令的命名 `location` 生成一个内部请求。 请求的处理方式完全取决于同一 `location` 中配置的其他指令, 例如 [fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass)、[proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), 或任何其他请求处理程序。 | 名称 | 由该钩子处理域名验证的
[ACME 客户端](#acme-client) 的名称。 | |------|-------------------------------------------------| | uri | 包含变量的字符串;
指定钩子调用的请求 URI。

默认值:`/`。 | 例如,以下配置将 [hook 变量](#http-acme-variables) 的值 通过请求 URI 传递给 FastCGI 应用程序: ```nginx acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth; fastcgi_param REQUEST_URI $request_uri; fastcgi_pass ...; ``` ## 内置变量 ### `$acme_cert_<名称>` 由此 名称 的客户端获得的最后一个证书文件(如果有)的内容。 ### `$acme_cert_key_<名称>` 此 名称 的客户端使用的证书密钥文件的内容。 #### NOTE 证书文件仅在 ACME 客户端获得至少一个证书后可用, 而密钥文件在启动后立即可用。 ### `$acme_hook_challenge` 验证类型。可能的值:`dns`,:samp:http,:samp:alpn。 ### `$acme_hook_client` 发起请求的 ACME 客户端的名称。 ### `$acme_hook_domain` 被验证的域名。 如果是通配符域名,将不带 `*.` 前缀传递。 ### `$acme_hook_keyauth` 授权字符串: - 在 DNS 验证中,用作 TXT 记录的值, 记录名称格式为 `_acme-challenge. + $acme_hook_domain + .`。 - 在 HTTP 验证中,此字符串应用作 ACME 服务器请求的响应内容。 ### `$acme_hook_name` 钩子名称。对于不同类型的验证,它可能有不同的值和含义: | 值 | DNS 验证中的含义 | HTTP 验证中的含义 | |-----------------|--------------------------|-----------------------------------------| | `add` (添加钩子) | 需要在 DNS 配置中添加相应的 TXT 记录。 | 需要准备对相应 HTTP 请求的响应。 | | `remove` (移除钩子) | 可以从 DNS 配置中删除 TXT 记录。 | 此 HTTP 请求不再相关;
可以删除先前创建的包含授权字符串的文件。 | ### `$acme_hook_token` 验证令牌。 在 HTTP 验证中,用作请求的文件名: `/.well-known/acme-challenge/` + `$acme_hook_token`。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_addition.md # Addition 该模块是一个过滤器，用于在响应之前和之后添加文本。 当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时， 该模块默认不被构建； 它需要通过 `--with-http_addition_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 来启用。 在来自 [我们的仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的包和镜像中， 该模块已包含在构建中。 ## 配置示例 ```nginx location / { add_before_body /before_action; add_after_body /after_action; } ``` ## 指令 ### add_before_body | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `add_before_body` uri; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在响应体之前添加处理给定子请求返回的文本。参数为空字符串 (`""`) 则取消继承自先前配置级别的添加。 ### add_after_body | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `add_after_body` uri; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在响应体之后添加处理给定子请求返回的文本。参数为空字符串 (`""`) 则取消继承自先前配置级别的添加。 ### addition_types | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `addition_types` mime-type ...; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `addition_types text/html;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许在具有指定 MIME 类型的响应中添加文本，除了 "text/html" 之外。特殊值 "\*" 匹配任何 MIME 类型。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_api.md # API `API` 模块实现了一个 HTTP RESTful 接口,用于以 JSON 格式获取 Web 服务器的基本信息,以及关于客户端连接、共享内存区域、DNS 查询、HTTP 请求、HTTP 响应缓存、[stream](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) 模块会话,以及 [limit_conn http](https://cn.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn)、[limit_conn stream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn)、[limit_req](https://cn.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) 和 [http upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream) 模块区域的 [统计信息](#metrics)。 该接口接受 `GET` 和 `HEAD` HTTP 方法; 使用其他方法的请求将导致错误: ```json { "error": "MethodNotAllowed", "description": "The POST method is not allowed for the requested API element \"/\"." } ``` 在 Angie PRO 中,此接口包含一个 [动态配置](#api-config) 部分,允许在不重新加载配置或重启的情况下更改设置;目前,可以配置 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 中的各个服务器。 ## 指令 ### api | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `api` path; | |--------------------------------------------------------------------------------------|---------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 在 `location` 中启用 HTTP RESTful 接口。 path 参数是必需的。与 [alias](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#alias) 指令类似,它设置用于替换 `location` 中指定路径的路径,但是是在 API 树上而不是文件系统上。 如果在前缀 `location` 中指定: ```nginx 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 中使用: ```nginx location ~^/api/([^/]+)/(.*)$ { api /status/http/$1_zones/$2; } ``` 这里 path 参数定义了 API 元素的完整路径; 因此,从对 `/api/location/data/` 的请求中将提取以下变量: ```console $1 = "location" $2 = "data/" ``` 最终请求将是 `/status/http/location_zones/data/`。 #### NOTE 在 Angie PRO 中,您可以分离 [动态配置 API](#api-config) 和反映当前状态的不可变 [状态 API](#metrics): ```nginx location /config/ { api /config/; } location /status/ { api /status/; } ``` path 参数还允许控制 API 访问: ```nginx location /status/ { api /status/; allow 127.0.0.1; deny all; } ``` 或者: ```nginx location /blog/requests/ { api /status/http/server_zones/blog/requests/; auth_basic "blog"; auth_basic_user_file conf/htpasswd; } ``` #### NOTE 如果 `api` 放置在前缀带有尾部斜杠的 `location` 中(例如,:samp:location /name/),并且 [auto_redirect](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) 指令设置为 `default`,则不带尾部斜杠的请求将被重定向(`/name -> /name/`)。 ### api_config_files | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `api_config_files` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | off | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location | 启用或禁用向 [/status/angie/](#status-angie) API 部分添加 `config_files` 对象,该对象列出服务器实例当前加载的所有 Angie 配置文件的内容。例如,使用此配置: ```nginx location /status/ { api /status/; api_config_files on; } ``` 对 `/status/angie/` 的请求返回大致如下内容: ```json { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12:58:39.789Z", "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` 默认情况下,输出被禁用,因为配置文件可能包含特别敏感的机密信息。 ## 指标 Angie 在 `/status/` API 部分发布使用统计信息;您可以通过设置适当的 `location` 来开放访问权限。完全访问: ```nginx location /status/ { api /status/; } ``` 部分访问的示例,如上所示: ```nginx location /stats/ { api /status/http/server_zones/; } ``` ### 配置示例 配置包含 `location /status/`、`resolver`、`upstream` 中的 `http`、`http server`、`location`、`cache`、`http` 中的 `limit_conn` 和 `limit_req` 区域： ```nginx 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 树 ```json { "angie": { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12: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":"" } }, "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 分支请求一组指标。例如： ```console $ 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//slots $ curl https://www.example.com/status/slabs//slots/64 $ curl https://www.example.com/status/http/ $ curl https://www.example.com/status/http/acme_clients $ curl https://www.example.com/status/http/acme_clients/ $ curl https://www.example.com/status/http/metric_zones $ curl https://www.example.com/status/http/metric_zones//metrics $ curl https://www.example.com/status/http/server_zones $ curl https://www.example.com/status/http/server_zones/ $ curl https://www.example.com/status/http/server_zones//ssl ``` #### NOTE 默认情况下，该模块使用 ISO 8601 格式字符串表示日期； 如需改用整数 UNIX 纪元格式， 请在查询字符串中添加 `date=epoch` 参数： ```console $ 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` ```json { "version": "|version|", "build_time": "|sampledateshort|T16:05:43.805Z", "address": "192.168.16.5", "generation": 1, "load_time": "|sampledateshort|T16:15:43.805Z" "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` | `version` | 字符串；正在运行的 Angie Web 服务器的版本 | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `build` | 字符串；编译期间指定的特定构建名称 | | `build_time` | 字符串；Angie 可执行文件的构建时间，
采用 [日期](#api-date-format) 格式 | | `address` | 字符串；接受 API 请求的服务器地址 | | `generation` | 数字；自上次启动以来配置重新加载的总次数 | | `load_time` | 字符串；上次配置重新加载的时间，
采用 [日期](#api-date-format) 格式；
字符串值具有毫秒精度 | | `config_files` | 对象；其成员是服务器实例当前加载的所有 Angie 配置文件的绝对路径名，
其值是文件内容的字符串表示，
例如：

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

#### WARNING
`config_files` 对象仅在启用
[api_config_files](#a-api-config-files)
指令时才在 `/status/angie/` 中可用。 | #### `/status/angie/license` (PRO) ```json { "path": "/etc/angie/license.pem", "status": "valid", "owner": "Example Corp", "days_left": 30, "since": "2024-01-01", "until": "2025-01-01", "limits": { "worker_processes": 16, "worker_connections": 65535 } } ``` | `path` | 字符串；许可证文件的完整路径 | |-------------|--------------------------------------------------------------------------| | `status` | 字符串；许可证状态：`missing`、`invalid`、`valid`、
`grace`、`expired` 或 `pending` | | `owner` | 字符串；来自证书主题的许可证所有者 | | `days_left` | 数字；许可证状态变更前的剩余天数。负值表示
许可证已过期，该值为过期后的天数 | | `since` | 字符串；许可证有效期开始日期 | | `until` | 字符串；许可证有效期结束日期 | | `limits` | 对象；当前实例的许可限制 | ### 连接 #### `/status/connections` ```json { "accepted": 2257, "dropped": 0, "active": 3, "idle": 1 } ``` | `accepted` | 数字；已接受的客户端连接总数 | |--------------|------------------| | `dropped` | 数字；已丢弃的客户端连接总数 | | `active` | 数字；当前活动的客户端连接数 | | `idle` | 数字；当前空闲的客户端连接数 | ### 使用 slab 分配的共享内存区 #### `/status/slabs/` 使用 [slab 分配](https://en.wikipedia.org/wiki/Slab_allocation) 的共享内存区的使用统计信息，例如 [limit_conn](#limit-conn)、[limit_req](#limit-req) 和 [HTTP 缓存](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache)： ```nginx 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` | 数字；分配指定大小内存失败的次数 | 示例： ```json { "pages": { "used": 2, "free": 506 }, "slots": { "64": { "used": 1, "free": 63, "reqs": 1, "fails": 0 } } ``` ### 解析器的 DNS 查询 #### `/status/resolvers/` 要收集解析器统计信息， [resolver](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver) 指令必须设置 `status_zone` 参数 （[HTTP](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) 或 [Stream](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver-status)）： ```nginx 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 类型查询的数量 | #### NOTE `queries` 和 `responses` 统计 Angie 在内部发出的每个解析请求， 包括从 TTL 缓存中响应的请求。`sent` 统计实际发送到名称服务器的 数据包；两者之间的差值反映了缓存命中数。 响应代码在 [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html) 的 [4.1.1](https://datatracker.ietf.org/doc/html/rfc1035.html#section-4.1.1) 节中描述。 各种 DNS 记录类型在 [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html)、 [RFC 2782](https://datatracker.ietf.org/doc/html/rfc2782.html) 和 [RFC 3596](https://datatracker.ietf.org/doc/html/rfc3596.html) 中详细说明。 示例： ```json { "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/` 要收集 `server` 指标， 在 [server](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#server) 上下文中设置 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 指令： ```nginx server { ... status_zone server_zone; } ``` 要按自定义值对指标进行分组，请使用替代语法。 此处，指标按 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 聚合， 每个组作为独立区域报告： ```nginx 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` | 对象；响应统计信息 | | `` | 数字；状态为 （100-599）的响应的非零数量 | | `xxx` | 数字；其他状态代码的响应的非零数量 | | `data` | 对象；数据统计信息 | | `received` | 数字；从客户端接收的总字节数 | | `sent` | 数字；发送到客户端的总字节数 | 示例： ```json { "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/` 要收集 `location` 指标，请在 [location](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#location) 或 [if in location](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if) 上下文中设置 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 指令： ```nginx location / { root /usr/share/angie/html; status_zone location_zone; if ($request_uri ~* "^/condition") { # ... status_zone if_location_zone; } } ``` 要按自定义值对指标进行分组，请使用替代语法。 在这里，指标按 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 聚合，每个组作为独立区域报告： ```nginx status_zone $host zone=server_zone:5; ``` 指定的共享内存区域将收集以下统计信息： | `requests` | 对象；请求统计信息 | |--------------|------------------------------| | `total` | 数字；客户端请求总数 | | `discarded` | 数字；未发送响应而完成的客户端请求总数 | | `responses` | 对象；响应统计信息 | | `` | 数字；状态为 （100-599）的非零响应数 | | `xxx` | 数字；其他状态代码的非零响应数 | | `data` | 对象；数据统计信息 | | `received` | 数字；从客户端接收的字节总数 | | `sent` | 数字；发送给客户端的字节总数 | 示例： ```json { "requests": { "total": 4158, "discarded": 0 }, "responses": { "200": 4157, "304": 1 }, "data": { "received": 538200, "sent": 177606236 } } ``` #### `/status/http/metric_zones/` 由 `http` 上下文中的 [metric_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) 或 [metric_complex_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) 定义的自定义指标。指标通过 [metric](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#id5) 指令或模块变量更新。 | `discarded` | 数字；因区域内存不足而丢弃的指标条目数。 | |---------------|------------------------------------------------------------------------| | `metrics` | 对象；按键的指标。对于单指标区域，值为数字。
对于复杂区域，值为带有指标名称的对象。对于直方图
模式，值为带有桶名称的对象。 | 如果设置了 `discard_key` 并且某些条目已过期， 它们的聚合指标将在此键下公开。 示例： ```json { "discarded": 3, "metrics": { "example.com": { "count": 42, "max": 8 } "expired": { "count": 10, "max": 3.2 } } } ``` ### Stream 服务器 #### `/status/stream/server_zones/` 要收集 `server` 指标， 请在 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) 上下文中设置 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) 指令： ```nginx server { ... status_zone server_zone; } ``` 要按自定义值对指标进行分组，请使用替代语法。 此处，指标按 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 聚合， 每个组作为独立区域报告： ```nginx 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` | 数字；发送到客户端的总字节数 | 示例： ```json { "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 缓存 ```nginx proxy_cache cache_zone; proxy_cache_valid 200 10m; ``` #### `/status/http/caches/` 对于使用 [proxy_cache](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) 配置的每个区域，存储以下数据： ```json { "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](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid)) | | `responses` | 数字；从缓存读取的响应总数 | | `bytes` | 数字；从缓存读取的总字节数 | | `stale` | 对象；从缓存获取的过期响应的统计信息 ([proxy_cache_use_stale](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale)) | | `responses` | 数字；从缓存读取的响应总数 | | `bytes` | 数字；从缓存读取的总字节数 | | `updating` | 对象；在响应更新期间从缓存获取的过期响应的统计信息 ([proxy_cache_use_stale](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating) | | `responses` | 数字；从缓存读取的响应总数 | | `bytes` | 数字；从缓存读取的总字节数 | | `revalidated` | 对象；从缓存获取的已过期并重新验证的响应的统计信息 ([proxy_cache_revalidate](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-revalidate)) | | `responses` | 数字；从缓存读取的响应总数 | | `bytes` | 数字；从缓存读取的总字节数 | | `miss` | 对象；在缓存中未找到的响应的统计信息 | | `responses` | 数字；相应响应的总数 | | `bytes` | 数字；从代理服务器读取的总字节数 | | `responses_written` | 数字；写入缓存的响应总数 | | `bytes_written` | 数字；写入缓存的总字节数 | | `expired` | 对象；未从缓存获取的已过期响应的统计信息 | | `responses` | 数字；相应响应的总数 | | `bytes` | 数字；从代理服务器读取的总字节数 | | `responses_written` | 数字；写入缓存的响应总数 | | `bytes_written` | 数字；写入缓存的总字节数 | | `bypass` | 对象；未在缓存中查找的响应的统计信息 ([proxy_cache_bypass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-bypass)) | | `responses` | 数字；相应响应的总数 | | `bytes` | 数字；从代理服务器读取的总字节数 | | `responses_written` | 数字；写入缓存的响应总数 | | `bytes_written` | 数字；写入缓存的总字节数 | 在 Angie PRO 中，如果使用 [proxy_cache_path](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) 指令启用了 cache sharding， 各个分片将作为 `shards` 对象的对象成员公开： | `shards` | 对象；将各个分片列为成员 | |------------|-------------------------------------| | `` | 对象；表示单个分片，其缓存路径作为名称 | | `size` | 数字；分片的当前大小 | | `max_size` | 数字；最大分片大小（如果已配置） | | `cold` | 布尔值；当 cache loader 从磁盘加载数据时为 `true` | ```json { "name_zone": { "shards": { "/path/to/shard1": { "size": 0, "cold": false }, "/path/to/shard2": { "size": 0, "cold": false } } } ``` ### ACME 客户端 #### `/status/http/acme_clients/` 对于 `http` 块中配置的每个 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client)，返回当前客户端和证书状态： ```json { "state": "ready", "certificate": "valid", "details": "The client is ready to request a certificate.", "next_run": "|sampledateshort|T16:15:43.805Z" } ``` | `state` | 字符串；ACME 客户端状态。可能的值：`ready`、
`requesting`、`disabled`、`failed`。 | |---------------|--------------------------------------------------------------------------| | `certificate` | 字符串；证书状态。可能的值：`valid`、
`expired`、`missing`、`mismatch`、`error`。 | | `details` | 字符串；上次 ACME 操作的简短状态详情。 | | `next_run` | 日期；下次计划请求或续订证书的尝试时间。
当 `state` 为 `disabled` 或
`requesting` 时不返回。 | ### limit_conn ```nginx limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; ``` #### `/status/http/limit_conns/`，`/status/stream/limit_conns/` 每个配置的 [http 中的 limit_conn](#limit-conn) 或 [stream 中的 limit_conn](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) 上下文的对象，包含以下字段： ```json { "passed": 73, "skipped": 0, "rejected": 0, "exhausted": 0 } ``` | `passed` | 数字；通过的连接总数 | |-------------|------------------------------| | `skipped` | 数字；使用零长度键或键超过 255 字节而通过的连接总数 | | `rejected` | 数字；超过配置限制的连接总数 | | `exhausted` | 数字；由于区域存储耗尽而拒绝的连接总数 | ### limit_req ```nginx limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; ``` #### `/status/http/limit_reqs/` 每个配置的 [limit_req](#limit-req) 的对象，包含以下字段： ```json { "passed": 54816, "skipped": 0, "delayed": 65, "rejected": 26, "exhausted": 0 } ``` | `passed` | 数字；通过的请求总数 | |-------------|------------------------------| | `skipped` | 数字；使用零长度键或键超过 255 字节而通过的请求总数 | | `delayed` | 数字；延迟的请求总数 | | `rejected` | 数字；拒绝的请求总数 | | `exhausted` | 数字；由于区域存储耗尽而拒绝的请求总数 | ### HTTP 上游 要启用以下指标的收集， 请在 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 上下文中设置 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令， 例如： ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/http/upstreams/` 其中 是使用 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令指定的任何 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 的名称 ```json { "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": "" } }, "keepalive": 2 } ``` | `peers` | 对象；包含上游节点的指标作为子对象，
子对象的名称是节点地址的规范表示。
每个子对象的成员： | |-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `server` | 字符串；[server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令的参数 | | `service` | 字符串；在 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令中指定的服务名称（如果已配置） | | `backup` | 布尔值；备份服务器为 `true` | | `weight` | 数字；配置的 [权重](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | | `state` | 字符串；节点的当前状态以及发送给它的请求：

- `busy`：表示发送到服务器的请求数量
已达到 [max_conns](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 设置的限制，
不再向其发送新请求；
- `down`：手动禁用，不发送请求；
- `recovering`：根据 [slow_start](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start) 从故障中恢复，
随着时间推移发送越来越多的请求；
- `unavailable`：达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) 限制，
仅在 [fail_timeout](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout) 定义的间隔内
发送试探性客户端请求；
- `up`：正常运行，正常发送请求；

Angie PRO 中的附加状态：

- `checking`：配置为 `essential` 并正在检查中，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)；
- `draining`：类似于 `down`，
但来自先前绑定会话的请求
（通过 [sticky](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)）仍会发送；
- `unhealthy`：不可操作，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)。 | | `selected` | 对象；节点选择统计信息 | | `current` | 数字；当前到节点的连接数 | | `total` | 数字；转发到节点的请求总数 | | `last` | 字符串或数字；节点最后被选择的时间，
格式为 [日期](#api-date-format) | | `max_conns` | 数字；配置的到节点的同时活动连接的 [最大](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 数量（如果指定） | | `responses` | 对象；响应统计信息 | | `` | 数字；状态码为 (100-599) 的响应的非零数量 | | `xxx` | 数字；其他状态码响应的非零数量 | | `data` | 对象；数据统计信息 | | `received` | 数字；从节点接收的字节总数 | | `sent` | 数字；发送到节点的字节总数 | | `health` | 对象；健康统计信息 | | `fails` | 数字；与节点通信失败的尝试总数 | | `unavailable` | 数字；由于达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) 限制而导致节点变为 `unavailable` 的次数 | | `downtime` | 数字；节点 `unavailable` 无法选择的总时间（以毫秒为单位） | | `downstart` | 字符串或数字；节点变为 `unavailable` 的时间，
格式为 [日期](#api-date-format) | | `header_time`
(PRO 1.3.0+) | 数字；从服务器接收响应头的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `response_time`
(PRO 1.3.0+) | 数字；从服务器接收完整响应的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `sid` | 字符串；上游组中服务器的 [配置 id](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) | | `keepalive` | 数字；当前缓存连接数 | | `backup_switch` | 对象；包含活动备份逻辑的当前状态，
如果为上游配置了 [backup_switch (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) 则存在 | | `active` | 数字；当前用于负载均衡请求的活动组级别。
如果活动组是主组，则值为 0 | | `timeout` | 数字；剩余等待时间（以毫秒为单位），
之后负载均衡器将重新检查较低级别组中的健康节点，
从主组开始，而不检查较高级别的组；
主组（级别 0）不显示 | ##### `health/probes` (PRO) #### Versionchanged 在 1.2.0 版本发生变更: PRO 如果上游配置了 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 探测， `health` 对象还有一个 `probes` 子对象 用于存储服务器的健康探测计数器， 而 `state` 除了上表中列出的值外， 还可以是 `checking` 和 `unhealthy`： ```json { "192.168.16.4:80": { "state": "unhealthy", "...": "...", "health": { "...": "...", "probes": { "count": 10, "fails": 10, "last": "|sampledateshort|T09:56:07Z" } } } } ``` `state` 的 `checking` 值不计入 `downtime`， 表示配置了 `essential` 探测的服务器尚未被检查； `unhealthy` 值表示服务器出现故障。 这两种状态都意味着服务器不包含在负载均衡中。 有关健康探测的详细信息，请参见 [upstream_probe](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)。 `probes` 中的计数器： | `count` | 数字；此服务器的探测总数 | |-----------|-----------------------------------------------| | `fails` | 数字；失败探测总数 | | `last` | 字符串或数字；最后探测时间，
格式为 [日期](#api-date-format) | ##### `queue` (PRO) #### Versionchanged 在 1.4.0 版本发生变更: PRO 如果为上游配置了 [请求队列](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue)， 上游对象还包含一个嵌套的 `queue` 对象， 其中包含请求队列计数器： ```json { "queue": { "queued": 20112, "waiting": 1011, "dropped": 6031, "timedout": 560, "overflows": 13 } } ``` 计数器值在所有工作进程中求和： | `queued` | 数字；进入队列的请求总数 | |-------------|---------------------------| | `waiting` | 数字；队列中当前的请求数 | | `dropped` | 数字；因客户端过早关闭连接而从队列中移除的请求总数 | | `timedout` | 数字；因超时而从队列中移除的请求总数 | | `overflows` | 数字；队列溢出发生的总次数 | ### Stream 上游 要启用以下指标的收集， 请在 [upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 上下文中设置 [zone](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) 指令， 例如： ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/stream/upstreams/` 其中 是使用 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令配置的 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 的名称。 ```json { "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](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 指令设置的地址 | | `service` | 字符串；在 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 指令中指定的服务名称（如果已配置） | | `backup` | 布尔值；备份服务器为 `true` | | `weight` | 数字；为对等节点设置的 [权重](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `state` | 字符串；对等节点的当前状态以及发送给它的请求：

- `busy`：表示发送到服务器的请求数
已达到 [max_conns](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 设置的限制，
不再向其发送新请求
- `down`：手动禁用，不发送请求
- `recovering`：根据 [slow_start](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) 从故障中恢复，
随着时间推移发送越来越多的请求
- `unavailable`：达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) 限制，
仅以 [fail_timeout](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout) 定义的间隔发送试探性客户端请求
- `up`：正常运行，照常发送请求

Angie PRO 中的附加状态：

- `checking`：配置为 `essential` 并正在检查中，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
- `draining`：类似于 `down`，
但来自先前绑定会话的请求
（通过 [sticky](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)）仍会发送
- `unhealthy`：不可用，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) | | `selected` | 对象；选择此对等节点进行连接的统计信息 | | `current` | 数字；当前到对等节点的连接数 | | `total` | 数字；转发到对等节点的连接总数 | | `last` | 字符串或数字；上次选择对等节点的时间，
格式为 [日期](#api-date-format) | | `max_conns` | 数字；到对等节点的同时活动连接的 [最大](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 数量（如果已设置） | | `data` | 对象；数据传输统计信息 | | `received` | 数字；从对等节点接收的总字节数 | | `sent` | 数字；发送到对等节点的总字节数 | | `health` | 对象；对等节点健康统计信息 | | `fails` | 数字；尝试到达对等节点失败的总次数 | | `unavailable` | 数字；由于达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) 值，对等节点变为 `unavailable` 的总次数 | | `downtime` | 数字；对等节点处于 `unavailable` 状态（无法被选择）的总时间（以毫秒为单位） | | `downstart` | 字符串或数字；对等节点上次变为 `unavailable` 的时间，
格式为 [日期](#api-date-format) | | `connect_time` | 数字；与服务器建立连接的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 | | `first_byte_time` | 数字；从服务器接收第一个字节的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 | | `last_byte_time` | 数字；从服务器接收完整响应的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 | | `backup_switch`
(PRO 1.10.0+) | 对象；包含活动备份逻辑的当前状态，
如果为上游配置了 [backup_switch (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) 则显示 | | `active` | 数字；当前用于负载均衡的活动组的级别。
如果活动组是主组，则值为 0 | | `timeout` | 数字；剩余等待时间（以毫秒为单位），
之后负载均衡器将重新检查较低级别组中的健康节点，
从主组开始，
而不检查较高级别的组；
主组（级别 0）不显示 | #### Versionchanged 在 1.4.0 版本发生变更: PRO 在 Angie PRO 中，如果上游配置了 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) 探测， `health` 对象还包含一个 `probes` 子对象， 用于存储服务器的健康探测计数器， 而 `state` 除了上表中列出的值外， 还可以是 `checking` 和 `unhealthy`： ```json { "192.168.16.4:80": { "state": "unhealthy", "...": "...", "health": { "...": "...", "probes": { "count": 2, "fails": 2, "last": "|sampledateshort|T11:03:54Z" } } } } ``` `state` 的 `checking` 值表示配置了 `essential` 参数探测的服务器尚未被检查； `unhealthy` 值表示服务器不可用。 这两种状态还意味着服务器不包含在负载均衡中。 有关健康探测的详细信息，请参见 [upstream_probe](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)。 `probes` 中的计数器： | `count` | 数字；此服务器的探测总数 | |-----------|------------------------------------------------| | `fails` | 数字；失败的探测数 | | `last` | 字符串或数字；上次探测的时间，
格式为 [日期](#api-date-format) | ## 动态配置 API (PRO) 该 API 包含一个 `/config` 节，可通过 `PUT`、`PATCH` 和 `DELETE` HTTP 请求 以 JSON 格式动态更新 Angie 的配置。 所有更新都是原子性的：新设置作为一个整体应用， 或者完全不应用。 出错时，Angie 会报告原因。 ### `/config` 的子节 目前，`/config` 节中可用于 [HTTP](#api-config-http-upstreams-servers) 和 [stream](#api-config-stream-upstreams-servers) 模块的上游内各个服务器的配置； 可进行动态配置的设置数量正在稳步增加。 #### `/config/http/upstreams//servers/` 允许配置单个上游对等节点， 包括删除现有对等节点或添加新对等节点。 URI 路径参数： | `` | 上游的名称；要通过 `/config` 进行配置，必须配置
[zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令，定义一个共享内存区域。 | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `` | 上游中对等节点的名称，定义为
`@`，其中：

- `@` 是可选的服务名称，用于
SRV 记录解析。
- `` 是服务的域名（如果存在 `resolve`）
或其 IP 地址；可以在此定义可选的端口。 | 例如，以下配置： ```nginx upstream backend { server backend.example.com service=_http._tcp resolve; server 127.0.0.1; zone backend 1m; } ``` 允许以下对等节点名称： ```console $ 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`、`slow_start`、`backup`、`down` 和 `sid` 参数，如 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 中所述。 #### NOTE 这里没有单独的 `drain` (PRO) 参数； 要启用 `drain`， 将 `down` 设置为字符串值 `drain`： ```console $ curl -X PUT -d \"drain\" \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down ``` 示例： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 0, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": true, "down": false, "sid": "" } ``` 实际可用的参数仅限于 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 当前负载均衡方法所支持的参数。 因此，如果上游配置了 `random` 方法： ```nginx upstream backend { zone backend 256k; server backend.example.com resolve max_conns=5; random; } ``` 您将无法添加定义了 `backup` 的新对等节点： ```console $ curl -X PUT -d '{ "backup": true }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com ``` ```json { "error": "FormatError", "description": "The \"backup\" field is unknown." } ``` #### NOTE 即使使用兼容的负载均衡方法，`backup` 参数 也只能在添加新对等节点时设置。 #### `/config/stream/upstreams//servers/` 允许配置单个上游对等节点， 包括删除现有对等节点或添加新对等节点。 URI 路径参数： | `` | `upstream` 块的名称；
要通过 `/config` 进行配置，
必须配置 [zone](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) 指令，
定义一个共享内存区域。 | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `` | 上游中对等节点的名称，定义为
`@`，其中：

- `@` 是可选的服务名称，用于
SRV 记录解析。
- `` 是服务的域名（如果存在 `resolve`）
或其 IP 地址；可以在此定义可选的端口。 | 例如，以下配置： ```nginx upstream backend { server backend.example.com:8080 service=_example._tcp resolve; server 127.0.0.1:12345; zone backend 1m; } ``` 允许以下对等节点名称： ```console $ 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`、`slow_start`、`backup` 和 `down` 参数，如 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 中所述。 #### NOTE 这里没有单独的 `drain`（PRO）参数； 要启用 :samp:`drain` 模式， 将 `down` 设置为字符串值 `drain`： ```console $ curl -X PUT -d \"drain\" \ http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down ``` 示例： ```console curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 0, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": true, "down": false, } ``` 实际可用的参数仅限于 [upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 当前负载均衡方法所支持的参数。 因此，如果上游配置了 `random` 方法： ```nginx upstream backend { zone backend 256k; server backend.example.com resolve max_conns=5; random; } ``` 您将无法添加定义了 `backup` 的新对等节点： ```console $ curl -X PUT -d '{ "backup": true }' \ http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com ``` ```json { "error": "FormatError", "description": "The \"backup\" field is unknown." } ``` #### NOTE 即使使用兼容的负载均衡方法，`backup` 参数 也只能在添加新对等节点时设置。 删除对等节点时，您可以设置 `connection_drop=` 参数（PRO）来覆盖 [proxy_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop) 设置： ```console $ 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 方法的语义： ```nginx 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/` 上游服务器分支支持以下查询： ```console $ 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` 参数获取默认参数值： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on ``` ```json { "backend.example.com": { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": false, "down": false, "sid": "" } } ``` #### PUT `PUT` HTTP 方法在指定路径创建一个新的 JSON 实体， 或\*完全\*替换现有实体。 例如，要向 `backend` 上游中的 `backend.example.com` 服务器 添加之前未指定的 `max_fails` 参数： ```console $ curl -X PUT -d '2' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing." } ``` 验证更改： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "max_conns": 5, "max_fails": 2 } ``` #### DELETE `DELETE` HTTP 方法删除指定路径上\*先前定义\*的设置； 这样做时，如果存在默认值，它会恢复默认值。 例如，要删除 `backend` 上游中 `backend.example.com` 服务器 之前修改的 `max_fails` 参数： ```console $ curl -X DELETE \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails ``` ```json { "success": "Reset", "description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default." } ``` 使用 `defaults=on` 参数验证更改： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": false, "down": false, "sid": "" } ``` `max_fails` 参数已恢复为其默认值。 删除服务器时，您可以设置 `connection_drop=` 参数 （PRO）来覆盖 [proxy_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop)、[grpc_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop)、 [fastcgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop)、[scgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) 和 [uwsgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) 设置： ```console $ 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](https://datatracker.ietf.org/doc/html/rfc7396)）， 通过在其有效负载中提供 JSON 定义。 该方法的操作如下：如果新定义中的实体 存在于配置中，则会被覆盖；否则，它们会被添加。 例如，要更改 `backend` 上游中 `backend.example.com` 服务器的 `down` 参数，同时保持其余部分不变： ```console $ curl -X PATCH -d '{ "down": true }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging." } ``` 验证更改： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "max_conns": 5, "down": true } ``` 请注意，随 `PATCH` 请求提供的 JSON 对象\*被合并\*到现有对象中， 而不是像 `PUT` 那样完全替换它。 `null` 值是一种特殊情况；它们用于在此类合并期间 删除特定的配置项。 #### NOTE 此删除与 `DELETE` 相同； 特别是，它会恢复默认值。 例如，要删除之前添加的 `down` 参数 并同时更新 `max_conns`： ```console $ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging." } ``` 验证更改： ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "max_conns": 6 } ``` 提供了 `null` 值的 `down` 参数已被删除； `max_conns` 值已更新。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_auth_basic.md # Auth Basic 允许通过使用"HTTP基本认证"协议验证用户名和密码来限制对资源的访问。 访问也可以通过 [地址](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) 或通过 [子请求结果](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 来限制。通过地址和密码同时限制访问由 [satisfy](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 指令控制。 ## 配置示例 ```nginx location / { auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } ``` ## 指令 ### auth_basic | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic` string | `off`; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认 | `auth_basic off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | 通过"HTTP基本认证"协议启用用户名和密码验证。指定的参数用作 领域。参数值可以包含变量。 | `off` | 取消从先前配置级别继承的 auth_basic 指令的效果 | |---------|---------------------------------| ### auth_basic_user_file | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_basic_user_file` file; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except | 指定一个 文件 来保存用户名和密码，格式如下： ```none # 注释 name1:password1 name2:password2:comment name3:password3 ``` 文件 名可以包含变量。 支持以下密码类型： * 使用 crypt() 函数加密；可以使用Apache HTTP Server发行版中的 `htpasswd` 工具或"openssl passwd"命令生成； * 使用基于MD5的密码算法的Apache变体（apr1）进行哈希；可以使用相同的工具生成； * 按照 [RFC 2307](https://datatracker.ietf.org/doc/html/rfc2307#section-5.3) 中描述的"{scheme}data"语法指定；目前实现的方案包括 PLAIN （一个示例，不应使用）、SHA （纯SHA-1哈希，不应使用）和 SSHA （加盐SHA-1哈希，一些软件包使用，尤其是OpenLDAP和Dovecot）。 #### WARNING SHA方案的支持仅为从其他Web服务器迁移提供帮助。它不应用于新密码，因为采用的未加盐SHA-1哈希易受 [彩虹表](http://en.wikipedia.org/wiki/Rainbow_attack) 攻击。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_auth_request.md # Auth Request 根据子请求的结果实现客户端授权。如果子请求返回 2xx 响应代码，则允许访问。如果返回 401 或 403，则拒绝访问，并返回相应的错误代码。子请求返回的任何其他响应代码都被视为错误。 对于 401 错误，客户端还会收到来自子请求响应的 `WWW-Authenticate` 头。 当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时，该模块默认未构建；应通过 `‑‑with‑http_auth_request_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 启用。 在来自 [我们的仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的包和镜像中，模块已包含在构建中。 该模块可以与其他访问模块组合，例如 [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) 和 [Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic)，通过 [satisfy](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) 指令。 ## 配置示例 ```nginx location /private/ { auth_request /auth; # ... } location = /auth { proxy_pass ...; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_set_header X-Original-URI $request_uri; } ``` ## 指令 ### auth_request | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request` `uri` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `auth_request off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 根据子请求的结果启用授权，并设置子请求将被发送的 URI。 ### auth_request_set | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_request_set` $variable value; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在授权请求完成后，将请求变量设置为给定值。值可以包含来自授权请求的变量，例如 `$upstream_http_*`。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_autoindex.md # AutoIndex 该模块处理以斜杠字符 (`/`) 结尾的请求，并生成目录列表。通常，当 [Index](https://cn.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index) 模块找不到索引文件时，请求会传递给 `AutoIndex` 模块。 ## 配置示例 ```nginx location / { autoindex on; } ``` ## 指令 ### autoindex | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `autoindex off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用目录列表输出。 ### autoindex_exact_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_exact_size` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `autoindex_exact_size on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 对于 HTML [格式](#autoindex-format)，指定目录列表中是否输出精确的文件大小，或者将其四舍五入到千字节、兆字节和千兆字节。 ### autoindex_format | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_format` `html` | `xml` | `json` | `jsonp`; | |--------------------------------------------------------------------------------------|---------------------------------------------------------| | 默认值 | `autoindex_format html;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置目录列表的格式。 当使用 JSONP 格式时，回调函数的名称通过 `callback` 请求参数设置。如果参数缺失或为空值，则使用 JSON 格式。 XML 输出可以通过 [XSLT](https://cn.angie.software//angie/docs/configuration/modules/http/http_xslt.md#http-xslt) 模块进行转换。 ### 输出格式 响应中的对象字段包含以下数据： | 字段 | 描述 | |---------|------------------------------------------------------------------------| | `name` | 文件或目录名称 | | `type` | 对象类型：`file` 或 `directory` | | `size` | 根据 [autoindex_exact_size](#autoindex-exact-size) 的对象大小；
对于目录 — `0` | | `mtime` | Unix 时间格式的最后修改时间 | HTML ```html Index of /files/

Index of /files/

            ../
            example.txt               12-Jun-2025 14:21    1234
            image.png                   12-Jun-2025 14:21    4321
``` XML ```xml example.txt file 1234 2025-06-12T14:21:00Z image.png file 4321 2025-06-12T14:21:00Z ``` JSON ```json [ { "name": "example.txt", "type": "file", "size": 1234, "mtime": "2025-06-12T14:21:00Z" }, { "name": "image.png", "type": "file", "size": 4321, "mtime": "2025-06-12T14:21:00Z" } ] ``` JSONP ```javascript callback([ { "name": "example.txt", "type": "file", "size": 1234, "mtime": "2025-06-12T14:21:00Z" }, { "name": "image.png", "type": "file", "size": 4321, "mtime": "2025-06-12T14:21:00Z" } ]); ``` ### autoindex_localtime | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `autoindex_localtime` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `autoindex_localtime off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 对于 HTML [格式](#autoindex-format)，指定目录列表中的时间是以本地时区还是以 UTC 输出。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_browser.md # Browser 该模块创建的变量值依赖于:samp:User-Agent 请求头字段的值。 ## 变量 ### `$modern_browser` 如果识别为现代浏览器，则等于由 [modern_browser_value](#modern-browser-value) 指令设置的值； ### `$ancient_browser` 如果识别为古老浏览器，则等于由 [ancient_browser_value](#ancient-browser-value) 指令设置的值； ### `$msie` 如果识别为任何版本的 MSIE 浏览器，则等于"1"。 ## 配置示例 ### 选择索引文件： ```nginx modern_browser_value "modern."; modern_browser msie 5.5; modern_browser gecko 1.0.0; modern_browser opera 9.0; modern_browser safari 413; modern_browser konqueror 3.0; index index.${modern_browser}html index.html; ``` ### 为旧浏览器重定向： ```nginx modern_browser msie 5.0; modern_browser gecko 0.9.1; modern_browser opera 8.0; modern_browser safari 413; modern_browser konqueror 3.0; modern_browser unlisted; ancient_browser Links Lynx netscape4; if ($ancient_browser) { rewrite ^ /ancient.html; } ``` ## 指令 ### ancient_browser | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser` string ...; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果在:samp:User-Agent 请求头字段中找到任何指定的子字符串，则该浏览器将被视为古老。特殊字符串"netscape4"对应于正则表达式"^Mozilla/[1-4]"。 ### ancient_browser_value | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ancient_browser_value` string; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认 | `ancient_browser_value 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为 [$ancient_browser](#v-ancient-browser) 变量设置值。 ### modern_browser | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser` browser version;

`modern_browser` `unlisted`; | |--------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定从哪个版本开始浏览器被视为现代。浏览器可以是以下任意一个：`msie`、`gecko` （基于 Mozilla 的浏览器）、`opera`、`safari` 或 `konqueror`。 版本可以采用以下格式指定：X、X.X、X.X.X 或 X.X.X.X。每种格式的最大值分别为 4000、4000.99、4000.99.99 和 4000.99.99.99。 特殊值 `unlisted` 指定如果浏览器未在 modern_browser 和 [ancient_browser](#id6) 指令中列出，则视为现代浏览器。否则，该浏览器将被视为古老。如果请求未在头中提供:samp:User-Agent 字段，则该浏览器被视为未列出。 ### modern_browser_value | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `modern_browser_value` string; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认 | `modern_browser_value 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为 [$modern_browser](#v-modern-browser) 变量设置值。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_charset.md # Charset 该模块将指定的字符集添加到:samp:Content-Type 响应头字段。此外，该模块可以在某些限制条件下将数据从一种字符集转换为另一种字符集： * 转换是单向进行的——从服务器到客户端， * 只能转换单字节字符集， * 或单字节字符集与 UTF-8 之间的转换。 ## 配置示例 ```nginx include conf/koi-win; charset windows-1251; source_charset koi8-r; ``` ## 指令 ### charset | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `charset` charset | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认 | `charset off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 将指定的字符集添加到:samp:Content-Type 响应头字段。如果该字符集与 [source_charset](#source-charset) 指令中指定的字符集不同，则会执行转换。 参数 `off` 取消将字符集添加到:samp:Content-Type 响应头字段。 字符集可以通过变量定义： ```nginx charset $charset; ``` 在这种情况下，变量的所有可能值必须至少在配置中以 [charset_map](#charset-map)、[charset](#id3) 或 [source_charset](#source-charset) 指令的形式出现一次。对于 `utf-8`、`windows-1251` 和 `koi8-r` 字符集，只需在配置中包含 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 文件。对于其他字符集，只需创建一个虚构的转换表即可，例如： ```nginx charset_map iso-8859-5 _ { } ``` 此外，可以在:samp:X-Accel-Charset\`响应头字段中设置字符集。可以使用 :ref:\`proxy_ignore_headers、[fastcgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers)、[uwsgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers)、[scgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) 和 [grpc_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ignore-headers) 指令禁用此功能。 ### charset_map | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_map` charset1 charset2 { ... } | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 描述从一种字符集到另一种字符集的转换表。使用相同的数据构建反向转换表。字符编码以十六进制给出。在范围 80-FF 中缺失的字符用 "?" 替代。从 UTF-8 转换时，在单字节字符集中缺失的字符用 "&#XXXX;" 替代。 示例： ```nginx charset_map koi8-r windows-1251 { C0 FE ; # 小 ю C1 E0 ; # 小 а C2 E1 ; # 小 б C3 F6 ; # 小 ц } ``` 在描述到 UTF-8 的转换表时，UTF-8 字符集的代码应在第二列给出，例如： ```nginx charset_map koi8-r utf-8 { C0 D18E ; # 小 ю C1 D0B0 ; # 小 а C2 D0B1 ; # 小 б C3 D186 ; # 小 ц } ``` 从 `koi8-r` 到 `windows-1251`，以及从 `koi8-r` 和 `windows-1251` 到 `utf-8` 的完整转换表在分发文件 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 中提供。 ### charset_types | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `charset_types` mime-type ...; | |--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| | 默认 | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 使模块在处理指定 MIME 类型的响应时生效，除了 `text/html` 之外。特殊值 `*` 匹配任何 MIME 类型。 ### override_charset | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `override_charset` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认 | `override_charset off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 确定是否应对从代理或 FastCGI/uwsgi/SCGI/gRPC 服务器接收到的响应进行转换，当这些响应已在:samp:Content-Type 响应头字段中携带字符集时。如果启用转换，则使用接收到的响应中指定的字符集作为源字符集。 #### NOTE 如果在子请求中收到响应，则始终会将响应字符集转换为主请求字符集，而不管 override_charset 指令的设置。 ### source_charset | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `source_charset` charset; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location | 定义响应的源字符集。如果该字符集与 [charset](#id3) 指令中指定的字符集不同，则会执行转换。 # https://cn.angie.software/angie/docs/configuration/modules/http/http_dav.md # DAV 该模块旨在通过 WebDAV 协议实现文件管理自动化。模块处理 HTTP 和 WebDAV 方法：PUT、DELETE、MKCOL、COPY 和 MOVE。 当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时，默认不包含该模块；需要通过 `‑‑with‑http_dav_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 来启用。 在来自 [我们的仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的包和镜像中，该模块包含在构建中。 #### NOTE 需要其他 WebDAV 方法才能操作的 WebDAV 客户端将无法与此模块一起使用。 ## 配置示例 ```nginx location / { root /data/www; client_body_temp_path /data/client_temp; dav_methods PUT DELETE MKCOL COPY MOVE; create_full_put_path on; dav_access group:rw all:r; limit_except GET { allow 192.168.1.0/32; deny all; } } ``` ## 指令 ### create_full_put_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `create_full_put_path` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `create_full_put_path off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | WebDAV 规范仅允许在已存在的目录中创建文件。此指令允许创建所有需要的中间目录。 ### dav_access | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_access` users:permissions ...; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `dav_access user:rw;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为新创建的文件和目录设置访问权限，例如： ```nginx dav_access user:rw group:rw all:r; ``` 如果指定了任一组或所有访问权限，则可以省略用户权限： ```nginx dav_access group:rw all:r; ``` ### dav_methods | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `dav_methods` `off` | method ...; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `dav_methods off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许指定的 HTTP 和 WebDAV 方法。参数 `off` 拒绝所有此模块处理的方法。支持以下方法：PUT、DELETE、MKCOL、COPY 和 MOVE。 使用 PUT 方法上传的文件首先被写入临时文件，然后文件被重命名。从版本 0.8.9 开始，临时文件和持久存储可以放在不同的文件系统上。但请注意，在这种情况下，文件是在两个文件系统之间复制，而不是便宜的重命名操作。因此建议在任何给定的 `location` 中，保存的文件和由 [client_body_temp_path](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#client-body-temp-path) 指令设置的临时文件目录放在同一个文件系统中。 使用 PUT 方法创建文件时，可以通过在 `Date` 头字段中传递修改日期来指定。 ### min_delete_depth | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `min_delete_depth` number; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `min_delete_depth 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许 DELETE 方法删除文件，前提是请求路径中的元素数量不小于指定的数量。例如，指令 ```nginx min_delete_depth 4; ``` 允许删除以下请求的文件 ```console /users/00/00/name /users/00/00/name/pic.jpg /users/00/00/page.html ``` 并拒绝删除 ```console /users/00/00 ``` # https://cn.angie.software/angie/docs/configuration/modules/http/http_docker.md # Docker 该模块基于 Docker 容器标签，在 [HTTP](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 和 [stream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 上下文中提供代理服务器组的动态配置。 要使该功能正常工作，必须在组中配置共享内存区域（参见 [http](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 和 [stream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) 的 `zone` 说明）。 #### NOTE 该模块支持与 Docker 及其替代品（如 Podman）配合使用，这些替代品实现了兼容的 API。 该模块通过 API 连接到 Docker 守护进程，与其交互的方法由 [docker_endpoint](#docker-endpoint) 指令指定。 在获取正在运行的容器列表后，Angie 会分析它们是否存在合适的 [标签](#docker-labels)。 如果容器描述中包含带有端口的标签，则该容器的地址和端口，以及该容器其他标签中的参数，将自动添加到 Angie 配置中相应的 `upstream` 块。 #### NOTE 同一个容器可以添加到多个 `upstream` 组。 要实现这一点，只需指定多组具有不同组名和端口的标签即可。 这在容器在不同端口上运行多个不同服务时特别有用——每个服务可以关联到自己的组。 然后，该模块订阅容器生命周期事件，并开始在不重新加载 Angie 的情况下更新代理服务器配置： - 当启动带有合适标签的容器时，其内部 IP 地址将添加到指定的组； - 当停止或删除容器时，它会自动从组中移除； - 当使用 **docker pause** 命令暂停容器时，服务器被标记为 `down`，使用 **docker unpause** 时——标记为 `up`。 ## 配置示例 该模块的指令始终位于 `http` 上下文中，但代理服务器组可以在 `http` 上下文和 `stream` 上下文中定义。 `http` 的配置示例： ```nginx http { # 连接选项示例： # docker_endpoint http://127.0.0.1:2375; # docker_endpoint https://127.0.0.1:2376; docker_endpoint unix:/var/run/docker.sock; # Docker 响应缓冲区最大大小（可选） # docker_max_object_size 128k; upstream u { zone z 1m; # 需要共享内存区域 } server { listen 80; server_name example.com; location / { proxy_pass http://u; } } } ``` stream 上下文中的类似配置： ```nginx http { # 连接选项示例： # docker_endpoint http://127.0.0.1:2375; # docker_endpoint https://127.0.0.1:2376; docker_endpoint unix:/var/run/docker.sock; # Docker 响应缓冲区最大大小（可选） # docker_max_object_size 128k; } stream { upstream u { zone z 1m; } server { listen 12345; proxy_pass u; } } ``` 收到容器事件后，Angie 会查找形式为 `angie.http.upstreams..port=` （用于 HTTP 上下文）或 `angie.stream.upstreams..port=` （用于 stream 上下文）的标签。 当存在标签时，容器在指定 Docker 网络中的地址（如果未指定 `angie.network` 标签，则为第一个可用的地址）将添加到相应的代理服务器组。 如果容器停止或被删除，服务器将从组中移除；如果容器被暂停，服务器将被标记为 `down`。 Angie 识别的带有标签的 `docker-compose.yml` 文件片段： ```yaml services: myapp: image: myapp:latest labels: - "angie.http.upstreams.u.port=8080" - "angie.network=my_bridge" - "angie.http.upstreams.u.weight=2" - "angie.http.upstreams.u.max_conns=50" - "angie.http.upstreams.u.max_fails=3" - "angie.http.upstreams.u.fail_timeout=10s" - "angie.http.upstreams.u.backup=true" ``` ## 标签 标签在代理服务器组中指定服务器参数，类似于 `server` 指令的参数： | 标签 | 用途 | |------------------------------------------------------------|-----------------------------------------| | `angie.(http|stream).upstreams..port=` *（必需）* | Angie 将连接到的容器端口；容器本身被添加到名为 `` 的组。 | | `angie.network=` | 用于获取容器 IP 地址的 Docker 网络名称。 | | `angie.(http|stream).upstreams..weight=` | `weight` 参数的值。 | | `angie.(http|stream).upstreams..max_conns=` | 最大并发连接数（`max_conns`）。 | | `angie.(http|stream).upstreams..max_fails=` | 失败尝试阈值（`max_fails`）。 | | `angie.(http|stream).upstreams..fail_timeout=` | 计算失败尝试的时间间隔（`fail_timeout`）。 | | `angie.(http|stream).upstreams..backup=true|false` | 将服务器标记为 `backup`。 | | `angie.(http|stream).upstreams..sid=` | 为代理服务器设置自定义服务器标识符（`sid`）。 | | `angie.(http|stream).upstreams..slow_start=