SST项目中MQTT连接问题的分析与解决

问题背景

在SST项目升级到v3.0.62版本后，部分开发者反馈使用Realtime示例配置的MQTT连接无法正常工作。当回退到v3.0.61版本时，问题消失。这表明新版本在MQTT连接处理上有所变更，导致原有连接方式失效。

问题根源分析

经过技术团队深入调查，发现问题源于v3.0.62版本中对PolicyDocument中principalId的生成逻辑变更：

1. 旧版本使用Date.now().toString()生成简单的数字时间戳作为principalId
2. 新版本改为使用evt.protocolData.mqtt?.username作为principalId

这种变更导致生成的principalId不符合AWS IoT Core的要求。AWS明确规定principalId必须是1-128个字母数字字符组成的字符串，不允许特殊字符。而新版本生成的principalId包含了连接参数和SDK信息，包含特殊字符如?、=和&，因此被AWS服务拒绝。

解决方案

技术团队提供了两种解决方案：

方案一：回退到v3.0.61版本

这是临时解决方案，但不推荐长期使用，因为会错过后续版本的安全更新和功能改进。

方案二：采用新的连接方式

根据更新后的官方文档建议，应使用以下方式建立MQTT连接：

return mqtt.connect(`wss://${endpoint}/mqtt?x-amz-customauthorizer-name=${authorizer}`, {
  protocolVersion: 5,
  manualConnect: true,
  username: "", // 对于authorizer必须为空
  password: "PLACEHOLDER_TOKEN", // 作为token传递给authorizer
  clientId: `client_${window.crypto.randomUUID()}`,
});

这种新方式会生成符合要求的principalId，确保连接成功。

技术细节说明

1. principalId要求：AWS IoT Core要求principalId必须是1-128个字母数字字符，正则表达式为([a-zA-Z0-9]){1,128}。

2. username字段：文档指出username必须为空，这是因为在使用自定义授权器时，授权信息通过URL参数传递，而不是传统的用户名/密码认证。

3. 密码字段：虽然标记为"PLACEHOLDER_TOKEN"，但实际上会作为token传递给authorizer进行认证。

最佳实践建议

1. 始终参考项目最新文档中的示例代码
2. 在升级版本前，先在测试环境验证MQTT连接
3. 监控连接日志，特别是认证相关的错误信息
4. 考虑实现连接重试机制，提高鲁棒性

总结

这次版本变更引发的MQTT连接问题，反映了AWS IoT服务对安全认证的严格要求。开发者应理解principalId的生成规则和格式要求，按照最新文档建议的方式建立连接。技术团队也会持续优化相关实现，确保向后兼容性，并在变更日志中明确标注可能影响现有功能的修改。

对于使用SST Realtime功能的开发者，建议尽快迁移到新的连接方式，以获得更好的安全性和稳定性保障。