Merge pull request 'tutorial' (#13) from myfeji8p7/Nginx:jfu into master

tutorial/README.adoc

@@ -0,0 +1,155 @@
+= 基于Nginx的高可用分布式网关开发手册
+
+== 一. 开发环境搭建
+=== 1. 开发环境组成
+
+* 操作系统：Windows 11（需要支持WSL2，WSL2为Ubuntu-22.04）；
+* 容器： Docker Desktop
+* IDE： Visual Studio Code
+* 编程语言：C语言为主
+* 编译器： GCC
+* 调试工具：gdb
+* 其他工具：kimi.ai
+
+=== 2. 开发环境安装
+暂略
+
+=== 3. 开发环境截图
+
+* WSL2：不想装虚拟机软件，就用WSL2替代了
+
+在windows系统查看wsl版本号：
+
+image::./imgs/wsl.png[WSL版本]
+进入wsl后，查看Linux系统版本号：
+
+image::./imgs/wsl-linux.png[Linux版本号]
+* Docker Desktop：通过创建多个docker容器模拟分布式计算环境：Nginx集群+后端服务器集群
+
+Docker Desktop设置截图：
+
+image::./imgs/DockerDesktop.png[Docker Desktop]
+其中，Docker镜像仓库代理设置参考如下：
+[source,json]
+----
+{
+  "builder": {
+    "gc": {
+      "defaultKeepStorage": "20GB",
+      "enabled": true
+    }
+  },
+  "experimental": false,
+  "registry-mirrors": [
+    "https://dockerproxy.com",
+    "https://hub-mirror.c.163.com",
+    "https://mirror.baidubce.com",
+    "https://ccr.ccs.tencentyun.com"
+  ]
+}
+----
+* Visual Studio Code，建议安装以下插件：插件安装方法见Visual Studio Code官网
+1. C语言的插件群，安装方法见：link:https://code.visualstudio.com/docs/languages/cpp[C语言插件]
+2. 安装WSL插件（可选）：远程连接WSL子系统，使用WSL子系统作为编译和运行环境，详见link:https://code.visualstudio.com/docs/remote/wsl-tutorial[在WSL进行远程开发]；
+3. 安装Dev Container插件：远程连接Docker容器，以将Docker容器作为Nginx组件开发和调试环境，详见：link:https://code.visualstudio.com/docs/devcontainers/create-dev-container[创建Dev Container]
+
+image::./imgs/dev-container.png[运行中的Dev Container]
+
+image::./imgs/dev-container-2.png[Visual Studio Code连接Dev Container]
+
+== 二. Nginx原理
+=== 1. 下载Nginx源码
+
+link:https://nginx.org/en/download.html[下载地址]
+
+image::./imgs/download-nginx-src.png[下载Nginx源码]
+
+=== 2. 编译Nginx源码
+编译Nginx之前，需要提前安装GCC、Make、GDB等编译工具，安装过程略。
+
+Nginx源码结构（不同下载路径，结构略有不同）
+
+image::./imgs/nginx-src-structure.png[Nginx源码结构]
+
+编译方法：link:https://nginx.org/en/docs/configure.html[编译Nginx源代码]
+
+
+=== 3. 一个开源实例模块
+开源地址：link:https://github.com/yaoweibin/nginx_upstream_check_module[nginx_upstream_check_module]
+
+=== 4. 编译开源组件
+为了便于编译，我们将编译命令和参数写成shell脚本（`configure-health-check.sh`）：
+[source,shell]
+----
+#!/bin/sh
+
+# -g3 -gdwarf-2 允许在gdb调试时查看macro definitions以及macro expansion
+# -O0 -DNDEBUG 允许compiler debugging
+# --with-debug 开启nginx debugging
+# -fexec-charset=GBK 允许nginx输出中文
+ ./configure --with-cc-opt="-O0 -DNDEBUG -fexec-charset=GBK -g3 -gdwarf-2 -fsanitize=address -DNGX_DEBUG_PALLOC=1" --with-debug --prefix=/opt/nginx --with-http_ssl_module --add-module=/workspaces/cpp-5/nginx_upstream_check_module
+----
+其中，+++--prefix+++表示nginx安装目录；+++--with-debug+++允许nginx打开debug模式，并与+++-O0 -g3 -DNDEBUG -gdwarf-2+++配合，避免由于编译优化导致部分调试信息丢失；+++--add-module+++指定开源模块的源码路径。 +++-fsanitize=address -DNGX_DEBUG_PALLOC=1+++将屏蔽nginx memory pool，并允许内存debug
+
+使用以下命令执行脚本：
+[source,shell]
+----
+sh configure-health-check.sh
+----
+
+然后再分别执行make和make install安装nginx：
+[source,shell]
+----
+make
+make install
+----
+清理编译结果：
+[source,shell]
+----
+make clean
+----
+
+=== 5. 调试Nginx
+执行以下命令，进入gdb调试界面
+[source,shell]
+----
+gdb /opt/nginx/sbin/nginx
+----
+image::./imgs/gdb-entry.png[打开gdb调试]
+在gdb命令行中开启多线程调试：当主进程fork出子进程后，将自动对子进程调试
+[source,shell]
+----
+set follow-fork-mode child
+set detach-on-fork on
+----
+image::./imgs/gdb-mutil-threads.png[多线程调试开关]
+在想要调试的地方设置断点后，开始调试：
+[source,shell]
+----
+br ngx_http_upstream_check_status_handler
+...
+start
+...
+cont
+....
+----
+image::./imgs/debug-nginx.png[调试nginx]
+
+关于gdb调试指令可参考：link:https://wizardforcel.gitbooks.io/100-gdb-tips/content/index.html[gdb调试小技巧]
+
+== 三. 网关原理
+
+参考：
+
+1. 负载均衡解释：link:https://www.nginx.org.cn/article/detail/440[]
+2. 高可用配置示例：link:https://blog.csdn.net/IT_10/article/details/89365436[]
+3. nginx开发参考1：link:https://tengine.taobao.org/book/[]
+4. nginx开发参考2：link:https://www.nginx.org.cn/article/detail/443[]
+5. nginx中文配置手册：link:https://wizardforcel.gitbooks.io/nginx-doc/content/index.html[]
+6. nginx开发参考3：link:https://www.kancloud.cn/kancloud/master-nginx-develop/51798[]
+
+== 四. 开发流程
+
+== 五. 其他
+
+== 六. 参考资料