如何为AWS Websocket API Gateway添加自定义wss域名

一、自定义域名配置完整操作流程 #

整个流程没有复杂的特殊配置，和普通REST API的自定义域名逻辑基本一致，步骤如下：

• 先验证基础连通性：在配置域名前，用默认的wss端点测试连接、路由转发、业务集成全流程正常，避免配完域名才发现API本身存在配置问题
• 进入API Gateway控制台的「自定义域名」模块，选择创建新的自定义域名
  • 根据业务场景选域名类型：面向全球用户选边缘优化类型，同区域低延迟场景选区域型类型
  • 关联提前申请好的ACM公网TLS证书，注意证书区域匹配规则：边缘优化类型必须关联us-east-1区域的证书，区域型类型关联同API所在区域的证书即可
  • 安全策略选TLS 1.2及以上版本，避免兼容性风险
• 完成域名创建后，配置「基础路径映射」：把刚创建的自定义域名，和你的WebSocket API、对应的dev部署阶段做关联；如果留空基础路径，就可以通过域名根路径直接接入，不需要额外加路径前缀
• 等自定义域名控制台状态变为「可用」后，获取AWS分配的目标端点，做域名解析指向即可

二、能否通过Route53直接使用https://*****.com形式的域名实现接入？ #

没法按这个形式直接配置，核心是混淆了「域名本身」和「带协议头的完整URL」的概念

• Route53作为DNS解析服务，记录的域名值是不带任何协议前缀的纯域名结构（比如xxx.com、api.example.com），根本不支持把https://*****.com这种带协议头的整串当域名写进解析记录
• 大家平时访问网页时习惯输入https://xxx.com，本质是浏览器自动把域名部分提取出来做DNS解析，https://只是客户端约定的协议标识，和域名本身的解析逻辑完全无关
• 只要把纯域名部分（比如xxxx.com）配置成API Gateway的自定义域名、做好解析，客户端完全可以在WebSocket连接地址里用对应的wss协议头访问，不需要在域名层面做特殊适配

三、如何创建适配的自定义wss域名 #

首先明确：没有强制要求自定义域名必须带wss.之类的前缀，只要是你有权限解析的纯域名，都可以拿来当WebSocket的接入域名，操作路径如下：

• 选好域名主体：可以是裸域xxxx.com，也可以是任意自定义子域（比如ws.xxxx.com、realtime.xxxx.com），没有强制的命名规则
• 在ACM为选中的域名申请覆盖范围匹配的免费公网TLS证书，严格按照之前提到的区域要求选择证书申请的区域
• 回到API Gateway的自定义域名创建页，填入选好的纯域名，关联对应ACM证书，按需选择边缘优化/区域型的域名类型
• 配置基础路径映射，把自定义域名和你的WebSocket API的dev部署阶段做绑定
• 等自定义域名状态变为可用后，在Route53里为这个域名创建别名A记录，直接指向API Gateway自动分配的目标端点（不要用普通CNAME，别名记录延迟更低、也不会出现证书校验异常的问题）
• 配置完成后，客户端的连接地址格式就是wss://你配置的纯域名，和默认端点的使用逻辑完全一致

小提示：不需要刻意给WebSocket接入配一个带wss前缀的域名，同一个域名只要配好了对应的路径映射，完全可以同时承载HTTPS网页访问和wss连接，不会产生冲突。

四、需要额外完成的配套配置 #

这些是多数人配置完域名后容易踩坑的点，必须提前排查：

• CORS规则校验：如果你的WebSocket是给前端网页调用的，要在$connect路由的响应里配置允许的跨域来源头，不然浏览器会拦截跨域的WebSocket握手请求，哪怕域名解析正常也连不上
• 鉴权逻辑对齐：自定义域名不会改变API本身的鉴权规则，如果你之前在默认端点上开了API Key、Lambda Authorizer、IAM鉴权，要确认客户端发起连接时，把对应的鉴权参数（比如query string传递的apikey、请求头携带的Authorization信息）正确带上，不要因为换了接入域名就搞错鉴权参数的传递规则
• 部署版本同步：每次修改WebSocket API的路由、集成配置后，一定要手动重新部署到对应的dev阶段，自定义域名的映射只会拉取已部署的阶段版本，不会自动同步未部署的代码变更
• 连通性校验：如果你的WebSocket集成了VPC内的资源，要确认API Gateway的执行角色有对应VPC资源的访问权限，同时源侧的安全组要放通API Gateway的访问流量，不要因为换了接入域名就遗漏了之前配置的VPC Endpoint、安全组规则
• 证书有效期监控：ACM的免费证书是自动续期的，要提前确认Route53的NS记录没有变更，保证续期流程能正常通过DNS校验，避免证书过期导致连接失败

内容的提问来源于stack exchange，提问作者Vinit Khandelwal