MQTTnet 项目中 MqttServer.StartAsync 无法启动监听端口的解决方案

在 ASP.NET Core 6 API 项目中使用 MQTTnet 4.3.3.952 版本时，开发者可能会遇到一个常见问题：调用 MqttServer.StartAsync() 方法后，虽然程序没有抛出异常且日志显示启动成功，但实际上服务器并未真正监听指定的端口。这种情况通常发生在 IHostedService 接口实现中。

问题现象

当开发者尝试在 IHostedService 中启动 MQTT 服务器时，使用如下代码：

var optionsBuilder = new MqttServerOptionsBuilder()
    .WithConnectionBacklog(100)
    .WithDefaultEndpointPort(87941);

var mMqtt = new MqttFactory(new MyLogger())
    .CreateMqttServer(optionsBuilder.Build());

await mMqtt.StartAsync();

尽管代码执行没有报错，但通过 netstat 或其他端口检测工具检查时，会发现指定的端口（如示例中的 87941）并未被监听。

根本原因

问题的根源在于 MQTT 服务器选项配置不完整。在 MQTTnet 中，仅指定端口号是不够的，还需要明确设置默认终结点（Default Endpoint）及其绑定的 IP 地址。

解决方案

正确的配置方式应该包含以下关键元素：

1. 显式调用 WithDefaultEndpoint() 方法
2. 指定绑定的 IP 地址（通常使用 0.0.0.0 表示监听所有网络接口）

修正后的代码如下：

var optionsBuilder = new MqttServerOptionsBuilder()
    .WithDefaultEndpoint()
    .WithDefaultEndpointBoundIPAddress(IPAddress.Parse("0.0.0.0"))
    .WithDefaultEndpointPort(87941)
    .WithConnectionBacklog(100);

最佳实践

在 ASP.NET Core 中实现 MQTT 服务器时，推荐使用 BackgroundService 作为基类，这能更好地与 ASP.NET Core 的生命周期集成。以下是完整的实现示例：

public sealed class MqttBrokerService : BackgroundService
{
    public MqttServer MqttServer { get; }
    
    public MqttBrokerService()
    {
        var mqttFactory = new MqttFactory();
        var mqttServerOptions = mqttFactory
            .CreateServerOptionsBuilder()
            .WithDefaultEndpoint()
            .WithDefaultEndpointBoundIPAddress(IPAddress.Parse("0.0.0.0"))
            .WithDefaultEndpointPort(1883)
            .Build();
            
        this.MqttServer = mqttFactory.CreateMqttServer(mqttServerOptions);
    }

    public override async Task StartAsync(CancellationToken cancellationToken)
    {
        await this.MqttServer.StartAsync();
        await base.StartAsync(cancellationToken);
    }

    public override async Task StopAsync(CancellationToken cancellationToken)
    {
        await this.MqttServer.StopAsync();
        await base.StopAsync(cancellationToken);
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

注意事项

1. IP 地址选择：

   • 使用 0.0.0.0 允许来自任何网络接口的连接
   • 使用 127.0.0.1 则只允许本地连接

2. 端口选择：

   • 1883 是 MQTT 标准端口
   • 开发环境中可以使用其他端口，但生产环境建议使用标准端口或配置防火墙规则

3. 服务注册： 在 Startup.cs 或 Program.cs 中正确注册服务：

   builder.Services.AddSingleton<MqttBrokerService>();
   builder.Services.AddHostedService(p => p.GetRequiredService<MqttBrokerService>());
   

通过以上配置，MQTT 服务器将能够正确启动并监听指定端口，为客户端提供稳定的连接服务。