Merge pull request #1824 from drawing/master

README:add xquic document
alibaba · Jul 24, 2023 · fb29798 · fb29798
2 parents 0facb9e + 62aa98b
commit fb29798
Showing 1 changed file with 94 additions and 0 deletions.
diff --git a/modules/ngx_http_xquic_module/README.md b/modules/ngx_http_xquic_module/README.md
@@ -97,3 +97,97 @@ http {
 ```
 
 更为详细的指令可参考官网文档 [XQUIC模块](http://tengine.taobao.org/document_cn/xquic_cn.html)
+
+# 浏览器使用 HTTP3
+
+浏览器默认不会使用 `HTTP3` 请求，需要服务端响应包头 `Alt-Svc` 进行升级说明，浏览器通过响应包头感知到服务端是支持 `HTTP3` 的，下次请求会尝试使用 `HTTP3`。
+
+```nginx
+worker_processes  1;
+
+events {
+    worker_connections  1024;
+}
+
+xquic_log   "pipe:rollback /usr/local/tengine/logs/tengine-xquic.log baknum=10 maxsize=1G interval=1d adjust=600" info;
+
+http {
+    xquic_ssl_certificate        /usr/local/tengine/ssl/default-fake-certificate.pem;
+    xquic_ssl_certificate_key    /usr/local/tengine/ssl/default-fake-certificate.pem;
+
+    server {
+        listen 2443 xquic reuseport;
+
+        location / {
+        }
+    }
+
+    server {
+        listen 80 default_server reuseport backlog=4096;
+        listen 443 default_server reuseport backlog=4096 ssl http2;
+        listen 443 default_server reuseport backlog=4096 xquic;
+
+        server_name s1.test.com;
+
+        add_header Alt-Svc 'h3=":443"; ma=2592000,h3-29=":443"; ma=2592000' always;
+
+        ssl_certificate     /etc/ingress-controller/ssl/s1.crt;
+        ssl_certificate_key /etc/ingress-controller/ssl/s1.key;
+    }
+
+    server {
+        listen 80;
+        listen 443 ssl http2;
+        listen 443 xquic;
+
+        server_name s2.test.com;
+
+        add_header Alt-Svc 'h3=":443"; ma=2592000,h3-29=":443"; ma=2592000' always;
+
+        ssl_certificate     /etc/ingress-controller/ssl/s2.crt;
+        ssl_certificate_key /etc/ingress-controller/ssl/s2.key;
+    }
+}
+```
+
+通过以上配置，浏览器访问对应域名，第一次访问 `HTTP2`，下次访问会切换至 `HTTP3`。
+
+**注意**：
+
+在生产环境中，处于安全性考虑，一般情况会以普通用户权限启动 `Tenigne`，而 `xquic` 功能在普通用户权限下，监听端口必须配置为 1024 以上，如监听 2443 端口，那对外的四层负载均衡需要做 443 到 2443 端口的映射，`Tenigne` `Server`段配置示例：
+
+```nginx
+    server {
+        listen 80 default_server reuseport backlog=4096;
+        listen 443 default_server reuseport backlog=4096 ssl http2;
+        listen 2443 default_server reuseport backlog=4096 xquic;
+
+        add_header Alt-Svc 'h3=":443"; ma=2592000,h3-29=":443"; ma=2592000' always;
+
+        ssl_certificate     /etc/ingress-controller/ssl/s1.crt;
+        ssl_certificate_key /etc/ingress-controller/ssl/s1.key;
+    }
+```
+
+四层负载均衡配置示例：
+
+```yaml
+  type: LoadBalancer
+  ports:
+  - port: 80
+    name: tengine-tcp-80
+    protocol: TCP
+    targetPort: 80
+  - port: 443
+    name: tengine-tcp-443
+    protocol: TCP
+    targetPort: 443
+  - port: 443
+    name: tengine-udp-443
+    protocol: UDP
+    targetPort: 2443
+  selector:
+    app: tengine
+```
+
+对用户来讲，还是通过 443 端口访问，通过四层负责均衡设备，转换为 `Tengine` 的 2443 端口。