lolly/docs/README.md

NGINX 文档汇总

本目录包含 NGINX 官方文档的深度总结，涵盖 NGINX 的所有常用功能。

文档索引

序号	文档	内容概述
01	概述与基础指南	NGINX 架构、配置结构、启动停止、信号控制、命令行参数
02	安装与构建指南	Linux 包安装、源码编译、配置参数、依赖库、模块编译
03	HTTP 核心模块	server/location 配置、请求路由、文件服务、客户端控制、性能优化
04	反向代理与负载均衡	proxy_pass、upstream、负载均衡算法、健康检查、缓存、WebSocket
05	SSL/TLS 与 HTTPS	HTTPS 配置、SSL 指令、会话缓存、OCSP、SNI、HTTP/2、HTTP/3
06	URL 重写与请求处理	rewrite、return、if、map、常用重写场景、最佳实践
07	压缩与缓存	Gzip 压缩、代理缓存、FastCGI 缓存、静态文件缓存
08	日志与监控	访问日志、错误日志、日志格式、条件日志、stub_status、日志分析
09	安全与访问控制	IP 访问控制、基础认证、请求限制、安全头部、防盗链、WAF
10	TCP/UDP Stream 模块	TCP/UDP 代理、负载均衡、SSL、PROXY 协议、速率限制
11	邮件代理模块	IMAP/POP3/SMTP 代理、认证配置、SSL/TLS、认证服务器
12	性能优化	Worker 配置、事件优化、连接复用、缓冲配置、内核参数
13	Git Commit 规范	Conventional Commits 格式、类型定义、范围划分、示例库
14	gRPC/uWSGI/SCGI 代理	gRPC 代理、uWSGI Python 部署、SCGI 通用代理、模块对比
15	高级特性	内部重定向、错误处理、请求拦截、高级路由
16	内部重定向	internal 指令、X-Accel-Redirect、try_files、命名 location
17	镜像与切片	mirror 请求镜像、slice 大文件切片、流量复制
18	Memcached 集成	memcached_pass、缓存加速、键值设计
19	HTTP 功能模块详解	access/auth/autoindex/geo/map/realip/referer/secure_link/ssi/sub 等 16 个模块
20	限流与连接控制	limit_req 请求限流、limit_conn 连接限制、令牌桶算法、DDoS 防护
21	HTTP/2 与 HTTP/3	HTTP/2 多路复用、HTTP/3 QUIC、配置迁移、性能对比
22	第三方扩展模块	NJS/Lua/Brotli/Cache Purge/Headers More/RTMP/Sticky 模块
23	特殊功能模块	WebDAV/图像过滤/FLV/MP4/HLS 流媒体/XSLT 转换
24	核心与事件模块	worker_processes/events/epoll/kqueue/连接数计算
25	内置变量速查表	HTTP/Stream/SSL/Upstream 变量完整列表（150+个）
26	Lua 模块深度指南	OpenResty、ngx_lua 指令、共享字典、cosocket API
27	安全深度指南	WAF/ModSecurity、DDoS 防护、OWASP Top 10、安全头部
28	API 网关配置	API 路由设计、JWT 验证、限流配额、版本控制
29	动态配置与服务发现	动态 upstream、etcd/Consul、dyups、nginx-unit
30	njs JavaScript 模块	njs 引擎、js_import/js_set/js_content、Fetch API、共享字典
31	OpenTelemetry 可观测性	ngx_otel_module、分布式追踪、Jaeger/Zipkin 集成、采样策略
32	ACME 自动证书管理	ngx_http_acme_module、Let's Encrypt、自动续期、HTTP-01/DNS-01 挑战

---

模块分类索引

核心模块

• 核心与事件模块 - ngx_core_module, ngx_events_module
• HTTP 核心模块 - ngx_http_core_module

代理与负载均衡

• 反向代理与负载均衡 - ngx_http_proxy_module, ngx_http_upstream_module
• gRPC/uWSGI/SCGI 代理 - gRPC, Python, CGI 代理
• TCP/UDP Stream 模块 - ngx_stream_* 模块
• 邮件代理模块 - ngx_mail_* 模块

安全与访问控制

• 安全与访问控制 - 综合安全配置
• HTTP 功能模块详解 - access/auth_basic/auth_request/referer/secure_link
• 限流与连接控制 - limit_req, limit_conn

性能与优化

• 性能优化 - Worker/事件/缓冲/内核参数
• 压缩与缓存 - Gzip, proxy_cache, fastcgi_cache
• HTTP/2 与 HTTP/3 - HTTP/2, HTTP/3 QUIC

内容处理

• URL 重写与请求处理 - rewrite, return, map
• 镜像与切片 - mirror, slice
• 特殊功能模块 - WebDAV, 图像过滤, 流媒体

扩展与第三方

• 第三方扩展模块 - NJS, Lua, Brotli, RTMP 等
• Lua 模块深度指南 - OpenResty、ngx_lua、cosocket
• njs JavaScript 模块 - njs 引擎、JavaScript 扩展

安全深度

• 安全与访问控制 - 综合安全配置
• 安全深度指南 - WAF、DDoS、OWASP
• ACME 自动证书管理 - Let's Encrypt、自动 SSL 证书

可观测性

• 日志与监控 - 访问日志、错误日志、stub_status
• OpenTelemetry 可观测性 - 分布式追踪、Jaeger/Zipkin

API 与动态配置

• API 网关配置 - API 路由、JWT、限流配额
• 动态配置与服务发现 - 动态 upstream、etcd/Consul

参考手册

• 内置变量速查表 - 150+ 个变量完整列表

快速参考

核心配置结构

# 全局配置
worker_processes auto;
error_log /var/log/nginx/error.log;

events {
    worker_connections 10240;
}

http {
    # HTTP 全局配置
    include       mime.types;
    default_type  application/octet-stream;

    # 上游服务器
    upstream backend {
        server 192.168.1.1:8080;
        server 192.168.1.2:8080;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_pass http://backend;
        }
    }
}

stream {
    # TCP/UDP 代理
    server {
        listen 3306;
        proxy_pass mysql:3306;
    }
}

mail {
    # 邮件代理
    server {
        listen 25;
        protocol smtp;
    }
}

常用命令

# 测试配置
nginx -t

# 重载配置
nginx -s reload

# 优雅停止
nginx -s quit

# 查看版本和编译参数
nginx -V

性能优化要点

1. Worker 进程：worker_processes auto
2. 连接数：worker_connections 10240
3. 文件传输：sendfile on
4. 长连接：keepalive_timeout 65
5. 压缩：gzip on; gzip_comp_level 6
6. 缓存：open_file_cache + proxy_cache
7. SSL 优化：ssl_session_cache shared:SSL:10m

安全配置要点

1. 隐藏版本：server_tokens off
2. 安全协议：ssl_protocols TLSv1.2 TLSv1.3
3. 安全头部：HSTS、X-Frame-Options、CSP
4. 请求限制：limit_req + limit_conn
5. 访问控制：IP 白名单 + 基础认证

---

官方资源

• 官方网站：https://nginx.org/
• 官方文档：https://nginx.org/en/docs/
• 模块参考：https://nginx.org/en/docs/ngx_core_module.html
• FAQ：https://nginx.org/en/docs/faq.html
• Wiki：https://wiki.nginx.org/

---

版本说明

• 文档基于 NGINX 官方文档整理
• 涵盖 NGINX 开源版主要功能
• 部分高级功能需要 NGINX Plus 商业版
• 建议使用 NGINX 1.24+ 版本以获得最新特性