Python gRPC服务向gRPC-Web客户端发送尾随元数据失败求助

我之前也遇到过一模一样的问题！折腾了好一阵才找到几个关键的排查点，你可以逐一验证：

1. 优先检查Envoy的CORS配置，确保自定义元数据头被暴露给客户端 #

浏览器的CORS政策会默认限制JavaScript访问非标准HTTP响应头，所以你必须在Envoy的CORS过滤器配置里，把自定义的尾随元数据键（checksum、retry）添加到expose_headers列表中。示例配置如下：

filters:
  - name: envoy.filters.http.cors
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
      allow_origin_string_match:
        - prefix: "*"
      allow_methods: GET, PUT, DELETE, POST, OPTIONS
      allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout
      expose_headers: grpc-status,grpc-message,grpc-status-details-bin,checksum,retry
      max_age: "1728000"

这一步是最容易被忽略的——哪怕Envoy已经正确转发了元数据，浏览器也会因为CORS限制不让客户端代码读取这些头。

2. 确认Envoy的gRPC-Web过滤器配置正确 #

要让gRPC的尾随元数据能被转换成gRPC-Web客户端识别的格式，必须确保Envoy配置中启用了gRPC-Web转换过滤器，且该过滤器放在router过滤器之前：

filters:
  - name: envoy.filters.http.grpc_web
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
  - name: envoy.filters.http.router
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

3. 验证客户端监听元数据的方式是否正确 #

不同版本的gRPC-Web库在元数据获取逻辑上可能有细微差异，你可以同时监听metadata和status事件，确保没有遗漏：

var call = greeterService.sayHello(request, {}, function(err, response) {
    if (err) {
        console.log(err.code);
        console.log(err.message);
    } else {
        console.log(response.getMessage());
    }
});

// 监听初始元数据（可选）
call.on('metadata', function(metadata) {
    console.log('Initial metadata:', metadata);
});

// 监听状态及尾随元数据
call.on('status', function(status) {
    console.log(status.code);
    console.log(status.details);
    console.log('Trailing metadata:', status.metadata);
});

另外，你可以打开浏览器开发者工具的Network面板，直接查看响应头里是否存在checksum和retry：如果能看到这些头，说明问题出在客户端代码或CORS配置；如果看不到，就是Envoy没有正确转发元数据。

4. 检查服务端元数据的键是否符合HTTP规范 #

虽然你的checksum和retry键看起来没问题，但要确保元数据键是有效的HTTP头名称（只能包含字母、数字、短横线，不能有下划线或特殊字符）。gRPC会自动转换格式，但手动确认能避免一些隐性问题。

我当初就是漏了CORS配置里的expose_headers，导致明明响应头里有元数据，客户端就是读不到！先从这个点排查应该能解决问题。

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