nginx-c-module-perf

nginx.org C 模块性能与可靠性最佳实践

这是一份全面的 nginx C 模块性能优化与可靠性指南，基于 nginx 官方开发文档和生产工程经验编写。指南涵盖 8 个类别中的 43 条规则，并按影响程度排序，以指导自动化优化和弹性改进。

配套技能：此技能与 nginx-c-modules 相辅相成；后者涵盖正确性（内存安全、请求生命周期、配置），此技能涵盖性能优化与运行可靠性。

适用场景

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

• 优化 nginx C 模块的吞吐量和延迟
• 减少缓冲区复制并启用零拷贝 I/O 路径
• 调优连接池和套接字选项
• 尽量减少 worker 之间的共享内存锁争用
• 实现优雅的错误恢复和回退响应
• 配置上游超时和重试策略
• 使用共享内存构建模块内响应缓存
• 调优负载下的 worker 进程行为

按优先级划分的规则类别

优先级	类别	影响	前缀
1	缓冲区与零拷贝 I/O	严重	buf-
2	连接效率	严重	conn-
3	锁争用与原子操作	高	lock-
4	错误恢复与弹性	高	err-
5	超时与重试策略	中高	timeout-
6	响应缓存	中	cache-
7	Worker 与进程调优	中	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 并提供回退方案，避免 worker 停顿
• lock-per-worker-aggregate - 汇总各 worker 的计数器，以减少共享内存访问
• 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 - 使用 Single-Flight 模式防止缓存击穿
• cache-key-hash - 使用 ngx_hash 查找固定缓存键
• cache-ttl-atomic - 使用原子时间戳比较检查 TTL 是否过期
• cache-conditional-store - 仅缓存成功响应，避免负缓存污染

7. Worker 与进程调优（中）

• worker-accept-mutex - 了解 Accept Mutex 对连接分配的影响
• worker-connection-prealloc - 使用预分配的空闲列表存储模块数据结构
• worker-graceful-shutdown - 处理 Worker 关闭信号，避免数据丢失
• worker-single-process-debug - 支持单进程模式以便调试
• worker-cycle-conf - 通过 Cycle 访问配置，以执行进程级操作

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	版本和参考信息