nginx-c-module-debug

nginx.org C 模块调试最佳实践

面向 nginx C 模块的综合调试指南，基于 nginx 官方开发文档和生产环境调试经验编写。包含 8 个类别、45 条规则，并按影响程度排序，帮助系统地诊断 nginx 模块中的崩溃、内存错误和行为异常。

配套技能：本技能与 nginx-c-modules（正确性）和 nginx-c-module-perf-reliability（性能）互为补充。本技能涵盖调试与诊断。

适用场景

在以下情况参考这些指南：

• 诊断 nginx 工作进程崩溃（段错误、SIGABRT、SIGSEGV）
• 查找内存错误（释放后使用、内存泄漏、内存池损坏、缓冲区溢出）
• 设置 GDB 和分析 nginx 核心转储
• 跟踪请求在各个阶段、子请求和过滤器链中的流转
• 使用调试日志和动态跟踪工具为 nginx 模块添加检测

按优先级划分的规则类别

优先级	类别	影响	前缀
1	崩溃诊断与信号	严重	crash-
2	内存错误检测	严重	memdbg-
3	GDB 与核心转储分析	高	gdb-
4	请求流跟踪	高	trace-
5	调试日志模式	中高	dbglog-
6	状态与生命周期调试	中	state-
7	动态跟踪工具	中	probe-
8	构建与消毒器配置	低中	build-

快速参考

1. 崩溃诊断与信号（严重）

• crash-segfault-signature - 根据信号和地址识别段错误崩溃特征
• crash-null-deref-pattern - 识别 nginx 模块中的 NULL 指针解引用模式
• crash-double-free-finalize - 根据请求引用计数诊断重复完成导致的崩溃
• crash-stack-overflow - 检测递归子请求或过滤器链导致的栈溢出
• crash-worker-exit-log - 从工作进程退出日志消息中提取崩溃上下文
• crash-error-page-redirect - 避免 error_page 内部重定向导致的上下文失效崩溃

2. 内存错误检测（严重）

• memdbg-use-after-free - 根据内存池销毁时机检测释放后使用
• memdbg-pool-leak-pattern - 根据工作进程 RSS 持续增长识别内存池泄漏模式
• memdbg-slab-corruption - 根据多工作进程崩溃诊断共享内存 slab 损坏
• memdbg-cleanup-handler-leak - 检测缺少内存池清理处理程序导致的资源泄漏
• memdbg-buffer-overrun - 查找 ngx_pnalloc 大小计算错误导致的缓冲区溢出
• memdbg-temp-pool-misuse - 避免在临时内存池中存储长期有效的指针
• memdbg-valgrind-pool-trace - 使用 Valgrind 内存池级跟踪查找泄漏的分配

3. GDB 与 Core Dump 分析（HIGH）

• gdb-coredump-setup - 配置 nginx 工作进程崩溃时生成 Core Dump
• gdb-attach-worker - 将 GDB 附加到正在运行的 nginx 工作进程
• gdb-backtrace-read - 阅读 nginx 回溯信息，识别崩溃模块和阶段
• gdb-inspect-request - 在 GDB 中检查 ngx_http_request_t 字段，了解请求状态
• gdb-memory-buffer-extract - 使用 GDB 脚本从内存缓冲区提取调试日志
• gdb-watchpoint-corruption - 使用 GDB 观察点在内存损坏写入时捕获问题

4. 请求流跟踪（HIGH）

• trace-phase-handler-flow - 跟踪请求在 HTTP 阶段处理程序中的流转
• trace-subrequest-tree - 映射子请求的父子关系以进行调试
• trace-filter-chain-order - 跟踪过滤器链的执行顺序和数据流
• trace-upstream-callback-seq - 跟踪上游回调序列以调试代理
• trace-event-handler-chain - 跟踪事件处理程序的执行以调试连接
• trace-config-inheritance - 跟踪配置在 server 和 location 块中的继承情况

5. 调试日志模式（MEDIUM-HIGH）

• dbglog-debug-mask - 使用正确的调试掩码筛选目标日志
• dbglog-debug-connection - 使用 debug_connection 隔离单个客户端的调试输出
• dbglog-memory-buffer - 使用内存缓冲区日志记录捕获调试输出，无需磁盘 I/O
• dbglog-log-action-string - 设置日志操作字符串，为错误消息提供上下文
• dbglog-format-ngx-str - 在调试日志消息中正确格式化 ngx_str_t

6. 状态与生命周期调试（MEDIUM）

• state-connection-lifecycle - 跟踪连接状态转换以调试生命周期
• state-upstream-state-machine - 通过记录状态转换点调试上游模块状态
• state-timer-leak - 检测事件在内存池销毁前未移除导致的定时器泄漏
• state-event-flag-debug - 检查事件标志，调试处理程序意外调用的问题
• state-request-count-track - 跟踪请求引用计数，调试过早销毁问题

7. 动态跟踪工具（MEDIUM）

• probe-strace-syscall - 使用 strace 跟踪 nginx 工作进程中的系统调用模式
• probe-dtrace-request - 使用 DTrace pid Provider 跟踪请求处理过程
• probe-systemtap-pool - 使用 SystemTap 跟踪内存池分配
• probe-ebpf-latency - 使用 eBPF 探针测量各函数的延迟
• probe-strace-fd-leak - 使用 strace 和 /proc 检测文件描述符泄漏

8. 构建与 Sanitizer 配置（低-中）

• build-debug-flags - 使用完整调试符号且不进行优化来编译 nginx
• build-asan-configure - 使用 AddressSanitizer 构建 nginx，以检测内存错误
• build-single-process - 使用单进程模式简化调试
• build-valgrind-suppressions - 使用 nginx Valgrind 抑制规则减少误报
• build-debug-palloc - 启用 NGX_DEBUG_PALLOC，以精细跟踪池分配情况

如何使用

阅读单独的参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息