gRPC-Web报错「14 UNAVAILABLE: Failed to connect」：CORS与代理配置的跨域方案

gRPC-Web报错「14 UNAVAILABLE: Failed to connect」：CORS与代理配置的跨域方案

在gRPC-Web开发中，14 UNAVAILABLE: Failed to connect错误通常与跨域请求（CORS）或代理配置不当有关。本文结合CSDN社区的实战经验与开源项目案例，系统性解析CORS配置、代理服务器搭建及错误排查的完整解决方案。

---

一、错误根本原因与诊断方法

1. 触发场景与根本原因

原因分类	具体场景	监控指标
CORS未配置	浏览器直接请求gRPC-Web服务端，未设置Access-Control-Allow-Origin头	浏览器开发者工具Network面板显示CORS policy错误
代理配置错误	Envoy/Nginx未正确转发gRPC-Web请求，或未启用grpc_web过滤器	Envoy日志显示connection refused或404 Not Found
TLS证书问题	HTTPS环境下证书不匹配或过期	curl -v https://server.com/grpc 返回SSL handshake failed

2. 诊断工具与命令

• CORS验证：

  # 使用curl模拟浏览器预检请求（OPTIONS方法）
  curl -i -X OPTIONS https://example.com/grpc \
    -H "Origin: http://localhost:8080" \
    -H "Access-Control-Request-Method: POST" \
    -H "Access-Control-Request-Headers: content-type"
  

• 代理转发测试：

  # 直接测试Envoy代理是否转发成功
  curl -v http://localhost:8080/grpc \
    -H "Content-Type: application/grpc-web+proto" \
    -d '{"method":"Greeter.SayHello","params":{"name":"world"}}'
  

• 日志聚合分析：

  // 示例：记录Envoy代理的CORS错误日志
  {
       
    "timestamp": "2025-05-08T10:00:00Z",
    "error_code": 14,
    "error_message": "CORS header missing",
    "client_ip": "192.168.1.100",
    "request_method": "OPTIONS",
    "request_path": "/grpc"
  }
  

---

二、CORS配置方案

1. Envoy代理配置（推荐）

• 核心逻辑：
  • 启用grpc_web过滤器，允许OPTIONS预检请求。
  • 设置Access-Control-Allow-Origin头，支持浏览器跨域。
• 代码示例：

  # envoy.yaml 配置示例
  static_resources:
    listeners:
      - name: listener_0
        address:
          socket_address: {
        address: 0.0.0.0, port_value: 8080 }
        filter_chains: