如何让本地部署服务对Google Home可见？及SYNC触发失败排查

这种情况我碰到过好几次，大概率是自签名证书、网络可达性或者账号链路的细节配置没做对，咱们一步步来排查：

1. 自签名证书的核心问题 #

Google Assistant的Fulfillment调用是由Google的服务器发起的，而不是你的手机——Google的服务器默认完全不信任自签名证书，哪怕你的手机和本地服务在同一网络。这会直接导致SYNC请求根本无法到达你的服务，或者请求被中途拦截。

解决办法：

• 如果你只是本地测试，推荐用ngrok这类隧道工具把本地服务暴露到公网，使用ngrok提供的HTTPS地址（它的证书是受信任的）来配置Fulfillment
• 如果你坚持用自签名证书，必须确保：
  • 你的安卓手机已安装并信任该证书（设置→安全→加密与凭据→安装证书）
  • 但注意：这只能解决账号链接时手机浏览器访问授权服务器的问题，Google服务器调用Fulfillment仍然会失败，所以公网隧道是更靠谱的测试方案

2. Fulfillment配置检查 #

• 确认Action控制台里的Fulfillment URL是HTTPS协议，端口正确（比如自定义端口要加上，例如https://your-local-ip:8443/fulfillment）
• 务必勾选「Enable webhook for all domains」，或者至少确保SYNC意图的webhook已启用
• 测试本地服务的路由：用curl发送POST请求到你的Fulfillment URL，携带模拟的SYNC请求体，看是否能收到正确响应

3. 账号链路的OAuth2配置验证 #

账号链接失败或令牌无效也会导致SYNC不触发：

• 检查Action控制台里的authorization_endpoint和token_endpoint是否与你的授权服务器完全一致，且都是HTTPS
• 手动走一遍授权流程：在浏览器访问授权地址，确认能正常获取授权码、交换到访问令牌，且你的服务能正确验证该令牌
• 确保客户端ID、客户端密钥在Action控制台和你的授权服务器配置中完全匹配，大小写、特殊字符都不能错

4. 网络可达性验证 #

记住：Google服务器需要能访问到你的Fulfillment服务，不是只有你的手机能访问。

• 如果是纯本地网络，Google服务器根本无法穿透到你的内网，这时候必须用隧道工具（如ngrok）把服务暴露到公网
• 测试公网可达性：用手机开热点，用另一台设备连接热点后，访问你的Fulfillment URL（或ngrok地址），看是否能正常响应

5. SYNC响应格式合规性 #

哪怕服务收到了SYNC请求，响应格式不符合Google规范也会报错：

• 确保响应包含必填字段：requestId（要和请求里的一致）、payload.agentUserId、payload.devices数组（每个设备要有id、type、traits、name等）
• 可以用Action控制台的「Test」标签，模拟SYNC请求，直接查看服务的响应是否符合要求

6. 日志排查关键线索 #

• 打开本地服务的日志，确认是否收到了SYNC请求：如果没收到，问题在网络/证书；如果收到了，看响应是否有错误
• 查看Action控制台的「Activity」标签，里面会有详细的错误日志（比如证书验证失败、请求超时、响应格式错误等），这是定位问题最快的方式

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