paskalmaksim/nginx-push-stream-module

Nginx Push Stream Module

概述和主要用途

Nginx Push Stream Module是一个为Nginx设计的纯流HTTP推送技术模块，旨在简化Comet（一种用于实现Web实时通信的技术）的实现并提供高度可扩展性。该模块不随Nginx源码分发，需单独安装，目前已被认为是生产就绪的稳定模块。

核心功能和特性

• 支持多种推送协议：EventSource、WebSocket、长轮询（Long Polling）和永久iframe（Forever Iframe）
• 实现发布者（publisher）和订阅者（subscriber）模式，支持频道化消息分发
• 内置频道统计功能，可实时查询频道状态、订阅者数量、消息历史等信息
• 提供灵活的配置选项，包括消息存储策略、TTL（生存时间）、连接超时等
• 支持频道生命周期管理，包括创建、删除和自动清理 inactive 频道
• 提供框架无关的JavaScript客户端实现，简化前端集成

使用场景和适用范围

• 实时通知系统（如社交媒体通知、系统告警、实时更新）
• 实时聊天应用（一对一或群组聊天）
• 实时数据监控（***行情、系统性能指标、传感器数据）
• 协作工具（实时文档编辑、项目看板更新）
• 需要服务器主动向客户端推送数据的高并发Web应用

基本配置

在Nginx配置文件中添加以下内容以启用模块功能：

nginx
# 在http上下文中配置共享内存大小
http {
    push_stream_shared_memory_size 32M;  # 设置推送流共享内存大小

    # 在server上下文中定义发布者、订阅者和统计端点
    server {
        # 频道统计端点
        location /channels-stats {
            push_stream_channels_statistics;  # 启用频道统计模式
            push_stream_channels_path $arg_id;  # 基于查询字符串的频道ID
        }

        # 发布者端点
        location /pub {
            push_stream_publisher admin;  # 启用发布者（管理员）模式
            push_stream_channels_path $arg_id;  # 基于查询字符串的频道ID
        }

        # 订阅者端点（通过URL路径匹配频道ID）
        location ~ /sub/(.*) {
            push_stream_subscriber;  # 启用订阅者（流）模式
            push_stream_channels_path $1;  # 基于URL路径的频道ID（捕获组匹配）
        }
    }
}

基本使用方法

通过命令行工具（如curl）即可体验模块的核心功能，建议使用多个终端分别执行发布和订阅操作：

订阅频道

bash
# 订阅频道"my_channel_1"
curl -s -v --no-buffer 'http://localhost/sub/my_channel_1'

# 订阅频道"your_channel_1"
curl -s -v --no-buffer 'http://localhost/sub/your_channel_1'

# 订阅频道"your_channel_2"
curl -s -v --no-buffer 'http://localhost/sub/your_channel_2'

发布消息

bash
# 向"my_channel_1"发布消息
curl -s -v -X POST 'http://localhost/pub?id=my_channel_1' -d 'Hello World!'

# 向"your_channel_1"发布消息
curl -s -v -X POST 'http://localhost/pub?id=your_channel_1' -d 'Hi everybody!'

# 向"your_channel_2"发布消息
curl -s -v -X POST 'http://localhost/pub?id=your_channel_2' -d 'Goodbye!'

频道统计查询

bash
# 获取指定频道信息（如"my_channel_1"）
curl -s -v 'http://localhost/pub?id=my_channel_1'

# 获取所有频道汇总统计
curl -s -v 'http://localhost/channels-stats'

# 获取所有频道详细统计
curl -s -v 'http://localhost/channels-stats?id=ALL'

# 获取前缀匹配的频道详细统计（如"your_channel_"开头的所有频道）
curl -s -v 'http://localhost/channels-stats?id=your_channel_*'

# 获取单个频道详细统计（如"my_channel_1"）
curl -s -v 'http://localhost/channels-stats?id=my_channel_1'

频道管理

bash
# 删除指定频道（如"my_channel_1"）
curl -s -v -X DELETE 'http://localhost/pub?id=my_channel_1'

使用示例

模块提供多种集成示例，包括：

• Curl命令行示例
• 永久隐藏iframe实现
• Event Source（SSE）实现
• WebSocket实现
• 长轮询实现
• JSONP跨域推送
• M-JPEG视频流推送
• 其他示例（详见项目wiki）

常见问题（FAQ）

使用中遇到问题，请查阅项目https://github.com/wandenberg/nginx-push-stream-module/wiki/_pages%E3%80%82

安装步骤

环境要求

• Nginx 1.2.0或更高版本
• Git、wget及编译工具（gcc、make等）

安装流程

bash
# 克隆项目仓库
git clone https://github.com/wandenberg/nginx-push-stream-module.git
NGINX_PUSH_STREAM_MODULE_PATH=$PWD/nginx-push-stream-module

# 下载Nginx源码（1.2.0或更高版本）
wget http://nginx.org/download/nginx-1.2.0.tar.gz

# 解压并编译Nginx（添加模块）
tar xzvf nginx-1.2.0.tar.gz
cd nginx-1.2.0
./configure --add-module=../nginx-push-stream-module  # 添加推送流模块
make

# 安装Nginx
sudo make install

# 验证安装版本
sudo /usr/local/nginx/sbin/nginx -v
# 预期输出：nginx version: nginx/1.2.0

# 测试配置文件
sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf -t
# 预期输出配置语法检查通过

# 启动Nginx（使用模块示例配置）
sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf

内存使用参考

模块各组件的最小内存占用：

• 共享内存中的消息：200字节/条
• 共享内存中的频道：270字节/个
• 订阅者：
  • 共享内存中：160字节/个
  • 系统内存中：6550字节/个

模块指令

以下是模块核心指令及其适用的配置上下文（(1)定义位置、(2)主要配置、(3)订阅者配置、(4)发布者配置、(5)频道统计配置、(6)WebSocket配置）：

测试信息

模块的服务器测试使用Ruby编写，采用验收测试框架，详细测试说明参见测试文档。

状态与支持

该模块已达到生产就绪状态，稳定用于各类实时推送场景。项目讨论可通过Nginx Push Stream Module讨论组进行。