Sign inSign up

bubua12/nginx

By bubua12

•Updated 4 months ago

Image
0

324

bubua12/nginx repository overview

⁠Nginx + OpenTelemetry 链路追踪网关

基于官方 Nginx 镜像，编译集成 nginx-otel⁠ 动态模块的网关镜像。开箱即用，支持分布式链路追踪，内置常用线上排查工具。

⁠Tags

TagNginx 版本OTel 模块版本说明
otel-1.31.01.31.00.1.2当前最新

⁠特性

  • 两阶段构建，最终镜像基于官方 nginx:1.31.0
  • 预编译 ngx_otel_module.so，开箱即用
  • 构建时自动注入 load_module 和 otel_exporter 配置
  • 内置常用排查工具：ss netstat top htop lsof strace tcpdump curl jq dig ping telnet 等

⁠快速开始

⁠1. 最小启动
docker run -d --name nginx-otel \
  -p 80:80 \
  bubua12/nginx:otel-1.31.0

⚠️ 单独启动时 Nginx 会尝试连接 otel-collector:4317，如果没有 OTel Collector 会报连接错误但不影响正常代理功能。

⁠2. 完整链路追踪（推荐）
# docker-compose.yml
version: "3.8"

services:
  nginx:
    image: bubua12/nginx:otel-1.31.0
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - otel-collector

  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.100.0
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
    ports:
      - "4317:4317"
      - "4318:4318"

  jaeger:
    image: jaegertracing/all-in-one:1.57
    ports:
      - "16686:16686"
    environment:
      COLLECTOR_OTLP_ENABLED: "true"

示例 nginx.conf：

server {
    listen 80;
    server_name _;

    otel_trace on;
    otel_trace_context propagate;
    otel_span_name "$request_method $uri";
    otel_span_attr "http.gateway" "nginx";

    location / {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /health {
        otel_trace off;
        return 200 "ok";
    }
}

示例 otel-collector-config.yaml：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger]

启动后访问 http://<IP>:16686 即可打开 Jaeger UI 查看链路。

⁠镜像内预装工具

方便在容器内直接排查线上问题，无需额外安装：

分类工具
进程监控top htop ps lsof strace
网络排查ss netstat ping dig tcpdump telnet traceroute
HTTP 测试curl wget
文件处理jq tree vim

进入容器排查：

docker exec -it nginx-otel bash

# 查看 Nginx 完整生效配置
nginx -T

# 查看连接状态
ss -tlnp

# 测试后端连通性
curl -v http://backend:8080/health

# 抓包分析
tcpdump -i eth0 port 80 -nn

⁠配置说明

⁠端口
端口说明
80HTTP
443HTTPS（需挂载证书）
⁠挂载卷
路径说明
/etc/nginx/conf.d/default.confServer 配置（建议挂载）
/etc/nginx/nginx.conf主配置（需要修改 otel_exporter 地址时挂载）
/etc/nginx/ssl/SSL 证书目录
⁠OTel 配置

otel_exporter 默认配置在主配置中，endpoint 为 otel-collector:4317。如需修改，可挂载自定义主配置：

docker run -d -p 80:80 \
  -v ./my-nginx.conf:/etc/nginx/nginx.conf:ro \
  -v ./my-server.conf:/etc/nginx/conf.d/default.conf:ro \
  bubua12/nginx:otel-1.31.0

主配置需包含：

load_module modules/ngx_otel_module.so;

user  nginx;
worker_processes  auto;
# ...

http {
    otel_exporter {
        endpoint your-collector:4317;
    }
    # ...
    include /etc/nginx/conf.d/*.conf;
}
⁠OTel 指令参考
指令说明示例
otel_trace on|off开启/关闭采集otel_trace on;
otel_trace_context上下文传播：propagate / inject / ignoreotel_trace_context propagate;
otel_span_nameSpan 名称（支持变量）otel_span_name "$request_method $uri";
otel_span_attr自定义 Span 属性otel_span_attr "http.gateway" "nginx";

⁠构建源码

镜像基于两阶段构建，源码和构建脚本见 GitHub 仓库：

https://github.com/bubua12/middle-manifests/tree/master/docker/single/nginx/nginx-otel

⁠License

MIT

Tag summary

Content type

Image

Digest

sha256:928a11d75…

Size

113.9 MB

Last updated

4 months ago

docker pull bubua12/nginx:1.31.0-devops-otel-lua