From 44d1620c558605bd79b56884e53fe96a32d3e7f7 Mon Sep 17 00:00:00 2001 From: CalunVier <13364488+CalunVier@users.noreply.github.com> Date: Sun, 27 Aug 2023 01:41:44 +0800 Subject: [PATCH 1/3] =?UTF-8?q?QUIC=E5=92=8CHTTP3=E6=94=AF=E6=8C=81.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SUMMARY.md | 1 + ...5\222\214HTTP3\346\224\257\346\214\201.md" | 130 ++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 "\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" diff --git a/SUMMARY.md b/SUMMARY.md index 3ddb327..28529a6 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -12,6 +12,7 @@ - [配置文件度量单位](介绍/配置文件度量单位.md) - [命令行参数](介绍/命令行参数.md) - [Windows 下的 nginx](介绍/Windows下的Nginx.md) + - [QUIC 和 HTTP/3 支持](介绍/QUIC和HTTP3支持.md) - [nginx 如何处理请求](介绍/Nginx如何处理请求.md) - [服务器名称](介绍/服务器名称.md) - [使用 nginx 作为 HTTP 负载均衡器](介绍/使用Nginx作为HTTP负载均衡器.md) diff --git "a/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" "b/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" new file mode 100644 index 0000000..2a836f0 --- /dev/null +++ "b/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" @@ -0,0 +1,130 @@ +# QUIC 和 HTTP/3 支持 + +- [从源码构建](#从源码构建) +- [配置](#配置) +- [配置示例](#配置示例) +- [故障排除](#故障排除) + +从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))中可用。 + +> QUIC 和 HTTP/3 支持是实验性的，请谨慎使用。 + +## 从源码构建 + +使用`configure`命令配置构建。请参考[从源码构建 nginx ](../How-To/从源码构建nginx.md)以获得更多细节。 + +当配置nginx时，可以使用 [`--with-http_v3_module`](../How-To/从源码构建nginx.md#http_v3_module) 配置参数来启用 QUIC 和 HTTP/3。 + +构建nginx时建议使用支持 QUIC 的 SSL 库，例如 [BoringSSL](https://boringssl.googlesource.com/boringssl)，[LibreSSL](https://www.libressl.org/)，或者 [QuicTLS](https://github.com/quictls/openssl)。否则，将使用不支持[早期数据](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data)的[OpenSSL](https://openssl.org/)兼容层。 + +使用以下命令为 nginx 配置 [BoringSSL](https://boringssl.googlesource.com/boringssl)： + +```bash +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../boringssl/include" + --with-ld-opt="-L../boringssl/build/ssl + -L../boringssl/build/crypto" +``` + +或者，可以使用 [QuicTLS](https://github.com/quictls/openssl) 配置 nginx： + +```bash +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../quictls/build/include" + --with-ld-opt="-L../quictls/build/lib" +``` + +或者，可以使用现代版本的 [LibreSSL](https://www.libressl.org/) 配置 nginx： + +```bash +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../libressl/build/include" + --with-ld-opt="-L../libressl/build/lib" +``` + +配置完成后，使用 `make` 编译和安装 nginx。 + +## 配置 + +[ngx_http_core_module](../模块参考/http/ngx_http_core_module.md) 模块中的 `listen` 指令获得了一个新参数 [`quic`](https://nginx.org/en/docs/http/ngx_http_core_module.html#quic)，它在指定端口上通过启用 HTTP/3 over QUIC。 + +除了 `quic` 参数外，还可以指定 [`reuseport`](../模块参考/http/ngx_http_core_module.md#reuseport) 参数，使其在多个工作线程中正常工作。 + +有关指令列表，请参阅 [ngx_http_v3_module](https://nginx.org/en/docs/http/ngx_http_v3_module.html)。 + +要[启用](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_retry)地址验证： + +```nginx +quic_retry on; +``` + +要[启用](../模块参考/http/ngx_http_ssl_module.md#ssl_early_data) 0-RTT： + +```nginx +ssl_early_data on; +``` + +要[启用](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_gso) GSO (Generic Segmentation Offloading)： + +```nginx +quic_gso on; +``` + +为多个 token [设置](https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_host_key) host key： + +```nginx +quic_host_key ; +``` + +QUIC 需要 TLSv1.3 协议版本，该版本在 [`ssl_protocols`](../模块参考/http/ngx_http_ssl_module.html#ssl_protocols) 指令中默认启用。 + +默认情况下，[GSO Linux 特定优化](http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf)处于禁用状态。如果相应的网络接口配置为支持 GSO，请启用它。 + +## 配置示例 + +```nginx +http { + log_format quic '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent" "$http3"'; + + access_log logs/access.log quic; + + server { + # for better compatibility it's recommended + # to use the same port for quic and https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # required for browsers to direct them to quic port + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} +``` + +## 故障排除 + +一些可能有助于识别问题的提示： + +- 确保 nginx 是使用正确的 SSL 库构建的。 +- 确保 nginx 在运行时使用正确的 SSL 库（`nginx -V` 显示当前使用的内容）。 +- 确保客户端实际通过 QUIC 发送请求。建议从简单的控制台客户端（如 [ngtcp2](https://nghttp2.org/ngtcp2)）开始，以确保服务器配置正确，然后再尝试使用可能对证书非常挑剔的真实浏览器。 +- 使用[调试支持](../介绍/调试日志.md)构建nginx并检查调试日志。它应包含有关连接及其失败原因的所有详细信息。所有相关消息都包含“`quic`”前缀，可以轻松过滤掉。 +- 为了进行更深入的调查，可以使用以下宏启用其他调试：`NGX_QUIC_DEBUG_PACKETS, NGX_QUIC_DEBUG_FRAMES, NGX_QUIC_DEBUG_ALLOC, NGX_QUIC_DEBUG_CRYPTO`。 +```bash +./configure + --with-http_v3_module + --with-debug + --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" +``` \ No newline at end of file From 5b6864a6a4f3b2de11a871bce31547b6d293a7a6 Mon Sep 17 00:00:00 2001 From: CalunVier <13364488+CalunVier@users.noreply.github.com> Date: Sun, 27 Aug 2023 01:50:42 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=E9=83=A8=E5=88=86=E6=9B=B4=E6=96=B0"?= =?UTF-8?q?=E4=BB=8E=E6=BA=90=E7=A0=81=E6=9E=84=E5=BB=BAnginx.md"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...7\240\201\346\236\204\345\273\272nginx.md" | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git "a/How-To/\344\273\216\346\272\220\347\240\201\346\236\204\345\273\272nginx.md" "b/How-To/\344\273\216\346\272\220\347\240\201\346\236\204\345\273\272nginx.md" index 647afb2..5e372a6 100644 --- "a/How-To/\344\273\216\346\272\220\347\240\201\346\236\204\345\273\272nginx.md" +++ "b/How-To/\344\273\216\346\272\220\347\240\201\346\236\204\345\273\272nginx.md" @@ -1,37 +1,48 @@ # 从源码构建 nginx -编译时使用 `configure` 命令进行配置。它定义了系统的各个方面，包括了 nginx 进行连接处理使用的方法。最终它会创建出一个 `Makefile`。`configure` 命令支持以下参数： +编译时使用 `configure` 命令进行配置。它定义了系统的各个方面，包括了 nginx 进行连接处理使用的方法。最终它会创建出一个 `Makefile`。 +`configure` 命令支持以下参数： + +- **--help** + + 打印帮助信息 - **--prefix=path** 定义一个用于保留服务器文件的目录。此目录也将用于所有通过 `configure` 设置的相对路径（除了库源码路径外）和 `nginx.conf` 配置文件。默认设置为 `/usr/local/nginx` 目录。 - **--sbin-path=path** 设置 nginx 可执行文件的名称。此名称仅在安装过程中使用。默认情况下，文件名为 `prefix/sbin/nginx`。 +- **--modules-path=path** + + 定义将安装 nginx 动态模块的目录。默认情况下，使用 `prefix/modules` 目录。 - **--conf-path=path** 设置 `nginx.conf` 配置文件的名称。如果需要，nginx 可以使用不同的配置文件启动，方法是使用命令行参数 `-c` 指定文件。默认情况下，文件名为 `prefix/conf/nginx.conf`。 +- **--error-log-path=path** + + 设置主要错误、警告和诊断文件的名称。安装后，可以在 `nginx.conf` 配置文件中使用 [error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log) 指令更改文件名。默认情况下，文件名为 `prefix/logs/error.log`。 - **--pid-path=path** 设置存储主进程的进程 ID 的 nginx.pid 文件名称。安装后，可以在 `nginx.conf` 配置文件中使用 [pid](http://nginx.org/en/docs/ngx_core_module.html#pid) 指令更改文件名。默认文件名为 `prefix/logs/nginx.pid`。 - **--lock-path=path** 设置锁文件的名称前缀。安装后，可以在 `nginx.conf` 配置文件中使用 [lock_file](http://nginx.org/en/docs/ngx_core_module.html#lock_file) 指令更改对应的值。默认值为 `prefix/logs/nginx.lock`。 -- **--error-log-path=path** +- **--user=name** - 设置主要错误、警告和诊断文件的名称。安装后，可以在 `nginx.conf` 配置文件中使用 [error_log](http://nginx.org/en/docs/ngx_core_module.html#error_log) 指令更改文件名。默认情况下，文件名为 `prefix/logs/error.log`。 -- **--http-log-path=path** + 设置一个非特权用户名称，其凭据将由工作进程使用。安装后，可以在 `nginx.conf` 配置文件中使用 [user](http://nginx.org/en/docs/ngx_core_module.html#user) 指令更改名称。默认的用户名为 `nobody`。 +- **--group=name** - 设置 HTTP 服务器主请求日志文件名称。安装后，可以在 `nginx.conf` 配置文件中使用 [access_log](http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) 指令更改文件名。默认情况下，文件名为 `prefix/logs/access.log`。 + 设置一个组的名称，其凭据将由工作进程使用。安装后，可以在 `nginx.conf` 配置文件中使用 [user](http://nginx.org/en/docs/ngx_core_module.html#user) 指令更改名称。默认情况下，组名称设置为一个非特权用户的名称。 - **--build=name** 设置一个可选的 nginx 构建名称 -- **--user=name** +- **--builddir=path** - 设置一个非特权用户名称，其凭据将由工作进程使用。安装后，可以在 `nginx.conf` 配置文件中使用 [user](http://nginx.org/en/docs/ngx_core_module.html#user) 指令更改名称。默认的用户名为 `nobody`。 -- **--group=name** + 设置构建文件夹 +- **--http-log-path=path** - 设置一个组的名称，其凭据将由工作进程使用。安装后，可以在 `nginx.conf` 配置文件中使用 [user](http://nginx.org/en/docs/ngx_core_module.html#user) 指令更改名称。默认情况下，组名称设置为一个非特权用户的名称。 + 设置 HTTP 服务器主请求日志文件名称。安装后，可以在 `nginx.conf` 配置文件中使用 [access_log](http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) 指令更改文件名。默认情况下，文件名为 `prefix/logs/access.log`。 - **--with-select_module 和 --without-select_module** 启用或禁用构建允许服务器使用 `select()` 方法的模块。如果平台不支持其他更合适的方法（如 kqueue、epoll 或 /dev/poll），则将自动构建该模块。 From fb8171e74d721b7d9d3cbb9eb0d7fdbe8e5c05d0 Mon Sep 17 00:00:00 2001 From: CalunVier <13364488+CalunVier@users.noreply.github.com> Date: Sun, 27 Aug 2023 03:13:15 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E4=BC=98=E5=8C=96=E4=BA=86"QUIC=E5=92=8CHT?= =?UTF-8?q?TP3=E6=94=AF=E6=8C=81.md"=E4=B8=AD=E7=9A=84=E9=83=A8=E5=88=86?= =?UTF-8?q?=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git "a/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" "b/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" index 2a836f0..82bd8d9 100644 --- "a/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" +++ "b/\344\273\213\347\273\215/QUIC\345\222\214HTTP3\346\224\257\346\214\201.md" @@ -15,7 +15,7 @@ 当配置nginx时，可以使用 [`--with-http_v3_module`](../How-To/从源码构建nginx.md#http_v3_module) 配置参数来启用 QUIC 和 HTTP/3。 -构建nginx时建议使用支持 QUIC 的 SSL 库，例如 [BoringSSL](https://boringssl.googlesource.com/boringssl)，[LibreSSL](https://www.libressl.org/)，或者 [QuicTLS](https://github.com/quictls/openssl)。否则，将使用不支持[早期数据](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data)的[OpenSSL](https://openssl.org/)兼容层。 +构建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/)兼容层。 使用以下命令为 nginx 配置 [BoringSSL](https://boringssl.googlesource.com/boringssl)： @@ -52,7 +52,7 @@ ## 配置 -[ngx_http_core_module](../模块参考/http/ngx_http_core_module.md) 模块中的 `listen` 指令获得了一个新参数 [`quic`](https://nginx.org/en/docs/http/ngx_http_core_module.html#quic)，它在指定端口上通过启用 HTTP/3 over QUIC。 +[ngx_http_core_module](../模块参考/http/ngx_http_core_module.md) 模块中的 `listen` 指令获得了一个新参数 [`quic`](../模块参考/http/ngx_http_core_module.md#quic)，它在指定端口上通过启用 HTTP/3 over QUIC。 除了 `quic` 参数外，还可以指定 [`reuseport`](../模块参考/http/ngx_http_core_module.md#reuseport) 参数，使其在多个工作线程中正常工作。 @@ -82,7 +82,7 @@ quic_gso on; quic_host_key ; ``` -QUIC 需要 TLSv1.3 协议版本，该版本在 [`ssl_protocols`](../模块参考/http/ngx_http_ssl_module.html#ssl_protocols) 指令中默认启用。 +QUIC 需要 TLSv1.3 协议版本，该版本在 [`ssl_protocols`](../模块参考/http/ngx_http_ssl_module.md#ssl_protocols) 指令中默认启用。 默认情况下，[GSO Linux 特定优化](http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf)处于禁用状态。如果相应的网络接口配置为支持 GSO，请启用它。