├── .gitignore ├── 介绍 ├── 配置文件度量单位.md ├── 安装nginx.md ├── 设置哈希.md ├── 命令行参数.md ├── 连接处理方式.md ├── Nginx如何处理TCP_UDP会话.md ├── 记录日志到syslog.md ├── Windows下的Nginx.md ├── 调试日志.md ├── 关于nginScript.md ├── QUIC和HTTP3支持.md ├── 使用Nginx作为HTTP负载均衡器.md └── 控制nginx.md ├── 模块参考 ├── http │ ├── ngx_http_empty_gif_module.md │ ├── ngx_http_random_index_module.md │ ├── ngx_http_flv_module.md │ ├── ngx_http_gzip_static_module.md │ ├── ngx_http_index_module.md │ ├── ngx_http_f4f_module.md │ ├── ngx_http_split_clients_module.md │ ├── ngx_http_gunzip_module.md │ ├── ngx_http_keyval_module.md │ ├── ngx_http_addition_module.md │ ├── ngx_http_slice_module.md │ ├── ngx_http_access_module.md │ ├── ngx_http_auth_request_module.md │ ├── ngx_http_mirror_module.md │ ├── ngx_http_autoindex_module.md │ ├── ngx_http_auth_basic_module.md │ ├── ngx_http_sub_module.md │ ├── ngx_http_stub_status_module.md │ ├── ngx_http_realip_module.md │ ├── ngx_http_session_log_module.md │ ├── ngx_http_referer_module.md │ ├── ngx_http_spdy_module.md │ ├── ngx_http_geo_module.md │ ├── ngx_http_headers_module.md │ ├── ngx_http_map_module.md │ ├── ngx_http_auth_jwt_module.md │ ├── ngx_http_dav_module.md │ ├── ngx_http_browser_module.md │ ├── ngx_http_limit_conn_module.md │ ├── ngx_http_limit_req_module.md │ ├── ngx_http_xslt_module.md │ ├── ngx_http_mp4_module.md │ ├── ngx_http_geoip_module.md │ ├── ngx_http_secure_link_module.md │ ├── ngx_http_charset_module.md │ ├── ngx_http_userid_module.md │ ├── ngx_http_image_filter_module.md │ ├── ngx_http_js_module.md │ ├── ngx_http_gzip_module.md │ ├── ngx_http_hls_module.md │ ├── ngx_http_upstream_hc_module.md │ ├── ngx_http_log_module.md │ ├── ngx_http_upstream_conf_module.md │ └── ngx_http_memcached_module.md ├── stream │ ├── ngx_stream_return_module.md │ ├── ngx_stream_access_module.md │ ├── ngx_stream_realip_module.md │ ├── ngx_stream_split_clients_module.md │ ├── ngx_stream_ssl_preread_module.md │ ├── ngx_stream_limit_conn_module.md │ ├── ngx_stream_geo_module.md │ ├── ngx_stream_keyval_module.md │ ├── ngx_stream_map_module.md │ ├── ngx_stream_geoip_module.md │ ├── ngx_stream_log_module.md │ ├── ngx_stream_js_module.md │ └── ngx_stream_upstream_hc_module.md ├── google │ └── ngx_google_perftools_module.md └── mail │ ├── ngx_mail_smtp_module.md │ ├── ngx_mail_pop3_module.md │ ├── ngx_mail_imap_module.md │ ├── ngx_mail_proxy_module.md │ └── ngx_mail_auth_http_module.md ├── CONTRIBUTING.md ├── book.json ├── README.md ├── How-To ├── WebSocket代理.md ├── 在Win32平台上使用VisualC构建nginx.md ├── 转换重写规则.md └── 使用DTrace_pid提供程序调试nginx.md ├── 开发 └── 贡献指南.md └── 其他 └── linux包.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | _book 4 | -------------------------------------------------------------------------------- /介绍/配置文件度量单位.md: -------------------------------------------------------------------------------- 1 | # 配置文件度量单位 2 | 3 | 度量单位可以是字节、千字节（单位是 k 或者 K ）或者兆字节（单位是 m 或者 M ），例如，`1024`，`8k`，`1m`。 4 | 5 | 也可以使用 g 或者 G 单位的千兆字节。 6 | 7 | 可以指定毫秒、秒、分、小时和天等时间来设定时间间隔，使用以下单位： 8 | 9 | 单位 | 含义 10 | :----|:---- 11 | ms | 毫秒 12 | s | 秒 13 | m | 分钟 14 | h | 小时 15 | d | 天 16 | w | 周 17 | M | 月，30天 18 | y | 年，365天 19 | 20 | 可以从大到小的顺序指定多个单位，用可选的空格符间隔组合成单个值。例如，`1h 30m` 与 `90m` 或者 `5400s` 时间相同。没有单位的值表示秒，建议始终加上单位。 21 | 22 | 某些时间设置只能区分秒级单位。 23 | 24 | ## 原文档 25 | 26 | [http://nginx.org/en/docs/syntax.html](http://nginx.org/en/docs/syntax.html) 27 | -------------------------------------------------------------------------------- /介绍/安装nginx.md: -------------------------------------------------------------------------------- 1 | # 安装 nginx 2 | 3 | nginx 可以以不同的方式安装，安装方式取决于当前的操作系统。 4 | 5 | ## 在 Linux 上安装 6 | 7 | 对于 Linux，可以使用 nginx.org 的 nginx [软件包](../其他/linux包.md)。 8 | 9 | ## 在 FreeBSD 上安装 10 | 11 | 在 FreeBSD 上，可以从 [软件包](http://www.freebsd.org/doc/handbook/pkgng-intro.html) 或通过 [ports](http://www.freebsd.org/doc/handbook/ports-using.html) 系统安装 nginx。ports 系统提供更大的灵活性，提供了各种选项可供选择。port 将使用指定的选项编译 nginx 并进行安装。 12 | 13 | ## 从源码安装 14 | 15 | 如果需要某些特殊功能软件包和 ports 无法提供，那么可以从源码中编译 nginx。虽然此方式更加灵活，但对于初学者来说可能会很复杂。更多信息请参阅 [从源码构建 nginx](../How-To/从源码构建nginx.md)。 16 | 17 | ## 原文档 18 | 19 | [http://nginx.org/en/docs/install.html](http://nginx.org/en/docs/install.html) 20 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_empty_gif_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_empty_gif_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [empty_gif](#empty_gif) 6 | 7 | `ngx_http_empty_gif_module` 模块发送单像素透明 GIF。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | location = /_.gif { 15 | empty_gif; 16 | } 17 | ``` 18 | 19 | 20 | 21 | ## 指令 22 | 23 | ### empty_gif 24 | 25 | |\-|说明| 26 | |------:|------| 27 | |**语法**|**empty_gif**;| 28 | |**默认**|——| 29 | |**上下文**|location| 30 | 31 | 开启针对 `location` 的模块处理。 32 | 33 | ## 原文档 34 | [http://nginx.org/en/docs/http/ngx_http_empty_gif_module.html](http://nginx.org/en/docs/http/ngx_http_empty_gif_module.html) -------------------------------------------------------------------------------- /介绍/设置哈希.md: -------------------------------------------------------------------------------- 1 | # 设置哈希 2 | 3 | 为了快速处理静态数据集，如服务器名称、[map](http://nginx.org/en/docs/http/ngx_http_map_module.html#map) 指令值、MIME 类型、请求头字符串的名称，nginx 使用了哈希表。在开始和每次重新配置时，nginx 尽可能选择最小的哈希表，以便存储具有相同散列值的存储桶大小不会超过配置参数（哈希桶大小）。表的大小以桶为单位。调整是持续的，直到表的大小超过哈希的最大大小参数。大多数哈希具有修改这些参数对应的指令，例如，对于服务器名称哈希，它们是 [server_names_hash_max](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) 和 [server_names_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size)。 4 | 5 | 哈希桶大小参数与处理器的高速缓存线大小的倍数对齐。可以通过减少内存访问的次数来加快现代处理器的哈希键搜索速度。如果哈希桶大小等于处理器的高速缓存线大小，则哈希键搜索期间内存访问次数最坏的情况下将有两次 —— 一是计算桶地址，二是在桶内搜索哈希键期间。因此，如果 nginx 发出消息请求增加到哈希的最大大小或者哈希桶的大小，那么首先应该增加第一个参数。 6 | 7 | ## 原文档 8 | 9 | - [http://nginx.org/en/docs/hash.html](http://nginx.org/en/docs/hash.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_random_index_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_random_index_module 2 | 3 | `ngx_http_random_index_module` 模块处理以 `/` 结尾的请求，然后随机选择目录中的一个文件作为索引文件展示，该模块优先于 [ngx_http_index_module](ngx_http_index_module.md) 之前处理。 4 | 5 | 该模块默认不会被构建到 nginx 中，需要在编译时加入 `--with-http_random_index_module` 配置参数启用。 6 | 7 | ## 配置示例 8 | 9 | ```nginx 10 | location / { 11 | random_index on; 12 | } 13 | ``` 14 | 15 | ### random_index 16 | 17 | |\-|说明| 18 | |:------|:------| 19 | |**语法**|**random_index** `on` | `off`;| 20 | |**默认**|random_index off;| 21 | |**上下文**|location| 22 | 23 | 启用或禁用 `location` 周边的模块处理。 24 | 25 | ## 原文档 26 | 27 | - [http://nginx.org/en/docs/http/ngx_http_random_index_module.html](http://nginx.org/en/docs/http/ngx_http_random_index_module.html) 28 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_return_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_return_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [return](#return) 6 | 7 | `ngx_stream_return_module` 模块（1.11.2）允许向客户端发送指定的值，然后关闭连接。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | server { 15 | listen 12345; 16 | return $time_iso8601; 17 | } 18 | ``` 19 | 20 | 21 | 22 | ## 指令 23 | 24 | ### return 25 | 26 | |\-|说明| 27 | |------:|------| 28 | |**语法**|**return** `value`;| 29 | |**默认**|——| 30 | |**上下文**|server| 31 | 32 | 指定要发送给客户端的值。该值可以包含文本、变量及其组合。 33 | 34 | ## 原文档 35 | [http://nginx.org/en/docs/stream/ngx_stream_return_module.html](http://nginx.org/en/docs/stream/ngx_stream_return_module.html) -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # 贡献导引 2 | 3 | 请严格按照以下步骤操作，如有任何问题，请提出 issue 4 | 5 | * 在 GitHub 上点击 `fork` 将本仓库 fork 到自己的仓库，如 `yourname/nginx-docs`，然后 `clone` 到本地。 6 | 7 | ```bash 8 | $ git clone git@github.com:yourname/nginx-docs.git 9 | $ cd nginx-docs 10 | # 将项目与上游关联 11 | $ git remote add source git@github.com:DocsHome/nginx-docs.git 12 | ``` 13 | 14 | * 增加内容或者修复错误后提交，并推送到自己的仓库。 15 | 16 | ```bash 17 | $ git add . 18 | $ git commit -am "Fix issue #1: change helo to hello" 19 | $ git push origin master 20 | ``` 21 | 22 | * 在 GitHub 上提交 `pull request`。 23 | 24 | * 请定期更新自己仓库内容。 25 | 26 | ```bash 27 | $ git fetch source 28 | $ git rebase source/master 29 | $ git push -f origin master 30 | ``` 31 | 32 | # 排版规范 33 | 34 | 本项目排版遵循 [中文排版指南](https://github.com/mzlogin/chinese-copywriting-guidelines) 规范。 35 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_flv_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_flv_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [flv](#flv) 6 | 7 | `ngx_http_flv_module` 模块为 Flash 视频（FLV）文件提供伪流服务端支持。 8 | 9 | 它通过发送回文件的内容来处理请求 URI 查询字符串中带有特定 `start` 参数的请求，文件的内容从请求字节偏移开始的且 FLV 头为前缀。 10 | 11 | 该模块不是默认构的，您可以在构建时使用 `--with-http_flv_module` 配置参数启用。 12 | 13 | 14 | 15 | ## 示例配置 16 | 17 | ```nginx 18 | location ~ \.flv$ { 19 | flv; 20 | } 21 | ``` 22 | 23 | 24 | 25 | ## 指令 26 | 27 | ### flv 28 | 29 | |\-|说明| 30 | |------:|------| 31 | |**语法**|**flv**;| 32 | |**默认**|——| 33 | |**上下文**|location| 34 | 35 | 开启针对 `location` 的模块处理。 36 | 37 | ## 原文档 38 | [http://nginx.org/en/docs/http/ngx_http_flv_module.html](http://nginx.org/en/docs/http/ngx_http_flv_module.html) -------------------------------------------------------------------------------- /介绍/命令行参数.md: -------------------------------------------------------------------------------- 1 | # 命令行参数 2 | 3 | nginx支持以下命令行参数： 4 | 5 | - `-?` 或者 `-h` —— 打印命令行参数帮助信息 6 | - `-c file` —— 使用指定的配置文件来替代默认的配置文件 7 | - `-g directive` —— 设置 [全局配置指令](http://nginx.org/en/docs/ngx_core_module.html)，例如： 8 | 9 | ```bash 10 | nginx -g "pid /var/run/nginx.pid; worker_processes `sysctl -n hw.ncpu`;" 11 | ``` 12 | 13 | - `-p prefix` —— 设置 nginx 路径前缀，比如一个存放着服务器文件的目录（默认是 `/usr/local/nginx` ）。 14 | - `-q` —— 在配置测试期间禁止非错误信息。 15 | - `-s signal` —— 向 Master 进程发送信号，信号参数可以是以下： 16 | - `stop` —— 快速关闭。 17 | - `quit` —— 正常关闭。 18 | - `reload` —— 重新加载配置，使用新配置后启动新的 Worker 进程并正常退出旧的工作进程。 19 | - `reopen` —— 重新打开日志文件。 20 | - `-t` —— 测试配置文件：nginx 检查配置文件的语法正确性，之后尝试打开配置中引用到的文件。 21 | - `-T` —— 与 `-t` 一样，但另外将配置文件转储到标准输出（1.9.2）。 22 | - `-v` —— 打印 nginx 版本。 23 | - `-V` —— 打印 nginx 版本，编译器版本和配置参数。 24 | 25 | ## 原文档 26 | 27 | [http://nginx.org/en/docs/switches.html](http://nginx.org/en/docs/switches.html) 28 | -------------------------------------------------------------------------------- /介绍/连接处理方式.md: -------------------------------------------------------------------------------- 1 | # 连接处理方式 2 | 3 | nginx 支持多种连接处理方式，每一种方式是否可用取决于所用的平台。在支持几种方式的平台上，nginx 会自动选择最有效的方式，然而，如果您需要明确指定使用哪一种方式，可以使用 [use](http://nginx.org/en/docs/ngx_core_module.html#use) 指令指定。 4 | 5 | 支持以下集中处理方式： 6 | 7 | - **select**，标准方式。当平台上缺乏其他有效的方式时自动构建。`--with-select-module` 和 `-without-select_module` 配置参数开启或者禁用此模块构建。 8 | - **poll**，标准方式，当平台上缺乏其它有效的处理方式时自动构建此模块。`-with-poll_moudle` 和 `-without-poll_module` 配置项开启或者禁用此模块构建。 9 | - **kqueue**，在 FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0, 和 macOS 使用有效。 10 | - **epoll**，在 Linux 2.6+ 上使用有效。 11 | 12 | > 从 1.11.3 起支持 EPOLLRDHUP（Linux 2.6.17，glibc 2.8）和 EPOLLEXCLUSIVE（Linux 4.5，glibc 2.24）标志。一些类似于 SuSE 8.2 这样的老版本提供了对 2.4 内核支持 epll 的补丁。 13 | 14 | - **/dev/poll**，在 Solaris 7 11/99+，HP / UX 11.22+（eventport），IRIX 6.5.15+ 和 Tru64 UNIX 5.1A+ 有效。 15 | - **eventport**，事件端口，在 Solaris 10+ 有效（由于已知问题，推荐使用 `/dev/poll` 方式代替）。 16 | 17 | ## 原文档 18 | 19 | - [http://nginx.org/en/docs/events.html](http://nginx.org/en/docs/events.html) 20 | -------------------------------------------------------------------------------- /book.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "Nginx中文文档", 3 | "author": "DocsHome", 4 | "language": "zh-hans", 5 | "links": { 6 | "sidebar": { 7 | "Home": "https://github.com/DocsHome" 8 | } 9 | }, 10 | "plugins": [ 11 | "-sharing", 12 | "-highlight", 13 | "-livereload", 14 | "prism", 15 | "favicon" 16 | ], 17 | "pluginsConfig": { 18 | "github": { 19 | "url": "https://github.com/DocsHome/nginx-docs" 20 | }, 21 | "prism": { 22 | "css": [ 23 | "prismjs/themes/prism-solarizedlight.css" 24 | ] 25 | }, 26 | "tbfed-pagefooter": { 27 | "copyright": "Copyright © Oopsguy.com 2017", 28 | "modify_label": "最后更新时间：", 29 | "modify_format": "YYYY-MM-DD HH:mm:ss" 30 | }, 31 | "github-buttons": { 32 | "repo": "DocsHome/nginx-docs", 33 | "types": [ 34 | "star", 35 | "watch" 36 | ], 37 | "size": "small" 38 | } 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /模块参考/google/ngx_google_perftools_module.md: -------------------------------------------------------------------------------- 1 | # ngx_google_perftools_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [google_perftools_profiles](#google_perftools_profiles) 6 | 7 | `ngx_google_perftoos_module` 模块（0.6.29）可以使用 [Google 性能工具](https://github.com/gperftools/gperftools) 对 nginx 的 worker 进程进行分析。该模块适用于 nginx 开发人员。 8 | 9 | 默认情况下不构建此模块，您可以在构建时使用 `--with-google_perftools_module` 配置参数启用此模块。 10 | 11 | > 该模块需要 [gperftools](https://github.com/gperftools/gperftools) 库。 12 | 13 | 14 | 15 | ## 示例配置 16 | 17 | ```nginx 18 | google_perftools_profiles /path/to/profile; 19 | ``` 20 | 21 | profile 文件将被存储为 `/path/to/profile.`。 22 | 23 | 24 | 25 | ## 指令 26 | 27 | ### google_perftools_profiles 28 | 29 | |\-|说明| 30 | |------:|------| 31 | |**语法**|**google_perftools_profiles** `file ...`;| 32 | |**默认**|——| 33 | |**上下文**|main| 34 | 35 | 设置保存 nginx worker 进程分析信息的文件的名名。worker 进程的 ID 始终是文件名的一部分，并追加在文件名的末尾。 36 | 37 | ## 原文档 38 | [http://nginx.org/en/docs/ngx_google_perftools_module.html](http://nginx.org/en/docs/ngx_google_perftools_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_gzip_static_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_gzip_static_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [gzip_static](#gzip_static) 6 | 7 | `ngx_http_gzip_static_module` 模块允许发送以 **.gz** 结尾的预压缩文件替代普通文件。 8 | 该模块默认不会被构建到 nginx 中，需要在编译时加入 `--with-http_gzip_static_module` 配置参数启用。 9 | 10 | 11 | 12 | ## 配置示例 13 | 14 | ```nginx 15 | gzip_static on; 16 | gzip_proxied expired no-cache no-store private auth; 17 | ``` 18 | 19 | 20 | ## 指令 21 | 22 | ### gzip_static 23 | 24 | |\-|说明| 25 | |:------|:------| 26 | |**语法**|**gzip_static** `on` | `off` | `always`; | 27 | |**默认**|gzip_static off;| 28 | |**上下文**|http、server、location| 29 | 30 | 开启(**on**)或禁用(**off**)会检查预压缩文件是否存在。下列指令也会被影响到 [gzip_http_verson](ngx_http_gzip_module.md#gzip_http_version)， [gzip_proxied](ngx_http_gzip_module.md#gzip_proxied)， [gzip_disable](ngx_http_gzip_module.md#gzip_disable)， [gzip_vary](ngx_http_gzip_module.md#gzip_vary)。 31 | 32 | 值为 **always** (1.3.6)，在所有情况下都会使用压缩文件，不检查客户端是否支持。如果磁盘上没有未被压缩的文件或者 [ngx_http_gunzip_module](ngx_http_gunzip_module.md) 模块被启用，这个参数非常有用。 33 | 34 | 文件可以使用`gzip`命令，或者任何兼容文件进行压缩。建议压缩文件和源文件的修改日期和时间保持一致。 35 | -------------------------------------------------------------------------------- /介绍/Nginx如何处理TCP_UDP会话.md: -------------------------------------------------------------------------------- 1 | # nginx 如何处理 TCP/UDP 会话 2 | 3 | 来自客户端的 TCP/UDP 会话以阶段的形式被逐步处理： 4 | 5 | |阶 段       |描 述| 6 | |:----|:----| 7 | | Post-accept | 接收客户端请求后的第一个阶段。[ngx_stream_realip_module](http://nginx.org/en/docs/stream/ngx_stream_realip_module.html) 模块在此阶段被调用。| 8 | | Pre-access | 初步检查访问，[ngx_stream_limit_conn_module](http://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html) 模块在此阶段被调用。 | 9 | | Access | 实际处理之前的客户端访问限制，ngx_stream_access_module 模块在此阶段被调用。 | 10 | | SSL | TLS/SSL 终止，ngx_stream_ssl_module 模块在此阶段被调用。 | 11 | | Preread | 将数据的初始字节读入 [预读缓冲区](http://nginx.org/en/docs/stream/ngx_stream_core_module.html#preread_buffer_size) 中，以允许如 [ngx_stream_ssl_preread_module](http://nginx.org/en/docs/stream/ngx_stream_ssl_preread_module.html) 之类的模块在处理前分析数据。 | 12 | | Content | 实际处理数据的强制阶段，通常 [代理](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html) 到 [upstream](http://nginx.org/en/docs/stream/ngx_stream_upstream_module.html) 服务器，或者返回一个特定的值给客户端 | 13 | | Log | 此为最后阶段，客户端会话处理结果将被记录， [ngx_stream_log_module module](http://nginx.org/en/docs/stream/ngx_stream_log_module.html) 模块在此阶段被调用。 | 14 | 15 | ## 原文档 16 | [http://nginx.org/en/docs/stream/stream_processing.html](http://nginx.org/en/docs/stream/stream_processing.html) 17 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_access_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_access_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [allow](#allow) 6 | - [deny](#deny) 7 | 8 | `ngx_stream_access_module` 模块（1.9.2）允许对某些客户端地址限制访问。 9 | 10 | 11 | 12 | ## 示例配置 13 | 14 | ```nginx 15 | server { 16 | ... 17 | deny 192.168.1.1; 18 | allow 192.168.1.0/24; 19 | allow 10.1.1.0/16; 20 | allow 2001:0db8::/32; 21 | deny all; 22 | } 23 | ``` 24 | 25 | 按顺序检查规则，直到找到第一个匹配项。在此示例中，仅允许 IPv4 网络 `10.1.1.0/16` 和 `192.168.1.0/24`（不包括地址 `192.168.1.1`）和 IPv6 网络`2001:0db8::/32` 进行访问。 26 | 27 | 28 | 29 | ## 指令 30 | 31 | ### allow 32 | 33 | |\-|说明| 34 | |------:|------| 35 | |**语法**|**allow** `address` | `CIDR` | `unix:` | `all`;| 36 | |**默认**|——| 37 | |**上下文**|stream、server| 38 | 39 | 允许指定的网络或地址访问。如果指定了值 `unix:`，则允许访问所有 UNIX 域套接字。 40 | 41 | ### deny 42 | 43 | |\-|说明| 44 | |------:|------| 45 | |**语法**|**deny** `address` | `CIDR` | `unix:` | `all`;| 46 | |**默认**|——| 47 | |**上下文**|stream、server| 48 | 49 | 拒绝指定的网络或地址访问。如果指定了值 `unix:`，则拒绝所有 UNIX 域套接字的访问。 50 | 51 | ## 原文档 52 | [http://nginx.org/en/docs/stream/ngx_stream_access_module.html](http://nginx.org/en/docs/stream/ngx_stream_access_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_index_module.md: -------------------------------------------------------------------------------- 1 | ngx_http_mirror_module# ngx_http_index_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [index](#index) 6 | 7 | `ngx_http_index_module` 模块处理以斜线字符（`/`）结尾的请求。这些请求也可以由[ngx_http_autoindex_module](ngx_http_autoindex_module.html) 和 [ngx_http_random_index_module](ngx_http_random_index_module.html) 模块来处理。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | location / { 15 | index index.$geo.html index.html; 16 | } 17 | ``` 18 | 19 | 20 | 21 | ## 指令 22 | 23 | ### index 24 | 25 | |\-|说明| 26 | |------:|------| 27 | |**语法**|**index** `file ...`;| 28 | |**默认**|index index.html;| 29 | |**上下文**|http、server、location| 30 | 31 | 定义将用作索引的文件。文件名可以包含变量。以指定的顺序检查文件。列表的最后一个元素可以是一个具有绝对路径的文件。例： 32 | 33 | ```nginx 34 | index index.$geo.html index.0.html /index.html; 35 | ``` 36 | 37 | 应该注意的是，使用索引文件发起内部重定向，可以在不同的 location 处理请求。例如，使用以下配置： 38 | 39 | ```nginx 40 | location = / { 41 | index index.html; 42 | } 43 | 44 | location / { 45 | ... 46 | } 47 | ``` 48 | 49 | `/` 请求实际上是将在第二个 location 处理为 `/index.html`。 50 | 51 | ## 原文档 52 | [http://nginx.org/en/docs/http/ngx_http_index_module.html](http://nginx.org/en/docs/http/ngx_http_index_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_f4f_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_f4f_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [f4f](#f4f) 6 | - [f4f_buffer_size](#f4f_buffer_size) 7 | 8 | `ngx_http_f4f_module` 模块为 Adobe HTTP 动态流（HDS）提供服务端支持。 9 | 10 | 该模块以 `/videoSeg1-Frag1` 形式处理 HTTP 动态流请求，使用 `videoSeg1.f4x` 索引文件从 `videoSeg1.f4f` 文件中提取所需的片段。该模块是 Apache 的 Adobe f4f 模块（HTTP Origin Module）的替代品。 11 | 12 | 它需要通过 Adobe 的 f4fpackager 进行预处理，有关详细信息，请参阅相关文档。 13 | 14 | > 此模块作为我们[商业订阅](http://nginx.com/products/?_ga=2.62027116.1975223854.1508572582-1890203964.1497190280)的一部分。 15 | 16 | 17 | 18 | ## 示例配置 19 | 20 | ```nginx 21 | location /video/ { 22 | f4f; 23 | ... 24 | } 25 | ``` 26 | 27 | 28 | 29 | ## 指令 30 | 31 | ### f4f 32 | 33 | |\-|说明| 34 | |------:|------| 35 | |**语法**|**f4f**;| 36 | |**默认**|——| 37 | |**上下文**|location| 38 | 39 | 开启针对 `location` 的模块处理。 40 | 41 | ### f4f_buffer_size 42 | 43 | |\-|说明| 44 | |------:|------| 45 | |**语法**|**f4f4f_buffer_sizef** `size`;| 46 | |**默认**|f4f_buffer_size 512k;| 47 | |**上下文**|http、server、location| 48 | 49 | 设置用于读取 `.f4x` 索引文件的缓冲区的 `size` （大小）。 50 | 51 | ## 原文档 52 | [http://nginx.org/en/docs/http/ngx_http_f4f_module.html](http://nginx.org/en/docs/http/ngx_http_f4f_module.html) -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | Nginx 3 |

Nginx 中文文档

4 |
5 | 6 | Nginx 官方文档中文翻译版，由本人在学习 nginx 时顺带翻译。因部分章节涉及到 Nginx Plus 或者其他内容，我将忽略该部分章节的内容。 7 | 8 | > 文档前期翻译得比较粗糙，而且是基于旧版文档对照翻译，可能存在许多不当和错误之处，之后会慢慢修正和校对。 9 | 10 | 如果您发现内容存在错误或者不当之处，欢迎提出 issue 或 PR，期待您的加入：[如何贡献](CONTRIBUTING.md)。 11 | 12 | 在线阅读：[Github](https://github.com/DocsHome/nginx-docs/blob/master/SUMMARY.md) | [GitBook](https://www.gitbook.com/book/docshome/nginx-docs/details) 13 | 14 | ## 安装 15 | 16 | 如果你没有安装 gitbook，则先使用 npm（或者 cnpm）安装 `gitbook-cli`： 17 | 18 | ```bash 19 | npm install gitbook-cli -g 20 | ``` 21 | 22 | 进入项目根目录，执行以下命令运行 gitbook： 23 | 24 | **安装依赖** 25 | 26 | ```bash 27 | gitbook install 28 | ``` 29 | 30 | **启动本地服务器** 31 | 32 | ```bash 33 | gitbook serve 34 | ``` 35 | 36 | **生成 HTML 文件，存放在 `_book` 目录下** 37 | 38 | ``` 39 | gitbook build 40 | ``` 41 | 42 | 更多操作命令，请参照 GitBook 命令。 43 | 44 | ## 项目状态 45 | 46 | 翻译中…… 47 | 48 | ## 排版规范 49 | 50 | 本项目排版遵循 [中文排版指南](https://github.com/mzlogin/chinese-copywriting-guidelines) 规范。 51 | 52 | ## LICENSE 53 | 54 | ![知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png) 55 | 56 | 本作品采用[知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](http://creativecommons.org/licenses/by-nc-sa/4.0/)进行许可。 57 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_realip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_realip_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [set_real_ip_from](#set_real_ip_from) 6 | - [内嵌变量](#embedded_variables) 7 | 8 | `ngx_stream_realip_module` 模块用于将客户端地址和端口更改为 PROXY 协议头（1.11.4）中发送。必须先在 `listen` 指令中设置 [proxy_protocol](ngx_stream_core_module.md#proxy_protocol) 参数才能启用 PROXY 协议。 9 | 10 | 该模块不是默认构建的，您可以在构建时使用 `--with-stream_realip_module` 配置参数启用。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | listen 12345 proxy_protocol; 18 | 19 | set_real_ip_from 192.168.1.0/24; 20 | set_real_ip_from 192.168.2.1; 21 | set_real_ip_from 2001:0db8::/32; 22 | ``` 23 | 24 | 25 | 26 | ## 指令 27 | 28 | ### set_real_ip_from 29 | 30 | |\-|说明| 31 | |------:|------| 32 | |**语法**|**set_real_ip_from** `address` \| `CIDR` \| `unix:`;| 33 | |**默认**|——| 34 | |**上下文**|stream、server| 35 | 36 | 定义已知可发送正确替换地址的受信任地址。如果指定了特殊值 `unix:`，则所有 UNIX 域套接字将被信任。 37 | 38 | 39 | 40 | ## 内嵌变量 41 | 42 | - `$realip_remote_addr` 43 | 44 | 保留原始客户端地址 45 | - `$realip_remote_port` 46 | 47 | 保留原始的客户端端口 48 | 49 | ## 原文档 50 | [http://nginx.org/en/docs/stream/ngx_stream_realip_module.html](http://nginx.org/en/docs/stream/ngx_stream_realip_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_split_clients_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_split_clients_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [split_clients](#split_clients) 6 | 7 | `ngx_http_split_clients_module` 模块用于创建适用于 A/B 测试的变量，也称为拆分测试。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | http { 15 | split_clients "${remote_addr}AAA" $variant { 16 | 0.5% .one; 17 | 2.0% .two; 18 | * ""; 19 | } 20 | 21 | server { 22 | location / { 23 | index index${variant}.html; 24 | ``` 25 | 26 | 27 | 28 | ## 指令 29 | 30 | ### split_clients 31 | 32 | |\-|说明| 33 | |:------|:------| 34 | |**语法**|**split_clients** `string $variable { ... }`;| 35 | |**默认**|——| 36 | |**上下文**|http| 37 | 38 | 创建一个用于 A/B 测试的变量。 39 | 40 | ```nginx 41 | split_clients "${remote_addr}AAA" $variant { 42 | 0.5% .one; 43 | 2.0% .two; 44 | * ""; 45 | } 46 | ``` 47 | 48 | 使用 MurmurHash2 对原始字符串的值进行哈希处理。在以上示例中，哈希值从 0 到 21474835（0.5％）对应 `$variant` 变量的值为 `.one`，哈希值从 21474836 到 107374180（2％）对应的值为 `.two`，哈希值从 107374181 到 4294967295 对应值为 `""`（空字符串）。 49 | 50 | ## 原文档 51 | [http://nginx.org/en/docs/http/ngx_http_split_clients_module.html](http://nginx.org/en/docs/http/ngx_http_split_clients_module.html) 52 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_gunzip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_gunzip_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [gunzip](#gunzip) 6 | - [gunzip_buffers](#gunzip_buffers) 7 | 8 | `ngx_http_gunzip_module` 模块是一个过滤器，用于对不支持 **gzip** 编码方法的客户端解压缩 `Content-Encoding：gzip` 的响应。当需要存储压缩数据以节省空间并降低 I/O 成本时，该模块将非常有用。 9 | 10 | 此模块不是默认构建，您可以使用 `--with-http_gunzip_module` 配置参数启用。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | location /storage/ { 18 | gunzip on; 19 | ... 20 | } 21 | ``` 22 | 23 | 24 | 25 | ## 指令 26 | 27 | ### gunzip 28 | 29 | |\-|说明| 30 | |------:|------| 31 | |**语法**|**gunzip** `on` | `off`;| 32 | |**默认**|gunzip off;| 33 | |**上下文**|http、server、location| 34 | 35 | 对缺少 gzip 支持的客户端启用或禁用 gzip 响应解压缩。如果开启，在确定客户端是否支持 gzip 时还会考虑以下指令：[gzip_http_version](ngx_http_gzip_module.md#gzip_http_version)、[gzip_proxied](ngx_http_gzip_module.md#gzip_proxied) 和 [gzip_disable](ngx_http_gzip_module.md#gzip_disable)。另请参阅 [gzip_vary](ngx_http_gzip_module.md#gzip_vary) 指令。 36 | 37 | ### gunzip_buffers 38 | 39 | |\-|说明| 40 | |------:|------| 41 | |**语法**|**gunzip_buffers** `number size`;| 42 | |**默认**|gunzip_buffers 32 4k|16 8k;| 43 | |**上下文**|http、server、location| 44 | 45 | 设置用于解压响应的缓冲区的数量（`number`）和大小（`size`）。默认情况下，缓冲区大小等于一个内存页（4K 或 8K，取决于平台）。 46 | 47 | ## 原文档 48 | [http://nginx.org/en/docs/http/ngx_http_gunzip_module.html](http://nginx.org/en/docs/http/ngx_http_gunzip_module.html) -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_split_clients_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_split_clients_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [split_clients](#split_clients) 6 | 7 | `ngx_stream_split_clients_module` 模块（1.11.3）创建适用于 A/B 测试的变量，也称为拆分测试。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | stream { 15 | ... 16 | split_clients "${remote_addr}AAA" $upstream { 17 | 0.5% feature_test1; 18 | 2.0% feature_test2; 19 | * production; 20 | } 21 | 22 | server { 23 | ... 24 | proxy_pass $upstream; 25 | } 26 | } 27 | ``` 28 | 29 | 30 | 31 | ## 指令 32 | 33 | ### split_clients 34 | 35 | |\-|说明| 36 | |------:|------| 37 | |**语法**|**split_clients** `string $variable { ... }`| 38 | |**默认**|——| 39 | |**上下文**|stream| 40 | 41 | 为 A/B 测试创建一个变量，例如： 42 | 43 | ```nginx 44 | split_clients "${remote_addr}AAA" $variant { 45 | 0.5% .one; 46 | 2.0% .two; 47 | * ""; 48 | } 49 | ``` 50 | 51 | 使用 MurmurHash2 对原始字符串的值进行哈希处理。在给出的例子中，从 0 到 21474835 （0.5％）的哈希值对应于 `$variant` 变量的值 `.one`，从 21474836 到 107374180 （2％）的哈希值对应于值 `.two`，哈希值从 107374181 到 4294967295 对应于值 `""`（空字符串）。 52 | 53 | ## 原文档 54 | [http://nginx.org/en/docs/stream/ngx_stream_split_clients_module.html](http://nginx.org/en/docs/stream/ngx_stream_split_clients_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_keyval_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_keyval_module 2 | 3 | - [指令](#directives) 4 | - [keyval](#keyval) 5 | - [keyval_zone](#keyval_zone) 6 | 7 | `ngx_http_keyval_module` 模块（1.13.3）创建的带值变量从 [API](ngx_http_api_module.md#http_keyvals_) 管理的键值对中获取。 8 | 9 | > 该模块可作为我们[商业订阅](http://nginx.com/products/?_ga=2.259594698.1917722686.1520954456-1859001452.1520648382)的一部分。 10 | 11 | 12 | 13 | ## 示例配置 14 | 15 | ```nginx 16 | http { 17 | 18 | keyval_zone zone=one:32k state=one.keyval; 19 | keyval $arg_text $text zone=one; 20 | ... 21 | server { 22 | ... 23 | location / { 24 | return 200 $text; 25 | } 26 | 27 | location /api { 28 | api write=on; 29 | } 30 | } 31 | } 32 | ``` 33 | 34 | 35 | 36 | ## 指令 37 | 38 | ### keyval 39 | 40 | |\-|说明| 41 | |------:|------| 42 | |**语法**|**keyval** `key $variable zone=name`;| 43 | |**默认**|——| 44 | |**上下文**|http| 45 | 46 | 创建一个新的变量 `$variable`，该变量的值从键值数据库中通过 `key` 查找。字符串匹配忽略大小写。数据库存储在 `zone` 参数指定的共享内存区域中。 47 | 48 | ### keyval_zone 49 | 50 | |\-|说明| 51 | |------:|------| 52 | |**语法**|**keyval_zone** `zone=name:size [state=file]`;| 53 | |**默认**|——| 54 | |**上下文**|http| 55 | 56 | 设置保存键值数据库的共享内存区域的名称（`name`）和大小（`size`）。键值对由 [API](ngx_http_api_module.md#http_keyvals_) 管理。 57 | 58 | 可选的 `state` 参数指定一个文件，该文件将键值数据库的当前状态保持为 JSON 格式，并使其在 nginx 重启时保持不变。 59 | 60 | ## 原文档 61 | 62 | [http://nginx.org/en/docs/http/ngx_http_keyval_module.html](http://nginx.org/en/docs/http/ngx_http_keyval_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_addition_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_addition_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [add_before_body](#add_before_body) 6 | - [add_after_body](#add_after_body) 7 | - [addition_types](#addition_types) 8 | 9 | `ngx_http_addition_module` 是一个过滤器，用于在响应之前和之后添加文本。该模块不是默认构建，要启用应使用 `--with-http_addition_module` 配置参数构建。 10 | 11 | 12 | 13 | ## 示例配置 14 | ```nginx 15 | location / { 16 | add_before_body /before_action; 17 | add_after_body /after_action; 18 | } 19 | ``` 20 | 21 | 22 | 23 | ## 指令 24 | 25 | ### add_before_body 26 | 27 | |\-|说明| 28 | |:------|:------| 29 | |**语法**|**add_before_body** `uri`;| 30 | |**默认**|——| 31 | |**上下文**|http、server、location| 32 | 33 | 在响应正文之前添加文本，作为给定子请求的一个处理结果返回。空字符串（`""`）作为参数时将取消从先前配置级别继承的额外文本。 34 | 35 | ### add_after_body 36 | 37 | |\-|说明| 38 | |:------|:------| 39 | |**语法**|**add_after_body** `uri`;| 40 | |**默认**|——| 41 | |**上下文**|http、server、location| 42 | 43 | 在响应正文之后添加文本，作为给定子请求的一个处理结果返回。空字符串（`""`）作为参数时将取消从先前配置级别继承的额外文本。 44 | 45 | ### addition_types 46 | 47 | |\-|说明| 48 | |:------|:------| 49 | |**语法**|**addition_types** `mime-type ...`;| 50 | |**默认**|addition_types text/html;| 51 | |**上下文**|http、server、location| 52 | |**提示**|该指令在 0.7.9 版本中出现| 53 | 54 | 除了 `text/html` 外，允许您在指定的 MIME 类型的响应中添加文本。特殊值 `*` 匹配所有 MIME类型（0.8.29）。 55 | 56 | ## 原文档 57 | 58 | [http://nginx.org/en/docs/http/ngx_http_addition_module.html](http://nginx.org/en/docs/http/ngx_http_addition_module.html) 59 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_slice_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_slice_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [slice](#slice) 6 | - [内嵌变量](#embedded_variables) 7 | 8 | `ngx_http_slice_module` 模块（1.9.8）是一个过滤器，它将请求拆分为子请求，每个子请求都返回一定范围的响应。该过滤器针对大响应缓存更加有效。 9 | 10 | 默认情况下不构建此模块，可在构建 nginx 时使用 `--with-http_slice_module` 配置参数启用。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | location / { 18 | slice 1m; 19 | proxy_cache cache; 20 | proxy_cache_key $uri$is_args$args$slice_range; 21 | proxy_set_header Range $slice_range; 22 | proxy_cache_valid 200 206 1h; 23 | proxy_pass http://localhost:8000; 24 | } 25 | ``` 26 | 27 | 在此示例中，响应被拆分为 1M 大小的可缓存切片。 28 | 29 | 30 | 31 | ## 指令 32 | 33 | ### slice 34 | 35 | |\-|说明| 36 | |:------|:------| 37 | |**语法**|**slice** `size`;| 38 | |**默认**|slice 0;| 39 | |**上下文**|http、server、location| 40 | 41 | 设置切片的 `size`（大小）。零值禁止将响应拆分为切片。请注意，值太低可能会导致内存使用过多并打开大量文件。 42 | 43 | 为了使子请求返回所需的范围，`$slice_range` 变量应作为 Range 请求头字段[传递](ngx_http_proxy_module.md#proxy_set_header)给代理服务器。如果启用了缓存，则应将 `$slice_range` 添加到[缓存键](ngx_http_proxy_module.md#proxy_cache_key)，并启用 206 状态代码的响应缓存。 44 | 45 | 46 | 47 | ## 内嵌变量 48 | 49 | `ngx_http_slice_module` 模块支持以下内嵌变量： 50 | 51 | - `$slice_range` 52 | 53 | [HTTP 字节范围](https://tools.ietf.org/html/rfc7233#section-2.1)格式的当前切片范围，例如：`bytes=0-1048575`。 54 | 55 | ## 原文档 56 | [http://nginx.org/en/docs/http/ngx_http_slice_module.html](http://nginx.org/en/docs/http/ngx_http_slice_module.html) 57 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_ssl_preread_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_ssl_preread_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [ssl_preread](#ssl_preread) 6 | - [内嵌变量](#embedded_variables) 7 | 8 | `ngx_stream_ssl_preread_module` 模块（1.11.5）允许从 [ClientHello](ClientHello) 消息中提取信息，而不会终止 SSL/TLS，例如提取通过 [SNI](https://tools.ietf.org/html/rfc6066#section-3) 请求的服务器名称。默认情况下不构建此模块，您可以在构建时使用 `--with-stream_ssl_preread_module` 配置参数启用此模块。 9 | 10 | 11 | 12 | ## 示例配置 13 | 14 | ```nginx 15 | map $ssl_preread_server_name $name { 16 | backend.example.com backend; 17 | default backend2; 18 | } 19 | 20 | upstream backend { 21 | server 192.168.0.1:12345; 22 | server 192.168.0.2:12345; 23 | } 24 | 25 | upstream backend2 { 26 | server 192.168.0.3:12345; 27 | server 192.168.0.4:12345; 28 | } 29 | 30 | server { 31 | listen 12346; 32 | proxy_pass $name; 33 | ssl_preread on; 34 | } 35 | ``` 36 | 37 | 38 | 39 | ## 指令 40 | 41 | ### google_perftools_profiles 42 | 43 | |\-|说明| 44 | |------:|------| 45 | |**语法**|**ssl_preread** `on` \| `off`;| 46 | |**默认**|ssl_preread off;| 47 | |**上下文**|stream、server| 48 | 49 | 启用在[预读阶段](stream_processing.md#preread_phase) 从 ClientHello 消息中提取信息。 50 | 51 | 52 | 53 | ## 内嵌变量 54 | 55 | - `$ssl_preread_server_name` 56 | 57 | 返回通过 SNI 请求的服务器名称 58 | 59 | ## 原文档 60 | [http://nginx.org/en/docs/ngx_google_perftools_module.html](http://nginx.org/en/docs/ngx_google_perftools_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_access_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_access_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [allow](#allow) 6 | - [deny](#deny) 7 | 8 | `ngx_http_access_module` 模块允许限制对某些客户端地址的访问。 9 | 10 | 访问也可以通过[密码](ngx_http_auth_basic_module.md)、[子请求结果](ngx_http_auth_request_module.md)或 [JWT](ngx_http_auth_jwt_module.md) 限制。可用 [satisfy](ngx_http_core_module.md#satisfy) 指令通过地址和密码同时限制访问。 11 | 12 | 13 | 14 | ## 示例配置 15 | ```nginx 16 | location / { 17 | deny 192.168.1.1; 18 | allow 192.168.1.0/24; 19 | allow 10.1.1.0/16; 20 | allow 2001:0db8::/32; 21 | deny all; 22 | } 23 | ``` 24 | 25 | 按顺序检查规则，直到找到第一个匹配项。在本例中，仅允许 IPv4 网络 `10.1.1.0/16` 和 `192.168.1.0/24` 与 IPv6 网络 `2001:0db8::/ 32` 访问，不包括地址 `192.168.1.1`。在很多规则的情况下，最好使用 [ngx_http_geo_module](ngx_http_geo_module.md) 模块变量。 26 | 27 | 28 | 29 | ## 指令 30 | 31 | ### allow 32 | 33 | |\-|说明| 34 | |:------|:------| 35 | |**语法**|**allow** `address` | `CIDR` | `unix:` | `all`;| 36 | |**默认**|——| 37 | |**上下文**|http、server、location、limit_except| 38 | 39 | 允许访问指定的网络或地址。如果指定了特殊值 `unix:`（1.5.1），则允许访问所有 UNIX 域套接字。 40 | 41 | ### deny 42 | 43 | |\-|说明| 44 | |:------|:------| 45 | |**语法**|**deny** `address` | `CIDR` | `unix:` | `all`;| 46 | |**默认**|——| 47 | |**上下文**|http、server、location、limit_except| 48 | 49 | 拒绝指定网络或地址的访问。如果指定了特殊值 `unix:`（1.5.1），则拒绝所有 UNIX 域套接字的访问。 50 | 51 | ## 原文档 52 | 53 | [http://nginx.org/en/docs/http/ngx_http_access_module.html](http://nginx.org/en/docs/http/ngx_http_access_module.html) 54 | -------------------------------------------------------------------------------- /模块参考/mail/ngx_mail_smtp_module.md: -------------------------------------------------------------------------------- 1 | # ngx_mail_smtp_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [ngx_mail_smtp_module](#ngx_mail_smtp_module) 6 | - [smtp_capabilities](#smtp_capabilities) 7 | 8 | 9 | 10 | ## 指令 11 | 12 | ### smtp_auth 13 | 14 | |\-|说明| 15 | |------:|------| 16 | |**语法**|**smtp_auth** `method ...`;| 17 | |**默认**|smtp_auth login plain;| 18 | |**上下文**|mail、server| 19 | 20 | 为 SMTP 客户端设置 [SASL 认证](https://tools.ietf.org/html/rfc2554) 的允许方法。支持的方法有： 21 | 22 | - `login` 23 | 24 | [AUTH LOGIN](https://tools.ietf.org/html/draft-murchison-sasl-login-00) 25 | - `plain` 26 | 27 | [AUTH PLAIN](https://tools.ietf.org/html/rfc4616) 28 | - `cram-md5` 29 | 30 | [AUTH CRAM-MD5](https://tools.ietf.org/html/rfc2195)。为了使此方法正常工作，密码不加密存储。 31 | - `external` 32 | 33 | [AUTH EXTERNAL](https://tools.ietf.org/html/rfc4422)（1.11.6）。 34 | - `none` 35 | 36 | 不需要验证 37 | 38 | ### smtp_capabilities 39 | 40 | |\-|说明| 41 | |------:|------| 42 | |**语法**|**smtp_capabilities** `extension ...`;| 43 | |**默认**|——| 44 | |**上下文**|mail、server| 45 | 46 | 设置传送给客户端响应 `EHLO` 命令的 SMTP 协议扩展列表。根据 [starttls](ngx_mail_ssl_module.md#starttls) 指令值，[smtp_auth](ngx_mail_smtp_module.md#smtp_auth) 指令和 [STARTTLS](https://tools.ietf.org/html/rfc3207) 中指定的认证方法将自动添加到此列表中。 47 | 48 | 指定被代理客户端的 MTA 支持扩展是有意义的（当 nginx 透明地将客户端连接代理到后端，如果这些扩展与认证后使用的命令相关）。 49 | 50 | 目前的标准扩展名单已发布在 [www.iana.org](http://www.iana.org/assignments/mail-parameters)。 51 | 52 | ## 原文档 53 | [http://nginx.org/en/docs/mail/ngx_mail_smtp_module.html](http://nginx.org/en/docs/mail/ngx_mail_smtp_module.html) -------------------------------------------------------------------------------- /模块参考/mail/ngx_mail_pop3_module.md: -------------------------------------------------------------------------------- 1 | # ngx_mail_pop3_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [pop3_auth](#pop3_auth) 6 | - [pop3_capabilities](#pop3_capabilities) 7 | 8 | 9 | 10 | ## 指令 11 | 12 | ### pop3_auth 13 | 14 | |\-|说明| 15 | |------:|------| 16 | |**语法**|**pop3_auth** `method ...`;| 17 | |**默认**|pop3_auth plain;| 18 | |**上下文**|mail、server| 19 | 20 | 为 POP3 客户端设置允许的认证方法。支持的方法有： 21 | 22 | - `plain` 23 | 24 | [USER/PASS](https://tools.ietf.org/html/rfc1939)、[AUTH PLAIN](https://tools.ietf.org/html/rfc4616)、[AUTH LOGIN](https://tools.ietf.org/html/draft-murchison-sasl-login-00)。不可能禁用这些方法。 25 | - `apop` 26 | 27 | [APOP](https://tools.ietf.org/html/rfc1939)。为了使此方法正常工作，密码不能加密存储。 28 | - `cram-md5` 29 | 30 | [AUTH CRAM-MD5](https://tools.ietf.org/html/rfc2195)。为了使此方法正常工作，密码不能加密存储。 31 | 32 | - `external` 33 | 34 | [AUTH EXTERNAL](https://tools.ietf.org/html/rfc4422)（1.11.6）。 35 | 36 | ### pop3_capabilities 37 | 38 | |\-|说明| 39 | |------:|------| 40 | |**语法**|**pop3_capabilities** `extension ...`;| 41 | |**默认**|pop3_capabilities TOP USER UIDL;| 42 | |**上下文**|mail、server| 43 | 44 | 设置响应 `CAPA` 命令传送给客户端的 [POP3 协议](https://tools.ietf.org/html/rfc2449) 扩展列表。根据 [starttls](ngx_mail_ssl_module.md#starttls) 指令值，[pop3_auth](#pop3_auth) 指令（[SASL](https://tools.ietf.org/html/rfc2449) 扩展）和 [STLS](https://tools.ietf.org/html/rfc2595) 中指定的认证方法将自动添加到此列表。 45 | 46 | 指定客户端代理的 POP3 后端支持的扩展（当 nginx 透明地代理到后端的客户端连接，如果这些扩展与认证后使用的命令相关），则是有意义的。 47 | 48 | ## 原文档 49 | [http://nginx.org/en/docs/mail/ngx_mail_pop3_module.html](http://nginx.org/en/docs/mail/ngx_mail_pop3_module.html) -------------------------------------------------------------------------------- /How-To/WebSocket代理.md: -------------------------------------------------------------------------------- 1 | # WebSocket 代理 2 | 3 | 要将客户端与服务器之间的连接从 HTTP/1.1 转换为 WebSocket，可是使用 HTTP/1.1 中的 [协议切换](https://tools.ietf.org/html/rfc2616#section-14.42) 机制。 4 | 5 | 然而，有一个微妙的地方：由于 `Upgrade` 是一个[逐跳](https://tools.ietf.org/html/rfc2616#section-13.5.1)（hop-by-hop）头，它不会从客户端传递到代理服务器。当使用转发代理时，客户端可以使用 `CONNECT` 方法来规避此问题。然而，这不适用于反向代理，因为客户端不知道任何代理服务器，这需要在代理服务器上进行特殊处理。 6 | 7 | 自 1.3.13 版本以来，nginx 实现了特殊的操作模式，如果代理服务器返回一个 101响应码（交换协议），则客户机和代理服务器之间将建立隧道，客户端 通过请求中的 `Upgrade` 头来请求协议交换。 8 | 9 | 如上所述，包括 `Upgrade` 和 `Connection` 的逐跳头不会从客户端传递到代理服务器，因此为了使代理服务器知道客户端将协议切换到 WebSocket 的意图，这些头必须明确地传递： 10 | 11 | ```nginx 12 | location /chat/ { 13 | proxy_pass http://backend; 14 | proxy_http_version 1.1; 15 | proxy_set_header Upgrade $http_upgrade; 16 | proxy_set_header Connection "upgrade"; 17 | } 18 | ``` 19 | 20 | 一个更复杂的例子是，对代理服务器的请求中的 `Connection` 头字段的值取决于客户端请求头中的 `Upgrade` 字段的存在： 21 | 22 | ```nginx 23 | http { 24 | map $http_upgrade $connection_upgrade { 25 | default upgrade; 26 | '' close; 27 | } 28 | 29 | server { 30 | ... 31 | 32 | location /chat/ { 33 | proxy_pass http://backend; 34 | proxy_http_version 1.1; 35 | proxy_set_header Upgrade $http_upgrade; 36 | proxy_set_header Connection $connection_upgrade; 37 | } 38 | } 39 | ``` 40 | 41 | 默认情况下，如果代理务器在 60 秒内没有传输任何数据，连接将被关闭。这个超时可以通过 [proxy_read_timeout](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) 指令来增加。 或者，代理服务器可以配置为定期发送 WebSocket ping 帧以重置超时并检查连接是否仍然活跃。 42 | 43 | ## 原文档 44 | 45 | [http://nginx.org/en/docs/http/websocket.html](http://nginx.org/en/docs/http/websocket.html) 46 | -------------------------------------------------------------------------------- /介绍/记录日志到syslog.md: -------------------------------------------------------------------------------- 1 | # 记录日志到 syslog 2 | 3 | [error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log) 和 [access_log](http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) 指令支持把日志记录到 syslog。以下配置参数将使 nginx 日志记录到 syslog： 4 | 5 | ```yaml 6 | server=address 7 | ``` 8 | > 定义 syslog 服务器的地址，可以将该地址指定为附带可选端口的域名或者 IP，或者指定为 “unix:” 前缀之后跟着一个特定的 UNIX 域套接字路径。如果没有指定端口，则使用 UDP 的 514 端口。如果域名解析为多个 IP 地址，则使用第一个地址。 9 | 10 | 11 | 12 | ``` 13 | facility=string 14 | ``` 15 | 16 | > 设置 syslog 的消息 facility（设备），[RFC3164](https://tools.ietf.org/html/rfc3164#section-4.1.1) 中定义，facility可以是 `kern`，`user`，`mail`，`daemon`，`auth`，`intern`，`lpr`，`news`，`uucp`，`clock`，`authpriv`，`ftp`，`ntp`，`audit`，`alert`，`cron`，`local0`，`local7` 中的一个，默认是 `local7`。 17 | 18 | ``` 19 | severity=string 20 | ``` 21 | 22 | > 设置 [access_log](http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) 的消息严重程度，在 [RFC3164](https://tools.ietf.org/html/rfc3164#section-4.1.1) 中定义。可能值与 [error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log) 指令的第二个参数（ `level`，级别）相同，默认是 `info`。错误消息的严重程度由 nginx 确定，因此在 `error_log` 指令中将忽略该参数。 23 | 24 | ``` 25 | tag=string 26 | ``` 27 | > 设置 syslog 消息标签。默认是 `nginx`。 28 | 29 | ``` 30 | nohostname 31 | ``` 32 | > 禁止将 `hostname` 域添加到 syslog 的消息（1.9.7）头中。 33 | 34 | syslog配置示例： 35 | 36 | ```nginx 37 | error_log syslog:server=192.168.1.1 debug; 38 | 39 | access_log syslog:server=unix:/var/log/nginx.sock,nohostname; 40 | access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=nginx,severity=info combined; 41 | ``` 42 | 43 | 记录日志到 syslog 的功能自从 1.7.2 版本开始可用。作为我们 [商业订阅](http://nginx.com/products/?_ga=2.80571039.986778370.1500745948-1890203964.1497190280) 的一部分，记录日志到 syslog 的功能从 1.5.3 开始可用。 44 | 45 | ## 原文档 46 | 47 | - [http://nginx.org/en/docs/syslog.html](http://nginx.org/en/docs/syslog.html) 48 | -------------------------------------------------------------------------------- /介绍/Windows下的Nginx.md: -------------------------------------------------------------------------------- 1 | # Windows 下的 nginx 2 | 3 | [已知问题](#已知问题) 4 | [以后可能的发展](#以后可能的发展) 5 | 6 | Nginx 的 Windows 版本使用了本地的 Win32 API（而不是 Cygwin 模拟层）。目前仅使用 `select()` 和 `poll()` (1.15.9) 连接处理方式。由于此版本和其他存在已知的问题的 Nginx Windows 版本都被认为是 beta 版本，因此您不应该期望它具有高性能和可扩展性。现在，它提供了与 Unix 版本的 nginx 几乎相同的功能，除了 XSLT 过滤器、图像过滤器、GeoIP 模块和嵌入式 Perl 语言。 7 | 8 | 9 | 10 | 要安装 nginx 的 Windows 版本，请 [下载](http://nginx.org/en/download.html) 最新的主线发行版（1.17.2），因为 nginx 的主线分支包含了所有已知的补丁。之后解压文件到 `nginx-1.17.2` 目录下，然后运行 `nginx`。以下是 `C盘` 的根目录： 11 | 12 | ```bash 13 | cd c:\ 14 | unzip nginx-1.17.2.zip 15 | cd nginx-1.17.2 16 | start nginx 17 | ``` 18 | 19 | 运行 `tasklist` 命令行工具查看 nginx 进程： 20 | 21 | ```bash 22 | C:\nginx-1.17.2>tasklist /fi "imagename eq nginx.exe" 23 | 24 | Image Name PID Session Name Session# Mem Usage 25 | =============== ======== ============== ========== ============ 26 | nginx.exe 652 Console 0 2 780 K 27 | nginx.exe 1332 Console 0 3 112 K 28 | ``` 29 | 其中有一个是主进程（master），另一个是工作进程（worker）。如果 nginx 未能启动，请在错误日志 `logs\error.log` 中查找原因。如果日志文件尚未创建，可以在 Windows 事件日志中查找原因。如果显示的页面为错误页面，而不是预期结果，也可以在 `logs\error.log` 中查找原因。 30 | 31 | Nginx 的 Windows 版本使用运行目录作为配置文件中的相对路径前缀。在上面的例子中，前缀是 `C:\nginx-1.17.2\`。在配置文件中的路径必须使类 Unix 风格的正斜杠： 32 | 33 | ```nginx 34 | access_log logs/site.log; 35 | root C:/web/html; 36 | ``` 37 | Nginx 的 Windows 版本作为标准的控制台应用程序（而不是服务）运行，可以使用以下命令进行管理： 38 | 39 | - `nginx -s stop` 快速退出 40 | - `nginx -s quit` 正常退出 41 | - `nginx -s reload` 重新加载配置文件，使用新的配置启动工作进程，正常关闭旧的工作进程 42 | - `nginx -s reopen` 重新打开日志文件 43 | 44 | ## 已知问题 45 | - 虽然可以启动多个工作进程，但实际上只有一个工作进程做完全部的工作 46 | - 不支持 UDP 代理功能 47 | 48 | ## 以后可能的发展 49 | - 作为服务运行 50 | - 使用 I/O 完成端口作为连接处理方式 51 | - 在单个工作进程中使用多个工作线程 52 | 53 | ## 原文档 54 | 55 | [http://nginx.org/en/docs/windows.html](http://nginx.org/en/docs/windows.html) 56 | -------------------------------------------------------------------------------- /模块参考/mail/ngx_mail_imap_module.md: -------------------------------------------------------------------------------- 1 | # ngx_mail_imap_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [imap_auth](#imap_auth) 6 | - [imap_capabilities](#imap_capabilities) 7 | - [imap_client_buffer](#imap_client_buffer) 8 | 9 | 10 | 11 | ## 指令 12 | 13 | ### imap_auth 14 | 15 | |\-|说明| 16 | |------:|------| 17 | |**语法**|**imap_auth** `method ...`;| 18 | |**默认**|imap_auth plain;| 19 | |**上下文**|mail、server| 20 | 21 | 为 IMAP 客户端设置允许的认证方法。支持的方法有： 22 | 23 | - `login` 24 | 25 | [AUTH=LOGIN](https://tools.ietf.org/html/draft-murchison-sasl-login-00) 26 | - `plain` 27 | 28 | [AUTH=PLAIN](https://tools.ietf.org/html/rfc4616) 29 | - `cram-md5` 30 | 31 | [AUTH=CRAM-MD5](https://tools.ietf.org/html/rfc2195)。为了使此方法正常工作，密码不能加密存储。 32 | 33 | - `external` 34 | 35 | [AUTH EXTERNAL](https://tools.ietf.org/html/rfc4422)（1.11.6）。 36 | 37 | ### imap_capabilities 38 | 39 | |\-|说明| 40 | |------:|------| 41 | |**语法**|**imap_capabilities** `extension ...`;| 42 | |**默认**|imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;| 43 | |**上下文**|mail、server| 44 | 45 | 设置响应 `CAPABILITY` 命令传递给客户端的 [IMAP 协议](https://tools.ietf.org/html/rfc3501) 扩展列表。根据 [starttls](ngx_mail_ssl_module.md#starttls) 指令值，[imap_auth](#imap_auth) 指令和 [STARTTLS](https://tools.ietf.org/html/rfc2595) 中指定的认证方法将自动添加到此列表中。 46 | 47 | 指定被代理客户端的 IMAP 后端支持的扩展（当 nginx 透明地代理到后端的客户端连接，如果这些扩展与认证后使用的命令相关），则是有意义的。 48 | 49 | 目前的标准扩展名单已发布在 [www.iana.org](http://www.iana.org/assignments/imap4-capabilities)。 50 | 51 | ### imap_client_buffer 52 | 53 | |\-|说明| 54 | |------:|------| 55 | |**语法**|**imap_client_buffer** `size`;| 56 | |**默认**|imap_client_buffer 4k|8k;| 57 | |**上下文**|mail、server| 58 | 59 | 设置 IMAP 命令读取缓冲区大小。默认情况下，缓冲区大小等于一个内存页面。4K 或 8K，取决于平台。 60 | 61 | ## 原文档 62 | [http://nginx.org/en/docs/mail/ngx_mail_imap_module.html](http://nginx.org/en/docs/mail/ngx_mail_imap_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_auth_request_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_auth_request_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [auth_request](#auth_request) 6 | - [auth_request_set](#auth_request_set) 7 | 8 | `ngx_http_auth_request_module` 模块（1.5.4+）基于子请求结果实现客户端授权。如果子请求返回一个 2xx 响应代码，则允许访问。如果返回 401 或 403，则拒绝访问并抛出相应的错误代码。子请求返回的任何其他响应代码被认为是一个错误。 9 | 10 | 对于 401 错误，客户端也从子请求响应中接收 **WWW-Authenticate** 头。 11 | 12 | 该模块不是默认构建，应该在构建时使用 `--with-http_auth_request_module` 配置参数启用。 13 | 14 | 该模块可以通过 [satisfy](ngx_http_core_module.md#satisfy) 指令与其他访问模块（如 [ngx_http_access_module](ngx_http_access_module.md)、[ngx_http_auth_basic_module](ngx_http_auth_basic_module.md) 和 [ngx_http_auth_jwt_module](ngx_http_auth_jwt_module.md)）进行组合。 15 | 16 | > 在 1.7.3 版本之前，无法缓存对授权子请求的响应（使用 [proxy_cache](ngx_http_proxy_module.html#proxy_cache)、[proxy_store](ngx_http_proxy_module.html#proxy_store) 等）。 17 | 18 | 19 | 20 | ## 示例配置 21 | ```nginx 22 | location /private/ { 23 | auth_request /auth; 24 | ... 25 | } 26 | 27 | location = /auth { 28 | proxy_pass ... 29 | proxy_pass_request_body off; 30 | proxy_set_header Content-Length ""; 31 | proxy_set_header X-Original-URI $request_uri; 32 | } 33 | ``` 34 | 35 | 36 | 37 | ## 指令 38 | 39 | ### auth_request 40 | 41 | |\-|说明| 42 | |:------|:------| 43 | |**语法**|**auth_request** `uri` | `off`;| 44 | |**默认**|auth_request off;| 45 | |**上下文**|http、server、location| 46 | 47 | 启用基于子请求结果的授权，并设置发送子请求的 URI。 48 | 49 | ### auth_request_set 50 | 51 | |\-|说明| 52 | |:------|:------| 53 | |**语法**|**auth_request_set** `$variable value;`;| 54 | |**默认**|——| 55 | |**上下文**|http| 56 | 57 | 在授权请求完成后，将请求 `variable`（变量）设置为给定的 `value`（值）。该值可能包含授权请求中的变量，例如 `$upstream_http_*`。 58 | 59 | ## 原文档 60 | [http://nginx.org/en/docs/http/ngx_http_auth_request_module.html](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) 61 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_mirror_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_mirror_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [mirror](#mirror) 6 | - [mirror_request_body](#mirror_request_body) 7 | 8 | `ngx_http_mirror_module` 模块（1.13.4）通过创建后台镜像子请求来实现原始请求的镜像。镜像子请求的响应将被忽略。 9 | 10 | > 译者注：利用 mirror 模块，业务可以将线上实时访问流量拷贝至其他环境，基于这些流量可以做版本发布前的预先验证，进行流量放大后的压测等等。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | location / { 18 | mirror /mirror; 19 | proxy_pass http://backend; 20 | } 21 | 22 | location /mirror { 23 | internal; 24 | proxy_pass http://test_backend$request_uri; 25 | } 26 | ``` 27 | 28 | 29 | 30 | ## 指令 31 | 32 | ### mirror 33 | 34 | |\-|说明| 35 | |------:|------| 36 | |**语法**|**mirror** `uri` | `off`;| 37 | |**默认**|mirror off;| 38 | |**上下文**|http、server、location| 39 | 40 | 设置将做成镜像的原始请求的 URI。可以在同一层级上指定多个镜像（译者注: 多次重复一个镜像可以实现流量放大）。 41 | 42 | ### mirror_request_body 43 | 44 | |\-|说明| 45 | |------:|------| 46 | |**语法**|**mirror_request_body** `on` | `off`;| 47 | |**默认**|mirror_request_body on;| 48 | |**上下文**|http、server、location| 49 | 50 | 指示是否将客户端请求体做成镜像。启用后，将在创建镜像子请求之前读取客户端请求体。在这种情况下，将禁用由 [proxy_request_buffering](ngx_http_proxy_module.md#proxy_request_buffering)、[fastcgi_request_buffering](ngx_http_fastcgi_module.md#fastcgi_request_buffering)、[scgi_request_buffering](ngx_http_scgi_module.md#scgi_request_buffering) 和 [uwsgi_request_buffering](ngx_http_uwsgi_module.md#uwsgi_request_buffering) 指令设置的未缓冲的客户端请求正代理。 51 | 52 | ```nginx 53 | location / { 54 | mirror /mirror; 55 | mirror_request_body off; 56 | proxy_pass http://backend; 57 | } 58 | 59 | location /mirror { 60 | internal; 61 | proxy_pass http://log_backend; 62 | proxy_pass_request_body off; 63 | proxy_set_header Content-Length ""; 64 | proxy_set_header X-Original-URI $request_uri; 65 | } 66 | ``` 67 | ## 原文档 68 | [http://nginx.org/en/docs/http/ngx_http_mirror_module.html](http://nginx.org/en/docs/http/ngx_http_mirror_module.html) 69 | -------------------------------------------------------------------------------- /How-To/在Win32平台上使用VisualC构建nginx.md: -------------------------------------------------------------------------------- 1 | # 在 Win32 平台上使用 Visual C 构建 nginx 2 | 3 | ## 先决条件 4 | 5 | 要在 Microsoft Win32® 平台上构建 nginx，您需要： 6 | 7 | - Microsoft Visual C编译器。已知 Microsoft Visual Studio® 8 和 10 可以正常工作。 8 | - [MSYS](http://www.mingw.org/wiki/MSYS)。 9 | - 如果您要构建 OpenSSL® 和有 SSL 支持的 nginx，则需要 Perl。例如 [ActivePerl](http://www.activestate.com/activeperl) 或 [Strawberry Perl](http://strawberryperl.com/)。 10 | - [Mercurial](https://www.mercurial-scm.org/) 客户端 11 | - [PCRE](http://www.pcre.org/)、[zlib](http://zlib.net/) 和 [OpenSSL](http://www.openssl.org/) 库源代码。 12 | 13 | ## 构建步骤 14 | 15 | 在开始构建之前，确保将 Perl、Mercurial 和 MSYS 的 bin 目录路径添加到 PATH 环境变量中。从 Visual C 目录运行 vcvarsall.bat 脚本设置 Visual C 环境。 16 | 17 | 构建 nginx： 18 | 19 | - 启动 MSYS bash。 20 | - 检出 hg.nginx.org 仓库中的 nginx 源代码。例如： 21 | 22 | ```bash 23 | hg clone http://hg.nginx.org/nginx 24 | ``` 25 | 26 | - 创建一个 build 和 lib 目录，并将 zlib、PCRE 和 OpenSSL 库源码解压到 lib 目录中： 27 | 28 | ```bash 29 | mkdir objs 30 | mkdir objs/lib 31 | cd objs/lib 32 | tar -xzf ../../pcre-8.41.tar.gz 33 | tar -xzf ../../zlib-1.2.11.tar.gz 34 | tar -xzf ../../openssl-1.0.2k.tar.gz 35 | ``` 36 | 37 | - 运行 configure 脚本： 38 | 39 | ```bash 40 | auto/configure --with-cc=cl --builddir=objs --prefix= \ 41 | --conf-path=conf/nginx.conf --pid-path=logs/nginx.pid \ 42 | --http-log-path=logs/access.log --error-log-path=logs/error.log \ 43 | --sbin-path=nginx.exe --http-client-body-temp-path=temp/client_body_temp \ 44 | --http-proxy-temp-path=temp/proxy_temp \ 45 | --http-fastcgi-temp-path=temp/fastcgi_temp \ 46 | --with-cc-opt=-DFD_SETSIZE=1024 --with-pcre=objs/lib/pcre-8.41 \ 47 | --with-zlib=objs/lib/zlib-1.2.11 --with-openssl=objs/lib/openssl-1.0.2k \ 48 | --with-select_module --with-http_ssl_module 49 | ``` 50 | 51 | - 运行 make： 52 | 53 | ```bash 54 | nmake -f objs/Makefile 55 | ``` 56 | 57 | ## 相关内容 58 | 59 | [Windows 下的 nginx](../介绍/Windows下的Nginx.md) 60 | 61 | ## 原文档 62 | 63 | [http://nginx.org/en/docs/howto_build_on_win32.html](http://nginx.org/en/docs/howto_build_on_win32.html) 64 | -------------------------------------------------------------------------------- /介绍/调试日志.md: -------------------------------------------------------------------------------- 1 | # 调试日志 2 | 3 | - [为指定客户端做调试日志](#为指定客户端做调试日志) 4 | - [记录日志到循环内存缓冲区](#记录日志到循环内存缓冲区) 5 | 6 | 要开启调试日志，需要在编译 Nignx 时增加如下配置： 7 | 8 | ```bash 9 | ./configure --with-debug ... 10 | ``` 11 | 12 | 之后应该使用 [error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log) 指令设置调试级别： 13 | 14 | ```nginx 15 | error_log /path/to/log debug; 16 | ``` 17 | 18 | 要验证 nginx 是否已经配置为支持调试功能，请运行 `nginx -V` 命令： 19 | 20 | ```bash 21 | configure arguments: --with-debug ... 22 | ``` 23 | 24 | 预构建 [Linux](http://nginx.org/en/linux_packages.html) 包为 nginx-debug 二进制文件的调试日志提供了开箱即用的支持，可以使用命令运行。 25 | 26 | ```bash 27 | service nginx stop 28 | service nginx-debug start 29 | ``` 30 | 31 | 之后设置 `debug` 级别。Windows 的 nginx 在编译时就已经支持调试日志，因此只需设置 `debug` 级别即可。 32 | 33 | 请注意，重新定义日志而不指定 `debug` 级别将禁止调试日志。在下面的示例中，重新定义 `server` 上的日志级别，nginx 将不会在此服务器上做日志调试。 34 | 35 | ```nginx 36 | error_log /path/to/log debug; 37 | 38 | http { 39 | server { 40 | error_log /path/to/log; 41 | ... 42 | ``` 43 | 44 | 为了避免这种情况，重新定义日志级别应该被注释掉，或者明确指定日志为 `debug` 级别。 45 | 46 | ```nginx 47 | error_log /path/to/log debug; 48 | 49 | http { 50 | server { 51 | error_log /path/to/log debug; 52 | ... 53 | ``` 54 | 55 | ## 为指定客户端做调试日志 56 | 57 | 也可以仅为选定的客户端地址启用调试日志： 58 | 59 | ```nginx 60 | error_log /path/to/log; 61 | 62 | events { 63 | debug_connection 192.168.1.1; 64 | debug_connection 192.168.10.0/24; 65 | } 66 | ``` 67 | 68 | ## 记录日志到循环内存缓冲区 69 | 70 | 调试日志可以被写入到循环内存缓冲区中： 71 | 72 | ```nginx 73 | error_log memory:32m debug; 74 | ``` 75 | 76 | 在 `debug` 级别将日志写入到内存缓冲区中，即使在高负载情况下也不会对性能产生重大的影响。在这种情况下，可以使用如下 `gdb` 脚本来提取日志： 77 | 78 | ```bash 79 | set $log = ngx_cycle->log 80 | 81 | while $log->writer != ngx_log_memory_writer 82 | set $log = $log->next 83 | end 84 | 85 | set $buf = (ngx_log_memory_buf_t *) $log->wdata 86 | dump binary memory debug_log.txt $buf->start $buf->end 87 | ``` 88 | 89 | ## 原文档 90 | 91 | - [http://nginx.org/en/docs/debugging_log.html](http://nginx.org/en/docs/debugging_log.html) 92 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_autoindex_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_autoindex_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [autoindex](#autoindex) 6 | - [autoindex_exact_size](#autoindex_exact_size) 7 | - [autoindex_format](#autoindex_format) 8 | - [autoindex_localtime](#autoindex_localtime) 9 | 10 | 11 | `ngx_http_autoindex_module` 模块处理以斜线字符（`/`）结尾的请求并生成一个目录列表。当 [ngx_http_index_module](ngx_http_index_module.md) 模块找不到索引文件时，通常会将请求传递给 `ngx_http_autoindex_module` 模块。 12 | 13 | 14 | 15 | ## 示例配置 16 | ```nginx 17 | location / { 18 | autoindex on; 19 | } 20 | ``` 21 | 22 | 23 | 24 | ## 指令 25 | 26 | ### autoindex 27 | 28 | |\-|说明| 29 | |:------|:------| 30 | |**语法**|**autoindex** `on` | `off`;| 31 | |**默认**|autoindex off;| 32 | |**上下文**|http、server、location| 33 | 34 | 启用或禁用目录列表输出。 35 | 36 | ### autoindex_exact_size 37 | 38 | |\-|说明| 39 | |:------|:------| 40 | |**语法**|**autoindex_exact_size** `on` | `off`;| 41 | |**默认**|autoindex_exact_size on;| 42 | |**上下文**|http、server、location| 43 | 44 | 对于 HTML [格式](#autoindex_format)，指定是否应在目录列表中输出确切的文件大小，或者四舍五入到千字节、兆字节和千兆字节。 45 | 46 | ### autoindex_format 47 | 48 | |\-|说明| 49 | |:------|:------| 50 | |**语法**|**autoindex_format** `html` | `xml` | `json` | `jsonp`;| 51 | |**默认**|autoindex_format html;| 52 | |**上下文**|http、server、location| 53 | |**提示**|该指令在 1.7.9 版本中出现| 54 | 55 | 设置目录列表的格式。 56 | 57 | 当使用 JSONP 格式时，使用 `callback` 请求参数设置回调函数的名称。如果没有参数或为空值，则使用 JSON 格式。 58 | 59 | XML 输出可以使用 [ngx_http_xslt_module](ngx_http_xslt_module.md) 模块进行转换。 60 | 61 | ### autoindex_localtime 62 | 63 | |\-|说明| 64 | |:------|:------| 65 | |**语法**|**autoindex_localtime** `on` | `off`;| 66 | |**默认**|autoindex_localtime off;| 67 | |**上下文**|http、server、location| 68 | 69 | 对于 HTML [格式](#autoindex_format)，指定目录列表中的时间是否应使用本地时区或 UTC 输出。 70 | 71 | ## 原文档 72 | [http://nginx.org/en/docs/http/ngx_http_autoindex_module.html](http://nginx.org/en/docs/http/ngx_http_autoindex_module.html) 73 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_auth_basic_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_auth_basic_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [auth_basic](#auth_basic) 6 | - [auth_basic_user_file](#auth_basic_user_file) 7 | 8 | `ngx_http_auth_basic_module` 模块允许通过使用 **HTTP Basic Authentication** 协议验证用户名和密码来限制对资源的访问。 9 | 10 | 也可以通过地址、子请求结果或 JWT 来限制访问。可使用 [satisfy](ngx_http_core_module.html#satisfy) 指令通过地址和密码同时限制访问。 11 | 12 | 13 | 14 | ## 示例配置 15 | ```nginx 16 | location / { 17 | auth_basic "closed site"; 18 | auth_basic_user_file conf/htpasswd; 19 | } 20 | ``` 21 | 22 | 23 | 24 | ## 指令 25 | 26 | ### auth_basic 27 | 28 | |\-|说明| 29 | |:------|:------| 30 | |**语法**|**auth_basic** `string` | `off`;| 31 | |**默认**|auth_basic off;| 32 | |**上下文**|http、server、location、limit_except| 33 | 34 | 使用 **HTTP Basic Authentication** 协议，启用用户名和密码验证。指定的参数用作为一个 `realm`。参数值可以包含变量（1.3.10、1.2.7）。特殊值 `off` 可以取消从先前配置级别继承的 `auth_basic` 指令的影响。 35 | 36 | ### auth_basic_user_file 37 | 38 | |\-|说明| 39 | |:------|:------| 40 | |**语法**|**auth_basic_user_file** `file`;| 41 | |**默认**|——| 42 | |**上下文**|http、server、location、limit_except| 43 | 44 | 指定一个用于保存用户名和密码的文件，格式如下： 45 | 46 | ``` 47 | # comment 48 | name1:password1 49 | name2:password2:comment 50 | name3:password3 51 | ``` 52 | 53 | `file` 的名称可以包含变量。 54 | 55 | 支持以下密码类型： 56 | 57 | - 用 `crypt()` 函数加密；可以使用 Apache HTTP Server 分发的或 `openssl passwd` 命令中的 `htpasswd` 工具生成； 58 | - 使用基于 MD5 密码算法（apr1）的 Apache 变体进行散列计算；可以用与上述相同的工具生成； 59 | - [RFC 2307](https://tools.ietf.org/html/rfc2307#section-5.3) 中指定的 `{scheme}data` 语法（1.0.3+）；目前的实现方案包括 `PLAIN`（一个不应该使用的示例）、`SHA`（1.3.13）（简单 SHA-1 散列，不应该使用）和 `SSHA`（一些软件包使用了加盐的 SHA-1 散列，特别是 OpenLDAP 和 Dovecot）。 60 | 61 | > 增加了对 SHA 模式的支持，仅用于帮助从其他 Web 服务器迁移。 它不应该用于新密码，因为它使用的未加盐的 SHA-1 散列容易受到[彩虹表](http://en.wikipedia.org/wiki/Rainbow_attack)的攻击。 62 | 63 | ## 原文档 64 | 65 | [http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html](http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) 66 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_sub_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_sub_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [sub_filter](#sub_filter) 6 | - [sub_filter_last_modified](#sub_filter_last_modified) 7 | - [sub_filter_once](#sub_filter_once) 8 | - [sub_filter_types](#sub_filter_types) 9 | 10 | `ngx_http_sub_module` 模块是一个过滤器，它通过替换指定的字符串来修改响应数据。 11 | 12 | 默认不构建此模块，可在构建时使用 `--with-http_sub_module` 配置参数启用。 13 | 14 | 15 | 16 | ## 示例配置 17 | 18 | ```nginx 19 | location / { 20 | sub_filter ' 27 | 28 | ## 指令 29 | 30 | ### sub_filter 31 | 32 | |\-|说明| 33 | |:------|:------| 34 | |**语法**|**sub_filter** `string replacement`;| 35 | |**默认**|——| 36 | |**上下文**|http、server、location| 37 | 38 | 设置要替换的字符串（`string`）和要替换成的字符串（`replacement`）。要替换的字符串匹配忽略大小写。要替换的字符串（1.9.4）和要替换成的字符串可以包含变量。可以在一个配置级别指定几个 `sub_filter` 指令（1.9.4）。当且仅当在当前级别上没有定义 `sub_filter` 指令时，这些指令才从上级继承。 39 | 40 | ### sub_filter_last_modified 41 | 42 | |\-|说明| 43 | |:------|:------| 44 | |**语法**|**sub_filter_last_modified** `on` | `off`;| 45 | |**默认**|sub_filter_last_modified off;| 46 | |**上下文**|http、server、location| 47 | |**提示**|该指令在 1.5.1 版本中出现| 48 | 49 | 允许在替换期间保留原始响应中的 **Last-Modified** 头字段，用于响应缓存。 50 | 51 | 默认情况下，在处理期间修改响应的内容时，将删除头字段。 52 | 53 | ### sub_filter_once 54 | 55 | |\-|说明| 56 | |:------|:------| 57 | |**语法**|**sub_filter_once** `on` | `off`;| 58 | |**默认**|sub_filter_once on;| 59 | |**上下文**|http、server、location| 60 | 61 | 只查找一次要替换的每个字符串或重复查找。 62 | 63 | ### sub_filter_types 64 | 65 | |\-|说明| 66 | |:------|:------| 67 | |**语法**|**sub_filter_types** `mime-type ...`;| 68 | |**默认**|sub_filter_types text/html;| 69 | |**上下文**|http、server、location| 70 | 71 | 除了 **text/html** 之外，还指定在其他 MIME 类型的响应中启用字符串替换。特殊值 `*` 匹配任何 MIME 类型（0.8.29）。 72 | 73 | ## 原文档 74 | 75 | - [http://nginx.org/en/docs/http/ngx_http_sub_module.html](http://nginx.org/en/docs/http/ngx_http_sub_module.html) 76 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_stub_status_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_stub_status_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [stub_status](#stub_status) 6 | - [数据](#data) 7 | - [内嵌变量](#embedded_variables) 8 | 9 | `ngx_http_stub_status_module` 模块提供对基本状态信息的访问的支持。 10 | 11 | 默认不构建此模块，可在构建时使用 `--with-http_stub_status_module` 配置参数启用。 12 | 13 | 14 | 15 | ## 示例配置 16 | 17 | ```nginx 18 | location = /basic_status { 19 | stub_status; 20 | } 21 | ``` 22 | 23 | 此配置将创建一个简单的网页，其基本状态数据可能如下： 24 | 25 | ``` 26 | Active connections: 291 27 | server accepts handled requests 28 | 16630948 16630948 31070465 29 | Reading: 6 Writing: 179 Waiting: 106 30 | ``` 31 | 32 | 33 | 34 | ## 指令 35 | 36 | ### stub_status 37 | 38 | |\-|说明| 39 | |:------|:------| 40 | |**语法**|**stub_status**;| 41 | |**默认**|——| 42 | |**上下文**|server、location| 43 | 44 | 可以从包含该指令的 location 访问基本状态信息。 45 | 46 | > 在 1.7.5 之前的版本中，指令语法需要一个任意参数，例如 `stub_status on`。 47 | 48 | ## 数据 49 | 50 | 提供以下状态信息： 51 | 52 | - `Active connections` 53 | 54 | 当前活动客户端连接数，包括等待连接。 55 | 56 | - `accepts` 57 | 58 | 已接受的客户端连接总数。 59 | 60 | - `handled` 61 | 62 | 已处理连接的总数。通常，参数值与 `accept` 相同，除非已达到某些资源限制阈值（例如，[worker_connections](../核心功能.md#worker_connections) 限制）。 63 | 64 | - `requests` 65 | 66 | 客户端请求的总数。 67 | 68 | - `Reading` 69 | 70 | nginx 正在读取请求头的当前连接数。 71 | 72 | - `Writing` 73 | 74 | nginx 将响应写回客户端的当前连接数。 75 | 76 | - `Waiting` 77 | 78 | 当前等待请求的空闲客户端连接数。 79 | 80 | 81 | 82 | ## 内嵌变量 83 | 84 | `ngx_http_stub_status_module` 模块支持以下内嵌变量（1.3.14）： 85 | 86 | - `$connections_active` 87 | 88 | 与 `Active connections` 的值相同 89 | 90 | - `$connections_reading` 91 | 92 | 与 `Reading` 的值相同 93 | 94 | - `$connections_writing` 95 | 96 | 与 `Writing` 的值相同 97 | 98 | - `$connections_waiting` 99 | 100 | 与 `Waiting` 的值相同 101 | 102 | ## 原文档 103 | 104 | - [http://nginx.org/en/docs/http/ngx_http_stub_status_module.html](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html) 105 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_limit_conn_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_limit_conn_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [limit_conn](#limit_conn) 6 | - [limit_conn_log_level](#limit_conn_log_level) 7 | - [limit_conn_zone](#limit_conn_zone) 8 | 9 | `ngx_stream_limit_conn_module` 模块（1.9.3）用于限制每个定义的 key 的连接数，特别是来自单个 IP 地址的连接数。 10 | 11 | 12 | 13 | ## 示例配置 14 | 15 | ```nginx 16 | stream { 17 | limit_conn_zone $binary_remote_addr zone=addr:10m; 18 | 19 | ... 20 | 21 | server { 22 | 23 | ... 24 | 25 | limit_conn addr 1; 26 | limit_conn_log_level error; 27 | } 28 | } 29 | ``` 30 | 31 | 32 | 33 | ## 指令 34 | 35 | ### limit_conn 36 | 37 | |\-|说明| 38 | |------:|------| 39 | |**语法**|**limit_conn** `zone number`;| 40 | |**默认**|——| 41 | |**上下文**|stream、server| 42 | 43 | 设置共享内存区域和给定 key 的最大允许连接数。超过此限制时，服务器将关闭连接。例如，以下指令： 44 | 45 | ```nginx 46 | limit_conn_zone $binary_remote_addr zone=addr:10m; 47 | 48 | server { 49 | ... 50 | limit_conn addr 1; 51 | } 52 | ``` 53 | 54 | 每次只允许一个 IP 地址一个连接。 55 | 56 | 如果指定了几个 `limit_conn` 指令，则将应用所有已配置的限制。 57 | 58 | 当且仅当当前级别没有 `limit_conn` 指令时，指令才从上级继承。 59 | 60 | ### limit_conn_log_level 61 | 62 | |\-|说明| 63 | |------:|------| 64 | |**语法**|**limit_conn_log_level** `info` | `notice` | `warn` | `error`;| 65 | |**默认**|limit_conn_log_level error;| 66 | |**上下文**|stream、server| 67 | 68 | 为服务器限制连接数设置日志记录级别。 69 | 70 | ### limit_conn_zone 71 | 72 | |\-|说明| 73 | |------:|------| 74 | |**语法**|**limit_conn_zone** `key zone=name:size`;| 75 | |**默认**|——| 76 | |**上下文**|stream| 77 | 78 | 为指定的共享内存区域设置参数，该区域将保留各种 key 的状态。尤其是状态包括当前的连接数。`key` 可以包含文本、变量及其组合（1.11.2）。不计算 key 为空的连接。用法示例： 79 | 80 | ```nginx 81 | limit_conn_zone $binary_remote_addr zone=addr:10m; 82 | ``` 83 | 84 | 上述中，key 是一个 `$binary_remote_addr` 变量设置的客户端 IP 地址。`$binary_remote_addr` 的大小为 IPv4 地址的 4 个字节或 IPv6 地址的 16 个字节。存储状态在 32 位平台上总是占用 32 或 64 字节，在 64 位平台上占用 64 字节。一兆字节区域可以保留大约 32,000 个 32 字节状态或大约 16,000 个 64 字节状态。如果区域存储耗尽，服务器将关闭连接。 85 | 86 | ## 原文档 87 | [http://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html](http://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html) -------------------------------------------------------------------------------- /模块参考/mail/ngx_mail_proxy_module.md: -------------------------------------------------------------------------------- 1 | # ngx_mail_proxy_module 2 | 3 | - [指令](#directives) 4 | - [proxy_buffer](#proxy_buffer) 5 | - [proxy_pass_error_message](#proxy_pass_error_message) 6 | - [proxy_timeout](#proxy_timeout) 7 | - [xclient](#xclient) 8 | 9 | 10 | 11 | ## 指令 12 | 13 | ### proxy_buffer 14 | 15 | |\-|说明| 16 | |:------|:------| 17 | |**语法**|**proxy_buffer** `size`;| 18 | |**默认**|proxy_buffer 4k|8k| 19 | |**上下文**|mail、server| 20 | 21 | 设置用于代理的缓冲区的大小。默认情况下，缓冲区大小等于一个内存页。根据平台的不同，它可以是 4K 或 8K。 22 | 23 | ### proxy_pass_error_message 24 | 25 | |\-|说明| 26 | |:------|:------| 27 | |**语法**|**proxy_pass_error_message** `on` | `off`;| 28 | |**默认**|proxy_pass_error_message off;| 29 | |**上下文**|mail、server| 30 | 31 | 指示是否将后端身份验证期间获得的错误消息传递给客户端。 32 | 33 | 通常，如果 nginx 中的身份验证成功，则后端无法返回错误。如果仍然返回错误，则表示发生了一些内部错误。在这种情况下，后端消息可能包含不应显示给客户端的信息。但是，对于某些 POP3 服务器，响应一个密码错误信息是正常现象。例如，CommuniGatePro 通过定期输出[身份验证错误](http://www.stalker.com/CommuniGatePro/POP.html#Alerts)来通知用户[邮箱溢出](http://www.stalker.com/CommuniGatePro/Alerts.html#Quota)或其他事件。在这种情况下，应启用该指令。 34 | 35 | ### proxy_timeout 36 | 37 | |\-|说明| 38 | |:------|:------| 39 | |**语法**|**proxy_timeout** `timeout`;| 40 | |**默认**|proxy_timeout 24h;| 41 | |**上下文**|mail、server| 42 | 43 | 设置客户端或代理服务器连接上两次连续的读取或写入操作之间的超时（`timeout`）。如果在此时间内没有数据传输，则连接将关闭。 44 | 45 | ### xclient 46 | 47 | |\-|说明| 48 | |:------|:------| 49 | |**语法**|**xclient** `on` | `off`;| 50 | |**默认**|xclient on;| 51 | |**上下文**|mail、server| 52 | 53 | 连接到 SMTP 后端时，启用或禁用 [XCLIENT](http://www.postfix.org/XCLIENT_README.html) 命令与客户端参数的传递。 54 | 55 | 借助 `XCLIENT`，MTA 能够将客户端信息写入日志并基于此数据应用各种限制。 56 | 57 | 如果启用了 `XCLIENT`，则 nginx 在连接到后端时会传递以下命令： 58 | 59 | - 附带[服务器名称](ngx_mail_core_module.md#server_name)的 EHLO 60 | - `XCLIENT` 61 | - 由客户传递的 `EHLO` 或 `HELO` 62 | 63 | 如果客户端 IP 地址[找到](ngx_mail_core_module.md#resolver)的名称指向相同的地址，则会在 `XCLIENT` 命令的 `NAME` 参数中传递该名称。如果找不到名称、指向其他地址或未指定[解析器](ngx_mail_core_module.md#resolver)，则在 `NAME` 参数中传递 `[UNAVAILABLE]`。如果在解析过程中发生错误，则使用 `[TEMPUNAVAIL]` 值。 64 | 65 | 如果禁用了 `XCLIENT`，则如果客户端已通过 `EHLO`，则 nginx 在连接到后端时将使用[服务器名称](ngx_mail_core_module.md#server_name)传递 EHLO 命令；否则，使用服务器名称传递 `HELO`。 66 | 67 | ## 原文档 68 | 69 | - [http://nginx.org/en/docs/mail/ngx_mail_proxy_module.html](http://nginx.org/en/docs/mail/ngx_mail_proxy_module.html) 70 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_realip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_realip_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [set_real_ip_from](#set_real_ip_from) 6 | - [real_ip_header](#real_ip_header) 7 | - [real_ip_recursive](#real_ip_recursive) 8 | - [内嵌变量](#embedded_variables) 9 | 10 | `ngx_http_realip_module` 模块用于将客户端地址和可选端口更改为发送的指定的头字段。 11 | 12 | 默认情况下不构建此模块，可在构建时使用 `--with-http_realip_module` 配置参数启用。 13 | 14 | 15 | 16 | ## 示例配置 17 | ```nginx 18 | set_real_ip_from 192.168.1.0/24; 19 | set_real_ip_from 192.168.2.1; 20 | set_real_ip_from 2001:0db8::/32; 21 | real_ip_header X-Forwarded-For; 22 | real_ip_recursive on; 23 | ``` 24 | 25 | 26 | 27 | ## 指令 28 | 29 | ### set_real_ip_from 30 | 31 | |\-|说明| 32 | |:------|:------| 33 | |**语法**|**set_real_ip_from** `address` | `CIDR` | `unix:`;| 34 | |**默认**|——| 35 | |**上下文**|http、server、location| 36 | 37 | 定义已知可发送正确替换地址的可信地址。如果指定了特殊值 `unix:`，则所有 UNIX 域套接字都将受信任。也可以使用主机名（1.13.1）指定可信地址。 38 | 39 | > 从 1.3.0 版本和 1.2.1 版本开始支持 IPv6 地址。 40 | 41 | ### real_ip_header 42 | 43 | |\-|说明| 44 | |:------|:------| 45 | |**语法**|**real_ip_header** `field` | `X-Real-IP` | `X-Forwarded-For` | `proxy_protocol`;| 46 | |**默认**|real_ip_header X-Real-IP;| 47 | |**上下文**|http、server、location| 48 | 49 | 定义请求头字段，其值将用于替换客户端地址。 50 | 51 | 包含可选端口的请求头字段值也用于替换客户端端口（1.11.0）。 应根据 [RFC 3986](https://tools.ietf.org/html/rfc3986) 指定地址和端口。 52 | 53 | `proxy_protocol` 参数（1.5.12）将客户端地址更改为 PROXY 协议头中的地址。必须先通过在 [listen](ngx_http_core_module.md#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。 54 | 55 | ### real_ip_recursive 56 | 57 | |\-|说明| 58 | |:------|:------| 59 | |**语法**|**real_ip_recursive** `on` | `off`;| 60 | |**默认**|real_ip_recursive off;| 61 | |**上下文**|http、server、location| 62 | |**提示**|该指令在 1.3.0 版本和 1.2.1 版本中出现| 63 | 64 | 如果禁用递归搜索，则匹配其中一个可信地址的原始客户端地址替换为 [real_ip_header](ngx_http_realip_module.md#real_ip_header) 指令定义的请求头字段中发送的最后一个地址。如果启用了递归搜索，则匹配其中一个可信地址的原始客户端地址替换为请求头字段中发送的最后一个非受信任地址。 65 | 66 | 67 | 68 | ## 内嵌变量 69 | 70 | - `$realip_remote_addr` 71 | 72 | 原始客户端地址 73 | 74 | - `$realip_remote_port` 75 | 76 | 原始客户端端口 77 | 78 | ## 原文档 79 | [http://nginx.org/en/docs/http/ngx_http_realip_module.html](http://nginx.org/en/docs/http/ngx_http_realip_module.html) 80 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_geo_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_geo_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [geo](#geo) 6 | 7 | `ngx_stream_geo_module` 模块（1.11.3）用于创建依赖于客户端 IP 地址的变量。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | geo $geo { 15 | default 0; 16 | 17 | 127.0.0.1 2; 18 | 192.168.1.0/24 1; 19 | 10.1.0.0/16 1; 20 | 21 | ::1 2; 22 | 2001:0db8::/32 1; 23 | } 24 | ``` 25 | 26 | 27 | 28 | ## 指令 29 | 30 | ### geo 31 | 32 | |\-|说明| 33 | |------:|------| 34 | |**语法**|**geo** `[$address] $variable { ... }`;| 35 | |**默认**|——| 36 | |**上下文**|stream| 37 | 38 | 描述指定变量的值与客户端 IP 地址的依赖关系。默认情况下，地址取自 `$remote_addr` 变量，但也可以从其他变量中获取，例如： 39 | 40 | ```nginx 41 | geo $arg_remote_addr $geo { 42 | ...; 43 | } 44 | ``` 45 | 46 | > 由于变量仅在使用时进行求值，因此即使存在大量已声明的 `geo` 变量增加连接处理的额外成本。 47 | 48 | 如果变量（`$variable`）的值不是有效的 IP 地址，则使用 `255.255.255.255` 地址。 49 | 50 | 地址（`$address`）可为 CIDR 记法中的前缀（包括单个地址）或作为范围。 51 | 52 | 还支持以下特殊参数： 53 | 54 | - `delete` 55 | 56 | 删除指定的网络 57 | 58 | - `default` 59 | 60 | 如果客户端地址与所有指定的地址都不匹配，则设置为该变量的值。当以 CIDR 记法指定地址时，使用 `0.0.0.0/0` 和 `::/0` 而不是默认值。如果未指定 `default`，则默认值为空字符串。 61 | 62 | - `include` 63 | 64 | 包含一个有地址和值的文件，文件中可以有多个记录。 65 | 66 | - `ranges` 67 | 68 | 表示地址指定为范围形式。这个参数应该放在第一个。要加快地理数据的加载速度，地址应按升序排列。 69 | 70 | 示例： 71 | 72 | ```nginx 73 | geo $country { 74 | default ZZ; 75 | include conf/geo.conf; 76 | delete 127.0.0.0/16; 77 | 78 | 127.0.0.0/24 US; 79 | 127.0.0.1/32 RU; 80 | 10.1.0.0/16 RU; 81 | 192.168.1.0/24 UK; 82 | } 83 | ``` 84 | 85 | `conf/geo.conf` 文件包含以下内容： 86 | 87 | ``` 88 | 10.2.0.0/16 RU; 89 | 192.168.2.0/24 RU; 90 | ``` 91 | 92 | 使用最佳匹配的值。例如，对于 127.0.0.1 地址，将选择值 `RU`，而不是 `US`。 93 | 94 | 范围指定示例： 95 | 96 | ```nginx 97 | geo $country { 98 | ranges; 99 | default ZZ; 100 | 127.0.0.0-127.0.0.0 US; 101 | 127.0.0.1-127.0.0.1 RU; 102 | 127.0.0.1-127.0.0.255 US; 103 | 10.1.0.0-10.1.255.255 RU; 104 | 192.168.1.0-192.168.1.255 UK; 105 | } 106 | ``` 107 | 108 | ## 原文档 109 | [http://nginx.org/en/docs/stream/ngx_stream_geo_module.html](http://nginx.org/en/docs/stream/ngx_stream_geo_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_session_log_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_session_log_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [session_log](#session_log) 6 | - [session_log_format](#session_log_format) 7 | - [session_log_zone](#session_log_zone) 8 | - [内嵌变量](#embedded_variables) 9 | 10 | `ngx_http_session_log_module` 模块启用会话日志（多个 HTTP 请求的聚合），而不是单个 HTTP 请求。 11 | 12 | > 该模块作为我们[商业订阅](http://nginx.com/products/?_ga=2.22237371.1497417506.1556973333-896013220.1554004850)的一部分提供。 13 | 14 | 15 | 16 | ## 示例配置 17 | 18 | 以下配置根据请求客户端的地址和 **User-Agent** 请求头字段设置会话日志并将请求映射到会话： 19 | 20 | ```nginx 21 | session_log_zone /path/to/log format=combined 22 | zone=one:1m timeout=30s 23 | md5=$binary_remote_addr$http_user_agent; 24 | 25 | location /media/ { 26 | session_log one; 27 | } 28 | ``` 29 | 30 | 31 | 32 | 33 | ## 指令 34 | 35 | ### session_log 36 | 37 | |\-|说明| 38 | |:------|:------| 39 | |**语法**|**session_log** `name` | `off`;| 40 | |**默认**|session_log off;| 41 | |**上下文**|http、server、location| 42 | 43 | 允许使用指定的会话日志。特殊值 `off` 取消从先前配置级别继承的所有 `session_log` 指令。 44 | 45 | ### session_log_format 46 | 47 | |\-|说明| 48 | |:------|:------| 49 | |**语法**|**session_log_format** `name string ...`;| 50 | |**默认**|session_log_format combined "...";| 51 | |**上下文**|http| 52 | 53 | 指定日志的输出格式。`$body_bytes_sent` 变量的值聚合在会话的所有请求中。可用于记录的所有其他变量的值对应于会话中的第一个请求。 54 | 55 | ### session_log_zone 56 | 57 | |\-|说明| 58 | |:------|:------| 59 | |**语法**|**session_log_zone** `path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5]`;| 60 | |**默认**|——| 61 | |**上下文**|http| 62 | 63 | 设置日志文件的路径，并配置用于存储当前活动会话的共享内存区域。 64 | 65 | 只要会话中的最后一个请求经过的时间不超过指定的 `timeout`（默认为 30 秒），会话就被视为活动状态。会话不再处于活动状态后将被写入日志。 66 | 67 | `id` 参数标识请求映射到的会话。`id` 参数设置为 MD5 哈希的十六进制形式（例如，使用变量从 cookie 中获取）。如果未指定此参数或不是有效的 MD5 哈希，则 nginx 将根据 `md5` 参数的值计算 MD5 哈希，并使用此哈希创建新会话。`id` 和 `md5` 参数都可以包含变量。 68 | 69 | `format` 参数设置 [session_log_format](#session_log_format) 指令配置的自定义会话日志格式。如果未指定 `format`，则使用预定义的 `combined`格式。 70 | 71 | 72 | 73 | ## 内嵌变量 74 | 75 | `ngx_http_session_log_module` 模块支持两个内嵌变量： 76 | 77 | - `$session_log_id` 78 | 79 | 当前会话 ID 80 | 81 | - `$session_log_binary_id` 82 | 83 | 二进制形式的当前会话 ID（16字节）。 84 | 85 | ## 原文档 86 | 87 | - [http://nginx.org/en/docs/http/ngx_http_session_log_module.html](http://nginx.org/en/docs/http/ngx_http_session_log_module.html) 88 | -------------------------------------------------------------------------------- /开发/贡献指南.md: -------------------------------------------------------------------------------- 1 | # 贡献变更 2 | 3 | ## 获取源码 4 | [Mercurial](https://www.mercurial-scm.org/) 是一个源码存储工具。可使用以下命令源码[仓库](http://hg.nginx.org/nginx?_ga=2.101961729.1619437240.1505835130-1890203964.1497190280)： 5 | 6 | ```bash 7 | hg clone http://hg.nginx.org/nginx 8 | ``` 9 | 10 | ## 格式化变更 11 | 变更应根据 nginx 使用的代码样式进行格式化。代码格式化不应该依赖于诸如语法高亮或自动换行等编辑器功能。以下是一些基本规则： 12 | 13 | - 最大文本宽度为 80 个字符 14 | - 缩进为四个空格 15 | - 没有 tab（制表符） 16 | - 文件中的逻辑代码块用两行空行分隔 17 | 18 | 参照现有 nginx 源码的格式，在您的代码中模仿此样式。如果风格与周围的代码相一致，则更改更容易被接受。 19 | 20 | 提交更改以创建一个 Mercurial [变更集](https://www.mercurial-scm.org/wiki/ChangeSet)（changeset）。请确保指定的 [电子邮件](https://www.mercurial-scm.org/wiki/QuickStart#Setting_a_username) 和变更作者的真实姓名正确无误。 21 | 22 | 提交消息应是单行简述，后跟一行空行加描述内容。第一行最好不要超过 67 个符号。可以使用 `hg export` 命令获得一个结果变更集 patch： 23 | 24 | ```diff 25 | # HG changeset patch 26 | # User Filipe Da Silva 27 | # Date 1368089668 -7200 28 | # Thu May 09 10:54:28 2013 +0200 29 | # Node ID 2220de0521ca2c0b664a8ea1e201ce1cb90fd7a2 30 | # Parent 822b82191940ef309cd1e6502f94d50d811252a1 31 | Mail: removed surplus ngx_close_connection() call. 32 | 33 | It is already called for a peer connection a few lines above. 34 | 35 | diff -r 822b82191940 -r 2220de0521ca src/mail/ngx_mail_auth_http_module.c 36 | --- a/src/mail/ngx_mail_auth_http_module.c Wed May 15 15:04:49 2013 +0400 37 | +++ b/src/mail/ngx_mail_auth_http_module.c Thu May 09 10:54:28 2013 +0200 38 | @@ -699,7 +699,6 @@ ngx_mail_auth_http_process_headers(ngx_m 39 | 40 | p = ngx_pnalloc(s->connection->pool, ctx->err.len); 41 | if (p == NULL) { 42 | - ngx_close_connection(ctx->peer.connection); 43 | ngx_destroy_pool(ctx->pool); 44 | ngx_mail_session_internal_server_error(s); 45 | return; 46 | ``` 47 | 48 | ## 提交前 49 | 提交更改前，有几点值得思考： 50 | 51 | - 建议的变更应能在大部分的 [支持平台](http://nginx.org/en/index.html#tested_os_and_platforms) 上正常工作。 52 | - 尽量说明清楚为什么需要更改，如果可以的话，请提供一个用例。 53 | - 通过测试套件传递您的更改是确保不会导致回归的好方法。可以使用以下命令克隆测试仓库： 54 | 55 | ```bash 56 | hg clone http://hg.nginx.org/nginx-tests 57 | ``` 58 | 59 | ## 提交变更 60 | 提议的更改应发送到 [nginx 开发](http://nginx.org/en/support.html#nginx_devel) 邮件列表。提交更改集的首选便捷方法是使用 [patchbomb](https://www.mercurial-scm.org/wiki/PatchbombExtension) 扩展。 61 | 62 | ## 许可证 63 | 提交变更意味着授予项目一个权限以在一个适当的许可证下使用它。 64 | 65 | ## 原文档 66 | 67 | [http://nginx.org/en/docs/contributing_changes.html](http://nginx.org/en/docs/contributing_changes.html) 68 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_keyval_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_keyval_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [keyval](#keyval) 6 | - [keyval_zone](#keyval_zone) 7 | 8 | `ngx_stream_keyval_module` 模块（1.13.7）可用于创建变量，变量的值从由 [API](ngx_http_api_module.md#stream_keyvals_) 管理的键值对中获取。 9 | 10 | > 此模块为[商业订阅](http://nginx.com/products/?_ga=2.203887064.99786210.1588592638-1615340879.1588592638)部分。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | http { 18 | 19 | server { 20 | ... 21 | location /api { 22 | api write=on; 23 | } 24 | } 25 | } 26 | 27 | stream { 28 | 29 | keyval_zone zone=one:32k state=one.keyval; 30 | keyval $ssl_server_name $name zone=one; 31 | 32 | server { 33 | listen 12345 ssl; 34 | proxy_pass $name; 35 | ssl_certificate /usr/local/nginx/conf/cert.pem; 36 | ssl_certificate_key /usr/local/nginx/conf/cert.key; 37 | } 38 | } 39 | ``` 40 | 41 | 42 | 43 | ## 指令 44 | 45 | ### keyval 46 | 47 | |\-|说明| 48 | |:------|:------| 49 | |**语法**|**keyval** `key $variable zone=name`;| 50 | |**默认**|——| 51 | |**上下文**|stream| 52 | 53 | 创建一个新的 `$variable`，其值在键值数据库中通过 key 查找。匹配规则由 [keyval_zone](#keyval_zone) 指令的 [type](#keyval_type) 参数定义。数据库存储在 `zone` 参数指定的共享内存区域中。 54 | 55 | ### keyval_zone 56 | 57 | |\-|说明| 58 | |:------|:------| 59 | |**语法**|**keyval_zone** `zone=name:size [state=file] [timeout=time] [type=string\|ip\|prefix] [sync]`;| 60 | |**默认**|——| 61 | |**上下文**|stream| 62 | 63 | 设置维持键值数据库的共享内存区域的名称（`name`）和大小（`size`）。键值对通过 [API](ngx_http_api_module.md#stream_keyvals_) 进行管理。 64 | 65 | 可选的 `state` 参数指定一个文件（`file`），该文件以 JSON 格式保存键值数据库的当前状态，并在重新启动 nginx 时保持不变。 66 | 67 | 可选的 `timeout` 参数（1.15.0）设置将键值对从区域中删除的时间。 68 | 69 | 可选的 `type` 参数（1.17.1）激活一个额外的索引，该索引针对某种类型的键匹配进行了优化，匹配规则在计算[键值](#keyval) `$variable` 时定义。 70 | 71 | > 索引存储在相同的共享存储区中，因此需要额外的存储。 72 | 73 | - `type=string` 74 | 75 | 默认配置，不启用索引；使用记录 key 和一个搜索 key 的完全匹配来执行变量查找 76 | 77 | - `type=ip` 78 | 79 | 搜索 key 是 IPv4 或 IPv6 地址或 CIDR 范围的文字表示；要匹配记录 key，搜索 key 必须属于记录 key 指定的子网或与 IP 地址完全匹配 80 | 81 | - `type=prefix` 82 | 83 | 使用记录 key 和搜索 key 的前缀匹配（1.17.5）执行变量查找；要与记录 key 匹配，记录 key 必须是搜索 key 的前缀 84 | 85 | 可选的 `sync` 参数（1.15.0）启用共享内存区域[同步](ngx_stream_zone_sync_module.md#zone_sync)。同步要求设置超时（`timeout`）参数。 86 | 87 | > 如果启用了同步，则将仅在目标群集节点上执行键值对（无论是[一个](ngx_http_api_module.md#patchStreamKeyvalZoneKeyValue)还是[全部](ngx_http_api_module.md#deleteStreamKeyvalZoneData)）的删除操作。经过 `timeout` 时间后，将删除其他群集节点上相同的键值对。 88 | 89 | ## 原文档 90 | 91 | - [http://nginx.org/en/docs/stream/ngx_stream_keyval_module.html](http://nginx.org/en/docs/stream/ngx_stream_keyval_module.html) 92 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_map_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_log_module 2 | 3 | - [示例配置](#ngx_stream_map_module) 4 | - [指令](#directives) 5 | - [map](#map) 6 | - [map_hash_bucket_size](#map_hash_bucket_size) 7 | - [map_hash_max_size](#map_hash_max_size) 8 | 9 | `ngx_stream_map_module` 模块（1.11.2）用于创建变量，其值取决于其他变量的值。 10 | 11 | 12 | 13 | ## 示例配置 14 | 15 | ```nginx 16 | map $remote_addr $limit { 17 | 127.0.0.1 ""; 18 | default $binary_remote_addr; 19 | } 20 | 21 | limit_conn_zone $limit zone=addr:10m; 22 | limit_conn addr 1; 23 | ``` 24 | 25 | 26 | 27 | ## 指令 28 | 29 | ### map 30 | 31 | |\-|说明| 32 | |------:|------| 33 | |**语法**|**map** `string $variable { ... }`;| 34 | |**默认**|——| 35 | |**上下文**|stream| 36 | 37 | 创建一个新变量，其值取决于第一个参数中指定的一个或多个源变量的值。 38 | 39 | > 由于仅在使用变量时才对它们进行求值，因此即使声明大量 `map` 变量，也不会为连接处理造成影响。 40 | 41 | `map` 块内的参数指定一个源值和结果值之间的映射关系。 42 | 43 | 源值可为字符串或正则表达式。 44 | 45 | 字符串匹配时忽略大小写。 46 | 47 | 正则表达式应以 `~` 符号开头（区分大小写），或者以 `~*` 符号开头（区分大小写）。正则表达式可以包含命名捕获和位置捕获，这些捕获以后可以在其他指令中与结果变量一起使用。 48 | 49 | 如果源值与以下描述的特殊参数名称之一匹配，则应在其前面加上 `\` 转义符号。 50 | 51 | 结果值可以包含文本，变量及其组合。 52 | 53 | 还支持以下特殊参数： 54 | 55 | - `default 默认值` 56 | 57 | 如果源值不匹配任何指定的变量值，则设置结果值。如果未指定 `default`，则默认结果值为空字符串 58 | 59 | - `主机名` 60 | 61 | 指示源值可以是带有前缀或后缀掩码的主机名： 62 | 63 | ``` 64 | *.example.com 1; 65 | example.* 1; 66 | ``` 67 | 68 | 以下两条记录 69 | 70 | ``` 71 | example.com 1; 72 | *.example.com 1; 73 | ``` 74 | 75 | 可以组合在一起： 76 | 77 | ``` 78 | .example.com 1; 79 | ``` 80 | 81 | 该参数应在值列表之前指定。 82 | 83 | - `include 文件` 84 | 85 | 包含有值的文件。可包含多个 86 | 87 | - `volatile` 88 | 89 | 表示该变量不可缓存（1.11.7） 90 | 91 | 如果源值匹配多个指定变体之一，例如 无论是掩码（mask）匹配还是正则表达式匹配，都将按照以下优先级顺序选择第一个匹配的变量值： 92 | 93 | 1. 不带掩码的字符串值 94 | 2. 带有前缀掩码的最长字符串值，例如 `*.example.com` 95 | 3. 带后缀掩码的最长字符串值，例如 `mail.*` 96 | 4. 第一个匹配的正则表达式（在配置文件中出现的顺序） 97 | 5. 默认值 98 | 99 | ### map_hash_bucket_size 100 | 101 | |\-|说明| 102 | |------:|------| 103 | |**语法**|**map_hash_bucket_size** `size`;| 104 | |**默认**|map_hash_bucket_size 32|64|128;| 105 | |**上下文**|stream| 106 | 107 | 设置 [map](#map) 变量哈希表的存储桶大小。默认值取决于处理器的缓存行大小。有关设置哈希表的详细信息已在单独的[文档](../../介绍/设置哈希.md)中提供。 108 | 109 | ### map_hash_max_size 110 | 111 | |\-|说明| 112 | |------:|------| 113 | |**语法**|**map_hash_max_size** `size`;| 114 | |**默认**|map_hash_max_size 2048;| 115 | |**上下文**|stream| 116 | 117 | 设置 [map](#map) 变量哈希表的最大大小（`size`）。有关设置哈希表的详细信息已在单独的[文档](../../介绍/设置哈希.md)中提供。 118 | 119 | ## 原文档 120 | [http://nginx.org/en/docs/stream/ngx_stream_map_module.html](http://nginx.org/en/docs/stream/ngx_stream_map_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_referer_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_referer_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [referer_hash_bucket_size](#referer_hash_bucket_size) 6 | - [referer_hash_max_size](#referer_hash_max_size) 7 | - [valid_referers](#valid_referers) 8 | - [内嵌变量](#embedded_variables) 9 | 10 | `ngx_http_referer_module` 模块用于阻止 **Referer** 头字段为无效值的请求访问站点。需记住的是，使用适当的 **Referer** 字段值来伪造请求非常容易，因此本模块的预期目的不是要彻底阻止此类请求，而是阻止常规浏览器发送的大量流量请求。还应该考虑到，即使是有效请求，常规浏览器也可能不发送 **Referer** 字段。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | valid_referers none blocked server_names 18 | *.example.com example.* www.example.org/galleries/ 19 | ~\.google\.; 20 | 21 | if ($invalid_referer) { 22 | return 403; 23 | } 24 | ``` 25 | 26 | 27 | 28 | ## 指令 29 | 30 | ### referer_hash_bucket_size 31 | 32 | |\-|说明| 33 | |:------|:------| 34 | |**语法**|**referer_hash_bucket_size** `size`;| 35 | |**默认**|referer_hash_bucket_size 64;| 36 | |**上下文**|server、location| 37 | 38 | 设置有效引用哈希表的桶大小。设置哈希表的详细信息在单独的[文档](../../介绍/设置哈希.md)中提供。 39 | 40 | ### referer_hash_max_size 41 | 42 | |\-|说明| 43 | |:------|:------| 44 | |**语法**|**referer_hash_max_size** `size`;| 45 | |**默认**|referer_hash_max_size 2048;| 46 | |**上下文**|server、location| 47 | |**提示**|该指令在 1.0.5 版本中出现| 48 | 49 | 设置有效引用哈希表的最大 `size`。设置哈希表的详细信息在单独的[文档](../../介绍/设置哈希.md)中提供。 50 | 51 | ### valid_referers 52 | 53 | |\-|说明| 54 | |:------|:------| 55 | |**语法**|**valid_referers** `none` | `blocked` | `server_names` | `string ...`;| 56 | |**默认**|——| 57 | |**上下文**|server、location| 58 | 59 | 指定 **Referer** 请求头字段值将导致内嵌的 `$invalid_referer` 变量设置为空字符串。否则，变量将为 `1`。匹配搜索不区分大小写。 60 | 61 | 参数说明如下： 62 | 63 | - `none` 64 | 65 | 请求头中缺少 **Referer** 字段 66 | 67 | - `blocked` 68 | 69 | **Referer** 字段出现在请求头中，但其值已被防火墙或代理服务器删除，这些值为不以 `http://` 或 `https://` 开头的字符串 70 | 71 | - `server_names` 72 | 73 | **Referer** 请求头字段包含一个服务器名称 74 | 75 | - 任意字符串 76 | 77 | 定义一个服务器名称和一个可选的 URI 前缀。服务器名称的开头或结尾可以包含`*`。在检查期间，**Referer** 字段中的服务器端口被忽略 78 | 79 | - 正则表达式 80 | 81 | 第一个符号应为 `〜`。要注意的是，表达式只与 `http://` 或 `https://` 之后的文本匹配。 82 | 83 | 示例： 84 | 85 | ```nginx 86 | valid_referers none blocked server_names 87 | *.example.com example.* www.example.org/galleries/ 88 | ~\.google\.; 89 | ``` 90 | 91 | 92 | 93 | ## 内嵌变量 94 | 95 | - `$invalid_referer` 96 | 97 | 如果 **Referer** 请求头字段的值[有效](#valid_referers)，则为空字符串，否则为 1。 98 | 99 | ## 原文档 100 | [http://nginx.org/en/docs/http/ngx_http_referer_module.html](http://nginx.org/en/docs/http/ngx_http_referer_module.html) 101 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_spdy_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_spdy_module 2 | 3 | - [已知问题](#issues) 4 | - [示例配置](#example_configuration) 5 | - [指令](#directives) 6 | - [spdy_chunk_size](#spdy_chunk_size) 7 | - [spdy_headers_comp](#spdy_headers_comp) 8 | - [内嵌变量](#embedded_variables) 9 | 10 | **该模块已被 `1.9.5` 中的 [ngx_http_v2_module](http://nginx.org/en/docs/http/ngx_http_v2_module.html) 模块所取代。** 11 | 12 | `ngx_http_spdy_module` 模块为 [SPDY](http://www.chromium.org/spdy/spdy-protocol) 提供实验性支持。目前，SPDY 协议[草案 3.1](http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft3-1)已实施。 13 | 14 | > 在 1.5.10 版之前，已实施 SPDY 协议[草案 2](http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft2)。 15 | 16 | 默认情况下不构建此模块，可在构建 nginx 时使用 `--with-http_spdy_module` 配置参数启用它。 17 | 18 | 19 | 20 | ## 已知问题 21 | 22 | 该模块处于实验阶段，请注意风险。 23 | 24 | 当前的 SPDY 协议实现不支持**服务器推送**。 25 | 26 | 在 1.5.9 之前的版本中，SPDY 连接中的响应无法做到[速率限制](ngx_http_core_module.md#limit_rate)。 27 | 28 | 无论 [proxy_request_buffering](ngx_http_proxy_module.md#proxy_request_buffering)、[fastcgi_request_buffering](ngx_http_fastcgi_module.md#fastcgi_request_buffering)、[uwsgi_request_buffering](ngx_http_uwsgi_module.md#uwsgi_request_buffering) 和 [scgi_request_buffering](ngx_http_scgi_module.md#scgi_request_buffering) 指令为何值，都无法禁用客户端请求体缓冲。 29 | 30 | 31 | 32 | ## 示例配置 33 | 34 | ```nginx 35 | server { 36 | listen 443 ssl spdy; 37 | 38 | ssl_certificate server.crt; 39 | ssl_certificate_key server.key; 40 | ... 41 | } 42 | ``` 43 | 44 | > 请注意，为了在同一端口上同时接受 [HTTPS](ngx_http_ssl_module.md) 和 SPDY 连接，使用的 [OpenSSL](http://www.openssl.org/) 库应支持 **Next Protocol Negotiation** TLS 扩展，该扩展自 OpenSSL 1.0.1 版开始可用。 45 | 46 | 47 | 48 | ## 指令 49 | 50 | ### spdy_chunk_size 51 | 52 | |\-|说明| 53 | |:------|:------| 54 | |**语法**|**spdy_chunk_size** `size`;| 55 | |**默认**|spdy_chunk_size 8k;| 56 | |**上下文**|http、server、location| 57 | |**提示**|该指令在 1.5.9 版本中出现| 58 | 59 | 设置响应体[分块](http://www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft2#TOC-Data-frames)的最大大小。值太低会导致更高的开销。由于 [HOL 阻塞](http://en.wikipedia.org/wiki/Head-of-line_blocking)，太高的值会破坏优先级。 60 | 61 | ### spdy_headers_comp 62 | 63 | |\-|说明| 64 | |:------|:------| 65 | |**语法**|**spdy_headers_comp** `level`;| 66 | |**默认**|spdy_headers_comp 0;| 67 | |**上下文**|http、server| 68 | 69 | 设置响应头压缩级别（`level`），范围从 `1`（最快，压缩程度较低）到 `9`（最慢，压缩程度最佳）。特殊值 `0` 将关闭头压缩。 70 | 71 | 72 | 73 | ## 内嵌变量 74 | 75 | `ngx_http_spdy_module` 模块支持以下内嵌变量： 76 | 77 | - `$spdy` 78 | 79 | SPDY 连接的 SPDY 协议版本，无则为空字符串 80 | 81 | - `$spdy_request_priority` 82 | 83 | 请求 SPDY 连接的优先级，无则为空字符串 84 | 85 | ## 原文档 86 | [http://nginx.org/en/docs/http/ngx_http_spdy_module.html](http://nginx.org/en/docs/http/ngx_http_spdy_module.html) 87 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_geo_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_geo_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [geo](#geo) 6 | 7 | `ngx_http_geo_module` 模块创建带值变量需依赖客户端 IP 地址。 8 | 9 | 10 | 11 | ## 示例配置 12 | 13 | ```nginx 14 | geo $geo { 15 | default 0; 16 | 17 | 127.0.0.1 2; 18 | 192.168.1.0/24 1; 19 | 10.1.0.0/16 1; 20 | 21 | ::1 2; 22 | 2001:0db8::/32 1; 23 | } 24 | ``` 25 | 26 | 27 | 28 | ## 指令 29 | 30 | ### geo 31 | 32 | |\-|说明| 33 | |------:|------| 34 | |**语法**|**geo** `[$address] $variable { ... }`;| 35 | |**默认**|——| 36 | |**上下文**|http| 37 | 38 | 描述指定变量的值对客户端 IP 地址的依赖。默认情况下，地址来自 `$remote_addr` 变量，但也可以从另一个变量（0.7.27）中获取，例如： 39 | 40 | ```nginx 41 | geo $arg_remote_addr $geo { 42 | ...; 43 | } 44 | ``` 45 | 46 | > 由于变量仅在使用时才生效，因此即使存在大量已声明的 `geo` 变量也不会增加请求处理开销。 47 | 48 | 如果变量的值不是有效的 IP 地址，则使用 `255.255.255.255` 地址。 49 | 50 | > 从1.3.10 版本和 1.2.7 版本开始支持 IPv6 前缀。 51 | 52 | 也支持以下特殊参数： 53 | 54 | - `delete` 55 | 56 | 删除指定的网络（0.7.23）。 57 | 58 | - `default` 59 | 60 | 如果客户端地址与所有指定地址都不匹配，则将设置为该变量的值。当以 CIDR 表示法指定地址时，可以使用 `0.0.0.0/0` 和 `::/0` 代替默认值。未指定默认值时，默认值为空字符串。 61 | 62 | - `include` 63 | 64 | 包含一个包含地址和值的文件。可包含多个。 65 | 66 | - `proxy` 67 | 68 | 定义可信地址（0.8.7、0.7.63）。当请求来自可信地址时，将使用来自 `X-Forwarded-For` 请求头字段的地址。与常规地址相比，可信地址是按顺序检查的。 69 | 70 | > 从 1.3.0 版本和 1.2.1 版本开始支持 IPv6 地址。 71 | 72 | - `proxy_recursive` 73 | 74 | 启用递归地址搜索（1.3.0、1.2.1）。如果递归搜索被禁用，将使用在 `X-Forwarded-For` 中发送的最后一个地址，而不是匹配其中一个可信地址的原始客户端地址。如果启用递归搜索，则将使用在 `X-Forwarded-For` 中发送的最后一个不可信地址，而不是匹配其中一个可信地址的原始客户端地址。 75 | 76 | - `ranges` 77 | 78 | 表示地址被指定为范围形式（0.7.23）。这个参数应该放在首位。想要加快加载地理区域，地址应按升序排列。 79 | 80 | 示例： 81 | 82 | ```nginx 83 | geo $country { 84 | default ZZ; 85 | include conf/geo.conf; 86 | delete 127.0.0.0/16; 87 | proxy 192.168.100.0/24; 88 | proxy 2001:0db8::/32; 89 | 90 | 127.0.0.0/24 US; 91 | 127.0.0.1/32 RU; 92 | 10.1.0.0/16 RU; 93 | 192.168.1.0/24 UK; 94 | } 95 | ``` 96 | 97 | `conf/geo.conf` 文件可能包含以下内容： 98 | 99 | ```nginx 100 | 10.2.0.0/16 RU; 101 | 192.168.2.0/24 RU; 102 | ``` 103 | 104 | 使用最明确匹配的值。例如，对于 127.0.0.1 地址，将选择 `RU` 值，而不是 `US`。 105 | 106 | 范围示例： 107 | 108 | ```nginx 109 | geo $country { 110 | ranges; 111 | default ZZ; 112 | 127.0.0.0-127.0.0.0 US; 113 | 127.0.0.1-127.0.0.1 RU; 114 | 127.0.0.1-127.0.0.255 US; 115 | 10.1.0.0-10.1.255.255 RU; 116 | 192.168.1.0-192.168.1.255 UK; 117 | } 118 | ``` 119 | 120 | ## 原文档 121 | [http://nginx.org/en/docs/http/ngx_http_geo_module.html](http://nginx.org/en/docs/http/ngx_http_geo_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_headers_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_headers_module 2 | 3 | - [指令](#directives) 4 | - [add_header](#gzadd_headerip) 5 | - [add_trailer](#add_trailer) 6 | - [expires](#expires) 7 | 8 | `ngx_http_headers_module` 模块允许将 `Expires` 和 `Cache-Control` 头字段以及任意字段添加到响应头中。 9 | 10 | 11 | 12 | ## 示例配置 13 | 14 | ```nginx 15 | expires 24h; 16 | expires modified +24h; 17 | expires @24h; 18 | expires 0; 19 | expires -1; 20 | expires epoch; 21 | expires $expires; 22 | add_header Cache-Control private; 23 | ``` 24 | 25 | 26 | 27 | ## 指令 28 | 29 | ### add_header 30 | 31 | |\-|说明| 32 | |------:|------| 33 | |**语法**|**add_header** `name value [always]`;| 34 | |**默认**|——| 35 | |**上下文**|http、server、location、location 中的 if| 36 | 37 | 如果响应代码等于 200、201（1.3.10）、204、206、301、302、303、304、307（1.1.16、1.0.13）或 308（1.13.0），则将指定的字段添加到响应报头中。该值可以包含变量。 38 | 39 | 可以存在几个 `add_header` 指令。当且仅当在当前级别上没有定义 `add_header` 指令时，这些指令才从上一级继承。 40 | 41 | 如果指定了 `always` 参数（1.7.5），则无论响应代码为何值，头字段都将被添加。 42 | 43 | ### add_trailer 44 | 45 | |\-|说明| 46 | |------:|------| 47 | |**语法**|**add_trailer** `number size`;| 48 | |**默认**|——| 49 | |**上下文**|http、server、location、location 中的 if| 50 | |**提示**|该指令在 1.13.2 版本中出现| 51 | 52 | 如果响应代码等于 200、201、206、301、302、303、307 或 308，则将指定的字段添加到响应的末尾。该值可以包含变量。 53 | 54 | 可以存在多个 `add_trailer` 指令。当且仅当在当前级别上没有定义 `add_trailer` 指令时，这些指令才从上一级继承。 55 | 56 | 如果指定 `always` 参数，则无论响应代码为何值，都会添加指定的字段。 57 | 58 | ### expires 59 | 60 | |\-|说明| 61 | |------:|------| 62 | |**语法**|**expires** `[modified] time`;
**expires** `epoch` |`max` | `off`;| 63 | |**默认**|expires off;| 64 | |**上下文**|http、server、location、location 中的 if| 65 | 66 | 如果响应代码等于 200、201（1.3.10）、204、206、301、302、303、304 67 | 307（1.1.16、1.0.13）或 308（1.13.0），则启用或禁用添加或修改 `Expires` 和 `Cache-Control` 响应头字段。参数可以是正值或负值。 68 | 69 | ``Expires` 字段中的时间计算为指令中指定的 `time` 和当前时间的总和。如果使用 `modified` 参数（0.7.0、0.6.32），则计算时间为文件修改时间与指令中指定的 `time` 之和。 70 | 71 | 另外，可以使用 `@` 前缀指定一天的时间（0.7.9、0.6.34）： 72 | 73 | ```nginx 74 | expires @15h30m; 75 | ``` 76 | 77 | `epoch` 参数对应于绝对时间 **Thu, 01 Jan 1970 00:00:01 GMT**。`Cache-Control` 字段的内容取决于指定时间的符号： 78 | 79 | - 时间为负值 — `Cache-Control:no-cache` 80 | - 时间为正值或为零 — `Cache-Control:max-age=t`，其中 `t` 是指令中指定的时间，单位为秒 81 | 82 | `max` 参数将 `Expires` 的值设为 `Thu, 2037 Dec 23:55:55 GMT`，`Cache-Control` 设置为 10 年。 83 | 84 | `off` 参数禁止添加或修改 `Expires` 和 `Cache-Control` 响应头字段。 85 | 86 | 最后一个参数值可以包含变量（1.7.9）： 87 | 88 | ```nginx 89 | map $sent_http_content_type $expires { 90 | default off; 91 | application/pdf 42d; 92 | ~image/ max; 93 | } 94 | 95 | expires $expires; 96 | ``` 97 | 98 | ## 原文档 99 | 100 | [http://nginx.org/en/docs/http/ngx_http_headers_module.html](http://nginx.org/en/docs/http/ngx_http_headers_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_map_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_map_module 2 | 3 | - [指令](#directives) 4 | - [map](#map) 5 | - [map_hash_bucket_size](#map_hash_bucket_size) 6 | - [map_hash_max_size](#map_hash_max_size) 7 | 8 | `ngx_http_map_module` 模块创建的变量的值取决于其他变量值。 9 | 10 | 11 | 12 | ## 示例配置 13 | 14 | ```nginx 15 | map $http_host $name { 16 | hostnames; 17 | 18 | default 0; 19 | 20 | example.com 1; 21 | *.example.com 1; 22 | example.org 2; 23 | *.example.org 2; 24 | .example.net 3; 25 | wap.* 4; 26 | } 27 | 28 | map $http_user_agent $mobile { 29 | default 0; 30 | "~Opera Mini" 1; 31 | } 32 | ``` 33 | 34 | 35 | 36 | ## 指令 37 | 38 | ### map 39 | 40 | |\-|说明| 41 | |------:|------| 42 | |**语法**|**map** `string $variable { ... }`;| 43 | |**默认**|——| 44 | |**上下文**|http| 45 | 46 | 创建一个新变量，其值取决于第一个参数中指定的一个或多个源变量的值。 47 | 48 | > 在 0.9.0 版本之前，只能在第一个参数中指定一个变量。 49 | 50 | > 由于只有在使用变量时才计算变量的值，因此仅仅声明大量的 `map` 变量也不会增加额外请求处理负荷。 51 | 52 | `map` 块内的参数指定源和结果值之间的映射。 53 | 54 | 源值可以是字符串或正则表达式（0.9.6）。 55 | 56 | 字符串匹配将忽略大小写。 57 | 58 | 正则表达式应该以区分大小写匹配的 `〜` 符号开始，或者以区分大小写匹配的 `〜*` 符号开始（1.0.4）。正则表达式可以包含命名和位置捕获，之后可以将其用于其他指令和作为结果变量。 59 | 60 | 如果源值与下面描罗列的特殊参数名称之一相匹配，则应该以 `\` 符号为前缀转义。 61 | 62 | 结果值可以包含文本，变量（0.9.0）及其组合（1.11.0）。 63 | 64 | 还支持以下特殊参数： 65 | 66 | - `default` 67 | 68 | 如果源值不匹配指定变体，则设置结果值。如果未指定 `default`，则默认结果值为空字符串。 69 | 70 | - `hostname` 71 | 72 | 表示源值可以是具有前缀或后缀掩码的主机名： 73 | 74 | ```nginx 75 | *.example.com 1; 76 | example.* 1; 77 | ``` 78 | 79 | 以下两条记录 80 | 81 | ```nginx 82 | example.com 1; 83 | * .example.com 1; 84 | ```` 85 | 86 | 可以合并： 87 | 88 | ```nginx 89 | .example.com 1; 90 | ``` 91 | 92 | 这个参数应该在值列表之前指定。 93 | 94 | - `include file` 95 | 96 | 包含一个包含值的文件。可以有多个包含。 97 | 98 | - `volatile` 99 | 100 | 表示该变量不可缓存（1.11.7） 101 | 102 | 如果源值匹配多于一个指定的变体，例如 掩码和正则表达式匹配时，将按照以下优先级顺序选择第一个匹配变体： 103 | 104 | 1. 没有掩码的字符串值 105 | 2. 带有前缀掩码的最长字符串值，例如 `*.example.com` 106 | 3. 带有后缀掩码的最长字符串值，例如 `mail.*` 107 | 4. 首先匹配正则表达式（按照在配置文件中出现的顺序） 108 | 5. 默认值 109 | 110 | ### map_hash_bucket_size 111 | 112 | |\-|说明| 113 | |------:|------| 114 | |**语法**|**map_hash_bucket_size** `size`;| 115 | |**默认**|map_hash_bucket_size 32|64|128;| 116 | |**上下文**|http| 117 | 118 | 设置 [map](#map) 变量哈希表的桶大小。默认值取决于处理器的缓存行大小。设置哈希表的详细内容可在单独的[文档](../../介绍/设置哈希.md)中找到。 119 | 120 | ### map_hash_max_size 121 | 122 | |\-|说明| 123 | |------:|------| 124 | |**语法**|**map_hash_max_size** `size`;| 125 | |**默认**|map_hash_max_size 2048;| 126 | |**上下文**|http| 127 | 128 | 设置 [map](#map) 变量哈希表的最大大小（`size`）。设置哈熟表的详细内容可在单独的[文档](../../介绍/设置哈希.md)中找到。 129 | 130 | ## 原文档 131 | 132 | [http://nginx.org/en/docs/http/ngx_http_map_module.html](http://nginx.org/en/docs/http/ngx_http_map_module.html) -------------------------------------------------------------------------------- /How-To/转换重写规则.md: -------------------------------------------------------------------------------- 1 | # 转换重写规则 2 | 3 | ## 重定向到主站点 4 | 5 | 使用共享主机的用户以前仅使用 Apache 的 `.htaccess` 文件来配置一切，通常翻译下列规则： 6 | 7 | ```apacheconf 8 | RewriteCond %{HTTP_HOST} example.org 9 | RewriteRule (.*) http://www.example.org$1 10 | ``` 11 | 12 | 像这样： 13 | 14 | ```nginx 15 | server { 16 | listen 80; 17 | server_name www.example.org example.org; 18 | if ($http_host = example.org) { 19 | rewrite (.*) http://www.example.org$1; 20 | } 21 | ... 22 | } 23 | ``` 24 | 25 | 这是一个错误、麻烦而无效的做法。正确的方式是为 `example.org` 定义一个单独的服务器： 26 | 27 | ```nginx 28 | server { 29 | listen 80; 30 | server_name example.org; 31 | return 301 http://www.example.org$request_uri; 32 | } 33 | 34 | server { 35 | listen 80; 36 | server_name www.example.org; 37 | ... 38 | } 39 | ``` 40 | 41 | 在 0.9.1 之前的版本，重定向可以通过以下方式实现： 42 | 43 | ```nginx 44 | rewrite ^ http://www.example.org$request_uri?; 45 | ``` 46 | 47 | 另一个例子是使用了颠倒逻辑，即 **所有不是 `example.com` 和 `www.example.com` 的**： 48 | 49 | ```apacheconf 50 | RewriteCond %{HTTP_HOST} !example.com 51 | RewriteCond %{HTTP_HOST} !www.example.com 52 | RewriteRule (.*) http://www.example.com$1 53 | ``` 54 | 55 | 应该简单地定义 `example.com`、`www.example.com` 和 **其他一切**： 56 | 57 | ```nginx 58 | server { 59 | listen 80; 60 | server_name example.com www.example.com; 61 | ... 62 | } 63 | 64 | server { 65 | listen 80 default_server; 66 | server_name _; 67 | return 301 http://example.com$request_uri; 68 | } 69 | ``` 70 | 71 | 在 0.9.1 之前的版本，重定向可以通过以下方式实现： 72 | 73 | ```nginx 74 | rewrite ^ http://example.com$request_uri?; 75 | ``` 76 | 77 | ## 转换 Mongrel 规则 78 | 79 | 典型的 Mongrel 规则： 80 | 81 | ```apacheconf 82 | DocumentRoot /var/www/myapp.com/current/public 83 | 84 | RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f 85 | RewriteCond %{SCRIPT_FILENAME} !maintenance.html 86 | RewriteRule ^.*$ %{DOCUMENT_ROOT}/system/maintenance.html [L] 87 | 88 | RewriteCond %{REQUEST_FILENAME} -f 89 | RewriteRule ^(.*)$ $1 [QSA,L] 90 | 91 | RewriteCond %{REQUEST_FILENAME}/index.html -f 92 | RewriteRule ^(.*)$ $1/index.html [QSA,L] 93 | 94 | RewriteCond %{REQUEST_FILENAME}.html -f 95 | RewriteRule ^(.*)$ $1.html [QSA,L] 96 | 97 | RewriteRule ^/(.*)$ balancer://mongrel_cluster%{REQUEST_URI} [P,QSA,L] 98 | ``` 99 | 100 | 应该转换为： 101 | 102 | ```nginx 103 | location / { 104 | root /var/www/myapp.com/current/public; 105 | 106 | try_files /system/maintenance.html 107 | $uri $uri/index.html $uri.html 108 | @mongrel; 109 | } 110 | 111 | location @mongrel { 112 | proxy_pass http://mongrel; 113 | } 114 | ``` 115 | 116 | ## 原文档 117 | 118 | [http://nginx.org/en/docs/http/converting_rewrite_rules.html](http://nginx.org/en/docs/http/converting_rewrite_rules.html) 119 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_auth_jwt_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_auth_jwt_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [auth_jwt](#auth_jwt) 6 | - [auth_jwt_header_set](#auth_jwt_header_set) 7 | - [auth_jwt_claim_set](#auth_jwt_claim_set) 8 | - [auth_jwt_key_file](#auth_jwt_key_file) 9 | - [内嵌变量](#embedded_variables) 10 | 11 | `ngx_http_auth_jwt_module` 模块（1.11.3）通过验证使用指定的密钥提供的 [JSON Web Token](https://tools.ietf.org/html/rfc7519)（JWT）来实现客户端授权。JWT claims 必须以 [JSON Web Signature](https://tools.ietf.org/html/rfc7515)（JWS）结构编码。该模块可用于 [OpenID Connect](http://openid.net/specs/openid-connect-core-1_0.html) 身份验证。 12 | 13 | 该模块可以通过 [satisfy](ngx_http_core_module.md#satisfy) 指令与其他访问模块（如 [ngx_http_access_module](ngx_http_access_module.md)、[ngx_http_auth_basic_module](ngx_http_auth_basic_module.md) 和 [ngx_http_auth_request_module](ngx_http_auth_request_module.md)）进行组合。 14 | 15 | > 此模块可作为我们商业订阅的一部分。 16 | 17 | 18 | 19 | ## 示例配置 20 | ```nginx 21 | location / { 22 | auth_jwt "closed site"; 23 | auth_jwt_key_file conf/keys.json; 24 | } 25 | ``` 26 | 27 | 28 | 29 | ## 指令 30 | 31 | ### auth_jwt 32 | 33 | |\-|说明| 34 | |:------|:------| 35 | |**语法**|**auth_jwt** `string [token=$variable]` | `off`;| 36 | |**默认**|auth_jwt off;| 37 | |**上下文**|http、server、location| 38 | 39 | 启用 JSON Web Token 验证。指定的字符串作为一个 `realm`。参数值可以包含变量。 40 | 41 | 可选的 `token` 参数指定一个包含 JSON Web Token 的变量。默认情况下，JWT 作 [Bearer Token](https://tools.ietf.org/html/rfc6750) 在 **Authorization** 头中传递。JWT 也可以作为 cookie 或查询字符串的一部分传递： 42 | 43 | ```nginx 44 | auth_jwt "closed site" token=$cookie_auth_token; 45 | ``` 46 | 47 | 特殊值 `off` 取消从上一配置级别继承的 `auth_jwt` 指令的作用。 48 | 49 | ### auth_basic_user_file 50 | 51 | |\-|说明| 52 | |:------|:------| 53 | |**语法**|**auth_jwt_header_set** `$variable name`;| 54 | |**默认**|——| 55 | |**上下文**|http| 56 | |**提示**|该指令在 1.11.10 版本中出现| 57 | 58 | 将 `variable` 设置为给定的 JOSE 头参数 `name`。 59 | 60 | ### auth_jwt_claim_set 61 | 62 | |\-|说明| 63 | |:------|:------| 64 | |**语法**|**auth_jwt_claim_set** `$variable name`;| 65 | |**默认**|——| 66 | |**上下文**|http| 67 | |**提示**|该指令在 1.11.10 版本中出现| 68 | 69 | 将 `variable` 设置为给定的 JWT claim 参数 `name`。 70 | 71 | ### auth_jwt_key_file 72 | 73 | |\-|说明| 74 | |:------|:------| 75 | |**语法**|**auth_jwt_key_file** `file`;| 76 | |**默认**|——| 77 | |**上下文**|http、server、location| 78 | 79 | 指定用于验证 JWT 签名的 [JSON Web Key Set](https://tools.ietf.org/html/rfc7517#section-5) 格式的 `file`（文件）。参数值可以包含变量。 80 | 81 | 82 | 83 | ## 内嵌变量 84 | 85 | `ngx_http_auth_jwt_module` 模块支持内嵌变量： 86 | 87 | - `$jwt_header_name` 88 | 89 | 返回 [JOSE 头](https://tools.ietf.org/html/rfc7515#section-4)的值 90 | - `$jwt_claim_name` 91 | 92 | 返回 [JWT claim](https://tools.ietf.org/html/rfc7519#section-4) 的值 93 | 94 | ## 原文档 95 | [http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) 96 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_dav_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_dav_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [dav_access](#dav_access) 6 | - [dav_methods](#dav_methods) 7 | - [create_full_put_path](#create_full_put_path) 8 | - [min_delete_depth](#min_delete_depth) 9 | 10 | `ngx_http_dav_module` 模块用于通过 WebDAV 协议进行文件管理自动化。该模块处理 HTTP 和 WebDAV 的 PUT、DELETE、MKCOL、COPY 和 MOVE 方法。 11 | 12 | 该模块不是默认构的，您可以在构建时使用 `--with-http_dav_module` 配置参数启用。 13 | 14 | > 需要其他 WebDAV 方法进行操作的 WebDAV 客户端将无法使用此模块。 15 | 16 | 17 | 18 | ## 示例配置 19 | 20 | ```nginx 21 | location / { 22 | root /data/www; 23 | 24 | client_body_temp_path /data/client_temp; 25 | 26 | dav_methods PUT DELETE MKCOL COPY MOVE; 27 | 28 | create_full_put_path on; 29 | dav_access group:rw all:r; 30 | 31 | limit_except GET { 32 | allow 192.168.1.0/32; 33 | deny all; 34 | } 35 | } 36 | ``` 37 | 38 | 39 | 40 | ## 指令 41 | 42 | ### dav_access 43 | 44 | |\-|说明| 45 | |------:|------| 46 | |**语法**|**dav_access** `users:permissions ...`;| 47 | |**默认**|dav_access user:rw;| 48 | |**上下文**|http、server、location| 49 | 50 | 设置新创建的文件和目录的访问权限，例如： 51 | 52 | ```nginx 53 | dav_access user:rw group:rw all:r; 54 | ``` 55 | 56 | 如果指定了任何 `group` （组）或所有访问权限，则可以省略 `user` 权限： 57 | 58 | ```nginx 59 | dav_access group:rw all:r; 60 | ``` 61 | 62 | ### dav_methods 63 | 64 | |\-|说明| 65 | |------:|------| 66 | |**语法**|**dav_methods** `off` \| `method ...`;| 67 | |**默认**|dav_methods off;| 68 | |**上下文**|http、server、location| 69 | 70 | 允许指定的 HTTP 方法和 WebDAV 方法。参数 `off` 将拒绝本模块处理的所有方法。支持以下方法：PUT、DELETE、MKCOL、COPY 和 MOVE。 71 | 72 | 使用 PUT 方法上传的文件首先需要写入一个临时文件，然后重命名该文件。从 0.8.9 版本开始，临时文件和持久存储可以放在不同的文件系统上。但是，请注意，在这种情况下，文件复制需要跨越两个文件系统，而不是简单的重命名操作。因此，建议通过 [client_body_temp_path](ngx_http_core_module.md#client_body_temp_path) 指令对临时文件设置存放目录，与保存文件的目录设置在同一文件系统上。 73 | 74 | 当使用 PUT 方法创建文件时，可以通过在 **Date** 头域中传递日期来指定修改日期。 75 | 76 | ### create_full_put_path 77 | 78 | |\-|说明| 79 | |------:|------| 80 | |**语法**|**create_full_put_path** `on` \| `off`;| 81 | |**默认**|create_full_put_path off;| 82 | |**上下文**|http、server、location| 83 | 84 | WebDAV 规范仅允许在已存在的目录中创建文件。开启该指令允许创建所有需要的中间目录。 85 | 86 | ### min_delete_depth 87 | 88 | |\-|说明| 89 | |------:|------| 90 | |**语法**|**min_delete_depth** `number`;| 91 | |**默认**|min_delete_depth 0;| 92 | |**上下文**|http、server、location| 93 | 94 | 允许 DELETE 方法删除文件，只要请求路径中的元素数不少于指定的数字。例如，指令： 95 | 96 | ```nginx 97 | min_delete_depth 4; 98 | ``` 99 | 100 | 允许删除请求中的文件 101 | 102 | ```nginx 103 | /users/00/00/name 104 | /users/00/00/name/pic.jpg 105 | /users/00/00/page.html 106 | ``` 107 | 108 | 拒绝删除的文件 109 | 110 | ```nginx 111 | /users/00/00 112 | ``` 113 | 114 | ## 原文档 115 | [http://nginx.org/en/docs/http/ngx_http_dav_module.html](http://nginx.org/en/docs/http/ngx_http_dav_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_browser_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_browser_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [ancient_browser](#ancient_browser) 6 | - [ancient_browser_value](#ancient_browser_value) 7 | - [modern_browser](#modern_browser) 8 | - [modern_browser_value](#modern_browser_value) 9 | 10 | 11 | `ngx_http_browser_module` 模块创建值由 **User-Agent** 请求头域决定的变量： 12 | 13 | - `$modern_browser` 14 | 15 | 如果浏览器被识别为现代，则等于 [modern_browser_value](#modern_browser_value) 指令设置的值 16 | - `$ancient_browser` 17 | 18 | 如果浏览器被识别为古代，则等于由 [ancient_browser_value](#ancient_browser_value) 指令设置的值 19 | 20 | - `$MSIE` 21 | 22 | 如果浏览器被识别为任何版本的 MSIE，则等于 `1` 23 | 24 | 25 | 26 | ## 示例配置 27 | 选择一个索引文件： 28 | 29 | ```nginx 30 | modern_browser_value "modern."; 31 | 32 | modern_browser msie 5.5; 33 | modern_browser gecko 1.0.0; 34 | modern_browser opera 9.0; 35 | modern_browser safari 413; 36 | modern_browser konqueror 3.0; 37 | 38 | index index.${modern_browser}html index.html; 39 | ``` 40 | 41 | 旧浏览器重定向： 42 | 43 | ```nginx 44 | modern_browser msie 5.0; 45 | modern_browser gecko 0.9.1; 46 | modern_browser opera 8.0; 47 | modern_browser safari 413; 48 | modern_browser konqueror 3.0; 49 | 50 | modern_browser unlisted; 51 | 52 | ancient_browser Links Lynx netscape4; 53 | 54 | if ($ancient_browser) { 55 | rewrite ^ /ancient.html; 56 | } 57 | ``` 58 | 59 | 60 | 61 | ## 指令 62 | 63 | ### ancient_browser 64 | 65 | |\-|说明| 66 | |------:|------| 67 | |**语法**|**ancient_browser** `string ...`;| 68 | |**默认**|——| 69 | |**上下文**|http、server、location| 70 | 71 | 如果在 **User-Agent** 请求头域中找到任何特殊的子字符串，浏览器将被视为传统类型。特殊字符串 `netscape4` 对应于正则表达式`^Mozilla/[1-4]`。 72 | 73 | ### ancient_browser_value 74 | 75 | |\-|说明| 76 | |------:|------| 77 | |**语法**|**ancient_browser_value** `string`;| 78 | |**默认**|ancient_browser_value 1;| 79 | |**上下文**|http、server、location| 80 | 81 | 设置 `$ancient_browser` 变量的值。 82 | 83 | ### modern_browser 84 | 85 | |\-|说明| 86 | |------:|------| 87 | |**语法**|**modern_browser** `browser version`;
**modern_browser** `unlisted`;| 88 | |**默认**|——| 89 | |**上下文**|http、server、location| 90 | 91 | 指定将浏览器视为现代版本开始的版本。浏览器可以是以下任何一种：`msie`、`gecko`（基于 Mozilla 的浏览器）、`opera`、`safari` 或 `konqueror`。 92 | 93 | 版本可以是以下列格式：X、X.X、X.X.X 或 X.X.X.X。每种格式的最大值分别为 4000、4000.99、4000.99.99 和 4000.99.99.99。 94 | 95 | 未列出的特殊值如果未被 `modern_browser` 和 [ancient_browser](#ancient_browser) 指令指定，则将其视为现代浏览器。否则被认为是传统浏览器。如果请求没有在头中提供 **User-Agent** 域，则浏览器被视为未列出。 96 | 97 | ### modern_browser_value 98 | 99 | |\-|说明| 100 | |------:|------| 101 | |**语法**|**modern_browser_value** `string`;| 102 | |**默认**|modern_browser_value 1;| 103 | |**上下文**|http、server、location| 104 | 105 | 设置 `$modern_browser` 变量的值。 106 | 107 | ## 原文档 108 | [http://nginx.org/en/docs/http/ngx_http_browser_module.html](http://nginx.org/en/docs/http/ngx_http_browser_module.html) -------------------------------------------------------------------------------- /介绍/关于nginScript.md: -------------------------------------------------------------------------------- 1 | # 关于 nginScript 2 | 3 | nginScript 是 JavaScript 语言的一个子集，其可在 [http](http://nginx.org/en/docs/http/ngx_http_js_module.html) 和 [stream](http://nginx.org/en/docs/stream/ngx_stream_js_module.html) 中实现位置（location）和变量处理器。nginScript 符合 [ECMAScript 5.1](http://www.ecma-international.org/ecma-262/5.1/) 规范和部分 [ECMAScript 6](http://www.ecma-international.org/ecma-262/6.0/) 扩展。合规性仍在不断发展。 4 | 5 | ## 目前支持什么 6 | - 布尔值、数字、字符串、对象、数组、函数和正则表达式 7 | - ES5.1 运算符，ES7 幂运算符 8 | - ES5.1语句：`var`、`if`、`else`、`switch`、`for`、`for in`、`while`、`do while`、`break`、`continue`、`return`、`try`、`catch`、`throw`、`finally` 9 | - ES6 `Number` 和 `Math` 的属性和方法 10 | - `String` 方法： 11 | - ES5.1：`fromCharCode`、`concat`、`slice`、`substring`、`substr`、`charAt`、`charCodeAt`、`indexOf`、`lastIndexOf`、`toLowerCase`、`toUpperCase`、`trim`、`search`、`match`、`split`、`replace` 12 | - ES6：`fromCodePoint`、`codePointAt`、`includes`、`startsWith`、`endsWith`、`repeat` 13 | - 非标准：`fromUTF8`、`toUTF8`、`fromBytes`、`toBytes` 14 | - `Object` 方法： 15 | - ES5.1：`create`（不支持属性列表），`keys`、`defineProperty`、`defineProperties`、`getOwnPropertyDescriptor`、`getPrototypeOf`、`hasOwnProperty`、`isPrototypeOf`、`preventExtensions`、`isExtensible`、`freeze`、`isFrozen`、`seal`、`isSealed` 16 | - `Array` 方法： 17 | - ES5.1：`isArray`、`slice`、`splice`、`push`、`pop`、`unshift`、`shift`、`reverse`、`sort`、`join`、`concat`、`indexOf`、`lastIndexOf`、`forEach`、`some`、`every`、`filter`、`map`、`reduce`、`reduceRight` 18 | - ES6：`of`、`fill`、`find`、`findIndex` 19 | - ES7：`includes` 20 | - ES5.1 `Function` 方法：`call`、`apply`、`bind` 21 | - ES5.1 `RegExp` 方法：`test`、`exec` 22 | - ES5.1 `Date` 方法 23 | - ES5.1 全局函数：`isFinite`、`isNaN`、`parseFloat`、`parseInt`、`decodeURI`、`decodeURIComponent`、`encodeURI`、`encodeURIComponent` 24 | 25 | ## 还不支持什么 26 | - ES6 `let` 和 `const` 声明 27 | - 标签 28 | - `arguments` 数组 29 | - `eval` 函数 30 | - `JSON` 对象 31 | - `Error` 对象 32 | - `setTimeout`、`setInterval`、`setImmediate` 函数 33 | - 非整数分数（.235），二进制（0b0101），八进制（0o77）字面量 34 | 35 | ## 下载与安装 36 | nginScript 可用于以下两个模块： 37 | 38 | - [ngx_http_js_module](http://nginx.org/en/docs/http/ngx_http_js_module.html) 39 | - [ngx_stream_js_module](http://nginx.org/en/docs/stream/ngx_stream_js_module.html) 40 | 41 | 这两个模块都不是默认构建的，它们应该从源文件中编译或者作为一个 Linux 软件包来安装 42 | 43 | ## Linux 包安装方式 44 | 在 Linux 环境中，可以使用 nginScript 模块[包](http://nginx.org/en/linux_packages.html#dynmodules)： 45 | 46 | - `nginx-module-njs` - nginScript [动态模块](http://nginx.org/en/docs/ngx_core_module.html#load_module) 47 | - `nginx-module-njs-dbg` - `nginx-module-njs` 包的调试符号 48 | 49 | ## 源码构建方式 50 | 可以使用以下命令克隆 nginScript 的源码[仓库](http://hg.nginx.org/njs?_ga=2.71762323.1468443122.1505551652-1890203964.1497190280)：（需要 [Mercurial](https://www.mercurial-scm.org/) 客户端）： 51 | 52 | ```bash 53 | hg clone http://hg.nginx.org/njs 54 | ``` 55 | 56 | 然后使用 `--add-module` 配置参数进行编译模块： 57 | 58 | ```bash 59 | ./configure --add-module=path-to-njs/nginx 60 | ``` 61 | 62 | 该模块也可以构建为[动态的](http://nginx.org/en/docs/ngx_core_module.html#load_module)： 63 | 64 | ```bash 65 | ./configure --add-dynamic-module=path-to-njs/nginx 66 | ``` 67 | 68 | ## 原文档 69 | 70 | [http://nginx.org/en/docs/njs_about.html](http://nginx.org/en/docs/njs_about.html) 71 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_geoip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_geoip_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [geoip_country](#geoip_country) 6 | - [geoip_city](#geoip_city) 7 | - [geoip_org](#geoip_org) 8 | 9 | `ngx_stream_geoip_module` 模块（1.11.3）使用预编译的 [MaxMind](http://www.maxmind.com/) 数据库创建依赖于客户端 IP 地址的变量。 10 | 11 | 使用支持 IPv6 的数据库时，查找 IPv4 地址将转为查找 IPv4 映射的 IPv6 地址。 12 | 13 | 默认构建不包含此模块，可在构建时使用 `--with-stream_geoip_module` 配置参数启用。 14 | 15 | > 该模块需要 [MaxMind GeoIP](http://www.maxmind.com/app/c) 库。 16 | 17 | 18 | 19 | ## 示例配置 20 | 21 | ```nginx 22 | stream { 23 | geoip_country GeoIP.dat; 24 | geoip_city GeoLiteCity.dat; 25 | 26 | map $geoip_city_continent_code $nearest_server { 27 | default example.com; 28 | EU eu.example.com; 29 | NA na.example.com; 30 | AS as.example.com; 31 | } 32 | ... 33 | } 34 | ``` 35 | 36 | 37 | 38 | ## 指令 39 | 40 | ### geoip_country 41 | 42 | |\-|说明| 43 | |------:|------| 44 | |**语法**|**geoip_country** `file`;| 45 | |**默认**|——| 46 | |**上下文**|stream| 47 | 48 | 指定用于根据客户端 IP 地址确定国家的数据库。使用此数据库时，以下变量可用： 49 | 50 | - `$geoip_country_code` 51 | 52 | 两个字母表示的国家代码，比如 `RU`、`US` 53 | 54 | - `$geoip_country_code3` 55 | 56 | 三个字母表示的国家代码，比如 `RUS`、`USA` 57 | 58 | - `$geoip_country_name` 59 | 60 | 国家名称，比如 `Russian Federation`、`United States` 61 | 62 | ### geoip_city 63 | 64 | |\-|说明| 65 | |------:|------| 66 | |**语法**|**geoip_city** `file`;| 67 | |**默认**|——| 68 | |**上下文**|stream| 69 | 70 | 指定用于根据客户端 IP 地址确定国家、地区和城市的数据库。使用此数据库时，以下变量可用： 71 | 72 | - `$geoip_area_code` 73 | 74 | 电话区号（仅限美国） 75 | 76 | > 因为使用到过时的数据库字段，此变量可能包含过时的信息。 77 | 78 | - `$geoip_city_continent_code` 79 | 80 | 两个字母表示的大陆代码，比如 `RU`、`US` 81 | 82 | - `$geoip_city_country_code` 83 | 84 | 两个字母表示的国家代码，比如 `RU`、`US` 85 | 86 | - `$geoip_city_country_code3` 87 | 88 | 三个字母表示的国家代码，比如 `RUS`、`USA` 89 | 90 | - `$geoip_city_country_name` 91 | 92 | 国家名称，比如 `Russian Federation`、`United States` 93 | 94 | - `$geoip_dma_code` 95 | 96 | 美国 DMA 区域代码（也称为**都市代码**），根据 Google AdWords API 中的[地理位置](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions)定位。 97 | 98 | - `$geoip_latitude` 99 | 100 | 维度 101 | 102 | - `$geoip_longitude` 103 | 104 | 经度 105 | 106 | - `$geoip_region` 107 | 108 | 双符号国家区域代码（地区、领土、州、省、联邦土地等），例如 `48`、`DC`。 109 | 110 | - `$geoip_region_name` 111 | 112 | 国家地区名称（地区、领土、州、省、联邦土地等），例如：`Moscow City`、`District of Columbia`。 113 | 114 | - `$geoip_city` 115 | 116 | 城市名称，例如：`Moscow”`、`Washington`。 117 | 118 | - `$geoip_postal_code` 119 | 120 | 邮政编码 121 | 122 | ### geoip_org 123 | 124 | |\-|说明| 125 | |------:|------| 126 | |**语法**|**geoip_org** `file`;| 127 | |**默认**|——| 128 | |**上下文**|stream| 129 | 130 | 指定用于根据客户端 IP 地址确定组织的数据库。使用此数据库时，以下变量可用： 131 | 132 | - `$geoip_org` 133 | 134 | 组织名称，例如：`The University of Melbourne`。 135 | 136 | ## 原文档 137 | [http://nginx.org/en/docs/stream/ngx_stream_geoip_module.html](http://nginx.org/en/docs/stream/ngx_stream_geoip_module.html) -------------------------------------------------------------------------------- /How-To/使用DTrace_pid提供程序调试nginx.md: -------------------------------------------------------------------------------- 1 | # 使用 DTrace pid 提供程序调试 nginx 2 | 3 | 本文假设读者对 nginx 内部原理和 [DTrace](http://nginx.org/en/docs/nginx_dtrace_pid_provider.html#see_also) 有了一定的了解。 4 | 5 | 虽然使用了 [--with-debug](http://nginx.org/en/docs/debugging_log.html) 选项构建的 nginx 已经提供了大量关于请求处理的信息，但有时候更有必要详细地跟踪代码路径的特定部分，同时省略其余不必要的调试输出。DTrace pid 提供程序（在 Solaris，MacOS 上可用）是一个用于浏览用户程序内部的有用工具，因为它不需要更改任何代码，就可以帮助您完成任务。跟踪和打印 nginx 函数调用的简单 DTrace 脚本示例如下所示： 6 | 7 | ```d 8 | #pragma D option flowindent 9 | 10 | pid$target:nginx::entry { 11 | } 12 | 13 | pid$target:nginx::return { 14 | } 15 | ``` 16 | 17 | 尽管如此，DTrace 的函数调用跟踪功能仅提供有限的有用信息。实时检查的功能参数通常更加有趣，但也更复杂一些。以下示例旨在帮助读者熟悉 DTrace 以及使用 DTrace 分析 nginx 行为的过程。 18 | 19 | 使用 DTrace 与 nginx 的常见方案之一是：附加到 nginx 的工作进程来记录请求行和请求开始时间。附加的相应函数是 `ngx_http_process_request()`，参数指向的是一个 `ngx_http_request_t` 结构的指针。使用 DTrace 脚本实现这种请求日志记录可以简单到： 20 | 21 | ```d 22 | pid$target::*ngx_http_process_request:entry 23 | { 24 | this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); 25 | this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data, 26 | this->request->request_line.len)); 27 | printf("request line = %s\n", this->request_line); 28 | printf("request start sec = %d\n", this->request->start_sec); 29 | } 30 | ``` 31 | 32 | 需要注意的是，在上面的示例中，DTrace 需要引用 `ngx_http_process_request` 结构的一些相关信息。不幸的是，虽然可以在 DTrace 脚本中使用特定的 `#include` 指令，然后将其传递给 C 预处理器（使用 `-C` 标志），但这并不能真正起效。由于大量的交叉依赖，几乎所有的 nginx 头文件都必须包含在内。反过来，基于 `configure` 脚本设置，nginx 头将包括 PCRE、OpenSSL 和各种系统头文件。理论上，在 DTrace 脚本预处理和编译时，与特定的 nginx 构建相关的所有头文件都有可能被包含进来，实际上 DTrace 脚本很有可能由于某些头文件中的未知语法而造成无法编译。 33 | 34 | 上述问题可以通过在 DTrace 脚本中仅包含相关且必要的结构和类型定义来解决。DTrace 必须知道结构、类型和字段偏移的大小。因此，通过手动优化用于 DTrace 的结构定义，可以进一步降低依赖。 35 | 36 | 让我们使用上面的 DTrace 脚本示例，看看它需要哪些结构定义才能正常地工作。 37 | 38 | 首先应该包含由 configure 生成的 `objs/ngx_auto_config.h` 文件，因为它定义了一些影响各个方面的 `＃ifdef` 常量。之后，一些基本类型和定义（如 `ngx_str_t`，`ngx_table_elt_t`，`ngx_uint_t` 等）应放在 DTrace 脚本的开头。这些定义经常被使用但不太可能经常改变的。 39 | 40 | 那里有一个包含许多指向其他结构的指针的 ngx_http_process_request_t 结构。因为这些指针与这个脚本无关，而且因为它们具有相同的大小，所以可以用 void 指针来替换它们。但最好添加合适的 typedef，而不是更改定义： 41 | 42 | ```d 43 | typedef ngx_http_upstream_t void; 44 | typedef ngx_http_request_body_t void; 45 | ``` 46 | 47 | 最后但同样重要的是，需要添加两个成员结构的定义（`ngx_http_headers_in_t`，`ngx_http_headers_out_t`）、回调函数声明和常量定义。 48 | 49 | 最后，DTrace 脚本可以从 [这里](http://nginx.org/download/trace_process_request.d) 下载。 50 | 51 | 以下示例是运行此脚本的输出： 52 | 53 | ``` 54 | # dtrace -C -I ./objs -s trace_process_request.d -p 4848 55 | dtrace: script 'trace_process_request.d' matched 1 probe 56 | CPU ID FUNCTION:NAME 57 | 1 4 .XAbmO.ngx_http_process_request:entry request line = GET / HTTP/1.1 58 | request start sec = 1349162898 59 | 60 | 0 4 .XAbmO.ngx_http_process_request:entry request line = GET /en/docs/nginx_dtrace_pid_provider.html HTTP/1.1 61 | request start sec = 1349162899 62 | ``` 63 | 64 | 使用类似的技术，读者应该能够跟踪其他 nginx 函数调用。 65 | 66 | ## 相关阅读 67 | 68 | - [Solaris 动态跟踪指南](http://docs.oracle.com/cd/E19253-01/817-6223/index.html) 69 | - [DTrace pid 提供程序介绍](http://dtrace.org/blogs/brendan/2011/02/09/dtrace-pid-provider/) 70 | 71 | ## 原文档 72 | 73 | [http://nginx.org/en/docs/nginx_dtrace_pid_provider.html](http://nginx.org/en/docs/nginx_dtrace_pid_provider.html) 74 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_limit_conn_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_limit_conn_module 2 | 3 | - [指令](#directives) 4 | - [limit_conn](#limit_conn) 5 | - [limit_conn_log_level](#limit_conn_log_level) 6 | - [limit_conn_status](#limit_conn_status) 7 | - [limit_conn_zone](#limit_conn_zone) 8 | - [limit_zone](#limit_zone) 9 | 10 | `ngx_http_limit_conn_module` 模块用于限制每个已定义的 key 的连接数量，特别是来自单个 IP 地址的连接数量。 11 | 12 | 并非所有的连接都会被计数。只有当服务器处理了请求并且已经读取了整个请求头时，连接才被计数。 13 | 14 | 15 | 16 | ## 示例配置 17 | 18 | ```nginx 19 | http { 20 | limit_conn_zone $binary_remote_addr zone=addr:10m; 21 | 22 | ... 23 | 24 | server { 25 | 26 | ... 27 | 28 | location /download/ { 29 | limit_conn addr 1; 30 | } 31 | ``` 32 | 33 | 34 | 35 | ## 指令 36 | 37 | ### limit_conn 38 | 39 | |\-|说明| 40 | |------:|------| 41 | |**语法**|**limit_conn** `zone number`;| 42 | |**默认**|——| 43 | |**上下文**|http、server、location| 44 | 45 | 设置给定键值的共享内存区域和最大允许连接数。当超过此限制时，服务器将返回错误响应请求。例如： 46 | 47 | ```nginx 48 | limit_conn_zone $binary_remote_addr zone=addr:10m; 49 | 50 | server { 51 | location /download/ { 52 | limit_conn addr 1; 53 | } 54 | ``` 55 | 56 | 同一时间只允许一个 IP 地址一个连接。 57 | 58 | > 在 HTTP/2和 SPDY 中，每个并发请求都被视为一个单独的连接。 59 | 60 | 可以有多个 `limit_conn` 指令。 例如，以下配置将限制每个客户端 IP 连接到服务器的数量，同时限制连接到虚拟服务器的总数： 61 | 62 | ```nginx 63 | limit_conn_zone $binary_remote_addr zone=perip:10m; 64 | limit_conn_zone $server_name zone=perserver:10m; 65 | 66 | server { 67 | ... 68 | limit_conn perip 10; 69 | limit_conn perserver 100; 70 | } 71 | ``` 72 | 73 | 当且仅当在当前级别上没有 `limit_conn` 指令时，这些指令才从前一级继承。 74 | 75 | ### limit_conn_log_level 76 | 77 | |\-|说明| 78 | |------:|------| 79 | |**语法**|**limit_conn_log_level** `info` | `notice` | `warn` | `error`;| 80 | |**默认**|limit_conn_log_level error;| 81 | |**上下文**|http、server、location| 82 | |**提示**|该指令在 0.8.18 版本中出现| 83 | 84 | 当服务器限制连接数时，设置所需的日志记录级别。 85 | 86 | ### limit_conn_status 87 | 88 | |\-|说明| 89 | |------:|------| 90 | |**语法**|**limit_conn_status** `code`;| 91 | |**默认**|limit_conn_status 503;| 92 | |**上下文**|http、server、location| 93 | |**提示**|该指令在 1.3.15 版本中出现| 94 | 95 | 设置响应拒绝请求返回的状态码。 96 | 97 | ### limit_conn_zone 98 | 99 | |\-|说明| 100 | |------:|------| 101 | |**语法**|**limit_conn_zone** `key zone=name:size`;| 102 | |**默认**|——| 103 | |**上下文**|http| 104 | 105 | 为共享内存区域设置参数，该区域将保留各种键的状态。特别是，该状态包含当前的连接数。`key` 可以包含文本、变量及其组合。不包括有空键值的请求。 106 | 107 | > 在 1.7.6 版本之前，一个 key 可能只包含一个变量。 108 | 109 | 用法示例： 110 | 111 | ```nginx 112 | limit_conn_zone $binary_remote_addr zone=addr:10m; 113 | ``` 114 | 115 | 在这里，客户端 IP 地址作为 key。请注意，不是 `$remote_addr`，而是使用 `$binary_remote_addr` 变量。`$remote_addr` 变量的大小可以为 7 到 15 个字节不等。存储状态在 32 位平台上占用 32 或 64 字节的内存，在 64 位平台上总是占用 64 字节。对于 IPv4 地址，`$binary_remote_addr` 变量的大小始终为 4 个字节，对于 IPv6 地址则为 16 个字节。存储状态在 32 位平台上始终占用 32 或 64 个字节，在 64 位平台上占用 64 个字节。一兆字节的区域可以保持大约 32000 个 32 字节的状态或大约 16000 个 64 字节的状态。如果区域存储耗尽，服务器会将错误返回给所有其余的请求。 116 | 117 | ### limit_zone 118 | 119 | |\-|说明| 120 | |------:|------| 121 | |**语法**|**limit_zone** `name $variable size`;| 122 | |**默认**|——| 123 | |**上下文**|http| 124 | 125 | 该指令在 1.1.8 版本中已过时，并在 1.7.6 版本中被删除。请使用等效 [limit_conn_zone](#limit_conn_zone) 指令代替： 126 | 127 | > `limit_conn_zone $variable zone=name:size;` 128 | 129 | ## 原文档 130 | 131 | [http://nginx.org/en/docs/http/ngx_http_limit_conn_module.html](http://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_log_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_log_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [access_log](#access_log) 6 | - [log_format](#log_format) 7 | - [open_log_file_cache](#open_log_file_cache) 8 | 9 | `ngx_stream_log_module` 模块（1.11.4）按指定的格式写入会话日志。 10 | 11 | 12 | 13 | ## 示例配置 14 | 15 | ```nginx 16 | log_format basic '$remote_addr [$time_local] ' 17 | '$protocol $status $bytes_sent $bytes_received ' 18 | '$session_time'; 19 | 20 | access_log /spool/logs/nginx-access.log basic buffer=32k; 21 | ``` 22 | 23 | 24 | 25 | ## 指令 26 | 27 | ### access_log 28 | 29 | |\-|说明| 30 | |------:|------| 31 | |**语法**|**access_log** `path format [buffer=size] [gzip[=level]] [flush=time] [if=condition]`;
**access_log** `off`;| 32 | |**默认**|access_log off;| 33 | |**上下文**|stream、server| 34 | 35 | 设置缓冲日志写入的路径、[格式](#log_format)和配置。可以在同一级别指定多个日志。可通过在第一个参数中指定 `syslog:` 前缀来配置记录到 [syslog](../../介绍/记录日志到syslog.md)。特殊值 `off` 取消当前级别的所有 `access_log` 指令。 36 | 37 | 如果使用 `buffer` 或 `gzip` 参数，则将缓冲 log 的写入。 38 | 39 | > 缓冲区大小不得超过磁盘文件的原子写入大小。对于 FreeBSD 而言，这个大小是无限制的。 40 | 41 | 启用缓冲后，以下情况数据将写入文件： 42 | 43 | - 如果下一个日志行不能放入缓冲区 44 | - 如果缓冲的数据早于 `flush` 参数指定的数据 45 | - 当 worker 进程重新打开日志文件或正在关闭时 46 | 47 | 如果使用 `gzip` 参数，将写入文件之前将压缩缓冲的数据。压缩级别可以设置为 1（最快，压缩级别低）到 9（最慢，压缩级别最高）之间。默认情况下，缓冲区大小等于 64K 字节，压缩级别设置为 1。由于数据是以原子块压缩，因此日志文件可以随时通过 `zcat` 解压缩或读取。 48 | 49 | 示例： 50 | 51 | ```nginx 52 | access_log /path/to/log.gz basic gzip flush=5m; 53 | ``` 54 | 55 | > 要使 gzip 压缩起作用，必须在构建 nginx 使用 zlib 库。 56 | 57 | 文件路径可以包含变量，但是这样的日志有一些约束： 58 | 59 | - 被 worker 进程使用凭据的[用户](../http/ngx_http_core_module.md#user)应具有在具有此类日志的目录中创建文件的权限 60 | - 缓冲写入将不起作用 61 | - 每个日志写入都会打开和关闭文件。但是，由于频繁使用的文件的描述符可以存储在[缓存](ngx_stream_log_module.md#open_log_file_cache)中，因此可以在 [open_log_file_cache](ngx_stream_log_module.md#open_log_file_cache) 指令的 `valid` 参数指定的时间内继续写入旧文件 62 | 63 | `if` 参数启用条件日志。如果 `condition` 计值为 0 或空字符串，则不会记录会话。 64 | 65 | ### log_format 66 | 67 | |\-|说明| 68 | |------:|------| 69 | |**语法**|**log_format** `name [escape=default\|json\|none] string ...`;| 70 | |**默认**|——| 71 | |**上下文**|stream| 72 | 73 | 指定日志格式，例如： 74 | 75 | ```nginx 76 | log_format proxy '$remote_addr [$time_local] ' 77 | '$protocol $status $bytes_sent $bytes_received ' 78 | '$session_time "$upstream_addr" ' 79 | '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"'; 80 | ``` 81 | 82 | `escape` 参数（1.11.8）允许在变量中设置转义的 `json` 或 `default` 字符，默认情况下，使用 `default` 转义。 `none` 参数（1.13.10）禁用转义。 83 | 84 | ### open_log_file_cache 85 | 86 | |\-|说明| 87 | |------:|------| 88 | |**语法**|**open_log_file_cache** `max=N [inactive=time] [min_uses=N] [valid=time]`;
**open_log_file_cache** `off`;| 89 | |**默认**|open_log_file_cache off;| 90 | |**上下文**|stream、server| 91 | 92 | 定义一个缓存，用于存储名称中包含变量的常用日志的文件描述符。该指令有以下参数： 93 | 94 | - `max` 95 | 96 | 设置缓存中的最大描述符数，如果缓存变满，则最近最少使用（LRU）的描述符将被关闭 97 | 98 | - `inactive` 99 | 100 | 如果在此期间没有发生访问，则设置关闭缓存描述符的时间。默认为 10 秒 101 | 102 | - `min_uses` 103 | 104 | 设置在 `inactive` 参数定义的时间内文件使用的最小数量，使描述符在缓存中保持打开状态。默认为 1 105 | 106 | - `valid` 107 | 108 | 设置检查同名文件是否仍然存在的时间。默认为 60 秒 109 | 110 | - `off` 111 | 112 | 禁用缓存 113 | 114 | 用法示例： 115 | 116 | ```nginx 117 | open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; 118 | ``` 119 | 120 | ## 原文档 121 | [http://nginx.org/en/docs/stream/ngx_stream_log_module.html](http://nginx.org/en/docs/stream/ngx_stream_log_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_limit_req_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_limit_req_module 2 | 3 | - [指令](#directives) 4 | - [limit_req](#limit_req) 5 | - [limit_req_log_level](#limit_req_log_level) 6 | - [limit_req_status](#limit_req_status) 7 | - [limit_req_zone](#limit_req_zone) 8 | 9 | `ngx_http_limit_req_module` 模块（0.7.21）用于限制每个已定义 key 的请求处理速率，特别是来自单个 IP 地址请求的处理速率。限制机制采用了 **leaky bucket** （漏桶算法）方法完成。 10 | 11 | 12 | 13 | ## 示例配置 14 | 15 | ```nginx 16 | http { 17 | limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; 18 | 19 | ... 20 | 21 | server { 22 | 23 | ... 24 | 25 | location /search/ { 26 | limit_req zone=one burst=5; 27 | } 28 | ``` 29 | 30 | 31 | 32 | ## 指令 33 | 34 | ### limit_req 35 | 36 | |\-|说明| 37 | |------:|------| 38 | |**语法**|**limit_req** `zone=name [burst=number] [nodelay]`;| 39 | |**默认**|——| 40 | |**上下文**|http、server、location| 41 | 42 | 设置共享内存区域和请求的最大突发大小。如果请求速率超过为某个区域配置的速率，则它们的处理会延迟，从而使请求以定义的速率处理。过多的请求被延迟，直到它们的数量超过最大突发大小，在这种情况下请求被终止并出现[错误](#limit_req_status)。 默认情况下，最大突发大小等于零。例如： 43 | 44 | ```nginx 45 | limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; 46 | 47 | server { 48 | location /search/ { 49 | limit_req zone=one burst=5; 50 | } 51 | ``` 52 | 53 | 平均每秒不超过 1 个请求，并且突发不超过 5 个请求。 54 | 55 | 如果在限制期间延迟请求过多，则不需要使用参数 `nodelay`： 56 | 57 | ```nginx 58 | limit_req zone=one burst=5 nodelay; 59 | ``` 60 | 61 | 可以存在多个 `limit_req` 指令。例如，以下配置将限制来自单个 IP 地址请求的处理速率，同时限制虚拟服务器的请求处理速率： 62 | 63 | ```nginx 64 | limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s; 65 | limit_req_zone $server_name zone=perserver:10m rate=10r/s; 66 | 67 | server { 68 | ... 69 | limit_req zone=perip burst=5 nodelay; 70 | limit_req zone=perserver burst=10; 71 | } 72 | ``` 73 | 74 | 当且仅当在当前级别上没有 `limit_req` 指令时，这些指令才从上一级继承。 75 | 76 | ### limit_req_log_level 77 | 78 | |\-|说明| 79 | |------:|------| 80 | |**语法**|**limit_req_log_level** `info` | `notice` | `warn` | `error`;| 81 | |**默认**|limit_req_log_level error;| 82 | |**上下文**|http、server、location| 83 | |**提示**|该指令在 0.8.18 版本中出现| 84 | 85 | 当服务器由于速率超出而拒绝处理请求或延迟请求处理时，设置所需的日志记录级别。延误情况的记录等级比拒绝情况的记录低一些。例如，如果指定了 `limit_req_log_level notice`，则延迟情况将会在 `info` 级别记录。 86 | 87 | ### limit_req_status 88 | 89 | |\-|说明| 90 | |------:|------| 91 | |**语法**|**limit_req_status** `code`;| 92 | |**默认**|limit_req_status 503;| 93 | |**上下文**|http、server、location| 94 | |**提示**|该指令在 1.3.15 版本中出现| 95 | 96 | 设置响应拒绝请求返回的状态码。 97 | 98 | ### limit_req_zone 99 | 100 | |\-|说明| 101 | |------:|------| 102 | |**语法**|**limit_req_zone** `key zone=name:size rate=rate`;| 103 | |**默认**|——| 104 | |**上下文**|http| 105 | 106 | 为共享内存区域设置参数，该区域将保留各种键的状态。特别是，该状态包含当前的连接数。`key` 可以包含文本、变量及其组合。不包括有空键值的请求。 107 | 108 | > 在 1.7.6 版本之前，一个 `key` 可能只包含一个变量。 109 | 110 | 用法示例： 111 | 112 | ```nginx 113 | limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; 114 | ``` 115 | 116 | 在这里，状态保持在 10 兆字节的区域 **one**，并且该区域的平均请求处理速率不能超过每秒 1 个请求。 117 | 118 | 客户端 IP 地址作为 key。请注意，不是 `$remote_addr`，而是使用 `$binary_remote_addr` 变量。`$binary_remote_addr` 变量的大小始终为 4 个字节，对于 IPv6 地址则为 16 个字节。存储状态在 32 位平台上始终占用 32 或 64 个字节，在 64 位平台上占用 64 个字节。一兆字节的区域可以保持大约 32000 个 32 字节的状态或大约 16000 个 64 字节的状态或大约 8000 个 128 字节的状态。 119 | 120 | 如果区域存储耗尽，最近最少使用的状态将被删除。即使在此之后无法创建新状态，该请求也会因[错误](#limit_req_status)而终止。 121 | 122 | 速率以每秒请求数（r/s）指定。如果需要每秒小于一个请求的速率，则按每分钟请求（r/m）指定。例如，每秒半请求是 30r/m。 123 | 124 | ## 原文档 125 | 126 | [http://nginx.org/en/docs/http/ngx_http_limit_req_module.html](http://nginx.org/en/docs/http/ngx_http_limit_req_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_xslt_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_xslt_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [xml_entities](#xml_entities) 6 | - [xslt_last_modified](#xslt_last_modified) 7 | - [xslt_param](#xslt_param) 8 | - [xslt_string_param](#xslt_string_param) 9 | - [xslt_stylesheet](#xslt_stylesheet) 10 | - [xslt_types](#xslt_types) 11 | 12 | `ngx_http_xslt_module`（0.7.8+）是一个过滤器，可使用一个或多个 XSLT 样式表来转换 XML 响应。 13 | 14 | 默认不构建此模块，可在构建时使用 `--with-http_xslt_module` 配置参数启用。 15 | 16 | > 该模块雨来 [libxml2](http://xmlsoft.org/) 和 [libxslt](http://xmlsoft.org/XSLT/) 库。 17 | 18 | 19 | 20 | ## 示例配置 21 | 22 | ```nginx 23 | location / { 24 | xml_entities /site/dtd/entities.dtd; 25 | xslt_stylesheet /site/xslt/one.xslt param=value; 26 | xslt_stylesheet /site/xslt/two.xslt; 27 | } 28 | ``` 29 | 30 | 31 | 32 | ## 指令 33 | 34 | ### xml_entities 35 | 36 | |\-|说明| 37 | |:------|:------| 38 | |**语法**|**xml_entities** `path`;| 39 | |**默认**|——| 40 | |**上下文**|http、server、location| 41 | 42 | 指定声明字符实体的 DTD 文件。该文件在配置阶段编译。出于技术原因，该模块无法在已处理的 XML 中使用外部子集声明，因此将其忽略，可使用专门定义的文件。该文件不应描述 XML 结构。仅声明所需的字符实体就足够了，例如： 43 | 44 | ``` 45 | 46 | ``` 47 | 48 | ### xslt_last_modified 49 | 50 | |\-|说明| 51 | |:------|:------| 52 | |**语法**|**xslt_last_modified** `on` | `off`;| 53 | |**默认**|xslt_last_modified off;| 54 | |**上下文**|http、server、location| 55 | |**提示**|该指令在 1.5.1 版本中出现| 56 | 57 | 允许在 XSLT 转换期间保留原始响应中的 `Last-Modified` 头字段，以方便响应缓存。 58 | 59 | 默认情况下，在转换期间修改响应的内容时，将删除头字段，并且该头字段可能包含动态生成的元素或片段，这些元素或片段独立于原始响应更改。 60 | 61 | ### xslt_param 62 | 63 | |\-|说明| 64 | |:------|:------| 65 | |**语法**|**xslt_param** `parameter value`;| 66 | |**默认**|——| 67 | |**上下文**|http、server、location| 68 | |**提示**|该指令在 1.1.18 版本中出现| 69 | 70 | 定义 XSLT 样式表的参数。该值（`value`）为 XPath 表达式。`value` 可以包含变量。要将字符串值传递给样式表，可使用 [xslt_string_param](#xslt_string_param) 指令。 71 | 72 | 可以有多个 `xslt_param` 指令。当且仅当当前级别上没有定义 `xslt_param` 和 [xslt_string_param](#xslt_string_param) 指令时，这些指令才从上一级继承。 73 | 74 | ### xslt_string_param 75 | 76 | |\-|说明| 77 | |:------|:------| 78 | |**语法**|**xslt_string_param** `parameter value`;| 79 | |**默认**|——| 80 | |**上下文**|http、server、location| 81 | |**提示**|该指令在 1.1.18 版本中出现| 82 | 83 | 定义 XSLT 样式表的字符串参数。`value` 中的 XPath 表达式不会被解释。`value` 可以包含变量。 84 | 85 | 可以有多个 `xslt_string_param` 指令。当且仅当当前级别上没有定义 [xslt_param](#xslt_param) 和 `xslt_string_param` 指令时，这些指令才从上一级继承。 86 | 87 | ### xslt_stylesheet 88 | 89 | |\-|说明| 90 | |:------|:------| 91 | |**语法**|**xslt_stylesheet** `stylesheet [parameter=value ...]`;| 92 | |**默认**|——| 93 | |**上下文**|http、server、location| 94 | 95 | 定义 XSLT 样式表及其可选参数。在配置阶段将编译样式表。 96 | 97 | 可以单独指定参数，也可以使用 `:` 定界符将其分组在一行中。如果参数包含 `:` 字符，则应将其转义为 `％3A`。另外，`libxslt` 要求将包含非字母数字字符的参数括在单引号或双引号中，例如： 98 | 99 | ``` 100 | param1='http%3A//www.example.com':param2=value2 101 | ``` 102 | 103 | 参数描述可以包含变量，例如，整行参数可以取自单个变量： 104 | 105 | ```nginx 106 | location / { 107 | xslt_stylesheet /site/xslt/one.xslt 108 | $arg_xslt_params 109 | param1='$value1':param2=value2 110 | param3=value3; 111 | } 112 | ``` 113 | 114 | 可以指定多个样式表。它们将按指定顺序应用。 115 | 116 | ### xslt_types 117 | 118 | |\-|说明| 119 | |:------|:------| 120 | |**语法**|**xslt_types** `mime-type ...`;| 121 | |**默认**|xslt_types text/xml;| 122 | |**上下文**|http、server、location| 123 | 124 | 除了 `text/xml` 之外，还启用有指定 MIME 类型的响应的转换。特殊值 `*` 与任何 MIME 类型（0.8.29）匹配。如果转换结果是 HTML 响应，则其 MIME 类型将更改为 `text/html`。 125 | 126 | ## 原文档 127 | 128 | - [http://nginx.org/en/docs/http/ngx_http_xslt_module.html](http://nginx.org/en/docs/http/ngx_http_xslt_module.html) 129 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_mp4_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_mp4_module 2 | 3 | - [指令](#directives) 4 | - [mp4](#mp4) 5 | - [mp4_buffer_size](#mp4_buffer_size) 6 | - [mp4_max_buffer_size](#mp4_max_buffer_size) 7 | - [mp4_limit_rate](#mp4_limit_rate) 8 | - [mp4_limit_rate_after](#mp4_limit_rate_after) 9 | 10 | `ngx_http_mp4_module` 模块为 MP4 文件提供伪流服务端支持。这些文件的扩展名通常为 `.mp4`、`.m4v` 或 `.m4a`。 11 | 12 | 伪流与兼容的 Flash 播放器可以很好地配合工作。播放器在查询字符串参数中指定的开始时间向服务器发送 HTTP 请求（简单地以 `start` 命名并以秒为单位），服务器以流响应方式使其起始位置与请求的时间相对应，例如： 13 | 14 | ```nginx 15 | http://example.com/elephants_dream.mp4?start=238.88 16 | ``` 17 | 18 | 这将允许随时执行随机查找，或者在时间线中间开始回放。 19 | 20 | 为了支持搜索，基于 H.264 的格式将元数据存储在所谓的 **moov atom** 中。它是保存整个文件索引信息文件的一部分。 21 | 22 | 要开始播放，播放器首先需要读取元数据。通过发送一个有 `start=0` 参数的特殊请求来完成的。许多编码软件在文件的末尾插入元数据。这对于伪流播来说很糟糕，因为播放器必须在开始播放之前下载整个文件。如果元数据位于文件的开头，那么 nginx 就可以简单地开始发回文件内容。如果元数据位于文件末尾，nginx 必须读取整个文件并准备一个新流，以便元数据位于媒体数据之前。这涉及到一些 CPU、内存和磁盘 I/O 开销，所以最好事先[准备一个用于伪流传输的原始文件](http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare)，而不是让 nginx 在每个这样的请求上都这样处理。 23 | 24 | 该模块还支持设置播放结束点的 HTTP 请求（1.5.13）的 `end` 参数。`end` 参数可以与 `start` 参数一起指定或单独指定： 25 | 26 | ```nginx 27 | http://example.com/elephants_dream.mp4?start=238.88&end=555.55 28 | ``` 29 | 30 | 对于有非零 `start` 或 `end` 参数的匹配请求，nginx 将从文件中读取元数据，准备有所需时间范围的流并将其发送到客户端 这与上面描述的开销相同。 31 | 32 | 如果匹配请求不包含 `start` 和 `end` 参数，则不会有开销，并且文件仅作为静态资源发送。有些播放器也支持 byte-range 请求，因此不需要这个模块。 33 | 34 | 该模块不是默认构建的，可以使用 `--with-http_mp4_module` 配置参数启用。 35 | 36 | > 如果以前使用过第三方 mp4 模块，则应该禁用它。 37 | 38 | [ngx_http_flv_module](ngx_http_flv_module.md) 模块提供了对 FLV 文件的类伪流式的支持。 39 | 40 | 41 | 42 | ## 示例配置 43 | 44 | ```nginx 45 | location /video/ { 46 | mp4; 47 | mp4_buffer_size 1m; 48 | mp4_max_buffer_size 5m; 49 | mp4_limit_rate on; 50 | mp4_limit_rate_after 30s; 51 | } 52 | ``` 53 | 54 | 55 | 56 | ## 指令 57 | 58 | ### mp4 59 | 60 | |\-|说明| 61 | |------:|------| 62 | |**语法**|**mp4**;| 63 | |**默认**|——| 64 | |**上下文**|location| 65 | 66 | 启用对 location 模块处理。 67 | 68 | ### mp4_buffer_size 69 | 70 | |\-|说明| 71 | |------:|------| 72 | |**语法**|**mp4_buffer_size** `size`;| 73 | |**默认**|mp4_buffer_size 512K;| 74 | |**上下文**|http、server、location| 75 | 76 | 设置用于处理 MP4 文件的缓冲区的初始大小。 77 | 78 | ### mp4_max_buffer_size 79 | 80 | |\-|说明| 81 | |------:|------| 82 | |**语法**|**mp4_max_buffer_size** `time`;| 83 | |**默认**|mp4_max_buffer_size 10M;| 84 | |**上下文**|http、server、location| 85 | 86 | 在元数据处理期间，可能需要更大的缓冲区。它的大小不能超过指定的大小，否则 nginx 将返回 500（内部服务器错误）错误状态码，并记录以下消息： 87 | 88 | ``` 89 | "/some/movie/file.mp4" mp4 moov atom is too large: 90 | 12583268, you may want to increase mp4_max_buffer_size 91 | ``` 92 | 93 | ### mp4_limit_rate 94 | 95 | |\-|说明| 96 | |------:|------| 97 | |**语法**|**mp4_limit_rate** `on` | `off` | `factor`;| 98 | |**默认**|p4_limit_rate off;| 99 | |**上下文**|http、server、location| 100 | 101 | 限制对客户响应的传输速率。速率限制基于所提供 MP4 文件的平均比特率。要计算速率，比特率将乘以指定的 `factor`。特殊值 `on` 对应于因子 1.1 。特殊值 `off` 禁用速率限制。限制是根据请求设置的，所以如果客户端同时打开两个连接，总体速率将是指定限制的两倍。 102 | 103 | > 该指令可作为我们[商业订阅](http://nginx.com/products/?_ga=2.21542971.1499146730.1522076644-1859001452.1520648382)的一部分。 104 | 105 | ### mp4_limit_rate_after 106 | 107 | |\-|说明| 108 | |------:|------| 109 | |**语法**|**mp4_limit_rate_after** `time`;| 110 | |**默认**|mp4_limit_rate_after 60s;| 111 | |**上下文**|http、server、location| 112 | 113 | 设置媒体数据的初始数量（在回放时计算），之后进一步传输到客户端的响应将受到速率限制。 114 | 115 | > 该指令可作为我们[商业订阅](http://nginx.com/products/?_ga=2.21542971.1499146730.1522076644-1859001452.1520648382)的一部分。 116 | 117 | ## 原文档 118 | [http://nginx.org/en/docs/http/ngx_http_mp4_module.html](http://nginx.org/en/docs/http/ngx_http_mp4_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_geoip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_geoip_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [geoip_country](#geoip_country) 6 | - [geoip_city](#geoip_city) 7 | - [geoip_org](#geoip_org) 8 | - [geoip_proxy](#geoip_proxy) 9 | - [geoip_proxy_recursive](#geoip_proxy_recursive) 10 | 11 | `ngx_http_geoip_module` 模块（0.8.6+）使用预编译的 [MaxMind](http://www.maxmind.com/) 数据库，其创建带值的变量依赖客户端 IP 地址。 12 | 13 | 当使用支持 IPv6 的数据库时（1.3.12、1.2.7），IPv4 地址将被视为 IPv4 映射的 IPv6 地址。 14 | 15 | 此模块不是默认构建的，可以使用 `--with-http_geoip_module` 配置参数启用。 16 | 17 | > 该模块需要 [MaxMind GeoIP](http://www.maxmind.com/app/c) 库。 18 | 19 | 20 | 21 | ## 示例配置 22 | 23 | ```nginx 24 | http { 25 | geoip_country GeoIP.dat; 26 | geoip_city GeoLiteCity.dat; 27 | geoip_proxy 192.168.100.0/24; 28 | geoip_proxy 2001:0db8::/32; 29 | geoip_proxy_recursive on; 30 | ... 31 | ``` 32 | 33 | 34 | 35 | ## 指令 36 | 37 | ### geoip_country 38 | 39 | |\-|说明| 40 | |------:|------| 41 | |**语法**|**geoip_country** `file`;| 42 | |**默认**|——| 43 | |**上下文**|http| 44 | 45 | 指定一个用于根据客户端 IP 地址确定国家的数据库。使用此数据库时，以下变量可用： 46 | 47 | - `$geoip_country_code` 48 | 49 | 双字母国家代码，例如 `RU`、`US` 50 | 51 | - `$geoip_country_code3` 52 | 53 | 三个字母的国家代码，例如 `RUS`、`USA` 54 | 55 | - `$geoip_country_name` 56 | 57 | 国家名称，例如 `Russian Federation`、`United States` 58 | 59 | ### geoip_city 60 | 61 | |\-|说明| 62 | |------:|------| 63 | |**语法**|**geoip_city** `file`;| 64 | |**默认**|——| 65 | |**上下文**|http| 66 | 67 | 指定一个用于根据客户端 IP 地址确定国家、地区和城市的数据库。使用此数据库时，以下变量可用： 68 | 69 | - `$geoip_area_code` 70 | 71 | 电话区号（仅限美国） 72 | 73 | > 由于相应的数据库字段已弃用，因此此变量可能包含过时的信息 74 | 75 | - `$geoip_city_continent_code` 76 | 77 | 双字母的大陆码，例如 `EU`、`NA` 78 | 79 | - `$geoip_city_country_code` 80 | 81 | 双字母国家代码，例如 `RU`、`US` 82 | 83 | - `$geoip_city_country_code3` 84 | 85 | 三个字母的国家代码，例如 `RUS`、`USA` 86 | 87 | - `$geoip_city_country_name` 88 | 89 | 国家名称，例如 `Russian Federation`、`United States` 90 | 91 | - `$geoip_dma_code` 92 | 93 | 美国的 DMA 地区代码（也称为**城市代码**），根据 Google AdWords API 中的[地理位置定位](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) 94 | 95 | - `$geoip_latitude` 96 | 97 | 纬度 98 | 99 | - `$geoip_longitude` 100 | 101 | 经度 102 | 103 | - `$geoip_region` 104 | 105 | 双符号国家地区代码（地区、领土、州、省、联邦土地等），例如 `48`、`DC` 106 | 107 | - `$geoip_region_name` 108 | 109 | 国家地区名称（地区，领土，州，省，联邦土地等），例如 `Moscow City`、`District of Columbia` 110 | 111 | - `$geoip_city` 112 | 113 | 城市名称，例如 `Moscow`、`Washington` 114 | 115 | - `$geoip_postal_code` 116 | 117 | 邮政编码 118 | 119 | ### geoip_org 120 | 121 | |\-|说明| 122 | |------:|------| 123 | |**语法**|**geoip_org** `file`;| 124 | |**默认**|——| 125 | |**上下文**|http| 126 | |**提示**|该指令在 1.0.3 版本中出现| 127 | 128 | 指定用于根据客户端 IP 地址确定组织的数据库。使用此数据库时，以下变量可用： 129 | 130 | - `$geoip_org` 131 | 132 | 组织名称，例如 `The University of Melbourne` 133 | 134 | ### geoip_proxy 135 | 136 | |\-|说明| 137 | |------:|------| 138 | |**语法**|**geoip_proxy** `address` | `CIDR`;| 139 | |**默认**|——| 140 | |**上下文**|http| 141 | |**提示**|该指令在 1.3.0 版本和 1.2.1. 版本中出现| 142 | 143 | 定义可信地址。当请求来自可信地址时，将使用来自 `X-Forwarded-For` 请求头字段的地址。 144 | 145 | ### geoip_proxy_recursive 146 | 147 | |\-|说明| 148 | |------:|------| 149 | |**语法**|**geoip_proxy_recursive** `on` | `off`;| 150 | |**默认**|geoip_proxy_recursive off;| 151 | |**上下文**|http| 152 | |**提示**|该指令在 1.3.0 版本和 1.2.1. 版本中出现| 153 | 154 | 如果递归搜索被禁用，那么将使用在 `X-Forwarded-For` 中发送的最后一个地址，而不是匹配其中一个可信地址的原始客户端地址。如果启用递归搜索，则将使用在 `X-Forwarded-For` 中发送的最后一个不可信地址，而不是匹配其中一个可信地址的原始客户端地址。 155 | 156 | ## 原文档 157 | [http://nginx.org/en/docs/http/ngx_http_geoip_module.html](http://nginx.org/en/docs/http/ngx_http_geoip_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_secure_link_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_secure_link_module 2 | 3 | - [指令](#directives) 4 | - [secure_link](#secure_link) 5 | - [secure_link_md5](#secure_link_md5) 6 | - [secure_link_secret](#secure_link_secret) 7 | - [内嵌变量](#embedded_variables) 8 | 9 | `ngx_http_secure_link_module` 模块（0.7.18）用于检查请求链接的真实性，保护资源免受未经授权的访问，并限制链接有效时长。 10 | 11 | 通过将请求中传递的校验和值与为请求计算的值进行比较，验证所请求链接的真实性。如果链接有效时长有限且时间已过，则链接将被视为过期。这些检查的状态在 `$secure_link` 变量中可用。 12 | 13 | 该模块提供两种替代操作模式。第一种模式由 [secure_link_secret](#secure_link_secret) 指令启用，用于检查请求链接的真实性以及保护资源免受未经授权的访问。第二种模式（0.8.50）由 [secure_link](#secure_link) 和 [secure_link_md5](#secure_link_md5) 指令启用，也用于限制链接的有效期。 14 | 15 | 默认情况下不构建此模块，可使用 `--with-http_secure_link_module` 配置参数启用它。 16 | 17 | 18 | 19 | ## 指令 20 | 21 | ### secure_link 22 | 23 | |\-|说明| 24 | |:------|:------| 25 | |**语法**|**secure_link** `expression`;| 26 | |**默认**|——| 27 | |**上下文**|http、server、location| 28 | 29 | 定义一个包含变量的字符串，从中提取链接的校验和值和有效期。 30 | 31 | 表达式中使用的变量通常与请求相关联。见下面的[例子](#secure_link_md5)。 32 | 33 | 将从字符串中提取的校验和值与 [secure_link_md5](#secure_link_md5) 指令定义的表达式的 MD5 哈希值进行比较。如果校验和不同，则 `$secure_link` 变量设置为空字符串。如果校验和相同，则检查链接有效期。如果链接的有效期有限且时间已过，则 `$secure_link` 变量将设置为 `0`。否则，它被设置为 `1`。请求中传递的 MD5 哈希值使用 [base64url](https://tools.ietf.org/html/rfc4648#section-5) 编码。 34 | 35 | 如果链接的有效时长有限，则自 Epoch（Thu, 01 Jan 1970 00:00:00 GMT）以秒为单位设置到期时间。该值在 MD5 哈希之后的表达式中指定，并以逗号分隔。请求中传递的到期时间可通过 `$secure_link_expires` 变量获得，以便在 [secure_link_md5](#secure_link_md5) 指令中使用。如果未指定到期时间，则链接将有无限有效时长。 36 | 37 | ### secure_link_md5 38 | 39 | |\-|说明| 40 | |:------|:------| 41 | |**语法**|**secure_link_md5** `expression`;| 42 | |**默认**|——| 43 | |**上下文**|http、server、location| 44 | 45 | 定义一个将为其计算 MD5 哈希值并与请求中传递的值进行比较的表达式。 46 | 47 | 表达式应包含链接（资源）的保护部分和秘密部分。如果链接的有效市场为有限，则表达式还应包含 `$secure_link_expires`。 48 | 49 | 为防止未经授权的访问，表达式可能包含有关客户端的一些信息，例如其地址和浏览器版本。 50 | 51 | 例如： 52 | 53 | ```nginx 54 | location /s/ { 55 | secure_link $arg_md5,$arg_expires; 56 | secure_link_md5 "$secure_link_expires$uri$remote_addr secret"; 57 | 58 | if ($secure_link = "") { 59 | return 403; 60 | } 61 | 62 | if ($secure_link = "0") { 63 | return 410; 64 | } 65 | 66 | ... 67 | } 68 | ``` 69 | 70 | `/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647` 链接限制了 IP 地址为 127.0.0.1 的客户端对 `/s/link` 访问。该链接的有效时长有限，直到 2038 年 1 月 19 日（GMT）。 71 | 72 | 在 UNIX 上，`md5` 请求参数值可以获取为： 73 | 74 | ```bash 75 | echo -n '2147483647/s/link127.0.0.1 secret' | \ 76 | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d = 77 | ``` 78 | 79 | ### secure_link_secret 80 | 81 | |\-|说明| 82 | |:------|:------| 83 | |**语法**|**secure_link_secret** `word`;| 84 | |**默认**|——| 85 | |**上下文**|http、server、location| 86 | 87 | 定义一个用于检查所请求链接真实性的暗语（`word`）。 88 | 89 | 请求链接的完整 URI 如下所示： 90 | 91 | ``` 92 | /prefix/hash/link 93 | ``` 94 | 95 | 其中 `hash` 是针对链接和暗语相连计算的 MD5 哈希的十六进制表示，而 `prefix` 是没有斜杠的任意字符串。 96 | 97 | 如果请求的链接通过了真实性检查，则 `$secure_link` 变量将设置为从请求 URI 中提取的链接。否则，`$secure_link` 变量设置为空字符串。 98 | 99 | 例如： 100 | 101 | ```nginx 102 | location /p/ { 103 | secure_link_secret secret; 104 | 105 | if ($secure_link = "") { 106 | return 403; 107 | } 108 | 109 | rewrite ^ /secure/$secure_link; 110 | } 111 | 112 | location /secure/ { 113 | internal; 114 | } 115 | ``` 116 | 117 | `/p/5e814704a28d9bc1914ff19fa0c4a00a/link` 的请求将在内部重定向到 `/secure/link`。 118 | 119 | 在 UNIX 上，此示例的哈希值可以通过以下方式获得： 120 | 121 | ```bash 122 | echo -n 'linksecret' | openssl md5 -hex 123 | ``` 124 | 125 | 126 | 127 | ## 内嵌变量 128 | 129 | - `$secure_link` 130 | 131 | 链接检查的状态。具体值取决于所选的操作模式。 132 | 133 | - `$secure_link_expires` 134 | 135 | 请求中传递的链接的过期时间，仅用于 `secure_link_md5` 指令。 136 | 137 | ## 原文档 138 | 139 | - [http://nginx.org/en/docs/http/ngx_http_secure_link_module.html](http://nginx.org/en/docs/http/ngx_http_secure_link_module.html) 140 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_charset_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_charset_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [charset](#charset) 6 | - [charset_map](#charset_map) 7 | - [charset_types](#charset_types) 8 | - [override_charset](#override_charset) 9 | - [source_charset](#source_charset) 10 | 11 | `ngx_http_charset_module` 模块将指定的字符集添加到 **Content-Type** 响应头域。此外，该模块可以将数据从一个字符集转换为另一个字符集，但也存在一些限制： 12 | 13 | - 转换工作只能是从服务器到客户端 14 | - 只能转换单字节字符集 15 | - 或转为/来自 UTF-8 的单字节字符集。 16 | 17 | 18 | 19 | ## 示例配置 20 | 21 | ```nginx 22 | include conf/koi-win; 23 | 24 | charset windows-1251; 25 | source_charset koi8-r; 26 | ``` 27 | 28 | 29 | 30 | ## 指令 31 | 32 | ### charset 33 | 34 | |\-|说明| 35 | |:------|:------| 36 | |**语法**|**charset** `charset` | `off`;| 37 | |**默认**|charset off;| 38 | |**上下文**|http、server、location、location 中的 if| 39 | 40 | 将指定的字符集添加到 **Content-Type** 响应头域。如果此字符集与 [source_charset](#source_charset) 指令指定的字符集不同，则执行转换。 41 | 42 | 参数 `off` 取消将字符集添加到 **Content-Type** 响应头。 43 | 44 | 可以使用一个变量来定义字符集： 45 | 46 | ```nginx 47 | charset $charset; 48 | ``` 49 | 50 | 在这种情况下，变量的值至少要在 [charset_map](#charset_map)、[charset](#charset) 或 [source_charset](#source_charset) 其中一个指令配置一次。对于 `utf-8`、`windows-1251` 和 `koi8-r` 字符集，将 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 文件包含到配置中就足够了。对于其他字符集，只需制作一个虚构的转换表即可，例如： 51 | 52 | ```nginx 53 | charset_map iso-8859-5 _ { } 54 | ``` 55 | 56 | 另外，可以在 **X-Accel-Charset** 响应头域中设置一个字符集。可以使用[proxy_ignore_headers](ngx_http_proxy_module.md#proxy_ignore_headers)、[fastcgi_ignore_headers](ngx_http_fastcgi_module.md#fastcgi_ignore_headers)、[uwsgi_ignore_headers](ngx_http_uwsgi_module.md#uwsgi_ignore_headers) 和 [scgi_ignore_headers](ngx_http_scgi_module.md#scgi_ignore_headers) 指令禁用此功能。 57 | 58 | ### charset_map 59 | 60 | |\-|说明| 61 | |:------|:------| 62 | |**语法**|**charset_map** `charset1 charset2 { ... }`;| 63 | |**默认**|——| 64 | |**上下文**|http| 65 | 66 | 描述转换表，将一个字符集转换到另一个字符集。反向转换表也使用相同的数据构建。字符代码是十六进制格式。不在 80-FF 范围内的字符将被替换为 `?`。当从 UTF-8 转换时，一个字节字符集中丢失的字符将被替换为 `&#XXXX;`。 67 | 68 | 示例： 69 | 70 | ```nginx 71 | charset_map koi8-r windows-1251 { 72 | C0 FE ; # small yu 73 | C1 E0 ; # small a 74 | C2 E1 ; # small b 75 | C3 F6 ; # small ts 76 | ... 77 | } 78 | ``` 79 | 80 | 在将转换表描述为 UTF-8 时，应在第二列中给出 UTF-8 字符集代码，例如： 81 | 82 | ```nginx 83 | charset_map koi8-r utf-8 { 84 | C0 D18E ; # small yu 85 | C1 D0B0 ; # small a 86 | C2 D0B1 ; # small b 87 | C3 D186 ; # small ts 88 | ... 89 | } 90 | ``` 91 | 92 | 在分发文件 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 中提供了从 `koi8-r` 到 `windows-1251` 以及从 `koi8-r` 和 `windows-1251` 到 `utf-8` 的完整转换表。 93 | 94 | ### charset_types 95 | 96 | |\-|说明| 97 | |:------|:------| 98 | |**语法**|**charset_types** `mime-type ...`;| 99 | |**默认**|charset_types text/html text/xml text/plain text/vnd.wap.wml 100 | application/javascript application/rss+xml;| 101 | |**上下文**|http、server、location| 102 | |**提示**|该指令在 0.7.9 版本中出现| 103 | 104 | 除了 `text/html` 之外，还可以使用指定了 MIME 类型的响应中的模块处理。特殊值 `*` 可匹配任何 MIME 类型（0.8.29）。 105 | 106 | > 直到 1.5.4 版本，`application/x-javascript` 被作为默认的 MIME 类型，而不是`application/javascript`。 107 | 108 | ### override_charset 109 | 110 | |\-|说明| 111 | |:------|:------| 112 | |**语法**|**override_charset** `on` | `off`;| 113 | |**默认**|override_charset off;| 114 | |**上下文**|http、server、location、location 中的 if| 115 | 116 | 当应答已经在 **Content-Type** 响应头域中携带字符集时，确定是否应该对从代理或 FastCGI/uwsgi/SCGI 服务器接收的应答执行转换。如果启用转换，则在接收到的响应中指定的字符集将用作源字符集。 117 | 118 | > 应该注意的是，如果在子请求中接收到响应，则始终执行从响应字符集到主请求字符集的转换，而不管 `override_charset` 指令如何设置。 119 | 120 | ### source_charset 121 | 122 | |\-|说明| 123 | |:------|:------| 124 | |**语法**|**source_charset** `charset`;| 125 | |**默认**|——| 126 | |**上下文**|http、server、location、location 中的 if| 127 | 128 | 定义响应的源字符集。如果此字符集与 [charset](#charset) 指令中指定的字符集不同，则执行转换。 129 | 130 | ## 原文档 131 | [http://nginx.org/en/docs/http/ngx_http_charset_module.html](http://nginx.org/en/docs/http/ngx_http_charset_module.html) 132 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_userid_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_userid_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [userid](#userid) 6 | - [userid_domain](#userid_domain) 7 | - [userid_expires](#userid_expires) 8 | - [userid_mark](#userid_mark) 9 | - [userid_name](#userid_name) 10 | - [userid_p3p](#userid_p3p) 11 | - [userid_path](#userid_path) 12 | - [userid_service](#userid_service) 13 | - [内嵌变量](#embedded_variables) 14 | 15 | `ngx_http_userid_module` 模块设置方便客户端识别的 cookie。可以使用内嵌变量 [$uid_got](#uid_got) 和 [$uid_set](#uid_set) 记录已接收和设置的 cookie。该模块与 Apache 的 [mod_uid](http://www.lexa.ru/programs/mod-uid-eng.html) 模块兼容。 16 | 17 | 18 | 19 | ## 示例配置 20 | 21 | ```nginx 22 | userid on; 23 | userid_name uid; 24 | userid_domain example.com; 25 | userid_path /; 26 | userid_expires 365d; 27 | userid_p3p 'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"'; 28 | ``` 29 | 30 | 31 | 32 | ## 指令 33 | 34 | ### userid 35 | 36 | |\-|说明| 37 | |:------|:------| 38 | |**语法**|**userid** `on` | `v1` | `log` | `off`;| 39 | |**默认**|userid off;| 40 | |**上下文**|http、server、location| 41 | 42 | 启用或禁用设置 cookie 和记录接受到的 cookie： 43 | 44 | - `on` 45 | 46 | 启用版本 2 cookie 设置并记录接收到的 cookie 47 | 48 | - `v1` 49 | 50 | 启用版本 1 cookie 设置并记录接收到的 cookie 51 | 52 | - `log` 53 | 54 | 禁用 cookie 设置，但允许记录接收到的 cookie 55 | 56 | - `off` 57 | 58 | 禁用 cookie 设置和记录接收到的 cookie 59 | 60 | ### userid_domain 61 | 62 | |\-|说明| 63 | |:------|:------| 64 | |**语法**|**userid_domain** `name` | `none`;| 65 | |**默认**|userid_domain none;| 66 | |**上下文**|http、server、location| 67 | 68 | 为设置的 cookie 定义域。`none` 参数禁用 cookie 域设置。 69 | 70 | ### userid_expires 71 | 72 | |\-|说明| 73 | |:------|:------| 74 | |**语法**|**userid_expires** `time` | `max` | `off`;| 75 | |**默认**|userid_expires off;| 76 | |**上下文**|http、server、location| 77 | 78 | 设置浏览器保留 cookie 的时间（`time`）。特殊值 `max` 将 cookie 设置在 `31 Dec 2037 23:55:55 GMT` 时到期。如果未指定参数，cookie 将在浏览器会话结束时到期。 79 | 80 | ### userid_mark 81 | 82 | |\-|说明| 83 | |:------|:------| 84 | |**语法**|**userid_mark** `letter` | `digit` | `=` | `off`;| 85 | |**默认**|userid_mark off;| 86 | |**上下文**|http、server、location| 87 | 88 | 如果参数不是 `off`，则启用 cookie 标记机制并设置用作标记的字符。此机制用于在保留客户端标识符的同时添加或更改 [userid_p3p](ngx_http_userid_module.md#userid_p3p) 和/或 cookie 的过期时间。标记可以是英文字母（区分大小写）、数字或 `=` 字符的任何字符。 89 | 90 | 如果设置了标记，则将其与 cookie 中传递的客户端标识符的 base64 形式中的第一个填充符号进行比较。如果它们不匹配，则会重新发送带有指定标记、到期时间和 **P3P** 头的 cookie。 91 | 92 | ### userid_name 93 | 94 | |\-|说明| 95 | |:------|:------| 96 | |**语法**|**userid_name** `name`;| 97 | |**默认**|userid_name uid;| 98 | |**上下文**|http、server、location| 99 | 100 | 设置 cookie 的名称。 101 | 102 | ### userid_p3p 103 | 104 | |\-|说明| 105 | |:------|:------| 106 | |**语法**|**userid_p3p** `string` | `none`;| 107 | |**默认**|userid_p3p none;| 108 | |**上下文**|http、server、location| 109 | 110 | 设置将与 cookie 一起发送的 **P3P** 头字段的值。如果指令设置为特殊值 `none`，则不会在响应中发送 **P3P** 头。 111 | 112 | ### userid_path 113 | 114 | |\-|说明| 115 | |:------|:------| 116 | |**语法**|**userid_path** `path`;| 117 | |**默认**|userid_path /;| 118 | |**上下文**|http、server、location| 119 | 120 | 为设置的 cookie 定义路径。 121 | 122 | ### userid_service 123 | 124 | |\-|说明| 125 | |:------|:------| 126 | |**语法**|**userid_service** `number`;| 127 | |**默认**|userid_service 服务器的 IP 地址;| 128 | |**上下文**|http、server、location| 129 | 130 | 如果标识符由多个服务器（服务）发出，则应为每个服务分配其自己的编号（`number`），以确保客户端标识符是唯一的。 对于版本 1 cookie，默认值为零。对于版本 2 cookie，默认值是从服务器 IP 地址的最后四个八位字节组成的数字。 131 | 132 | 133 | 134 | ## 内嵌变量 135 | 136 | `ngx_http_userid_module` 模块支持以下内嵌变量： 137 | 138 | 139 | 140 | - `$uid_got` 141 | 142 | cookie 名称和收到的客户端标识符 143 | 144 | - `$uid_reset` 145 | 146 | 如果变量设置为非空字符串且非 `"0"`，则重置客户端标识符。特殊值 `log` 会将关于重置标识符的消息输出到 [error_log](../核心功能.md#error_log)。 147 | 148 | 149 | 150 | - `$uid_set` 151 | 152 | cookie 名称和已发送的客户端标识符 153 | 154 | 155 | ## 原文档 156 | 157 | - [http://nginx.org/en/docs/http/ngx_http_userid_module.html](http://nginx.org/en/docs/http/ngx_http_userid_module.html) 158 | -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_js_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_js_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [js_access](#js_access) 6 | - [js_filter](#js_filter) 7 | - [js_include](#js_include) 8 | - [js_preread](#js_preread) 9 | - [js_set](#js_set) 10 | - [会话对象属性](#properties) 11 | 12 | `ngx_stream_js_module` 模块用于在 [njs](../../介绍/关于nginScript.md) 中实现处理程序 —— 这是 JavaScript 语言的一个子集。 13 | 14 | 默认情况下不构建此模块。可在[此处](http://nginx.org/en/docs/njs/install.html)下载和安装说明。 15 | 16 | 17 | 18 | > 此示例适用于 njs [0.2.4](http://nginx.org/en/docs/njs/changes.html#njs0.2.4) 及更高版本。对于 njs [0.2.3](http://nginx.org/en/docs/njs/changes.html#njs0.2.3) 及更早版本，请使用[此示例](http://nginx.org/en/docs/njs/examples.html#legacy)。 19 | 20 | ## 示例配置 21 | 22 | ```nginx 23 | load_module modules/ngx_stream_js_module.so; 24 | ... 25 | 26 | stream { 27 | js_include stream.js; 28 | 29 | js_set $bar bar; 30 | js_set $req_line req_line; 31 | 32 | server { 33 | listen 12345; 34 | 35 | js_preread preread; 36 | return $req_line; 37 | } 38 | 39 | server { 40 | listen 12346; 41 | 42 | js_access access; 43 | proxy_pass 127.0.0.1:8000; 44 | js_filter header_inject; 45 | } 46 | } 47 | 48 | http { 49 | server { 50 | listen 8000; 51 | location / { 52 | return 200 $http_foo\n; 53 | } 54 | } 55 | } 56 | ``` 57 | 58 | `stream.js` 内容： 59 | 60 | ```js 61 | var line = ''; 62 | 63 | function bar(s) { 64 | var v = s.variables; 65 | s.log("hello from bar() handler!"); 66 | return "bar-var" + v.remote_port + "; pid=" + v.pid; 67 | } 68 | 69 | function preread(s) { 70 | s.on('upload', function (data, flags) { 71 | var n = data.indexOf('\n'); 72 | if (n != -1) { 73 | line = data.substr(0, n); 74 | s.done(); 75 | } 76 | }); 77 | } 78 | 79 | function req_line(s) { 80 | return line; 81 | } 82 | 83 | // Read HTTP request line. 84 | // Collect bytes in 'req' until 85 | // request line is read. 86 | // Injects HTTP header into a client's request 87 | 88 | var my_header = 'Foo: foo'; 89 | function header_inject(s) { 90 | var req = ''; 91 | s.on('upload', function(data, flags) { 92 | req += data; 93 | var n = req.search('\n'); 94 | if (n != -1) { 95 | var rest = req.substr(n + 1); 96 | req = req.substr(0, n + 1); 97 | s.send(req + my_header + '\r\n' + rest, flags); 98 | s.off('upload'); 99 | } 100 | }); 101 | } 102 | 103 | function access(s) { 104 | if (s.remoteAddress.match('^192.*')) { 105 | s.abort(); 106 | return; 107 | } 108 | 109 | s.allow(); 110 | } 111 | ``` 112 | 113 | 114 | 115 | ## 指令 116 | 117 | ### js_access 118 | 119 | |\-|说明| 120 | |------:|------| 121 | |**语法**|**js_access** `function`;| 122 | |**默认**|——| 123 | |**上下文**|stream、server| 124 | 125 | 设置一个将在 [access](../../介绍/Nginx如何处理TCP_UDP会话.md) 阶段调用的 njs 函数。 126 | 127 | ### js_filter 128 | 129 | |\-|说明| 130 | |------:|------| 131 | |**语法**|**js_filter** `function`;| 132 | |**默认**|——| 133 | |**上下文**|stream、server| 134 | 135 | 设置一个数据过滤器。 136 | 137 | ### js_include 138 | 139 | |\-|说明| 140 | |------:|------| 141 | |**语法**|**js_include** `file`;| 142 | |**默认**|——| 143 | |**上下文**|stream| 144 | 145 | 指定一个使用 njs 实现服务器和变量处理程序的文件。 146 | 147 | ### js_preread 148 | 149 | |\-|说明| 150 | |------:|------| 151 | |**语法**|**js_preread** `function`;| 152 | |**默认**|——| 153 | |**上下文**|stream、server| 154 | 155 | 设置一个将在 [preread]((../../介绍/Nginx如何处理TCP_UDP会话.md)) 阶段调用的 njs 函数。 156 | 157 | ### js_set 158 | 159 | |\-|说明| 160 | |------:|------| 161 | |**语法**|**js_set** `function`;| 162 | |**默认**|——| 163 | |**上下文**|stream| 164 | 165 | 设置一个用于指定变量的 njs 函数。 166 | 167 | 168 | 169 | ## 会话对象属性 170 | 171 | 每一个流 njs 处理程序都会接收一个参数，一个流会话[对象](http://nginx.org/en/docs/njs/reference.html#stream)。 172 | 173 | ## 原文档 174 | [http://nginx.org/en/docs/stream/ngx_stream_js_module.html](http://nginx.org/en/docs/stream/ngx_stream_js_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_image_filter_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_image_filter_module 2 | 3 | - [指令](#directives) 4 | - [image_filter](#image_filter) 5 | - [image_filter_buffer](#image_filter_buffer) 6 | - [image_filter_interlace](#image_filter_interlace) 7 | - [image_filter_jpeg_quality](#image_filter_jpeg_quality) 8 | - [image_filter_sharpen](#image_filter_sharpen) 9 | - [image_filter_transparency](#image_filter_transparency) 10 | - [image_filter_webp_quality](#image_filter_webp_quality) 11 | 12 | `ngx_http_image_filter_module` 模块（0.7.54+）是一个可以转换 JPEG、GIF、PNG 和 WebP 格式图像的过滤器。 13 | 14 | 此模块不是默认构建的，可以使用 `--with-http_image_filter_module` 配置参数启用。 15 | 16 | > 该模块使用了 [libgd](http://libgd.org/) 库。建议使用该库的最新版本。 17 | 18 | > WebP 格式支持出现在 1.11.6 版本中。要转换成此格式的图像，必须在编译 `libgd` 库时启用 WebP 支持。 19 | 20 | 21 | 22 | ## 示例配置 23 | 24 | ```nginx 25 | location /img/ { 26 | proxy_pass http://backend; 27 | image_filter resize 150 100; 28 | image_filter rotate 90; 29 | error_page 415 = /empty; 30 | } 31 | 32 | location = /empty { 33 | empty_gif; 34 | } 35 | ``` 36 | 37 | 38 | 39 | ## 指令 40 | 41 | ### image_filter 42 | 43 | |\-|说明| 44 | |------:|------| 45 | |**语法**|**image_filter** `off`;
**image_filter** `test`;
**image_filter** `size`;
**image_filter** `rotate 90 | 180 | 270`;
**image_filter** `resize width height`;
**image_filter** `crop width height`;| 46 | |**默认**|image_filter off;| 47 | |**上下文**|location| 48 | 49 | 设置图片执行的转换类型： 50 | 51 | - `off` 52 | 53 | 关闭对 location 模块的处理 54 | 55 | - `test` 56 | 57 | 确保响应是 JPEG、GIF、PNG 或 WebP 格式的图片。否则，返回 415（不支持的媒体类型）错误。 58 | 59 | - `size` 60 | 61 | 以 JSON 格式输出图片的信息，例如： 62 | 63 | ```json 64 | { "img" : { "width": 100, "height": 100, "type": "gif" } } 65 | ``` 66 | 67 | 发生错误时，输出如下： 68 | 69 | ```json 70 | {} 71 | ``` 72 | 73 | - `rotate 90|180|270` 74 | 75 | 将图片逆时针旋转指定的度数。参数值可以包含变量。此模式可以单独使用，也可以与调整大小和裁剪转换一起使用。 76 | 77 | - `resize width height` 78 | 79 | 按比例将图片缩小到指定的尺寸。要只指定一个维度，可以将另一个维度指定为 `-`。当发生错误，服务器将返回 415 状态码（不支持的媒体类型）。参数值可以包含变量。当与 `rotate` 参数一起使用时，旋转变换将在缩小变换**之后**执行。 80 | 81 | - `crop width height` 82 | 83 | 按比例将图片缩小到较大的一边，并裁剪另一边多余的边缘。要只指定一个维度，可以将另一个维度指定为 `-`。当发生错误，服务器将返回 415 状态码（不支持的媒体类型）。参数值可以包含变量。当与 `rotate` 参数一起使用时，旋转变换将在缩小变换**之前**执行。 84 | 85 | ### image_filter_buffer 86 | 87 | |\-|说明| 88 | |------:|------| 89 | |**语法**|**image_filter_buffer** `size`;| 90 | |**默认**|image_filter_buffer 1M;| 91 | |**上下文**|http、server、location| 92 | 93 | 设置用于读取图片的缓冲区的最大大小。当超过指定大小时，服务器返回 415 错误状态码（不支持的媒体类型）。 94 | 95 | ### image_filter_interlace 96 | 97 | |\-|说明| 98 | |------:|------| 99 | |**语法**|**image_filter_interlace** `on` | `off`;| 100 | |**默认**|image_filter_interlace off;| 101 | |**上下文**|http、server、location| 102 | |**提示**|该指令在 1.3.15 版本中出现| 103 | 104 | 如果启用此选项，图片最后将被逐行扫描。对于 JPEG，图片最终将采用**逐行 JPEG** 格式。 105 | 106 | ### image_filter_jpeg_quality 107 | 108 | |\-|说明| 109 | |------:|------| 110 | |**语法**|**image_filter_jpeg_quality** `quality`;| 111 | |**默认**|image_filter_jpeg_quality 75;| 112 | |**上下文**|http、server、location| 113 | 114 | 设置 JPEG 图片的转换质量。可接受的值范围在 1 到 100 之间。较小的值意味着较低的图片质量和较少的数据传输。最大的推荐值是 95，参数值可以包含变量。 115 | 116 | ### image_filter_sharpen 117 | 118 | |\-|说明| 119 | |------:|------| 120 | |**语法**|**image_filter_sharpen** `percent`;| 121 | |**默认**|image_filter_sharpen 0;| 122 | |**上下文**|http、server、location| 123 | 124 | 增加最终图像的清晰度。锐度百分比可以超过 100。零值将禁用锐化。参数值可以包含变量。 125 | 126 | ### image_filter_transparency 127 | 128 | |\-|说明| 129 | |------:|------| 130 | |**语法**|**image_filter_transparency** `on` | `off`;| 131 | |**默认**|image_filter_transparency on;| 132 | |**上下文**|http、server、location| 133 | 134 | 定义在使用调色板指定的颜色转换 GIF 图像或 PNG 图像时是否保留透明度。透明度的丧失使图像的质量更好的。PNG 中的 alpha 通道透明度始终保留。 135 | 136 | ### image_filter_webp_quality 137 | 138 | |\-|说明| 139 | |------:|------| 140 | |**语法**|**image_filter_webp_quality** `quality`;| 141 | |**默认**|image_filter_webp_quality 80;| 142 | |**上下文**|http、server、location| 143 | |**提示**|该指令在 1.11.6 版本中出现| 144 | 145 | 设置 WebP 图片的转换质量。可接受的值在 1 到 100 之间。较小的值意味着较低的图片质量和较少的数据传输。参数值可以包含变量。 146 | 147 | ## 原文档 148 | [http://nginx.org/en/docs/http/ngx_http_image_filter_module.html](http://nginx.org/en/docs/http/ngx_http_image_filter_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_js_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_js_module 2 | 3 | - [指令](#directives) 4 | - [js_include](#js_include) 5 | - [js_content](#js_content) 6 | - [ js_set](# js_set) 7 | - [请求与响应参数](#arguments) 8 | 9 | `ngx_http_js_module` 模块用于在 [nginScript](../../介绍/关于nginScript.md) 中实现 location 和变量处理器 — 它是 JavaScript 语言的一个子集。 10 | 11 | 此模块不是默构建，可以使用 `--add-module` 配置参数与 nginScript 模块一起编译： 12 | 13 | ```bash 14 | ./configure --add-module=path-to-njs/nginx 15 | ``` 16 | 17 | 可以使用以下命令克隆 nginScript 模块[仓库](http://hg.nginx.org/njs?_ga=2.21584507.1917722686.1520954456-1859001452.1520648382)（需要 [Mercurial](https://www.mercurial-scm.org/) 客户端）： 18 | 19 | ```bash 20 | hg clone http://hg.nginx.org/njs 21 | ``` 22 | 23 | 该模块也可以构建为[动态形式](../核心功能.md#load_module)： 24 | 25 | ``` 26 | ./configure --add-dynamic-module=path-to-njs/nginx 27 | ``` 28 | 29 | 30 | 31 | ## 示例配置 32 | 33 | ```nginx 34 | js_include http.js; 35 | 36 | js_set $foo foo; 37 | js_set $summary summary; 38 | 39 | server { 40 | listen 8000; 41 | 42 | location / { 43 | add_header X-Foo $foo; 44 | js_content baz; 45 | } 46 | 47 | location /summary { 48 | return 200 $summary; 49 | } 50 | } 51 | ``` 52 | 53 | `http.js` 文件： 54 | 55 | ```js 56 | function foo(req, res) { 57 | req.log("hello from foo() handler"); 58 | return "foo"; 59 | } 60 | 61 | function summary(req, res) { 62 | var a, s, h; 63 | 64 | s = "JS summary\n\n"; 65 | 66 | s += "Method: " + req.method + "\n"; 67 | s += "HTTP version: " + req.httpVersion + "\n"; 68 | s += "Host: " + req.headers.host + "\n"; 69 | s += "Remote Address: " + req.remoteAddress + "\n"; 70 | s += "URI: " + req.uri + "\n"; 71 | 72 | s += "Headers:\n"; 73 | for (h in req.headers) { 74 | s += " header '" + h + "' is '" + req.headers[h] + "'\n"; 75 | } 76 | 77 | s += "Args:\n"; 78 | for (a in req.args) { 79 | s += " arg '" + a + "' is '" + req.args[a] + "'\n"; 80 | } 81 | 82 | return s; 83 | } 84 | 85 | function baz(req, res) { 86 | res.headers.foo = 1234; 87 | res.status = 200; 88 | res.contentType = "text/plain; charset=utf-8"; 89 | res.contentLength = 15; 90 | res.sendHeader(); 91 | res.send("nginx"); 92 | res.send("java"); 93 | res.send("script"); 94 | 95 | res.finish(); 96 | } 97 | ``` 98 | 99 | 100 | 101 | ## 指令 102 | 103 | ### js_include 104 | 105 | |\-|说明| 106 | |------:|------| 107 | |**语法**|**js_include** `file`;| 108 | |**默认**|——| 109 | |**上下文**|http| 110 | 111 | 指定一个在 nginScript 中实现 location 和变量处理器的文件。 112 | 113 | ### hls_buffers 114 | 115 | |\-|说明| 116 | |------:|------| 117 | |**语法**|**js_content** `function`;| 118 | |**默认**|——| 119 | |**上下文**|location、limit_except| 120 | 121 | 将 nginScript 函数设置为 location 内容处理器。 122 | 123 | ### js_set 124 | 125 | |\-|说明| 126 | |------:|------| 127 | |**语法**|**js_set** `$variable function`;| 128 | |**默认**|——| 129 | |**上下文**|http| 130 | |**提示**|该指令在 1.5.12 版本中出现| 131 | 132 | 为指定变量设置 nginScript 函数。 133 | 134 | 135 | 136 | ## 请求与响应参数 137 | 138 | 每个 HTTP nginScript 处理器接收两个参数，请求和响应。 139 | 140 | 请求对象具有以下属性： 141 | 142 | - `uri` 143 | 144 | 请求的当前 URI，只读 145 | 146 | - `method` 147 | 148 | 请求方法，只读 149 | 150 | - `httpVersion` 151 | 152 | HTTP 版本，只读 153 | 154 | - `remoteAddress` 155 | 156 | 客户端地址，只读 157 | 158 | - `headers{}` 159 | 160 | 请求头对象，只读 161 | 162 | 例如，可以使用语法 `headers['Header-Name']` 或 `headers.Header_name` 来访问 `Header-Name` 头 163 | 164 | - `args{}` 165 | 166 | 请求参数对象，只读 167 | 168 | - `variables{}` 169 | 170 | nginx 变量对象，只读 171 | 172 | - `log(string)` 173 | 174 | 将 `string` 写入错误日志 175 | 176 | 响应对象具有以下属性： 177 | 178 | - `status` 179 | 180 | 响应状态，可写 181 | 182 | - `headers{}` 183 | 184 | 响应头对象 185 | 186 | - `contentType` 187 | 188 | 响应的 `Content-Type` 头字段值，可写 189 | 190 | - `contentLength` 191 | 192 | 响应的 `Content-Length` 头字段值，可写 193 | 194 | 响应对象具有以下方法： 195 | 196 | - `sendHeader()` 197 | 198 | 将 HTTP 头发送到客户端 199 | 200 | - `send(string)` 201 | 202 | 将部分响应体的发送给客户端 203 | 204 | - `finish()` 205 | 206 | 完成向客户端发送响应 207 | 208 | ## 原文档 209 | 210 | [http://nginx.org/en/docs/http/ngx_http_js_module.html](http://nginx.org/en/docs/http/ngx_http_js_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_gzip_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_gzip_module 2 | 3 | - [指令](#directives) 4 | - [gzip](#gzip) 5 | - [gzip_buffers](#gzip_buffers) 6 | - [gzip_comp_level](#gzip_comp_level) 7 | - [gzip_disable](#gzip_disable) 8 | - [gzip_min_length](#gzip_min_length) 9 | - [gzip_http_version](#gzip_http_version) 10 | - [gzip_proxied](#gzip_proxied) 11 | - [gzip_types](#gzip_types) 12 | - [gzip_vary](#gzip_vary) 13 | - [内嵌变量](#embedded_variables) 14 | 15 | `ngx_http_gzip_module` 模块是一个使用了 **gzip** 方法压缩响应的过滤器。有助于将传输数据的大小减少一半甚至更多。 16 | 17 | 18 | 19 | ## 示例配置 20 | 21 | ```nginx 22 | gzip on; 23 | gzip_min_length 1000; 24 | gzip_proxied expired no-cache no-store private auth; 25 | gzip_types text/plain application/xml; 26 | ``` 27 | 28 | `$gzip_ratio` 变量可用于记录实现的压缩比率。 29 | 30 | 31 | 32 | ## 指令 33 | 34 | ### gzip 35 | 36 | |\-|说明| 37 | |------:|------| 38 | |**语法**|**gzip** `on` | `off`;| 39 | |**默认**|gzip off;| 40 | |**上下文**|http、server、location、location 中的 if| 41 | 42 | 启用或禁用响应的 gzip 压缩。 43 | 44 | ### gzip_buffers 45 | 46 | |\-|说明| 47 | |------:|------| 48 | |**语法**|**gzip_buffers** `number size`;| 49 | |**默认**|gzip_buffers 32 4k|16 8k;| 50 | |**上下文**|http、server、location| 51 | 52 | 设置用于压缩响应的缓冲区的数量（`number`）和大小（`size`）。默认情况下，缓冲区大小等于一个内存页（4K 或 8K，取决于平台）。 53 | 54 | > 在 0.7.28 版本之前，默认使用 4 个 4K 或 8K 缓冲区。 55 | 56 | ### gzip_comp_level 57 | 58 | |\-|说明| 59 | |------:|------| 60 | |**语法**|**gzip_comp_level** `level`;| 61 | |**默认**|gzip_comp_level 1;| 62 | |**上下文**|http、server、location| 63 | 64 | 设置响应的 gzip 压缩级别（`level`）。值的范围为 1 到 9。 65 | 66 | ### gzip_disable 67 | 68 | |\-|说明| 69 | |------:|------| 70 | |**语法**|**gzip_disable** `regex ...`;| 71 | |**默认**|——| 72 | |**上下文**|http、server、location| 73 | |**提示**|该指令在 0.6.23 版本中出现| 74 | 75 | 禁用对与任何指定正则表达式匹配的 `User-Agent` 头字段的请求响应做 gzip 处理。 76 | 77 | 特殊掩码 `msie6`（0.7.12）对应正则表达式 `MSIE [4-6]\.`，但效率更高。从 0.8.11 版本开始，`MSIE 6.0; ... SV1` 不包含在此掩码中。 78 | 79 | ### gzip_min_length 80 | 81 | |\-|说明| 82 | |------:|------| 83 | |**语法**|**gzip_min_length** `length`;| 84 | |**默认**|gzip_min_length 20;| 85 | |**上下文**|http、server、location| 86 | 87 | 设置被压缩响应的最小长度。该长度仅由 `Content-Length` 响应头字段确定。 88 | 89 | ### gzip_http_version 90 | 91 | |\-|说明| 92 | |------:|------| 93 | |**语法**|**gzip_http_version** `1.0` | `1.1`;| 94 | |**默认**|gzip_http_version 1.1;| 95 | |**上下文**|http、server、location| 96 | 97 | 设置压缩响应一个请求所需的最小 HTTP 版本。 98 | 99 | ### gzip_proxied 100 | 101 | |\-|说明| 102 | |------:|------| 103 | |**语法**|**gzip_proxied** `off` | `expired` | `no-cache` | `no-store` | `private` | `no_last_modified` | `no_etag` | `auth` | `any ...`;| 104 | |**默认**|gzip_proxied off;| 105 | |**上下文**|http、server、location| 106 | 107 | 根据请求和响应，启用或禁用针对代理请求的响应的 gzip。事实上请求被代理取决于 `Via` 请求头字段是否存在。该指令接受多个参数： 108 | 109 | - `off` 110 | 111 | 禁用所有代理请求压缩，忽略其他参数 112 | 113 | - `expired` 114 | 115 | 如果响应头包含 `Expires”` 字段并且其值为禁用缓存，则启用压缩 116 | 117 | - `no-cache` 118 | 119 | 如果响应头包含具有 `no-cache` 参数的 `Cache-Control` 字段，则启用压缩 120 | 121 | - `no-store` 122 | 123 | 如果响应头包含具有 `no-store` 参数的 `Cache-Control` 字段，则启用压缩 124 | 125 | - `private` 126 | 127 | 如果响应头包含带有 `private` 参数的 `Cache-Control` 字段，则启用压缩 128 | 129 | - `no_last_modified` 130 | 131 | 如果响应头不包含 `Last-Modified` 字段，则启用压缩 132 | 133 | - `no_etag` 134 | 135 | 如果响应头不包含 `ETag` 字段，则启用压缩 136 | 137 | - `auth` 138 | 139 | 如果请求头包含 `Authorization` 字段，则启用压缩 140 | 141 | - `any` 142 | 143 | 为所有代理请求启用压缩 144 | 145 | ### gzip_types 146 | 147 | |\-|说明| 148 | |------:|------| 149 | |**语法**|**gzip_types** `mime-type ...`;| 150 | |**默认**|gzip_types text/html;| 151 | |**上下文**|http、server、location| 152 | 153 | 除了 `text/html` 之外，还可以针对指定的 MIME 类型启用 gzip 响应。特殊值 `*` 匹配任何 MIME 类型（0.8.29）。对 `text/html` 类型的响应始终启用压缩。 154 | 155 | ### gzip_vary 156 | 157 | |\-|说明| 158 | |------:|------| 159 | |**语法**|**gzip_vary** `on` | `off`;| 160 | |**默认**|gzip_vary off;| 161 | |**上下文**|http、server、location| 162 | 163 | 如果指令 [gzip](ngx_http_gzip_module.md#gzip)、[gzip_static](ngx_http_gzip_static_module.md#gzip_static) 或 [gunzip](ngx_http_gunzip_module.md#gunzip) 处于激活状态，则启用或禁用插入 `Vary:Accept-Encoding` 响应头字段。 164 | 165 | 166 | 167 | ## 内嵌变量 168 | 169 | - `$gzip_ratio` 170 | 171 | 实现压缩比率，计算为原始压缩响应大小与压缩后响应大小之间的比率。 172 | 173 | ## 原文档 174 | [http://nginx.org/en/docs/http/ngx_http_gzip_module.html](http://nginx.org/en/docs/http/ngx_http_gzip_module.html) -------------------------------------------------------------------------------- /介绍/QUIC和HTTP3支持.md: -------------------------------------------------------------------------------- 1 | # QUIC 和 HTTP/3 支持 2 | 3 | - [从源码构建](#从源码构建) 4 | - [配置](#配置) 5 | - [配置示例](#配置示例) 6 | - [故障排除](#故障排除) 7 | 8 | 从1.25.0后，对 [QUIC](https://datatracker.ietf.org/doc/html/rfc9000) 和 [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114) 协议的支持可用。同时，1.25.0之后，QUIC 和 HTTP/3 支持在Linux二进制包 ([binary package](https://nginx.org/en/linux_packages.html))中可用。 9 | 10 | > QUIC 和 HTTP/3 支持是实验性的，请谨慎使用。 11 | 12 | ## 从源码构建 13 | 14 | 使用`configure`命令配置构建。请参考[从源码构建 nginx ](../How-To/从源码构建nginx.md)以获得更多细节。 15 | 16 | 当配置nginx时，可以使用 [`--with-http_v3_module`](../How-To/从源码构建nginx.md#http_v3_module) 配置参数来启用 QUIC 和 HTTP/3。 17 | 18 | 构建nginx时建议使用支持 QUIC 的 SSL 库，例如 [BoringSSL](https://boringssl.googlesource.com/boringssl)，[LibreSSL](https://www.libressl.org/)，或者 [QuicTLS](https://github.com/quictls/openssl)。否则，将使用不支持[早期数据](../模块参考/http/ngx_http_ssl_module.md#ssl_early_data)的[OpenSSL](https://openssl.org/)兼容层。 19 | 20 | 使用以下命令为 nginx 配置 [BoringSSL](https://boringssl.googlesource.com/boringssl)： 21 | 22 | ```bash 23 | ./configure 24 | --with-debug 25 | --with-http_v3_module 26 | --with-cc-opt="-I../boringssl/include" 27 | --with-ld-opt="-L../boringssl/build/ssl 28 | -L../boringssl/build/crypto" 29 | ``` 30 | 31 | 或者，可以使用 [QuicTLS](https://github.com/quictls/openssl) 配置 nginx： 32 | 33 | ```bash 34 | ./configure 35 | --with-debug 36 | --with-http_v3_module 37 | --with-cc-opt="-I../quictls/build/include" 38 | --with-ld-opt="-L../quictls/build/lib" 39 | ``` 40 | 41 | 或者，可以使用现代版本的 [LibreSSL](https://www.libressl.org/) 配置 nginx： 42 | 43 | ```bash 44 | ./configure 45 | --with-debug 46 | --with-http_v3_module 47 | --with-cc-opt="-I../libressl/build/include" 48 | --with-ld-opt="-L../libressl/build/lib" 49 | ``` 50 | 51 | 配置完成后，使用 `make` 编译和安装 nginx。 52 | 53 | ## 配置 54 | 55 | [ngx_http_core_module](../模块参考/http/ngx_http_core_module.md) 模块中的 `listen` 指令获得了一个新参数 [`quic`](../模块参考/http/ngx_http_core_module.md#quic)，它在指定端口上通过启用 HTTP/3 over QUIC。 56 | 57 | 除了 `quic` 参数外，还可以指定 [`reuseport`](../模块参考/http/ngx_http_core_module.md#reuseport) 参数，使其在多个工作线程中正常工作。 58 | 59 | 有关指令列表，请参阅 [ngx_http_v3_module](https://nginx.org/en/docs/http/ngx_http_v3_module.html)。 60 | 61 | 要[启用](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_retry)地址验证： 62 | 63 | ```nginx 64 | quic_retry on; 65 | ``` 66 | 67 | 要[启用](../模块参考/http/ngx_http_ssl_module.md#ssl_early_data) 0-RTT： 68 | 69 | ```nginx 70 | ssl_early_data on; 71 | ``` 72 | 73 | 要[启用](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_gso) GSO (Generic Segmentation Offloading)： 74 | 75 | ```nginx 76 | quic_gso on; 77 | ``` 78 | 79 | 为多个 token [设置](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_host_key) host key： 80 | 81 | ```nginx 82 | quic_host_key ; 83 | ``` 84 | 85 | QUIC 需要 TLSv1.3 协议版本，该版本在 [`ssl_protocols`](../模块参考/http/ngx_http_ssl_module.md#ssl_protocols) 指令中默认启用。 86 | 87 | 默认情况下，[GSO Linux 特定优化](http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf)处于禁用状态。如果相应的网络接口配置为支持 GSO，请启用它。 88 | 89 | ## 配置示例 90 | 91 | ```nginx 92 | http { 93 | log_format quic '$remote_addr - $remote_user [$time_local] ' 94 | '"$request" $status $body_bytes_sent ' 95 | '"$http_referer" "$http_user_agent" "$http3"'; 96 | 97 | access_log logs/access.log quic; 98 | 99 | server { 100 | # for better compatibility it's recommended 101 | # to use the same port for quic and https 102 | listen 8443 quic reuseport; 103 | listen 8443 ssl; 104 | 105 | ssl_certificate certs/example.com.crt; 106 | ssl_certificate_key certs/example.com.key; 107 | 108 | location / { 109 | # required for browsers to direct them to quic port 110 | add_header Alt-Svc 'h3=":8443"; ma=86400'; 111 | } 112 | } 113 | } 114 | ``` 115 | 116 | ## 故障排除 117 | 118 | 一些可能有助于识别问题的提示： 119 | 120 | - 确保 nginx 是使用正确的 SSL 库构建的。 121 | - 确保 nginx 在运行时使用正确的 SSL 库（`nginx -V` 显示当前使用的内容）。 122 | - 确保客户端实际通过 QUIC 发送请求。建议从简单的控制台客户端（如 [ngtcp2](https://nghttp2.org/ngtcp2)）开始，以确保服务器配置正确，然后再尝试使用可能对证书非常挑剔的真实浏览器。 123 | - 使用[调试支持](../介绍/调试日志.md)构建nginx并检查调试日志。它应包含有关连接及其失败原因的所有详细信息。所有相关消息都包含“`quic`”前缀，可以轻松过滤掉。 124 | - 为了进行更深入的调查，可以使用以下宏启用其他调试：`NGX_QUIC_DEBUG_PACKETS, NGX_QUIC_DEBUG_FRAMES, NGX_QUIC_DEBUG_ALLOC, NGX_QUIC_DEBUG_CRYPTO`。 125 | ```bash 126 | ./configure 127 | --with-http_v3_module 128 | --with-debug 129 | --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" 130 | ``` -------------------------------------------------------------------------------- /模块参考/stream/ngx_stream_upstream_hc_module.md: -------------------------------------------------------------------------------- 1 | # ngx_stream_upstream_hc_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [health_check](#health_check) 6 | - [health_check_timeout](#health_check_timeout) 7 | - [match](#match) 8 | 9 | `ngx_stream_upstream_hc_module` 模块（1.9.0）允许对[组](ngx_stream_upstream_module.md#upstream)中服务器启用定期健康检查。服务器组必须驻留在[共享内存](ngx_stream_upstream_module.md#zone)中。 10 | 11 | 如果健康检查失败，则服务器将被视为不可用。如果为同一组服务器定义了多个健康检查，则任何一次检查失败都会使相应的服务器不可用。客户端连接不会传递给不可用的服务器，并且服务器不会处于「检查」状态。 12 | 13 | > 此模块为[商业订阅](http://nginx.com/products/?_ga=2.131045135.1858436578.1589555275-1645619674.1589555275)部分。 14 | 15 | 16 | 17 | ## 示例配置 18 | 19 | ```nginx 20 | upstream tcp { 21 | zone upstream_tcp 64k; 22 | 23 | server backend1.example.com:12345 weight=5; 24 | server backend2.example.com:12345 fail_timeout=5s slow_start=30s; 25 | server 192.0.2.1:12345 max_fails=3; 26 | 27 | server backup1.example.com:12345 backup; 28 | server backup2.example.com:12345 backup; 29 | } 30 | 31 | server { 32 | listen 12346; 33 | proxy_pass tcp; 34 | health_check; 35 | } 36 | ``` 37 | 38 | 使用此配置，nginx 将每 5 秒钟检查是否能与 tcp 组中的每个服务器建立 TCP 连接。如果无法与服务器建立连接，则健康检查将失败，并且服务器将被视为不可用。 39 | 40 | 可以为 UDP 协议配置健康检查： 41 | 42 | ```nginx 43 | upstream dns_upstream { 44 | 45 | zone dns_zone 64k; 46 | 47 | server dns1.example.com:53; 48 | server dns2.example.com:53; 49 | server dns3.example.com:53; 50 | } 51 | 52 | server { 53 | listen 53 udp; 54 | proxy_pass dns_upstream; 55 | health_check udp; 56 | } 57 | ``` 58 | 59 | 在这种情况下，nginx 将发送 `nginx health check` 字符串，期望得到的响应中没有 ICMP `Destination Unreachable` 消息。 60 | 61 | 健康检查也可以配置为[测试](#match)从服务器获得的数据。使用 `match` 指令单独配置测试规则，并在 [health_check](#health_check) 指令的 `match` 参数中引用测试规则。 62 | 63 | 64 | 65 | ## 指令 66 | 67 | ### health_check 68 | 69 | |\-|说明| 70 | |------:|------| 71 | |**语法**|**health_check** `[parameters]`;| 72 | |**默认**|——| 73 | |**上下文**|server| 74 | 75 | 对[组](ngx_stream_upstream_module.md#upstream)中服务器启用定期健康检查。 76 | 77 | 支持以下可选参数： 78 | 79 | - `interval=time` 80 | 81 | 设置两次连续运行健康检查之间的间隔时间，默认为 5 秒。 82 | 83 | - `jitter=time` 84 | 85 | 设置每次运行健康检查将随机延迟的时间，默认没有延迟。 86 | 87 | - `fails=number` 88 | 89 | 设置指定服务器在连续运行健康检查失败次数达到 `number` 后，将被视为不可用，默认为 1。 90 | 91 | - `passes=number` 92 | 93 | 设置指定服务器在连续通过健康检查次数达到 `number` 后，将被视为健康，默认为 1。 94 | 95 | - `mandatory` 96 | 97 | 设置服务器的初始「检查中」（checking）状态，直到完成第一次健康检查运行（1.11.7）。客户端连接不会以「检查中」的状态传递到服务器。如果未指定该参数，则服务器初始状态将被视为健康。 98 | 99 | - `match=name` 100 | 101 | 指定 `match` 块，该匹配块配置健康检查中正常的连接必须要通过的测试。默认情况下，对于 TCP，仅检查与服务器建立 TCP 的连接。对于 [UDP](#health_check_udp)，nginx 发送 `nginx health check` 字符串，期望得到的响应不应存在 ICMP `Destination Unreachable` 消息。 102 | 103 | > 在 1.11.7 版本之前，默认情况下，UDP 运行健康检查需要带有 [send](#match_send) 和 [expect](#match_expect) 参数的 [match](#hc_match) 块。 104 | 105 | - `port=number` 106 | 107 | 定义连接到服务器执行健康检查（1.9.7）时使用的端口，默认等于[服务器](ngx_stream_upstream_module.md#server)端口。 108 | 109 | - `udp` 110 | 111 | 指定将 UDP 协议代替默认的 TCP 协议（1.9.13）用于健康检查。 112 | 113 | ### health_check_timeout 114 | 115 | |\-|说明| 116 | |------:|------| 117 | |**语法**|**health_check_timeout** `name { ... }`;| 118 | |**默认**|——| 119 | |**上下文**|stream| 120 | 121 | 覆盖用于健康检查的 [proxy_timeout](ngx_stream_proxy_module.md#proxy_timeout) 值。 122 | 123 | ### match 124 | 125 | |\-|说明| 126 | |------:|------| 127 | |**语法**|**match** `name { ... }`;| 128 | |**默认**|——| 129 | |**上下文**|stream| 130 | 131 | 定义用于验证对服务器运行健康检查返回的响应的具名测试集。 132 | 133 | 可以配置以下参数： 134 | 135 | - `send string;` 136 | 137 | 向服务器发送一个 `string`（字符串） 138 | 139 | - `expect string | ~ regex;` 140 | 141 | 从服务器获得的数据应匹配的文字字符串（1.9.12）或正则表达式。正则表达式以前 `~*` 修饰符（不区分大小写）或 `~` 修饰符（不区分大小写）指定。 142 | 143 | `send` 和 `expect` 参数都可以包含带有 `\x` 前缀的十六进制文字，后跟两个十六进制数字，例如 `\x80`（1.9.12）。 144 | 145 | 如果满足以下条件，则通过健康检查： 146 | 147 | - TCP 连接建立成功 148 | - 发送了来自 `send` 参数的 `string`（如果已指定） 149 | - 将从服务器获取的数据与来自 `expect` 参数的字符串或正则表达式匹配（如果已指定） 150 | - 经过的时间不超过 [health_check_timeout](#health_check_timeout) 指令中指定的值 151 | 152 | 示例： 153 | 154 | ```nginx 155 | upstream backend { 156 | zone upstream_backend 10m; 157 | server 127.0.0.1:12345; 158 | } 159 | 160 | match http { 161 | send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; 162 | expect ~ "200 OK"; 163 | } 164 | 165 | server { 166 | listen 12346; 167 | proxy_pass backend; 168 | health_check match=http; 169 | } 170 | ``` 171 | 172 | > 仅检查从服务器获得的数据的首个 [proxy_buffer_size](ngx_stream_proxy_module.md#proxy_buffer_size) 字节。 173 | 174 | ## 原文档 175 | 176 | [http://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html](http://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html) -------------------------------------------------------------------------------- /模块参考/mail/ngx_mail_auth_http_module.md: -------------------------------------------------------------------------------- 1 | # ngx_mail_auth_http_module 2 | 3 | - [指令](#directives) 4 | - [auth_http](#auth_http) 5 | - [auth_http_header](#auth_http_header) 6 | - [auth_http_pass_client_cert](#auth_http_pass_client_cert) 7 | - [auth_http_timeout](#auth_http_timeout) 8 | - [协议](#protocol) 9 | 10 | 11 | 12 | ## 指令 13 | 14 | ### auth_http 15 | 16 | |\-|说明| 17 | |:------|:------| 18 | |**语法**|**auth_http** `URL`;| 19 | |**默认**|——| 20 | |**上下文**|mail、server| 21 | 22 | 设置 HTTP 认证服务器的 URL。协议描述[如下](#protocol)。 23 | 24 | ### auth_http_header 25 | 26 | |\-|说明| 27 | |:------|:------| 28 | |**语法**|**auth_http_header** `header value`;| 29 | |**默认**|——| 30 | |**上下文**|mail、server| 31 | 32 | 将指定的头附加到发送到身份验证服务器的请求。该头可以用作共享密钥，以验证请求来自 nginx。例如： 33 | 34 | ```nginx 35 | auth_http_header X-Auth-Key "secret_string"; 36 | ``` 37 | 38 | ### auth_http_pass_client_cert 39 | 40 | |\-|说明| 41 | |:------|:------| 42 | |**语法**|**auth_http_pass_client_cert** `on` | `off`;| 43 | |**默认**|auth_http_pass_client_cert off;| 44 | |**上下文**|mail、server| 45 | |**提示**|该指令在 1.7.11 版本中出现| 46 | 47 | 将 **Auth-SSL-Cert** 头和 PEM 格式（已编码）的[客户端](./ngx_mail_ssl_module.md#ssl_verify_client)证书附加到发送到身份验证服务器的请求。 48 | 49 | ### auth_http_timeout 50 | 51 | |\-|说明| 52 | |:------|:------| 53 | |**语法**|**auth_http_timeout** `time`| 54 | |**默认**|auth_http_timeout 60s;| 55 | |**上下文**|mail、server| 56 | 57 | 设置与认证服务器通信的超时时间。 58 | 59 | 60 | 61 | ## 协议 62 | 63 | HTTP 协议用于与身份验证服务器进行通信。响应正文中的数据将被忽略，信息仅在头中传递。 64 | 65 | 请求和响应的示例： 66 | 67 | 请求： 68 | 69 | ``` 70 | GET /auth HTTP/1.0 71 | Host: localhost 72 | Auth-Method: plain # plain/apop/cram-md5/external 73 | Auth-User: user 74 | Auth-Pass: password 75 | Auth-Protocol: imap # imap/pop3/smtp 76 | Auth-Login-Attempt: 1 77 | Client-IP: 192.0.2.42 78 | Client-Host: client.example.org 79 | ``` 80 | 81 | 好的响应： 82 | 83 | ``` 84 | HTTP/1.0 200 OK 85 | Auth-Status: OK 86 | Auth-Server: 198.51.100.1 87 | Auth-Port: 143 88 | ``` 89 | 90 | 坏的响应： 91 | 92 | ``` 93 | HTTP/1.0 200 OK 94 | Auth-Status: Invalid login or password 95 | Auth-Wait: 3 96 | ``` 97 | 98 | 如果没有 **Auth-Wait** 头，则将返回错误并关闭连接。当前实现为每次身份验证尝试分配内存。仅在会话结束时才释放内存。因此，必须限制单个会话中无效身份验证尝试的次数 — 服务器必须在 10-20 次尝试后响应不带 **Auth-Wait** 头（尝试次数在 **Auth-Login-Attempt** 头中传递）。 99 | 100 | 使用 APOP 或 CRAM-MD5 时，请求-响应如下所示： 101 | 102 | ``` 103 | GET /auth HTTP/1.0 104 | Host: localhost 105 | Auth-Method: apop 106 | Auth-User: user 107 | Auth-Salt: <238188073.1163692009@mail.example.com> 108 | Auth-Pass: auth_response 109 | Auth-Protocol: imap 110 | Auth-Login-Attempt: 1 111 | Client-IP: 192.0.2.42 112 | Client-Host: client.example.org 113 | ``` 114 | 115 | 好的响应： 116 | 117 | ``` 118 | HTTP/1.0 200 OK 119 | Auth-Status: OK 120 | Auth-Server: 198.51.100.1 121 | Auth-Port: 143 122 | Auth-Pass: plain-text-pass 123 | ``` 124 | 125 | 如果响应中存在 **Auth-User** 头，它将覆盖用于与后端进行身份验证的用户名。 126 | 127 | 对于 SMTP，响应还考虑了 **Auth-Error-Code** 头 — 如果存在，则在发生错误时用作响应代码。否则，将 535 5.7.0 代码添加到 **Auth-Status** 头中。 128 | 129 | 例如，如果从身份验证服务器收到以下响应： 130 | 131 | ``` 132 | HTTP/1.0 200 OK 133 | Auth-Status: Temporary server problem, try again later 134 | Auth-Error-Code: 451 4.3.0 135 | Auth-Wait: 3 136 | ``` 137 | 138 | 则 SMTP 客户端将收到错误 139 | 140 | ``` 141 | 451 4.3.0 Temporary server problem, try again later 142 | ``` 143 | 144 | 如果代理 SMTP 不需要身份验证，则请求将如下所示： 145 | 146 | ``` 147 | GET /auth HTTP/1.0 148 | Host: localhost 149 | Auth-Method: none 150 | Auth-User: 151 | Auth-Pass: 152 | Auth-Protocol: smtp 153 | Auth-Login-Attempt: 1 154 | Client-IP: 192.0.2.42 155 | Client-Host: client.example.org 156 | Auth-SMTP-Helo: client.example.org 157 | Auth-SMTP-From: MAIL FROM: <> 158 | Auth-SMTP-To: RCPT TO: 159 | ``` 160 | 161 | 对于 SSL/TLS 客户端连接（1.7.11），添加了 **Auth-SSL** 头，并且 **Auth-SSL-Verify** 将包含客户端证书验证的结果（如果[启用](ngx_mail_ssl_module.md#ssl_verify_client)）：`SUCCESS`、`FAILED:reason` 和 `NONE`（如果不存在证书）。 162 | 163 | > 在 1.11.7 版本之前，`FAILED` 结果不包含原因字符串。 164 | 165 | 存在客户端证书时，其详细信息将在以下请求头中传递：**Auth-SSL-Subject**、**Auth-SSL-Issuer**、**Auth-SSL-Serial** 和 **Auth-SSL-Fingerprint**。如果启用了 [auth_http_pass_client_cert](#auth_http_pass_client_cert)，则证书本身将在 **Auth-SSL-Cert** 头中传递。该请求将如下所示： 166 | 167 | ``` 168 | GET /auth HTTP/1.0 169 | Host: localhost 170 | Auth-Method: plain 171 | Auth-User: user 172 | Auth-Pass: password 173 | Auth-Protocol: imap 174 | Auth-Login-Attempt: 1 175 | Client-IP: 192.0.2.42 176 | Auth-SSL: on 177 | Auth-SSL-Verify: SUCCESS 178 | Auth-SSL-Subject: /CN=example.com 179 | Auth-SSL-Issuer: /CN=example.com 180 | Auth-SSL-Serial: C07AD56B846B5BFF 181 | Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad 182 | ``` 183 | 184 | ## 原文档 185 | 186 | - [http://nginx.org/en/docs/mail/ngx_mail_auth_http_module.html](http://nginx.org/en/docs/mail/ngx_mail_auth_http_module.html) 187 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_hls_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_headers_module 2 | 3 | - [指令](#directives) 4 | - [hls](#hls) 5 | - [hls_buffers](#hls_buffers) 6 | - [hls_forward_args](#hls_forward_args) 7 | - [hls_fragment](#hls_fragment) 8 | - [hls_mp4_buffer_size](#hls_mp4_buffer_size) 9 | - [hls_mp4_max_buffer_size](#hls_mp4_max_buffer_size) 10 | 11 | `ngx_http_hls_module` 模块为 MP4 和 MOV 媒体文件提供 HTTP Live Streaming（HLS）服务器端支持。这些文件通常具有 `.mp4`、`.m4v`、`.m4a`、`.mov` 或 `.qt` 扩展名。该模块支持 H.264 视频编解码器、AAC 和 MP3 音频编解码器。 12 | 13 | 对于每个媒体文件，支持两种 URI： 14 | 15 | - 带有 `.m3u8` 文件扩展名的播放列表 URI。该 URI 可以接受可选参数： 16 | - `start` 和 `end` 以秒为单位定义播放列表范围（1.9.0）。 17 | - `offset` 将初始播放位置移动到以秒为单位的时间偏移（1.9.0）。正值设置播放列表开头的时间偏移量。负值设置播放列表中最后一个片段末尾的时间偏移量。 18 | - `len` 以秒为单位定义片段长度。 19 | - 带有 `.ts` 文件扩展名的片段 URI。该 URI 可以接受可选参数： 20 | - `start` 和 `end` 以秒为单位定义片段范围。 21 | 22 | > 该模块可作为我们[商业订阅](http://nginx.com/products/?_ga=2.248085959.1917722686.1520954456-1859001452.1520648382)的一部分。 23 | 24 | 25 | 26 | ## 示例配置 27 | 28 | ```nginx 29 | location / { 30 | hls; 31 | hls_fragment 5s; 32 | hls_buffers 10 10m; 33 | hls_mp4_buffer_size 1m; 34 | hls_mp4_max_buffer_size 5m; 35 | root /var/video/; 36 | } 37 | ``` 38 | 39 | 在此配置中，`/var/video/test.mp4` 文件支持以下 URI： 40 | 41 | ```nginx 42 | http://hls.example.com/test.mp4.m3u8?offset=1.000&start=1.000&end=2.200 43 | http://hls.example.com/test.mp4.m3u8?len=8.000 44 | http://hls.example.com/test.mp4.ts?start=1.000&end=2.200 45 | ``` 46 | 47 | 48 | 49 | ## 指令 50 | 51 | ### hls 52 | 53 | |\-|说明| 54 | |------:|------| 55 | |**语法**|**hls**;| 56 | |**默认**|——| 57 | |**上下文**|location| 58 | 59 | 为当前 location 打开 HLS 流。 60 | 61 | ### hls_buffers 62 | 63 | |\-|说明| 64 | |------:|------| 65 | |**语法**|**hls_buffers** `number size`;| 66 | |**默认**|hls_buffers 8 2m;| 67 | |**上下文**|http、server、location| 68 | 69 | 设置用于读取和写入数据帧的缓冲区的最大数量（`number`）和大小（`size`）。 70 | 71 | ### hls_forward_args 72 | 73 | |\-|说明| 74 | |------:|------| 75 | |**语法**|**hls_forward_args** `on` | `off`;| 76 | |**默认**|hls_forward_args off;| 77 | |**上下文**|http、server、location| 78 | |**提示**|该指令在 1.5.12 版本中出现| 79 | 80 | 将播放列表请求中的参数添加到片段的 URI 中。这对于在请求片段时或在使用 [ngx_http_secure_link_module](ngx_http_secure_link_module.md) 模块保护 HLS 流时执行客户端授权非常有用。 81 | 82 | 例如，如果客户端请求播放列表 `http://example.com/hls/test.mp4.m3u8?a=1&b=2`，参数 `a=1` 和 `b=2` 将在参数 `start` 和 `end` 后面添加到片段 URI 中： 83 | 84 | ``` 85 | #EXTM3U 86 | #EXT-X-VERSION:3 87 | #EXT-X-TARGETDURATION:15 88 | #EXT-X-PLAYLIST-TYPE:VOD 89 | 90 | #EXTINF:9.333, 91 | test.mp4.ts?start=0.000&end=9.333&a=1&b=2 92 | #EXTINF:7.167, 93 | test.mp4.ts?start=9.333&end=16.500&a=1&b=2 94 | #EXTINF:5.416, 95 | test.mp4.ts?start=16.500&end=21.916&a=1&b=2 96 | #EXTINF:5.500, 97 | test.mp4.ts?start=21.916&end=27.416&a=1&b=2 98 | #EXTINF:15.167, 99 | test.mp4.ts?start=27.416&end=42.583&a=1&b=2 100 | #EXTINF:9.626, 101 | test.mp4.ts?start=42.583&end=52.209&a=1&b=2 102 | 103 | #EXT-X-ENDLIST 104 | ``` 105 | 106 | 如果 HLS 流受到 [ngx_http_secure_link_module](ngx_http_secure_link_module.md) 模块的保护，则不应在 [secure_link_md5](ngx_http_secure_link_module.md#secure_link_md5) 表达式中使用 `$uri`，因为这会在请求片段时触发错误。应该使用 [Base URI](ngx_http_map_module.md#map) 而不是 `$uri`（在示例中为 `$hls_uri`）： 107 | 108 | ```nginx 109 | http { 110 | ... 111 | 112 | map $uri $hls_uri { 113 | ~^(?.*).m3u8$ $base_uri; 114 | ~^(?.*).ts$ $base_uri; 115 | default $uri; 116 | } 117 | 118 | server { 119 | ... 120 | 121 | location /hls { 122 | hls; 123 | hls_forward_args on; 124 | 125 | alias /var/videos; 126 | 127 | secure_link $arg_md5,$arg_expires; 128 | secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret"; 129 | 130 | if ($secure_link = "") { 131 | return 403; 132 | } 133 | 134 | if ($secure_link = "0") { 135 | return 410; 136 | } 137 | } 138 | } 139 | } 140 | ``` 141 | 142 | ### hls_fragment 143 | 144 | |\-|说明| 145 | |------:|------| 146 | |**语法**|**hls_fragment** `time`;| 147 | |**默认**|hls_fragment 5s;| 148 | |**上下文**|http、server、location| 149 | 150 | 定义未使用 `len` 参数请求的播放列表 URI 的默认片段长度。 151 | 152 | ### hls_mp4_buffer_size 153 | 154 | |\-|说明| 155 | |------:|------| 156 | |**语法**|**hls_mp4_buffer_size** `size`;| 157 | |**默认**|hls_mp4_buffer_size 512k;| 158 | |**上下文**|http、server、location| 159 | 160 | 设置用于处理 MP4 和 MOV 文件的缓冲区的初始大小（`size`）。 161 | 162 | ### hls_mp4_max_buffer_size 163 | 164 | |\-|说明| 165 | |------:|------| 166 | |**语法**|**hls_mp4_max_buffer_size** `size`;| 167 | |**默认**|hls_mp4_max_buffer_size 10m;| 168 | |**上下文**|http、server、location| 169 | 170 | 在元数据处理期间，可能需要更大的缓冲区。其大小不能超过指定的大小（`size`），否则 nginx 将返回 500 状态码（内部服务器错误），并记录以下消息： 171 | 172 | ``` 173 | "/some/movie/file.mp4" mp4 moov atom is too large: 174 | 12583268, you may want to increase hls_mp4_max_buffer_size 175 | ``` 176 | 177 | ## 原文档 178 | 179 | [http://nginx.org/en/docs/http/ngx_http_hls_module.html](http://nginx.org/en/docs/http/ngx_http_hls_module.html) -------------------------------------------------------------------------------- /介绍/使用Nginx作为HTTP负载均衡器.md: -------------------------------------------------------------------------------- 1 | # 使用 nginx 作为 HTTP 负载均衡器 2 | ## 介绍 3 | 负载均衡跨越多个应用程序实例，是一种常用的技术，其用于优化资源利用率、最大化吞吐量、减少延迟和确保容错配置。 4 | 5 | 可以使用 nginx 作为高效的 HTTP 负载均衡器，将流量分布到多个应用服务器，并通过 nginx 提高 web 应用程序的性能、可扩展性和可靠性。 6 | 7 | ## 负载均衡方法 8 | nginx 支持以下负载均衡机制（或方法）： 9 | 10 | - **轮询（round-robin）** - 发送给应用服务器的请求以轮询的方式分发 11 | - **最少连接（least-connected）** - 下一个请求被分配给具有最少数量活动连接的服务器 12 | - **ip 哈希（ip-hash）** - 使用哈希函数确定下一个请求应该选择哪一个服务器（基于客户端的 IP 地址） 13 | 14 | ## 默认负载均衡配置 15 | 使用 nginx 进行负载均衡的最简单配置如下所示： 16 | 17 | ```nginx 18 | http { 19 | upstream myapp1 { 20 | server srv1.example.com; 21 | server srv2.example.com; 22 | server srv3.example.com; 23 | } 24 | 25 | server { 26 | listen 80; 27 | 28 | location / { 29 | proxy_pass http://myapp1; 30 | } 31 | } 32 | } 33 | ``` 34 | 在上述示例中，在 srv1-srv3 上运行相同的应用的三个实例。当负载均衡方法没有被特别配置时，默认采用轮询（round-robin）。所有请求都被 [代理](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) 到服务器组 myapp1，nginx 应用 HTTP 负载均衡来分发请求。 35 | 36 | nginx 中的反向代理实现包括 HTTP、HTTPS、FastCGI、uwsgi、SCGI 和 memcached。 37 | 38 | 要配置 HTTPS 而不是 HTTP 负载均衡，只需要使用 HTTPS 协议。 39 | 40 | 在为 FastCGI、uwsgi、SCGI 或 memcached 设置负载均衡时，分别使用 [fastcgi_pass](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_pass)、[uwsgi_pass](http://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_pass)、[scgi_pass](http://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_pass) 和 [memcached_pass](http://nginx.org/en/docs/http/ngx_http_memcached_module.html#memcached_pass) 指令。 41 | 42 | ## 最少连接负载均衡 43 | 另一个负载均衡的规则是最少连接。在一些请求需要更长的时间才能完成的情况下，最少连接可以更公正地控制应用程序实例的负载。 44 | 45 | 使用最少连接的负载均衡，nginx 将尽量不给过于繁忙的应用服务器负载过多的请求，而是将新的请求分发到不太忙的服务器。 46 | 47 | 当使用 [least_conn](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#least_conn) 指令作为服务组配置的一部分时，将激活 nginx 中的最少连接负载均衡： 48 | 49 | ```nginx 50 | upstream myapp1 { 51 | least_conn; 52 | server srv1.example.com; 53 | server srv2.example.com; 54 | server srv3.example.com; 55 | } 56 | ``` 57 | 58 | ## 会话持久化 59 | 请注意，使用轮询或者最少连接的负载均衡，每个后续客户端的请求都可能被分配到不同的服务器。不能保证同一个客户端始终指向同一个服务器。 60 | 61 | 如果需要将客户端绑定到特定的应用服务器，换而言之，使客户端会话「粘滞」或者「永久」，始终尝试选择特定的服务器，IP 哈希负载均衡机制可以做到这点。 62 | 63 | 使用 IP 哈希，客户端的 IP 地址用作为哈希键，以确定应用为客户端请求选择服务器组中的哪个服务器。此方法确保了来自同一个客户端的请求始终被定向到同一台服务器，除非该服务器不可用。 64 | 65 | 要配置 IP 哈希负载均衡，只需要将 [ip_hash](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#ip_hash) 指令添加到服务器 upstream 组配置中即可： 66 | 67 | ```nginx 68 | upstream myapp1 { 69 | ip_hash; 70 | server srv1.example.com; 71 | server srv2.example.com; 72 | server srv3.example.com; 73 | } 74 | ``` 75 | 76 | ## 加权负载均衡 77 | 还可以通过使用服务器权重进一步加强 nginx 的负载均衡算法。 78 | 79 | 在上面的示例中，服务器权重没有被配置，这意味对于特定的负载均衡方法来说所有指定的服务器都具有同等资格。 80 | 81 | 特别是使用轮询方式，这也意味着服务器上的请求分配或多或少都是相等的 —— 只要有足够的请求，并且以统一的方式足够快速地完成请求处理。 82 | 83 | 当服务器指定 [weight](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 参数时，权重将作为负载均衡决策的一部分进行核算。 84 | 85 | ```nginx 86 | upstream myapp1 { 87 | server srv1.example.com weight=3; 88 | server srv2.example.com; 89 | server srv3.example.com; 90 | } 91 | ``` 92 | 通过这样配置，每 5 个新的请求将分布在应用程序实例之中，如下所示：三个请求被定向到 srv1，一个请求将转到 srv2，另一个请求将转到 srv3。 93 | 94 | 在 nginx 的最近版本中，可以在最少连接和 IP 哈希负载均衡中使用权重。 95 | 96 | ## 健康检查 97 | nginx 中的反向代理实现包括了带内（或者被动）服务器健康检查。如果特定服务器的响应失败并出现错误，则 nginx 会将此服务器标记为失败，并尝试避免为此后续请求选择此服务器而浪费一段时间。 98 | 99 | [max_fails](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 用于设置在 [fail_timeout](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 期间与服务器通信失败重新尝试的次数。默认情况下，[max_fails](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 设置为 1。当设置为 0 时，该服务器的健康检查将被禁用。[fail_timeout](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 参数还定义了服务器被标记为失败的时间。在服务器发生故障后的 [fail_timeout](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 间隔后，nginx 开始以实时客户端的请求优雅地探测服务器。如果探测成功，则将服务器标记为活动。 100 | 101 | ## 进一步阅读 102 | 此外，还有更多的指令和参数可以控制 nginx 中的服务器负载均衡，例如，[proxy_next_upstream](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream)、[backup](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server)、[down](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server) 和 [keepalive](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive)。有关更多的信息，请查看我们的参考文档。 103 | 104 | 最后但同样重要，[应用程序负载均衡](https://www.nginx.com/products/application-load-balancing/?_ga=2.104451654.798520331.1503766923-1890203964.1497190280)、[应用程序健康检查](https://www.nginx.com/products/application-health-checks/?_ga=2.104451654.798520331.1503766923-1890203964.1497190280)、[活动监控](https://www.nginx.com/products/live-activity-monitoring/?_ga=2.104451654.798520331.1503766923-1890203964.1497190280) 和服务组 [动态重新配置](https://www.nginx.com/products/on-the-fly-reconfiguration/?_ga=2.96194266.798520331.1503766923-1890203964.1497190280) 作为我们 NGINX Plus 付费订阅的一部分。 105 | 106 | 以下文章详细介绍了 NGINX Plus 负载均衡： 107 | - [NGINX 负载均衡与 NGINX Plus](https://www.nginx.com/blog/load-balancing-with-nginx-plus/?_ga=2.96194266.798520331.1503766923-1890203964.1497190280) 108 | - [NGINX 负载均衡与 Nginx Plus 第2部分](https://www.nginx.com/blog/load-balancing-with-nginx-plus-part2/?_ga=2.96194266.798520331.1503766923-1890203964.1497190280) 109 | 110 | ## 原文档 111 | 112 | - [http://nginx.org/en/docs/http/load_balancing.html](http://nginx.org/en/docs/http/load_balancing.html) 113 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_upstream_hc_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_upstream_hc_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [health_check](#health_check) 6 | - [match](#match) 7 | 8 | `ngx_http_upstream_hc_module` 模块允许对周边 location 中引用的[组](ngx_http_upstream_module.md#upstream)中的服务器进行定期健康检查。服务器组必须驻留在[共享内存](ngx_http_upstream_module.md#zone)中。 9 | 10 | 如果健康检查失败，则服务器将被视为运行状况不佳。如果为同一组服务器定义了多个健康检查，则任何检查的单个故障都将使相应的服务器被视为运行状况不佳。客户端请求不会传递到处于 **checking** 状态的服务器和不健康的服务器。 11 | 12 | > 请注意，与健康检查一起使用时，大多数变量都将为空值。 13 | 14 | > 该模块作为[商业订阅](http://nginx.com/products/?_ga=2.72493466.860729840.1564753618-1186072494.1564163363)部分提供。 15 | 16 | 17 | 18 | ## 示例配置 19 | 20 | ```nginx 21 | upstream dynamic { 22 | zone upstream_dynamic 64k; 23 | 24 | server backend1.example.com weight=5; 25 | server backend2.example.com:8080 fail_timeout=5s slow_start=30s; 26 | server 192.0.2.1 max_fails=3; 27 | 28 | server backup1.example.com:8080 backup; 29 | server backup2.example.com:8080 backup; 30 | } 31 | 32 | server { 33 | location / { 34 | proxy_pass http://dynamic; 35 | health_check; 36 | } 37 | } 38 | ``` 39 | 40 | 使用此配置，nginx 将每隔五秒向 `backend` 组中的每个服务器发送 `/` 请求。如果发生任何通信错误或超时，或代理服务器以 2xx 或 3xx 以外的状态码响应，则健康检查将失败，并且服务器将被视为运行状况不佳。 41 | 42 | 可以配置健康检查以测试响应的状态码、某些头字段及其值的存在以及报文体。测试使用 [match](#match) 指令单独配置，并在 [health_check](#health_check) 指令的 `match` 参数中引用： 43 | 44 | ```nginx 45 | http { 46 | server { 47 | ... 48 | location / { 49 | proxy_pass http://backend; 50 | health_check match=welcome; 51 | } 52 | } 53 | 54 | match welcome { 55 | status 200; 56 | header Content-Type = text/html; 57 | body ~ "Welcome to nginx!"; 58 | } 59 | } 60 | ``` 61 | 62 | 此配置显示，发起传递一个健康检查，健康检查请求的响应应该为成功，状态码为 200，并在正文中包含 `Welcome to nginx!`。 63 | 64 | 65 | 66 | ## 指令 67 | 68 | ### health_check 69 | 70 | |\-|说明| 71 | |:------|:------| 72 | |**语法**|**health_check** `[parameters]`;| 73 | |**默认**|——| 74 | |**上下文**|location| 75 | 76 | 启用对周边 location 中引用的[组](ngx_http_upstream_module.md#upstream)中的服务器定期健康检查。 77 | 78 | 支持以下可选参数： 79 | 80 | - `interval=time` 81 | 82 | 设置两次连续健康检查之间的间隔时间，默认为 5 秒 83 | 84 | - `jitter=time` 85 | 86 | 设置每个健康检查随机延迟的时间，默认情况下，没有延迟 87 | 88 | - `fails=number` 89 | 90 | 设置特定服务器的连续失败健康检查的数量，在此之后，此服务器将被视为不健康，默认情况下为 1。 91 | 92 | - `passes=number` 93 | 94 | 设置特定服务器的连续通过健康检查的数量，在此之后服务器将被视为健康，默认情况下为 1。 95 | 96 | - `uri=uri` 97 | 98 | 定义健康检查请求中使用的 URI，默认情况下为 `/`。 99 | 100 | - `mandatory` 101 | 102 | 设置服务器的初始 **checking** 状态，直到第一次运行健康检查完成（1.11.7）。客户端请求不会传递到处于 **checking** 状态的服务器。如果未指定参数，则服务器开始将被视为健康。 103 | 104 | - `match=name` 105 | 106 | 指定 `match` 块配置测试，为响应通过测试做参照，以便通过健康检查。默认情况下，响应的状态码应为 2xx 或 3xx。 107 | 108 | - `port=number` 109 | 110 | 定义连接到服务器以执行健康检查时使用的端口（1.9.7）。默认情况下，等于 [server](ngx_http_upstream_module.md#server) 端口。 111 | 112 | ### match 113 | 114 | |\-|说明| 115 | |:------|:------| 116 | |**语法**|**match** `name { ... }`;| 117 | |**默认**|——| 118 | |**上下文**|http| 119 | 120 | 定义用于验证健康检查请求的响应的具名测试集。 121 | 122 | 可以在响应中测试以下项目： 123 | 124 | - `status 200;` 125 | 126 | 状态码为 200 127 | 128 | - `status ! 500;` 129 | 130 | 状态码非 500 131 | 132 | - `status 200 204;` 133 | 134 | 状态码为 200 或 204 135 | 136 | - `status ! 301 302;` 137 | 138 | 状态码既不是 301 也不是 302 139 | 140 | - `status 200-399;` 141 | 142 | 状态码在 200 到 399 之间 143 | 144 | - `status ! 400-599;` 145 | 146 | 状态码不在 400 到 599 之间 147 | 148 | - `status 301-303 307;` 149 | 150 | 状态码为 301、302、303 或 307 151 | 152 | - `header Content-Type = text/html;` 153 | 154 | header 包含值为 `text/html` 的 **Content-Type** 155 | 156 | - `header Content-Type != text/html;` 157 | 158 | header 包含 **Content-Type**，其值不是 `text/html` 159 | 160 | - `header Connection ~ close;` 161 | 162 | header 包含 **Connection** ，其值与正则表达式 `close` 匹配 163 | 164 | - `header Connection !~ close;` 165 | 166 | header 包含 **Connection**，其值与正则表达式 `close` 不匹配 167 | 168 | - `header Host;` 169 | 170 | header 包含 **Host** 171 | 172 | - `header ! X-Accel-Redirect;` 173 | 174 | header 没有 **X-Accel-Redirect** 175 | 176 | - `body ~ "Welcome to nginx!";` 177 | 178 | 正文内容匹配正则表达式 `Welcome to nginx!` 179 | 180 | - `body !~ "Welcome to nginx!";` 181 | 182 | 正文内容不符合正则表达式 `Welcome to nginx!` 183 | 184 | - `require $variable ...;` 185 | 186 | 所有指定的变量都不为空且不等于 `"0"`（1.15.9）。 187 | 188 | 如果指定了多个测试，则响应仅在匹配所有测试时才匹配。 189 | 190 | > 仅检查响应体的前 256k 数据。 191 | 192 | 示例： 193 | 194 | ```nginx 195 | # status is 200, content type is "text/html", 196 | # and body contains "Welcome to nginx!" 197 | match welcome { 198 | status 200; 199 | header Content-Type = text/html; 200 | body ~ "Welcome to nginx!"; 201 | } 202 | # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:" 203 | match not_redirect { 204 | status ! 301-303 307; 205 | header ! Refresh; 206 | } 207 | # status ok and not in maintenance mode 208 | match server_ok { 209 | status 200-399; 210 | body !~ "maintenance mode"; 211 | } 212 | # status is 200 or 204 213 | map $upstream_status $good_status { 214 | 200 1; 215 | 204 1; 216 | } 217 | 218 | match server_ok { 219 | require $good_status; 220 | } 221 | ``` 222 | 223 | ## 原文档 224 | 225 | - [http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html](http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html) 226 | -------------------------------------------------------------------------------- /其他/linux包.md: -------------------------------------------------------------------------------- 1 | ## nginx：Linux 软件包 2 | 3 | 目前，nginx 软件支持以下 Linux 发行版： 4 | 5 | RHEL/CentOS： 6 | 7 | | 版本 | 支持平台 | 8 | |:------|:------| 9 | | 6.x | x86_64，i386 | 10 | | 7.x | x86_64，ppc64le | 11 | 12 | Debian： 13 | 14 | | 版本 | 代号 | 支持平台 | 15 | |:------|:------|:------| 16 | | 7.x | wheezy | x86_64，i386 | 17 | | 8.x | jessie | x86_64，i386 | 18 | | 9.x | stretch | x86_64，i386 | 19 | 20 | Ubuntu： 21 | 22 | | 版本 | 代号 | 支持平台 | 23 | |:------|:------|:------| 24 | | 12.04 | precise | x86_64，i386 | 25 | | 14.04 | trusty | x86_64，i386, aarch64/arm64 | 26 | | 16.04 | xenial | x86_64，i386, ppc64el，aarch64/arm64 | 27 | | 16.10 | yakkety | x86_64，i386 | 28 | 29 | SLES： 30 | 31 | | 版本 | 支持平台 | 32 | |:------|:------| 33 | | 12 | x86_64 | 34 | 35 | 要启用 Linux 软件包的自动更新，可设置 RHEL/CentOS 发行版的 yum 仓库（repository），Debian/Ubuntu 发行版的 apt 仓库或 SLES 的 zypper 仓库。 36 | 37 | ## 稳定版本的预构建软件包 38 | 39 | 要设置 RHEL/CentOS 的 yum 仓库，请创建名为 `/etc/yum.repos.d/nginx.repo` 的文件，其中包含以下内容： 40 | 41 | ```ini 42 | [nginx] 43 | name=nginx repo 44 | baseurl=http://nginx.org/packages/OS/OSRELEASE/$basearch/ 45 | gpgcheck=0 46 | enabled=1 47 | ``` 48 | 49 | 根据所使用的发行版，使用 `rhel` 或 `centos` 替换掉 `OS`，对于 6.x 或 7.x 版本，将 `OSRELEASE` 替换为 `6` 或 `7`。 50 | 51 | 对于 Debian/Ubuntu，为了验证 nginx 仓库签名，并且在安装 nginx 软件包时消除关于缺少 PGP 密钥的警告，需要将用于将 nginx 软件包和仓库签署的密钥添加到 `apt` 程序密钥环中。请从我们的网站下载此[密钥](http://nginx.org/keys/nginx_signing.key)，并使用以下命令将其添加到 `apt` 程序密钥环： 52 | 53 | ```bash 54 | sudo apt-key add nginx_signing.key 55 | ``` 56 | 57 | 对于 Debian，使用 Debian 发行版代号替换掉 `codename`，并将以下内容追加到 `/etc/apt/sources.list` 文件末尾： 58 | 59 | ```bash 60 | deb http://nginx.org/packages/debian/ codename nginx 61 | deb-src http://nginx.org/packages/debian/ codename nginx 62 | ``` 63 | 64 | 对于 Ubuntu，使用 Ubuntu 发行版代号替换掉 `codename`，并将以下内容追加到 `/etc/apt/sources.list` 文件末尾： 65 | 66 | ```bash 67 | deb http://nginx.org/packages/ubuntu/ codename nginx 68 | deb-src http://nginx.org/packages/ubuntu/ codename nginx 69 | ``` 70 | 71 | 对于 Debian/Ubuntu，请运行以下命令： 72 | 73 | ```bash 74 | apt-get update 75 | apt-get install nginx 76 | ``` 77 | 78 | 对于 SLES，运行以下命令： 79 | 80 | ```bash 81 | zypper addrepo -G -t yum -c 'http://nginx.org/packages/sles/12' nginx 82 | ``` 83 | 84 | ## 主线版本的预构建软件包 85 | 86 | 要设置 RHEL/CentOS 的 yum 仓库，请创建名为 `/etc/yum.repos.d/nginx.repo` 的文件，其中包含以下内容： 87 | 88 | ```ini 89 | [nginx] 90 | name=nginx repo 91 | baseurl=http://nginx.org/packages/mainline/OS/OSRELEASE/$basearch/ 92 | gpgcheck=0 93 | enabled=1 94 | ``` 95 | 96 | 根据所使用的发行版，使用 `rhel` 或 `centos` 替换掉 `OS`，对于 6.x 或 7.x 版本，将 `OSRELEASE` 替换为 `6` 或 `7`。 97 | 98 | 对于 Debian/Ubuntu，为了验证 nginx 仓库签名，并且在安装 nginx 软件包时消除关于缺少 PGP 密钥的警告，必须将用于将 nginx 软件包和仓库签署的密钥添加到 `apt` 程序密钥环中。请从我们的网站下载此 [密钥](http://nginx.org/keys/nginx_signing.key)，并使用以下命令将其添加到 `apt` 程序密钥环： 99 | 100 | ```bash 101 | sudo apt-key add nginx_signing.key 102 | ``` 103 | 104 | 对于 Debian，使用 Debian 发行版代号替换 `codename`，并将以下内容追加到 `/etc/apt/sources.list` 文件末尾： 105 | 106 | ```bash 107 | deb http://nginx.org/packages/mainline/debian/ codename nginx 108 | deb-src http://nginx.org/packages/mainline/debian/ codename nginx 109 | ``` 110 | 111 | 对于 Ubuntu，使用 Ubuntu 发行版代号替换 `codename`，并将以下内容追加到 `/etc/apt/sources.list` 文件末尾： 112 | 113 | ```bash 114 | deb http://nginx.org/packages/mainline/ubuntu/ codename nginx 115 | deb-src http://nginx.org/packages/mainline/ubuntu/ codename nginx 116 | ``` 117 | 118 | 对于 Debian/Ubuntu，请运行以下命令： 119 | 120 | ```bash 121 | apt-get update 122 | apt-get install nginx 123 | ``` 124 | 125 | 对于 SLES，请运行以下命令： 126 | 127 | ```bash 128 | zypper addrepo -G -t yum -c 'http://nginx.org/packages/mainline/sles/12' nginx 129 | ``` 130 | 131 | ## 源码包 132 | 源码包可以在 [源码包库](http://hg.nginx.org/pkg-oss?_ga=2.100560158.1468443122.1505551652-1890203964.1497190280) 中找到。 133 | 134 | `default` 分支保存当前主线版本的源码包，而 `stable-*` 分支包含了稳定版本的最新源码。要构建二进制包，请在 Debian/Ubuntu 上的 `debian/` 目录或在 RHEL/CentOS/SLES 上的 `rpm/SPECS/` 中运行 `make`。 135 | 136 | 源码包在 [类 BSD 的两项条款许可证](http://nginx.org/LICENSE) 下发行，与 nginx 相同。 137 | 138 | ## 动态模块 139 | 主 nginx 包使用了所有模块进行构建，没有使用到附加库，以避免额外的依赖。自 1.9.11 版本开始，nginx 支持 [动态模块](http://nginx.org/en/docs/ngx_core_module.html#load_module)，并将以下模块构建为动态模块，以独立软件包的形式发布： 140 | 141 | ``` 142 | nginx-module-geoip 143 | nginx-module-image-filter 144 | nginx-module-njs 145 | nginx-module-perl 146 | nginx-module-xslt 147 | ``` 148 | 149 | ## 签名 150 | RPM 软件包和 Debian/Ubuntu 仓库都使用数字签名来验证下载包的完整性和来源。为了检查签名，需要下载 [nginx 签名密钥](http://nginx.org/keys/nginx_signing.key) 并将其导入 rpm 或 apt 程序密钥环： 151 | 152 | 在 Debian/Ubuntu 上： 153 | 154 | ```bash 155 | sudo apt-key add nginx_signing.key 156 | ``` 157 | 158 | 在 RHEL/CentOS 上； 159 | 160 | ```bash 161 | sudo rpm --import nginx_signing.key 162 | ``` 163 | 164 | 在 SLES 上： 165 | 166 | ```bash 167 | sudo rpm --import nginx_signing.key 168 | ``` 169 | 170 | Debian/Ubuntu/SLES 签名默认情况被检查，但是在 RHEL/CentOS 上，需要在 `/etc/yum.repos.d/nginx.repo` 文件中进行设置： 171 | 172 | ``` 173 | gpgcheck= 1 174 | ``` 175 | 176 | 由于我们的 [PGP 密钥](http://nginx.org/en/pgp_keys.html) 和软件包都位于同一台服务器上，因此它们都是可信的。强烈建议另行验证下载的 PGP 密钥的真实性。PGP 具有“Web of Trust”（信任网络）的概念，当一个密钥是由别人的密钥签署的，而另一个密钥则由另一个密钥签名。它通常可以建立一个从任意密钥到您知道和信任的某人的密钥，从而验证链中第一个密钥的真实性。这个概念在 [GPG Mini Howto](http://www.dewinter.com/gnupg_howto/english/GPGMiniHowto-1.html) 中有详细描述。我们的钥匙有足够的签名，其真实性比较容易检查。 177 | 178 | ## 原文档 179 | 180 | [http://nginx.org/en/linux_packages.html#distributions](http://nginx.org/en/linux_packages.html#distributions) 181 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_log_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_log_module 2 | 3 | - [指令](#directives) 4 | - [access_log](#access_log) 5 | - [log_format](#log_format) 6 | - [open_log_file_cache](#open_log_file_cache) 7 | 8 | `ngx_http_log_module` 模块可让请求日志以指定的格式写入。 9 | 10 | 请求会在处理结束的 location 的上下文中记录。如果在请求处理期间发生[内部重定向](ngx_http_core_module.md#internal)，可能会造成与原始 location 不同。 11 | 12 | 13 | 14 | ## 示例配置 15 | 16 | ```nginx 17 | log_format compression '$remote_addr - $remote_user [$time_local] ' 18 | '"$request" $status $bytes_sent ' 19 | '"$http_referer" "$http_user_agent" "$gzip_ratio"'; 20 | 21 | access_log /spool/logs/nginx-access.log compression buffer=32k; 22 | ``` 23 | 24 | 25 | 26 | ## 指令 27 | 28 | ### access_log 29 | 30 | |\-|说明| 31 | |------:|------| 32 | |**语法**|**access_log** `path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]`;
**access_log** `off`;| 33 | |**默认**|access_log logs/access.log combined;| 34 | |**上下文**|http、server、location、location 中的 if、limit_except| 35 | 36 | 设置缓冲日志写入的路径、格式和配置。可以在同一级别指定多个日志。可以通过在第一个参数中指定 `syslog:` 前缀配置将日志记录到 [syslog](../../介绍/记录日志到syslog.md)。特殊值 `off` 取消当前级别的所有 `access_log` 指令。如果未指定格式，则使用预定义的 `combined` 格式。 37 | 38 | 如果使用缓冲区或 `gzip` 参数（1.3.10、1.2.7），则日志写入将被缓冲。 39 | 40 | > 缓冲区大小不得超过原子写入磁盘文件的大小。对于 FreeBSD，该大小是无限的。 41 | 42 | 启用缓冲时，以下情况数据将被写入文件中： 43 | 44 | - 如果下一个日志行不适合放入缓冲区 45 | - 如果缓冲数据比 `flush参数`指定的更旧（1.3.10,1.2.7） 46 | - 当 worker 进程[重新打开](../../介绍/控制nginx.md)日志文件或正在关闭时 47 | 48 | 如果使用 `gzip` 参数，那么在写入文件之前，缓冲的数据将被压缩。压缩级别可以设置在 1（最快、较少压缩）和 9（最慢、最佳压缩）之间。默认情况下，缓冲区大小等于 64K 字节，压缩级别设置为 1。由于数据是以原子块的形式压缩的，因此日志文件可以随时解压缩或由 `zcat` 读取。 49 | 50 | 示例： 51 | 52 | ```nginx 53 | access_log /path/to/log.gz combined gzip flush=5m; 54 | ``` 55 | 56 | > 要使 gzip 压缩起作用，必须在构建 nginx 时使用 zlib 库。 57 | 58 | 文件路径可以包含变量（0.7.6+），但存在一些限制： 59 | 60 | - 被 woker 进程使用凭据的[用户](ngx_core_module.md#user)应有在此类日志在目录中创建文件的权限 61 | - 缓冲写入不起作用 62 | - 该文件在每次日志写入都要打开和关闭。然而，由于常用文件的描述符可以存储在[缓存](#open_log_file_cache)中，因此可以在 [open_log_file_cache](#open_log_file_cache) 指令的 `valid` 参数指定的时间内继续写入旧文件 63 | - 在每次写入日志期间，检查请求根目录是否存在，如果不存在，则不创建日志。因此，在同一级别指定 [root](ngx_http_core_module.md#root) 和 access_log 是一个好方法： 64 | 65 | ```nginx 66 | server { 67 | root /spool/vhost/data/$host; 68 | access_log /spool/vhost/logs/$host; 69 | ... 70 | ``` 71 | 72 | `if` 参数（1.7.0）启用条件日志记录。如果 `condition`为 `0` 或空字符串，则不会记录请求。在以下示例中，不会记录响应代码为 2xx 和 3xx 的请求： 73 | 74 | ```nginx 75 | map $status $loggable { 76 | ~^[23] 0; 77 | default 1; 78 | } 79 | 80 | access_log /path/to/access.log combined if=$loggable; 81 | ``` 82 | 83 | ### log_format 84 | 85 | |\-|说明| 86 | |------:|------| 87 | |**语法**|**log_format** `name [escape=default\|json\|none] string ...`;| 88 | |**默认**|log_format combined "...";| 89 | |**上下文**|http| 90 | 91 | 指定日志格式。 92 | 93 | `escape` 参数（1.11.8）允许设置 `json` 或 `default` 字符在变量中转义，默认情况下使用 `default` 转义。`none` 参数（1.13.10）禁用转义。 94 | 95 | 日志格式可以包含公共变量和仅在日志写入时存在的变量： 96 | 97 | - `$bytes_sent` 98 | 99 | 发送给客户端的字节数 100 | 101 | - `$connection` 102 | 103 | 连接序列号 104 | 105 | - `$connection_requests` 106 | 107 | 当前通过连接发出的请求数量（1.1.18） 108 | 109 | - `$msec` 110 | 111 | 以秒为单位的时间，日志写入时的毫秒精度 112 | 113 | - `$pipe` 114 | 115 | 如果请求是 pipe，则为 **p**，否则为 **.** 116 | 117 | - `$request_length` 118 | 119 | 请求长度（包括请求行、头部和请求体） 120 | 121 | - `$request_time` 122 | 123 | 以毫秒为精度的请求处理时间，以秒为单位。从客户端读取第一个字节到最后一个字节发送到客户端并写入日志过程的时间 124 | 125 | - `$status` 126 | 127 | 响应状态 128 | 129 | - `$time_iso8601` 130 | 131 | 本地时间采用 ISO 8601 标准格式 132 | 133 | - `$time_local` 134 | 135 | 本地时间采用通用日志格式（Common Log Format） 136 | 137 | > 在现代 nginx 版本中，变量 [$status](ngx_http_core_module.md#var_status)（1.3.2、1.2.2）、[$bytes_sent](ngx_http_core_module.md#var_bytes_sent)（1.3.8、1.2.5）、[$connection](ngx_http_core_module.md#var_connection)（1.3.8、1.2.5）、[$connection_requests](ngx_http_core_module.md#var_connection_requests)（1.3.8、1.2.5）、[$msec](ngx_http_core_module.md#var_msec)（1.3.9、1.2.6）、[$request_time](ngx_http_core_module.md#var_request_time)（1.3.9、1.2.6）、[$pipe](ngx_http_core_module.md#var_pipe)（1.3.12、1.2.7）、`$request_length`（1.3.12、1.2.7）、[$time_iso8601](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_length)（1.3.12、1.2.7）和 [$time_local](ngx_http_core_module.md#var_time_local)（1.3.12、1.2.7）也作为公共变量。 138 | 139 | 发送到客户端的头字段前缀为 `sent_http_`，例如 `$sent_http_content_range`。 140 | 141 | 配置始终包含预定义的 `combined` 格式： 142 | 143 | ```nginx 144 | log_format combined '$remote_addr - $remote_user [$time_local] ' 145 | '"$request" $status $body_bytes_sent ' 146 | '"$http_referer" "$http_user_agent"'; 147 | ``` 148 | 149 | ### open_log_file_cache 150 | 151 | |\-|说明| 152 | |------:|------| 153 | |**语法**|**open_log_file_cache** `max=N [inactive=time] [min_uses=N] [valid=time]`;
**open_log_file_cache** `off`;| 154 | |**默认**|open_log_file_cache off;| 155 | |**上下文**|http、server、location| 156 | 157 | 定义一个缓存，用于存储名称中包含变量的常用日志的文件描述符。该指令有以下参数： 158 | 159 | - `max` 160 | 161 | 设置缓存中描述符的最大数量。如果缓存变满，则最近最少使用（LRU）的描述符将被关闭 162 | 163 | - `inactive` 164 | 165 | 如果在此时间后缓存描述符没有被访问，则被关闭，默认为 10 秒 166 | 167 | - `min_uses` 168 | 169 | 在 `inactive` 参数定义的时间内设置文件使用的最小数量，以使描述符在缓存中保持打开状态，默认为 1 170 | 171 | - `valid` 172 | 173 | 设置检查同名文件是否仍然存在的时间，默认为 60 秒 174 | 175 | - `off` 176 | 177 | 禁用缓存 178 | 179 | 使用示例： 180 | 181 | ```nginx 182 | open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; 183 | ``` 184 | 185 | ## 原文档 186 | 187 | [http://nginx.org/en/docs/http/ngx_http_log_module.html](http://nginx.org/en/docs/http/ngx_http_log_module.html) -------------------------------------------------------------------------------- /模块参考/http/ngx_http_upstream_conf_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_upstream_conf_module 2 | 3 | - [示例配置](#example_configuration) 4 | - [指令](#directives) 5 | - [upstream_conf](#upstream_conf) 6 | 7 | **直到 1.13.10 版本，它被 1.13.3 中的 [ngx_http_api_module](ngx_http_api_module.md) 模块所取代。** 8 | 9 | `ngx_http_upstream_conf_module` 模块允许通过简单的 HTTP 接口即时配置上游（upstream）服务器组，而无需重新启动 nginx。[http](ngx_http_upstream_module.md#zone) 或[流](ngx_stream_upstream_module.md#zone)服务器组必须驻留在共享内存中。 10 | 11 | > 该模块作为[商业订阅](http://nginx.com/products/?_ga=2.70698388.504417624.1562407216-1811470965.1562407216)部分提供， 12 | 13 | 14 | 15 | ## 示例配置 16 | 17 | ```nginx 18 | upstream backend { 19 | zone upstream_backend 64k; 20 | 21 | ... 22 | } 23 | 24 | server { 25 | location /upstream_conf { 26 | upstream_conf; 27 | allow 127.0.0.1; 28 | deny all; 29 | } 30 | } 31 | ``` 32 | 33 | 34 | 35 | ## 指令 36 | 37 | ### upstream_conf 38 | 39 | |\-|说明| 40 | |:------|:------| 41 | |**语法**|**upstream_conf**;| 42 | |**默认**|——| 43 | |**上下文**|location| 44 | 45 | 在 location 中引入该指令，开启上游配置 HTTP 接口。 应[限制](ngx_http_core_module.md#satisfy)访问此 location。 46 | 47 | 配置命令可用于： 48 | 49 | - 查看组配置 50 | - 查看、修改或删除服务器 51 | - 添加新服务器 52 | 53 | > 由于组中的地址不要求唯一，因此组中的服务器使用 ID 引用。添加新服务器或查看组配置时，会自动分配 ID 并显示 ID。 54 | 55 | 配置命令作为请求参数传入，例如： 56 | 57 | ``` 58 | http://127.0.0.1/upstream_conf?upstream=backend 59 | ``` 60 | 61 | 支持以下参数： 62 | 63 | - `stream=` 64 | 65 | 选择一个 [stream](../stream/ngx_stream_upstream_module.md) 上游服务器组。如果没有此参数，将选择一个 [http](ngx_http_upstream_module.md) 上游服务器组。 66 | 67 | - `upstream=name` 68 | 69 | 选择要使用的组。此参数是必需的。 70 | 71 | - `id=number` 72 | 73 | 选择一个要查看、修改或删除的服务器。 74 | 75 | - `remove=` 76 | 77 | 从组中删除一个服务器。 78 | 79 | - `add=` 80 | 81 | 向组中添加一个新服务器。 82 | 83 | - `backup=` 84 | 85 | 需要添加一个备用服务器。 86 | 87 | > 在 1.7.2 版之前，查看、修改或删除现有备用服务器还需要 `backup=` 参数。 88 | 89 | - `server=address` 90 | 91 | 与 [http](ngx_http_upstream_module.md#server) 或 [stream](../stream/ngx_stream_upstream_module.md#server) 上游服务器的 `address` 参数相同。 92 | 93 | 添加服务器时，可以将其指定为一个域名。这种情况下，将监视与域名对应的 IP 地址的更改并自动应用于上游配置，无需重新启动 nginx（1.7.2）。这需要 [http](ngx_http_upstream_module.md#server) 或 [stream](../stream/ngx_stream_upstream_module.md#server) 块中的 `resolver` 指令。另请参阅 [http](ngx_http_upstream_module.md#server) 或 [stream](../stream/ngx_stream_upstream_module.md#server) 上游服务器的 `resolve` 参数。 94 | 95 | - `service=name` 96 | 97 | 与 [http](ngx_http_upstream_module.md#service) 或 [stream](../stream/ngx_stream_upstream_module.md#service) 上游服务器的 `service` 参数相同（1.9.13）。 98 | 99 | - `weight=number` 100 | 101 | 与 [http](ngx_http_upstream_module.md#weight) 或 [stream](../stream/ngx_stream_upstream_module.md#weight) 上游服务器的 `weight` 参数相同。 102 | 103 | - `max_conns=number` 104 | 105 | 与 [http](ngx_http_upstream_module.md#max_conns) 或 [stream](../stream/ngx_stream_upstream_module.md#max_conns) 上游服务器的 `max_conns` 参数相同。 106 | 107 | - `max_fails=number` 108 | 109 | 与 [http](ngx_http_upstream_module.md#max_fails) 或 [stream](../stream/ngx_stream_upstream_module.md#max_fails) 上游服务器的 `max_fails` 参数相同。 110 | 111 | - `fail_timeout=time` 112 | 113 | 与 [http](ngx_http_upstream_module.md#fail_timeout) 或 [stream](../stream/ngx_stream_upstream_module.md#fail_timeout) 上游服务器的 `fail_timeout` 参数相同。 114 | 115 | - `slow_start=time` 116 | 117 | 与 [http](ngx_http_upstream_module.md#slow_start) 或 [stream](../stream/ngx_stream_upstream_module.md#slow_start) 上游服务器的 `slow_start` 参数相同。 118 | 119 | - `down=` 120 | 121 | 与 [http](ngx_http_upstream_module.md#down) 或 [stream](../stream/ngx_stream_upstream_module.md#down) 上游服务器的 `down` 参数相同。 122 | 123 | - `drain=` 124 | 将 [http](ngx_http_upstream_module.md#draining) 上游服务器置为 `draining` 模式（1.7.5）。在此模式下，只有绑定到服务器的请求才会被代理。 125 | 126 | - `up=` 127 | 128 | 与 [http](ngx_http_upstream_module.md#down) 或 [stream](../stream/ngx_stream_upstream_module.md#down) 上游服务器的 `down` 参数相反。 129 | 130 | - `route=string` 131 | 132 | 与 [http](ngx_http_upstream_module.md#route) 上游服务器的 `route` 参数相同。 133 | 134 | 前三个参数会选择一个对象。这可以是整个 http 或 stream 上游服务器组，也可以是特定服务器。如果没有其他参数，则会显示所选组或服务器的配置。 135 | 136 | 例如，要查看整个组的配置，请发送： 137 | 138 | ``` 139 | http://127.0.0.1/upstream_conf?upstream=backend 140 | ``` 141 | 142 | 要查看特定服务器的配置，还要指定其 ID： 143 | 144 | ``` 145 | http://127.0.0.1/upstream_conf?upstream=backend&id=42 146 | ``` 147 | 148 | 要添加新服务器，请在 `server=` 参数中指定其地址。如果未指定其他参数，添加服务器时将其他参数设置为其默认值（请参阅 [http](ngx_http_upstream_module.md#server) 或 [stream](../stream/ngx_stream_upstream_module.md#server) 的 `server` 指令）。 149 | 150 | 例如，要添加一个新的主服务器，请发送： 151 | 152 | ``` 153 | http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080 154 | ``` 155 | 156 | 要添加一个备用服务器，发送： 157 | 158 | ``` 159 | http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080 160 | ``` 161 | 162 | 要添加一个新的主服务器，将其参数设置为非默认值并将其标记为 `down`，发送： 163 | 164 | ``` 165 | http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down= 166 | ``` 167 | 168 | 删除一个服务器，指定其 ID： 169 | 170 | ``` 171 | http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42 172 | ``` 173 | 174 | 讲一个现有的服务器标记为 `down`，发送： 175 | 176 | ``` 177 | http://127.0.0.1/upstream_conf?upstream=backend&id=42&down= 178 | ``` 179 | 180 | 修改一个现有服务器的地址，发送： 181 | 182 | ``` 183 | http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123 184 | ``` 185 | 186 | 修改一个现有服务器的其他参数，发送： 187 | 188 | ``` 189 | http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4 190 | ``` 191 | 192 | 以上示例适用于 [http](ngx_http_upstream_module.md) 上游服务器组。[stream](../stream/ngx_stream_upstream_module.md) 上游服务器组需要加上 `stream=` 参数。 193 | 194 | ## 原文档 195 | 196 | - [http://nginx.org/en/docs/http/ngx_http_upstream_conf_module.html](http://nginx.org/en/docs/http/ngx_http_upstream_conf_module.html) 197 | -------------------------------------------------------------------------------- /模块参考/http/ngx_http_memcached_module.md: -------------------------------------------------------------------------------- 1 | # ngx_http_memcached_module 2 | 3 | - [指令](#directives) 4 | - [memcached_bind](#memcached_bind) 5 | - [memcached_buffer_size](#memcached_buffer_size) 6 | - [memcached_connect_timeout](#memcached_connect_timeout) 7 | - [memcached_force_ranges](#memcached_force_ranges) 8 | - [memcached_gzip_flag](#memcached_gzip_flag) 9 | - [memcached_next_upstream](#memcached_next_upstream) 10 | - [memcached_next_upstream_timeout](#memcached_next_upstream_timeout) 11 | - [memcached_next_upstream_tries](#memcached_next_upstream_tries) 12 | - [memcached_pass](#memcached_pass) 13 | - [memcached_read_timeout](#memcached_read_timeout) 14 | - [memcached_send_timeout](#memcached_send_timeout) 15 | - [内嵌变量](#embedded_variables) 16 | 17 | `ngx_http_memcached_module` 模块用于从 memcached 服务器上获取响应。key 设置在 `$memcached_key` 变量中。应通过 nginx 之外的方式提前将响应放入 memcached。 18 | 19 | 20 | 21 | ## 示例配置 22 | 23 | ```nginx 24 | server { 25 | location / { 26 | set $memcached_key "$uri?$args"; 27 | memcached_pass host:11211; 28 | error_page 404 502 504 = @fallback; 29 | } 30 | 31 | location @fallback { 32 | proxy_pass http://backend; 33 | } 34 | } 35 | ``` 36 | 37 | 38 | 39 | ## 指令 40 | 41 | ### memcached_bind 42 | 43 | |\-|说明| 44 | |------:|------| 45 | |**语法**|**memcached_bind** `address [transparent ]` | `off`;| 46 | |**默认**|——| 47 | |**上下文**|http、server、location| 48 | |**提示**|该指令在 0.8.22 版本中出现| 49 | 50 | 连接到一个指定了本地 IP 地址和可选端口（1.11.2）的 memcached 服务器。参数值可以包含变量（1.3.12）。特殊值 `off` （1.3.12）取消从上层配置级别继承的 `memcached_bind` 指令的作用，其允许系统自动分配本地 IP 地址和端口。 51 | 52 | `transparent` 参数（1.11.0）允许出站从非本地 IP 地址到 memcached 服务器的连接（例如，来自客户端的真实 IP 地址）： 53 | 54 | ```nginx 55 | memcached_bind $remote_addr transparent; 56 | ``` 57 | 58 | 为了使这个参数起作用，通常需要以[超级用户](../核心模块.md#user)权限运行 nginx worker 进程。在 Linux 上，不需要指定 `transparent` 参数，工作进程会继承 master 进程的 `CAP_NET_RAW` 功能。此外，还要配置内核路由表来拦截来自 memcached 服务器的网络流量。 59 | 60 | ### memcached_buffer_size 61 | 62 | |\-|说明| 63 | |------:|------| 64 | |**语法**|**memcached_buffer_size** `size`;| 65 | |**默认**|memcached_buffer_size 4k|8k| 66 | |**上下文**|http、server、location| 67 | 68 | 设置用于读取从 memcached 服务器收到的响应的缓冲区的大小（`size`）。一旦收到响应，响应便会同步传送给客户端。 69 | 70 | ### memcached_connect_timeout 71 | 72 | |\-|说明| 73 | |------:|------| 74 | |**语法**|**memcached_connect_timeout** `time`;| 75 | |**默认**|memcached_connect_timeout 60s| 76 | |**上下文**|http、server、location| 77 | 78 | 定义与 memcached 服务器建立连接的超时时间。需要说明的是，超时通常不能超过 75 秒。 79 | 80 | ### memcached_force_ranges 81 | 82 | |\-|说明| 83 | |------:|------| 84 | |**语法**|**memcached_force_ranges** `on` | `off`;| 85 | |**默认**|memcached_force_ranges off;| 86 | |**上下文**|http、server、location| 87 | |**提示**|该指令在 1.7.7 版本中出现| 88 | 89 | 无论响应中的 **Accept-Ranges** 字段如何，都对来自 memcached 服务器的缓存和未缓存的响应启用 byte-range 支持。 90 | 91 | ### memcached_gzip_flag 92 | 93 | |\-|说明| 94 | |------:|------| 95 | |**语法**|**memcached_gzip_flag** `flag`;| 96 | |**默认**|——| 97 | |**上下文**|http、server、location| 98 | |**提示**|该指令在 1.3.6 版本中出现| 99 | 100 | 启用对 memcached 服务器响应中的 `flag` 存在测试，并在 flag 设置时将 **Content-Encoding** 响应头字段设置为 **gzip**。 101 | 102 | ### memcached_next_upstream 103 | 104 | |\-|说明| 105 | |------:|------| 106 | |**语法**|**memcached_next_upstream** `error` | `timeout` | `invalid_response` | `not_found` | `off ...`;| 107 | |**默认**|memcached_next_upstream error timeout;| 108 | |**上下文**|http、server、location| 109 | 110 | 指定在哪些情况下请求应传递给下一台服务器： 111 | 112 | - `error` 113 | 114 | 在与服务器建立连接、传递请求或读取响应头时发生错误 115 | 116 | - `timeout` 117 | 118 | 在与服务器建立连接、传递请求或读取响应头时发生超时 119 | 120 | - `invalid_response` 121 | 122 | 服务器返回空或无效的响应 123 | 124 | - `not_found` 125 | 126 | 在服务器上未找到响应 127 | 128 | - `off` 129 | 130 | 禁用将请求传递给下一个服务器。 131 | 132 | 我们应该记住，只有在没有任何内容发送给客户端的情况下，才能将请求传递给下一个服务器。也就是说，如果在响应传输过程中发生错误或超时，修复这样的错误是不可能的。 133 | 134 | 该指令还定义了与服务器进行通信的[失败尝试](ngx_http_upstream_module.md#max_fails)。`error`、`timeout` 和 `invalid_response` 的情况始终被视为失败尝试，即使它们没有在指令中指定。`not_found` 的情况永远不会被视为失败尝试。 135 | 136 | 将请求传递给下一个服务器可能受到[尝试次数](#grpc_next_upstream_tries)和[时间](#grpc_next_upstream_timeout)的限制。 137 | 138 | ### memcached_next_upstream_tries 139 | 140 | |\-|说明| 141 | |------:|------| 142 | |**语法**|**memcached_next_upstream_tries** `number`;| 143 | |**默认**|memcached_next_upstream_tries 0;| 144 | |**上下文**|http、server、location| 145 | |**提示**|该指令在 1.7.5 版本中出现| 146 | 147 | 限制尝试将请求传递到[下一个服务器](#grpc_next_upstream)的次数。`0` 值表示关闭此限制。 148 | 149 | ### memcached_pass 150 | 151 | |\-|说明| 152 | |------:|------| 153 | |**语法**|**memcached_pass** `address`;| 154 | |**默认**|——| 155 | |**上下文**|http、location 中 if| 156 | 157 | 设置 memcached 服务器地址。该地址可以指定为域名或 IP 地址以及端口： 158 | 159 | ```nginx 160 | memcached_pass localhost:11211; 161 | ``` 162 | 163 | 或使用 UNIX 域套接字路径： 164 | 165 | ```nginx 166 | memcached_pass unix:/tmp/memcached.socket; 167 | ``` 168 | 169 | 如果域名解析为多个地址，则这些地址将以循环方式使用。另外，地址可以被指定为[服务器组](ngx_http_upstream_module.md)。 170 | 171 | ### memcached_read_timeout 172 | 173 | |\-|说明| 174 | |------:|------| 175 | |**语法**|**memcached_read_timeout** `time`;| 176 | |**默认**|memcached_read_timeout 60s;| 177 | |**上下文**|http、server、location| 178 | memcached 179 | 定义从 gRPC 服务器读取响应的超时时间。超时间隔只在两次连续的读操作之间，而不是整个响应的传输过程。如果 memcached 服务器在此时间内没有发送任何内容，则连接关闭。 180 | 181 | ### memcached_send_timeout 182 | 183 | |\-|说明| 184 | |------:|------| 185 | |**语法**|**memcached_send_timeout** `time`;| 186 | |**默认**|memcached_send_timeout 60s;| 187 | |**上下文**|http、server、location| 188 | 189 | 设置将请求传输到 memcached 服务器的超时时间。超时间隔只在两次连续写入操作之间，而不是整个请求的传输过程。如果 memcached 服务器在此时间内没有收到任何内容，则连接将关闭。 190 | 191 | 192 | 193 | ## 内嵌变量 194 | 195 | - `$memcached_key` 196 | 197 | 定义从 memcached 服务器获取响应的密钥 198 | 199 | ## 原文档 200 | [http://nginx.org/en/docs/http/ngx_http_memcached_module.html](http://nginx.org/en/docs/http/ngx_http_memcached_module.html) -------------------------------------------------------------------------------- /介绍/控制nginx.md: -------------------------------------------------------------------------------- 1 | # 控制 nginx 2 | 3 | - [配置变更](#配置变更) 4 | - [日志轮转](#日志轮转) 5 | - [升级可执行文件](#升级可执行文件) 6 | 7 | 可以用信号控制 nginx。默认情况下，主进程（Master）的 pid 写在 `/use/local/nginx/logs/nginx.pid` 文件中。这个文件的位置可以在配置时更改或者在 nginx.conf 文件中使用 `pid` 指令更改。Master 进程支持以下信号： 8 | 9 | 信号 | 作用 10 | :---|:--- 11 | TERM, INT | 快速关闭 12 | QUIT| 正常退出 13 | HUP | 当改变配置文件时，将有一段过渡时间段（仅 FreeBSD 和 Linux），新启动的 Worker 进程将应用新的配置，旧的 Worker 进程将被平滑退出 14 | USR1| 重新打开日志文件 15 | USR2| 升级可执行文件 16 | WINCH| 正常关闭 Worker 进程 17 | 18 | Worker 进程也是可以用信号控制的，尽管这不是必须的。支持以下信号： 19 | 20 | 信号 | 作用 21 | :---|:--- 22 | TERM, INT | 快速关闭 23 | QUIT | 正常关闭 24 | USR1 | 重新打开日志文件 25 | WINCH | 调试异常终止（需要开启 [debug_points](http://nginx.org/en/docs/ngx_core_module.html#debug_points)） 26 | 27 | ## 配置变更 28 | 29 | 为了让 nginx 重新读取配置文件，应将 `HUP` 信号发送给 Master 进程。Master 进程首先会检查配置文件的语法有效性，之后尝试应用新的配置，即打开日志文件和新的 socket。如果失败了，它会回滚更改并继续使用旧的配置。如果成功，它将启动新的 Worker 进程并向旧的 Worker 进程发送消息请求它们正常关闭。旧的 Worker 进程关闭监听 socket 并继续为旧的客户端服务，当所有旧的客户端被处理完成，旧的 Worker 进程将被关闭。 30 | 31 | 我们来举例说明一下。 假设 nginx 是在 FreeBSD 4.x 命令行上运行的 32 | 33 | ```bash 34 | ps axw -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)' 35 | ``` 36 | 37 | 得到以下输出结果： 38 | 39 | ```bash 40 | PID PPID USER %CPU VSZ WCHAN COMMAND 41 | 33126 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 42 | 33127 33126 nobody 0.0 1380 kqread nginx: worker process (nginx) 43 | 33128 33126 nobody 0.0 1364 kqread nginx: worker process (nginx) 44 | 33129 33126 nobody 0.0 1364 kqread nginx: worker process (nginx) 45 | ``` 46 | 47 | 如果把 `HUP` 信号发送到 master 进程，输出的结果将会是： 48 | 49 | ```bash 50 | PID PPID USER %CPU VSZ WCHAN COMMAND 51 | 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 52 | 33129 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx) 53 | 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 54 | 33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 55 | 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 56 | ``` 57 | 58 | 其中一个 PID 为 33129 的 worker 进程仍然在继续工作，过一段时间之后它退出了： 59 | 60 | ```bash 61 | PID PPID USER %CPU VSZ WCHAN COMMAND 62 | 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 63 | 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 64 | 33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 65 | 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 66 | ``` 67 | 68 | ## 日志轮转 69 | 70 | 为了做日志轮转，首先需要重命名。之后应该发送 `USR1` 信号给 master 进程。Master 进程将会重新打开当前所有的日志文件，并将其分配给一个正在运行未经授权的用户为所有者的 worker 进程。成功重新打开之后 Master 进程将会关闭所有打开的文件并且发送消息给 worker 进程要求它们重新打开文件。Worker 进程重新打开新文件和立即关闭旧文件。因此，旧的文件几乎可以立即用于后期处理，例如压缩。 71 | 72 | ## 升级可执行文件 73 | 74 | 为了升级服务器可执行文件，首先应该将新的可执行文件替换旧的可执行文件。之后发送 `USR2` 信号到 master 进程。Master 进程首先将以进程 ID 文件重命名为以 `.oldbin` 为后缀的新文件，例如 `/usr/local/nginx/logs/nginx.pid.oldbin`。之后启动新的二进制文件和依次期待能够新的 worker 进程： 75 | 76 | ```bash 77 | PID PPID USER %CPU VSZ WCHAN COMMAND 78 | 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 79 | 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 80 | 33135 33126 nobody 0.0 1380 kqread nginx: worker process (nginx) 81 | 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) 82 | 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 83 | 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 84 | 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 85 | 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 86 | ``` 87 | 88 | 之后所有的 worker 进程（旧的和新的）继续接收请求，如果 `WINCH` 信号被发送给了第一个 master 进程，它将向其 worker 进程发送消息要求它们正常关闭，之后它们开始退出： 89 | 90 | ``` 91 | PID PPID USER %CPU VSZ WCHAN COMMAND 92 | 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 93 | 33135 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx) 94 | 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 95 | 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 96 | 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 97 | 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 98 | ``` 99 | 100 | 过一段时间，仅有新的 worker 进程处理请求： 101 | 102 | ```bash 103 | PID PPID USER %CPU VSZ WCHAN COMMAND 104 | 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 105 | 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 106 | 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 107 | 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 108 | 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 109 | ``` 110 | 111 | 需要注意的是旧的 master 进程不会关闭它的监听 socket，并且如果需要的话，可以管理它来启动 worker 进程。如果出于某些原因不能接受新的可执行文件工作方式，可以执行以下操作之一： 112 | 113 | - 发送 `HUP` 信号给旧的 master 进程，旧的 master 进程将会启动不会重新读取配置文件的 worker 进程。之后，通过将 `QUIT` 信号发送到新的主进程就可以正常关闭所有的新进程。 114 | - 发送 `TERM` 信号到新的 master 进程，它将会发送一个消息给 worker 进程要求它们立即关闭，并且它们立即退出（如果由于某些原因新的进程没有退出，应该发送 `KILL` 信号让它们强制退出）。当新的 master 进程退出时，旧 master 将会自动启动新的 worker 进程。 115 | 116 | 新的 master 进程退出之后，旧的 master 进程会从以进程 ID 命名的文件中忽略掉 `.oldbin` 后缀的文件。 117 | 118 | 如果升级成功，应该发送 `QUIT` 信号给旧的 master 进程，仅仅新的进程驻留： 119 | 120 | ```bash 121 | PID PPID USER %CPU VSZ WCHAN COMMAND 122 | 36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 123 | 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 124 | 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 125 | 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 126 | ``` 127 | 128 | ## 原文档 129 | 130 | - [http://nginx.org/en/docs/control.html](http://nginx.org/en/docs/control.html) 131 | --------------------------------------------------------------------------------