chainstack/ingress-nginx

ingress-nginx 自定义镜像技术文档

一、镜像概述和主要用途

概述

ingress-nginx 自定义镜像是基于官方 nginx-ingress-controller 构建的增强版镜像，内置了第三方 Nginx 模块，旨在扩展对 WebSocket 协议的监控与日志能力。

主要用途

• 作为 Kubernetes 集群的入口控制器，管理外部流量路由至集群内部服务（继承官方 nginx-ingress-controller 基础能力）。
• 增强 WebSocket 协议的可观测性，支持收集连接统计数据及记录 WebSocket 消息内容至访问日志，适用于需要深度监控 WebSocket 通信的场景。

二、核心功能和特性

基础功能（继承自官方 nginx-ingress-controller）

• HTTP/HTTPS 流量路由、负载均衡、SSL 终止。
• 支持 Ingress 资源配置、路径重写、请求头修改等标准入口控制器功能。

增强功能（内置自定义模块）

• WebSocket 监控模块：集成 https://github.com/chainstack/ngx_http_websocket_stat_module%EF%BC%8C%E6%8F%90%E4%BE%9B%E4%BB%A5%E4%B8%8B%E8%83%BD%E5%8A%9B%EF%BC%9A
  • 收集 WebSocket 连接统计数据（如连接数、建立/关闭次数、数据传输量）。
  • 将 WebSocket 消息内容（文本/二进制）打印至 Nginx 访问日志，支持调试与流量分析。

三、使用场景和适用范围

适用场景

1. 实时通信应用监控：需监控 WebSocket 连接状态的场景（如即时聊天、在线协作工具、实时游戏）。
2. WebSocket 流量分析：需要统计 WebSocket 连接数、消息频率等指标的业务（如直播弹幕、实时数据推送服务）。
3. 调试与问题排查：需捕获 WebSocket 消息内容以诊断通信异常的开发/测试环境。

适用范围

• Kubernetes 集群环境（作为入口控制器部署）。
• 依赖 WebSocket 协议进行实时通信的服务。
• 需要增强日志能力以满足合规审计或故障排查需求的场景。

四、使用方法和配置说明

1. 前置条件

• Docker 环境（20.10+）或 Kubernetes 集群（1.21+）。
• 若使用 Kubernetes，需具备集群管理员权限（用于部署 Ingress Controller）。

2. 镜像获取

假设镜像托管于私有仓库或公共 Registry，拉取命令：

bash
docker pull [镜像仓库地址]/ingress-nginx:latest  # 替换为实际镜像地址

3. 模块配置说明

内置的 ngx_http_websocket_stat_module 需通过 Nginx 配置指令启用，支持以下核心配置（具体参数以模块官方文档为准）：

4. 在 Ingress 中应用配置

通过 Ingress 资源的 nginx.ingress.kubernetes.io/configuration-snippet 注解注入模块配置，示例：

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: websocket-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      # 启用 WebSocket 统计及消息日志
      websocket_stat on;
      websocket_log_message on;
      # 自定义日志格式（包含 WebSocket 变量）
      log_format websocket_log '$remote_addr [$time_local] "$request" $status '
                               '"$websocket_message" $websocket_frame_size';
      access_log /var/log/nginx/websocket-access.log websocket_log;
spec:
  ingressClassName: nginx  # 需与自定义 ingress-nginx 控制器的 class 匹配
  rules:
    - host: ws.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: websocket-service
                port:
                  number: 80

五、Docker 部署方案示例

1. 单机 Docker 运行（简化示例）

bash
docker run -d \
  --name custom-ingress-nginx \
  --net=host \
  -v /path/to/custom-nginx.conf:/etc/nginx/nginx.conf \  # 挂载包含模块配置的 Nginx 配置文件
  -v /var/log/nginx:/var/log/nginx \  # 挂载日志目录
  [镜像仓库地址]/ingress-nginx:latest

2. Docker Compose 配置（本地测试用）

yaml
version: '3.8'
services:
  ingress-nginx:
    image: [镜像仓库地址]/ingress-nginx:latest
    container_name: custom-ingress-nginx
    network_mode: host  # 需使用 host 网络以监听主机端口（模拟集群入口）
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf  # 本地挂载自定义 Nginx 配置（含模块配置）
      - ./logs:/var/log/nginx  # 日志持久化
    restart: always
    environment:
      - NGINX_HOST=ws.example.com  # 可选：设置默认主机名

六、注意事项

1. 兼容性：镜像版本需与官方 nginx-ingress-controller 版本对应（如 v1.8.0 需基于官方 v1.8.0 构建），避免功能冲突。
2. 性能影响：启用 websocket_log_message 可能增加日志体积及 CPU 开销，生产环境建议按需开启。
3. 安全风险：WebSocket 消息可能包含敏感数据，需确保日志存储符合数据安全规范（如加密、访问控制）。

七、参考链接

• https://github.com/chainstack/ngx_http_websocket_stat_module
• https://kubernetes.github.io/ingress-nginx/