名称: nginx-c-module-debug 描述: 基于官方nginx开发指南的nginx C模块调试指南。该技能应用于调试nginx C模块崩溃、内存错误、请求流问题或生产问题。触发任务包括segfault分析、coredump调试、GDB检查、内存泄漏检测、请求阶段跟踪、AddressSanitizer设置或nginx模块故障排除。
nginx.org C模块调试最佳实践
nginx C模块的全面调试指南，源自官方nginx开发文档和生产调试经验。包含8个类别的45条规则，按影响优先级排序，以系统诊断nginx模块的崩溃、内存错误和行为问题。
配套技能: 本技能补充nginx-c-modules（正确性）和nginx-c-module-perf-reliability（性能）。本技能涵盖调试和诊断。
何时应用
在以下情况下参考这些指南：
- 诊断nginx工作进程崩溃（segfaults、SIGABRT、SIGSEGV）
- 查找内存错误（使用后释放、泄漏、池损坏、缓冲区溢出）
- 为nginx设置GDB和核心转储分析
- 跟踪请求通过阶段、子请求和过滤器链的流程
- 使用调试日志记录和动态跟踪工具检测nginx模块
按优先级分类的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 崩溃诊断与信号 | 关键 | crash- |
| 2 | 内存错误检测 | 关键 | memdbg- |
| 3 | GDB与核心转储分析 | 高 | gdb- |
| 4 | 请求流跟踪 | 高 | trace- |
| 5 | 调试日志记录模式 | 中高 | dbglog- |
| 6 | 状态与生命周期调试 | 中 | state- |
| 7 | 动态跟踪工具 | 中 | probe- |
| 8 | 构建与消毒器配置 | 低中 | build- |
快速参考
1. 崩溃诊断与信号（关键）
crash-segfault-signature- 从信号和地址识别Segfault崩溃签名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与核心转储分析（高）
gdb-coredump-setup- 为nginx工作进程崩溃配置核心转储生成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. 请求流跟踪（高）
trace-phase-handler-flow- 跟踪请求通过HTTP阶段处理器的流程trace-subrequest-tree- 映射子请求父子关系以进行调试trace-filter-chain-order- 跟踪过滤器链执行顺序和数据流trace-upstream-callback-seq- 跟踪上游回调序列以进行代理调试trace-event-handler-chain- 跟踪事件处理器执行以进行连接调试trace-config-inheritance- 跟踪通过服务器和位置块的配置继承
5. 调试日志记录模式（中高）
dbglog-debug-mask- 使用正确的调试掩码进行目标日志过滤dbglog-debug-connection- 使用debug_connection隔离单客户端调试输出dbglog-memory-buffer- 使用内存缓冲区日志记录捕获调试输出而无需磁盘I/Odbglog-log-action-string- 设置日志操作字符串以在错误消息中提供上下文dbglog-format-ngx-str- 在调试日志消息中正确格式化ngx_str_t
6. 状态与生命周期调试（中）
state-connection-lifecycle- 跟踪连接状态转换以进行生命周期调试state-upstream-state-machine- 通过记录转换点调试上游模块状态state-timer-leak- 检测池销毁前未移除事件导致的定时器泄漏state-event-flag-debug- 检查事件标志以调试意外处理器调用state-request-count-track- 跟踪请求引用计数以调试过早销毁
7. 动态跟踪工具（中）
probe-strace-syscall- 使用strace跟踪nginx工作进程的系统调用模式probe-dtrace-request- 使用DTrace pid提供程序跟踪请求处理probe-systemtap-pool- 使用SystemTap跟踪内存池分配probe-ebpf-latency- 使用eBPF探针测量每函数延迟probe-strace-fd-leak- 使用strace和/proc检测文件描述符泄漏
8. 构建与消毒器配置（低中）
build-debug-flags- 使用完整调试符号和无优化编译nginxbuild-asan-configure- 使用AddressSanitizer构建nginx以检测内存错误build-single-process- 使用单进程模式简化调试build-valgrind-suppressions- 使用nginx Valgrind抑制以减少误报build-debug-palloc- 启用NGX_DEBUG_PALLOC进行细粒度池分配跟踪
如何使用
阅读个别参考文件以获取详细解释和代码示例：
- Section definitions - 类别结构和影响级别
- Rule template - 添加新规则的模板
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本和参考信息 |