在微服务架构里，Nginx通常作为流量入口负责反向代理和负载均衡，而后端服务通过SkyWalking探针上报调用链。如果Nginx这一层没有追踪能力，整条链路在网关处就会断裂，排查跨服务超时往往只能靠猜。将Nginx与SkyWalking打通，本质上是让网关具备生成Segment并向下游透传Trace上下文的能力，从而把客户端到后端的所有跳跃串联起来。
编译与部署Nginx SkyWalking模块
SkyWalking官方提供了nginx-lua模块，它基于OpenResty或原生Nginx加lua-nginx-module运行。最稳妥的方式是从源码编译Nginx，并加入--add-module指向skywalking-nginx-lua目录。这样编译出的二进制直接携带追踪逻辑，不需要额外sidecar进程，性能损耗可控。若团队已用OpenResty，可直接把模块放进现有环境，减少重复构建成本。
在编译阶段需留意LuaJIT版本与模块要求的兼容性，部分老环境使用Lua 5.1会报上下文注册错误。推荐采用OpenResty自带的高性能LuaJIT，并开启lua_shared_dict用于缓存追踪元数据。以下示例展示最简configure参数：
./configure --prefix=/usr/local/nginx --add-module=/opt/skywalking-nginx-lua --with-http_ssl_module --with-luajit make && make install
部署完成后，不要急于全量开启采样，应先在预发环境验证Segment上报格式。SkyWalking后端如果版本低于8.x，部分字段命名存在差异，会导致网关数据无法被拓扑图识别。建议在Nginx错误日志中临时打印lua脚本异常，确认无证书校验失败或UDP发送阻塞后再逐步放大流量。
Lua脚本配置与上下文透传
核心配置在nginx.conf的http块中引入skywalking模块提供的lua文件，并指定后端OAP地址。模块默认通过HTTP或gRPC上报，生产环境更推荐gRPC以减少头部开销。上下文透传依赖sw_trace_context变量，它会在location转发前写入下游请求头，例如traceparent或SkyWalking自定义的sw8头，保证后端探针能续接父Span。
一个易错点是Nginx在proxy_pass时若未显式携带透传头，链路会在网关后重新开始。需要在配置里用proxy_set_header把lua生成的上下文注入出去。下面片段演示最小可用配置：
http {
lua_package_path "/opt/skywalking-nginx-lua/lib/?.lua;;";
# 引入初始化
init_by_lua_block {
require("skywalking.client"):startBackendTimer("http://127.0.0.1:12800")
}
server {
location /api/ {
set $skywalking_context "";
rewrite_by_lua_block {
require("skywalking.tracer"):start("127.0.0.1", "80")
}
proxy_pass http://backend/;
proxy_set_header sw8 $skywalking_context;
}
}
}
除了透传，采样率也应在lua层控制。默认全采样在高峰时会让网关CPU明显上升，可通过require("skywalking.util").set_sample_rate(10)只采十分之一的请求。注意采样决策要在rewrite_by_lua阶段完成，否则已创建的Span仍会部分上报，失去限流意义。对于静态资源或健康检查路径，直接用if判断跳过追踪能进一步减负。
排障场景与性能权衡
当后端显示某个接口偶发变慢，但网关日志只有状态码时，集成后的调用链就能指出时间是耗在Nginx转发排队还是后端业务逻辑。SkyWalking界面中Nginx作为独立服务节点出现，其Span包含upstream_response_time等原生变量，比传统access_log更易关联。我们在某次大促压测中，正是通过对比网关Span与订单服务Span，发现瓶颈在网关到鉴权服务的连接池耗尽。
性能方面，lua注入带来的额外开销主要来自上下文序列化和上报网络调用。如果OAP集群短暂不可用，模块内部应采用异步队列避免阻塞worker。下表列出两种接入方式在千QPS下的观测数据：
| 接入方式 | 额外延迟 | CPU增长 | 运维复杂度 |
|---|---|---|---|
| 本地Lua模块 | 约3ms | 8% | 中 |
| Sidecar代理 | 约6ms | 12% | 高 |
从表格可见本地模块在延迟与资源上更优，但要求团队有能力维护自定义Nginx构建。若组织已全面使用Service Mesh，sidecar虽重却统一了埋点标准。无论哪种方案，都应设置熔断：当SkyWalking OAP连续多次不可达，网关需自动关闭追踪，防止雪崩。这种降级策略通过lua中的全局计数器即可实现，不需要改动业务代码。
NginxSkyWalking链路追踪修改时间：2026-08-15 04:36:29