SST 项目中 AppSync 连接错误的排查与解决指南

问题背景

在使用 SST (Serverless Stack Toolkit) 进行 Lambda 实时开发时，开发者可能会遇到 AppSync 连接失败的问题。具体表现为在运行 sst dev 命令启动开发环境时，控制台日志中出现 service=appsync.connection type=subscribe_error 的错误信息。

错误现象分析

从日志中可以观察到以下关键信息流：

1. 系统成功找到了 AppSync 的 REST 和实时 API 端点
2. 检查 AppSync 是否准备就绪
3. 开始建立 WebSocket 连接
4. 连接成功建立 (connection_ack)
5. 但随后出现订阅错误 (subscribe_error)

这种错误通常表明虽然基础连接已经建立，但在尝试订阅特定数据流时遇到了权限或配置问题。

可能的原因

1. IAM 权限不足：虽然开发者已经为 SST 用户添加了 AppSync 相关权限，但可能权限范围不够或配置不正确
2. 残留的旧配置：之前的部署可能留下了不兼容的资源配置
3. 端点配置问题：AppSync 的 GraphQL 端点可能存在问题
4. 实时订阅协议不匹配：客户端与服务器端的订阅协议版本不一致

解决方案

1. 清理并重建资源

最有效的解决方法是完全清理旧的 AWS 资源并重新部署：

# 删除旧的 SST 堆栈
npx sst remove

# 清理权限存储中的旧策略
# 通过 AWS 控制台删除相关 IAM 策略和角色

# 重新部署应用
npx sst deploy

2. 权限配置建议

虽然问题可能不是直接由权限引起，但确保正确的 IAM 配置是必要的：

• 对于开发环境，可以授予较宽的 AppSync 权限
• 生产环境应该遵循最小权限原则
• 确保 Lambda 执行角色也有适当的 AppSync 权限

3. 配置检查要点

在 sst.config.ts 中，确保：

• 区域设置与 AppSync API 创建的区域一致
• 移除不必要的 AppSync 权限声明（这些应该在 IAM 层面处理）
• 检查所有相关 Lambda 函数的权限配置

最佳实践

1. 开发流程：在遇到连接问题时，首先尝试完全清理旧部署
2. 权限管理：使用 SST 提供的标准权限模板，避免手动配置错误
3. 日志监控：密切关注 sst dev 启动时的完整日志输出
4. 版本控制：确保所有 SST 相关包版本一致

总结

AppSync 连接问题通常源于权限或资源配置的残留问题。通过完全清理旧资源并重新部署，大多数情况下可以解决这类连接错误。开发者应该建立规范的开发流程，避免配置残留，并合理管理 AWS 权限，以确保开发环境的稳定性。

对于持续出现的问题，建议检查 AWS CloudTrail 日志以获取更详细的错误信息，这有助于精准定位权限或配置问题的具体原因。