emitter/server

Emitter：分布式发布订阅平台

!Emitter Logo

 ![关注]([]

镜像概述和主要用途

Emitter是一个分布式、可扩展且容错的发布订阅平台，基于MQTT协议构建，具备消息存储、安全控制、监控等功能。它旨在提供低延迟、高吞吐量的实时通信能力，支持集群部署，适用于多种实时数据传输场景。

核心功能和特性

• 发布/订阅：通过TCP或Websockets基于MQTT协议实现消息发布与订阅。
• 高可用与分区容错：遵循CAP定理中的AP特性，具备弹性和高可用性。
• 高吞吐量：单节点可处理300万+消息/秒。
• 消息存储与过期：支持消息历史存储及消息级别的过期机制。
• 安全通道密钥：提供带权限的安全通道密钥，可直接暴露在互联网环境中使用。
• 自动TLS/SSL：支持自动TLS/SSL配置及加密的节点间通信。
• 内置监控：集成Prometheus、StatsD等监控工具。
• 共享订阅与链接：支持共享订阅、链接及私有通道链接。
• 易于部署：支持Docker和Kubernetes部署，可快速构建生产级集群。

使用场景和适用范围

Emitter适用于以下场景：

• 在线游戏和移动应用：满足低延迟、二进制消息传输和高吞吐量需求。
• 实时Web应用：如数据仪表板、可视化分析系统、在线聊天系统等。
• 物联网（IoT）：支持传感器控制、数据采集与分析，实现设备间实时通信。

教程与演示

以下视频教程演示了Emitter的各种功能：

![FOSDEM 2018]([] ![FOSDEM 2019]([] ![Go中的发布订阅]([] ![消息存储]([] ![使用MQTTSpy]([] ![ISS跟踪]([] ![自签名TLS]([] ![使用eTop监控]([] ![StatsD和DataDog]([] ![链接与私有链接]([] ![使用Go构建发布订阅客户端-服务器应用]([] ![基于发布订阅和Go的分布式Actor模型]([] ![基于Emitter的在线多人平台游戏]([] ![使用MQTT Retain保留每个通道的最后一条消息]([] ![使用订阅组负载均衡消息]([***]

部署方法

![本地Emitter集群]([] ![K8s与DigitalOcean]([] ![K8s与Google Cloud]([] ![K8s与Azure]([]

详细使用方法和配置说明

快速开始

运行服务器

通过以下docker run命令快速启动Emitter代理：

注意：必须使用-e指定Docker环境变量，许可证信息可在Docker日志中获取。

shell
docker run -d --name emitter -p 8080:8080 --restart=unless-stopped emitter/server

或者，也可通过源码编译运行：

shell
go get -u github.com/emitter-io/emitter && emitter

获取许可证

若未提供配置或环境变量，服务器启动后会在日志中输出类似以下消息（包含生成的许可证和密钥）：

shell
[service] unable to find a license, make sure 'license' value is set in the config file or EMITTER_LICENSE environment variable
[service] generated new license: uppD0PFIcNK6VY-7PTo7uWH8EobaOGgRAAAAAAAAAAI
[service] generated new secret key: JUoOxjoXLc4muSxXynOpTc60nWtwUI3o

记录生成的许可证，用于后续重新运行服务器。

重新运行命令

使用获取的许可证重新启动服务器（替换<license>为实际许可证值）：

shell
docker run -d --name emitter -p 8080:8080 -e EMITTER_LICENSE=<license> --restart=unless-stopped emitter/server

生成密钥

打开浏览器访问**<[*]> 生成通道密钥。使用生成的密钥可创建带权限的通道密钥，开始使用Emitter。

警告：默认生成的密钥（如示例中的JUoOxjoXLc4muSxXynOpTc60nWtwUI3o）安全性较低，生产环境中需更换为自定义密钥。

使用示例

以下是使用JavaScript SDK的示例代码，API提供publish和subscribe等简洁方法，支持二进制消息 payload，并通过通道密钥确保安全：

javascript
// 连接到Emitter服务
var connection = emitter.connect({ host: '127.0.0.1' });

// 连接成功后，订阅'chat'通道
emitter.on('connect', function(){
    emitter.subscribe({
        key: "<channel key>",  // 替换为实际通道密钥
        channel: "chat"
    });
});

// 向chat通道发布消息
emitter.publish({
    key: "<channel key>",  // 替换为实际通道密钥
    channel: "chat/my_name",
    message: "hello, emitter!"
});

更多文档、演示和语言/平台SDK可在官方网站开发部分查看，建议参考快速入门教程了解Emitter和MQTT的基本使用方法。

命令行参数

Emitter代理支持以下命令行参数：

shell
-config string
   指定代理使用的配置文件路径。（默认值："emitter.conf"）

-help
   显示帮助信息而非启动代理。

配置文件

配置文件（默认emitter.conf）是配置代理的主要方式，支持通过环境变量和/或Hashicorp Vault进行多级别覆盖。配置文件为JSON格式，示例如下：

json
{
    "listen": ":8080",
    "license": "/*许可证*/",
    "tls": {
        "listen": ":443",
        "host": "example.com"
    },
    "cluster": {
        "listen": ":4000",
        "seed": "192.168.0.2:4000",
        "advertise": "public:4000"
    },
    "storage": {
        "provider": "inmemory"
    }
}

配置项说明如下表：

Docker容器部署

Emitter提供Docker容器化部署方式：

单服务器模式

启动单节点Emitter服务：

shell
docker run -d -p 8080:8080 emitter/server

服务器启动后会生成新的安全配置，可通过添加-e EMITTER_LICENSE=<许可证值>重新运行以使用指定许可证。

集群（多服务器）模式

启动集群模式容器需指定3个主要参数：

shell
docker run -d -p 8080:8080 -p 4000:4000 -e EMITTER_LICENSE=[密钥] -e EMITTER_CLUSTER_SEED=[种子地址] -e EMITTER_CLUSTER_PASSPHRASE=[密码] emitter/server

支持、讨论与社区

如需Emitter服务器或客户端SDK帮助，可通过以下方式联系：

• Gitter聊天：开发团队主要交流平台。
• 电子邮件：<***>。

Emitter的bug、问题和功能请求请提交至emitter-io/emitter仓库。安全问题请发送邮件至***，而非在Github提交公开issue。

贡献

欢迎贡献代码！请fork仓库并使用功能分支开发，Pull Request将被优先处理。

许可

版权所有 (c) 2009-2019 Misakai Ltd. 本项目基于https://github.com/emitter-io/emitter/blob/master/LICENSE%E8%AE%B8%E5%8F%AF%E3%80%82

Emitter提供支持合同，同时也提供商业许可。详情请联系***。