name: nginx-c-module-perf description: 基于官方 nginx 开发指南的 nginx C 模块性能优化和可靠性指南。此技能应在优化 nginx C 模块的吞吐量、延迟、内存效率和操作韧性时使用。触发涉及缓冲区优化、连接调优、共享内存争用、错误恢复、超时策略、缓存实现、工作进程调优或 nginx C 模块中的日志性能的任务。
nginx.org C 模块性能与可靠性最佳实践
全面的 nginx C 模块性能优化和可靠性指南，源自官方 nginx 开发文档和生产工程经验。包含 8 个类别中的 43 条规则，按影响优先级排序，以指导自动优化和韧性改进。
配套技能：此技能补充 nginx-c-modules，后者涵盖正确性（内存安全、请求生命周期、配置）。此技能涵盖 性能优化和操作可靠性。
何时应用
参考这些指南当：
- 优化 nginx C 模块的吞吐量和延迟
- 减少缓冲区复制并启用零拷贝 I/O 路径
- 调优连接池和套接字选项
- 最小化工作进程间的共享内存锁争用
- 实现优雅的错误恢复和回退响应
- 配置上游超时和重试策略
- 使用共享内存构建模块内响应缓存
- 在负载下调优工作进程行为
按优先级分类的规则类别
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 缓冲区与零拷贝 I/O | 关键 | buf- |
| 2 | 连接效率 | 关键 | conn- |
| 3 | 锁争用与原子操作 | 高 | lock- |
| 4 | 错误恢复与韧性 | 高 | err- |
| 5 | 超时与重试策略 | 中高 | timeout- |
| 6 | 响应缓存 | 中 | cache- |
| 7 | 工作进程与进程调优 | 中 | worker- |
| 8 | 日志记录与指标 | 低中 | log- |
快速参考
1. 缓冲区与零拷贝 I/O（关键）
buf-chain-reuse- 重用缓冲区链链接而非分配新的buf-file-sendfile- 使用文件缓冲区处理静态内容而非读入内存buf-avoid-copy- 在通过过滤器链传递时避免复制缓冲区buf-coalesce-small- 在输出前合并小缓冲区buf-shadow-reference- 使用影子缓冲区处理派生数据而非完全复制buf-recycled-flag- 标记缓冲区为可回收以供上游响应重用
2. 连接效率（关键）
conn-reusable-queue- 标记空闲连接为可重用以进行池恢复conn-drain-pressure- 在内存压力下处理连接耗尽conn-tcp-nodelay- 控制 TCP_NODELAY 以处理延迟敏感响应conn-prealloc-pool- 调整连接池大小以避免运行时重新分配conn-close-linger- 使用延迟关闭以实现优雅连接关闭conn-ssl-session-reuse- 在上游连接中启用 SSL 会话缓存
3. 锁争用与原子操作（高）
lock-minimize-critical- 最小化共享内存中的临界区持续时间lock-atomic-counters- 使用原子操作处理简单计数器而非互斥锁lock-trylock-fallback- 使用 ngx_shmtx_trylock 并回退以避免工作进程停滞lock-per-worker-aggregate- 聚合每工作进程计数器以减少共享内存访问lock-alloc-outside- 在热路径外执行 slab 分配lock-rw-pattern- 对读密集型共享数据使用读-复制-更新模式
4. 错误恢复与韧性（高）
err-cache-errno- 立即缓存 ngx_errno 以防止覆盖err-fallback-response- 当上游失败时返回回退响应err-resource-exhaustion- 优雅地处理池和 slab 分配耗尽err-blocked-counter- 使用阻塞计数器以防止过早请求销毁err-connection-error-check- 在 I/O 操作前检查连接错误标志err-log-once-pattern- 限制重复错误日志记录以防止日志风暴
5. 超时与重试策略（中高）
timeout-upstream-phases- 为连接、发送和读取阶段设置单独的超时timeout-retry-next-upstream- 配置 next_upstream 掩码以处理可重试失败timeout-backoff-reconnect- 使用指数退避进行上游重新连接尝试timeout-client-body-limit- 设置客户端主体超时以限制慢客户端资源使用
6. 响应缓存（中）
cache-shm-lru- 在共享内存缓存区域实现 LRU 淘汰cache-stampede-lock- 使用单次飞行模式防止缓存风暴cache-key-hash- 使用 ngx_hash 进行固定缓存键查找cache-ttl-atomic- 使用原子时间戳比较进行 TTL 到期检查cache-conditional-store- 仅缓存成功响应以避免负缓存污染
7. 工作进程与进程调优（中）
worker-accept-mutex- 理解接受互斥锁对连接分布的影响worker-connection-prealloc- 使用预分配空闲列表处理模块数据结构worker-graceful-shutdown- 处理工作进程关闭信号而无数据丢失worker-single-process-debug- 支持单进程模式以进行调试worker-cycle-conf- 通过周期访问配置以进行进程级操作
8. 日志记录与指标（低中）
log-level-guard- 在级别检查后保护昂贵的调试参数计算log-connection-context- 将模块上下文附加到连接日志以进行跟踪log-shared-metrics- 通过共享内存计数器收集指标log-error-dedup- 通过节流去重重复错误消息log-action-string- 设置日志操作字符串以提供操作上下文
如何使用
阅读单个参考文件以获取详细解释和代码示例：
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则的模板 |
| metadata.json | 版本和参考信息 |