This is an automated email from the ASF dual-hosted git repository.
xuetaoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 9c4a8960e76 docs(pixiu): add gRPC Server Reflection documentation
(#3179)
9c4a8960e76 is described below
commit 9c4a8960e76a5798d3d3fa8e5c983b945d5d452e
Author: Tsukikage <[email protected]>
AuthorDate: Tue Jan 6 17:13:59 2026 +0800
docs(pixiu): add gRPC Server Reflection documentation (#3179)
- Add comprehensive documentation for gRPC Server Reflection feature
- Cover three reflection modes: passthrough, reflection, hybrid
- Include configuration examples and multi-language setup guides
- Provide mode comparison and troubleshooting guide
Addresses review feedback from apache/dubbo-go-pixiu#849
---
.../other/user/networkfilter/grpc-reflection.md | 275 ++++++++++++++++++++
.../other/user/networkfilter/grpc-reflection.md | 276 +++++++++++++++++++++
2 files changed, 551 insertions(+)
diff --git
a/content/en/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
b/content/en/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
new file mode 100644
index 00000000000..fd090675b06
--- /dev/null
+++
b/content/en/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
@@ -0,0 +1,275 @@
+---
+aliases:
+ - /en/docs3-v2/dubbo-go-pixiu/user/networkfilter/grpc-reflection/
+description: gRPC Server Reflection Support in Pixiu
+linkTitle: gRPC Server Reflection
+title: gRPC Server Reflection Support
+type: docs
+weight: 21
+---
+
+# gRPC Server Reflection Support
+
+> [Implementation Reference](https://github.com/apache/dubbo-go-pixiu/pull/849)
+
+The gRPC Proxy filter (`dgp.filter.grpc.proxy`) now supports **gRPC Server
Reflection**, enabling dynamic message parsing and inspection at the gateway
level without requiring pre-compiled proto files.
+
+## Overview
+
+gRPC Server Reflection is a feature that allows Pixiu gateway to dynamically
discover and decode gRPC service definitions at runtime. This eliminates the
need to maintain proto files in the gateway configuration.
+
+### Key Features
+
+- **Three Reflection Modes**: Passthrough, Reflection, and Hybrid
+- **Dynamic Message Decoding**: Parse messages at runtime without proto files
+- **TTL-based Caching**: Efficient descriptor caching with automatic cleanup
+- **Protocol Detection**: Support for both gRPC and Triple protocols
+- **Graceful Fallback**: Hybrid mode provides automatic passthrough fallback
+
+## Reflection Modes
+
+### Passthrough Mode (Default)
+
+Performs transparent binary proxying without decoding messages.
+
+**Use Cases:**
+- High-performance scenarios where message inspection is not needed
+- Simple routing based on service/method names only
+
+**Configuration:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "passthrough" # or omit (default)
+```
+
+### Reflection Mode
+
+Uses gRPC Server Reflection API to dynamically decode and inspect message
contents.
+
+**Use Cases:**
+- Content-aware routing (route based on message fields)
+- Field-level filtering or transformation
+- Logging and debugging with full message inspection
+
+**Configuration:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "reflection"
+ descriptor_cache_ttl: 300 # 5 minutes cache
+```
+
+### Hybrid Mode
+
+Tries reflection first, falls back to passthrough on failure.
+
+**Use Cases:**
+- Mixed environments with varying reflection support
+- Migration scenarios (gradually enabling reflection)
+- Production environments requiring high availability
+
+**Configuration:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "hybrid"
+ reflection_timeout: 5s
+```
+
+## Complete Configuration Example
+
+```yaml
+static_resources:
+ listeners:
+ - name: "grpc-gateway"
+ protocol_type: "GRPC"
+ address:
+ socket_address:
+ address: "0.0.0.0"
+ port: 8882
+ filter_chains:
+ filters:
+ - name: dgp.filter.network.grpcconnectionmanager
+ config:
+ route_config:
+ routes:
+ - match:
+ prefix: "/echo.EchoService/"
+ route:
+ cluster: "echo-grpc"
+ grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ # Reflection mode (default: "passthrough")
+ reflection_mode: "reflection"
+
+ # Cache TTL for method descriptors (seconds)
+ descriptor_cache_ttl: 300
+
+ # Enable Triple protocol detection
+ enable_protocol_detection: true
+
+ # Reflection timeout for hybrid mode
+ reflection_timeout: 5s
+
+ clusters:
+ - name: "echo-grpc"
+ lb_policy: "RoundRobin"
+ endpoints:
+ - socket_address:
+ address: 127.0.0.1
+ port: 50051
+ protocol_type: "GRPC"
+```
+
+## Configuration Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `reflection_mode` | string | `"passthrough"` | Reflection mode:
`"passthrough"`, `"reflection"`, or `"hybrid"` |
+| `descriptor_cache_ttl` | int | `300` | Cache TTL for method descriptors in
seconds |
+| `enable_protocol_detection` | bool | `false` | Enable Triple protocol
detection |
+| `reflection_timeout` | string | `"5s"` | Max time to wait for reflection in
hybrid mode |
+| `enable_tls` | bool | `false` | Enable TLS for backend connections |
+| `tls_cert_file` | string | `""` | Path to TLS certificate file |
+| `tls_key_file` | string | `""` | Path to TLS key file |
+| `keepalive_time` | string | `"300s"` | Keepalive time for backend
connections |
+| `keepalive_timeout` | string | `"5s"` | Keepalive timeout |
+| `connect_timeout` | string | `"5s"` | Connection timeout |
+| `max_concurrent_streams` | uint32 | `0` (unlimited) | Max concurrent streams
|
+
+## Enabling Server Reflection
+
+To use `reflection` or `hybrid` modes, your backend gRPC server must have
Server Reflection enabled.
+
+### Go (gRPC-Go)
+
+```go
+import (
+ "google.golang.org/grpc"
+ "google.golang.org/grpc/reflection"
+)
+
+func main() {
+ server := grpc.NewServer()
+
+ // Register your service
+ echo.RegisterEchoServiceServer(server, &echoServer{})
+
+ // Enable server reflection
+ reflection.Register(server)
+
+ // Start server
+ lis, _ := net.Listen("tcp", ":50051")
+ server.Serve(lis)
+}
+```
+
+### Java (gRPC-Java)
+
+```java
+import io.grpc.Server;
+import io.grpc.ServerBuilder;
+import io.grpc.reflection.v1alpha.ServerReflectionGrpc;
+
+public class EchoServer {
+ public static void main(String[] args) throws Exception {
+ Server server = ServerBuilder
+ .forPort(50051)
+ .addService(new EchoServiceImpl())
+ // Enable server reflection
+ .addService(ServerReflectionGrpc.newInstance())
+ .build()
+ .start();
+
+ server.awaitTermination();
+ }
+}
+```
+
+### Python (gRPC-Python)
+
+```python
+import grpc
+from grpc_reflection.v1alpha import reflection
+from concurrent import futures
+
+class EchoService(echo_pb2_grpc.EchoServiceServicer):
+ # ... implementation ...
+
+def serve():
+ server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
+ echo_pb2_grpc.add_EchoServiceServicer_to_server(EchoService(), server)
+
+ # Enable server reflection
+ reflection.enable_server_reflection(
+
service_names=[echo.DESCRIPTOR.services_by_name['EchoService'].full_name,
+ reflection.SERVICE_NAME],
+ server=server
+ )
+
+ server.add_insecure_port('[::]:50051')
+ server.start()
+ server.wait_for_termination()
+```
+
+## Mode Comparison
+
+| Feature | Passthrough | Reflection | Hybrid |
+|---------|-------------|------------|--------|
+| **Performance** | Best | Good | Better |
+| **Message Inspection** | No | Yes | Yes (when available) |
+| **Requires Reflection** | No | Yes | Optional |
+| **Fallback** | N/A | No | Yes |
+
+## Descriptor Cache
+
+The reflection mode uses a TTL-based cache to store method descriptors
retrieved from the backend server.
+
+**Recommended TTL Values:**
+- Development: `60` (1 minute)
+- Testing: `300` (5 minutes)
+- Production: `1800` (30 minutes)
+
+## Triple Protocol Detection
+
+Pixiu supports the **Dubbo Triple protocol**, a gRPC-compatible protocol
developed by the Apache Dubbo community.
+
+**Enable protocol detection:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ enable_protocol_detection: true
+```
+
+## Troubleshooting
+
+### Problem: Reflection mode returns "service not found"
+
+**Cause**: Backend server does not have Server Reflection enabled.
+
+**Solution**: Enable reflection on your server:
+```go
+reflection.Register(grpcServer)
+```
+
+### Problem: Hybrid mode falls back to passthrough
+
+**Cause**: Reflection timeout exceeded or reflection service unavailable.
+
+**Solution**:
+1. Check if reflection is enabled on the backend
+2. Increase `reflection_timeout` value
+3. Check network connectivity
+
+## Related Resources
+
+- [Issue #821](https://github.com/apache/dubbo-go-pixiu/issues/821) - Original
feature request
+- [PR #849](https://github.com/apache/dubbo-go-pixiu/pull/849) -
Implementation details
+- [Sample
Code](https://github.com/apache/dubbo-go-pixiu-samples/tree/master/grpc/reflection)
- Complete working examples
+- [gRPC Server Reflection
Protocol](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) -
Official specification
diff --git
a/content/zh-cn/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
b/content/zh-cn/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
new file mode 100644
index 00000000000..ca053ef20d8
--- /dev/null
+++
b/content/zh-cn/overview/reference/pixiu/other/user/networkfilter/grpc-reflection.md
@@ -0,0 +1,276 @@
+---
+aliases:
+ - /zh/docs3-v2/dubbo-go-pixiu/user/networkfilter/grpc-reflection/
+ - /zh-cn/docs3-v2/dubbo-go-pixiu/user/networkfilter/grpc-reflection/
+description: Pixiu 中的 gRPC Server Reflection 支持
+linkTitle: gRPC Server Reflection
+title: gRPC Server Reflection 支持
+type: docs
+weight: 21
+---
+
+# gRPC Server Reflection 支持
+
+> [实现参考](https://github.com/apache/dubbo-go-pixiu/pull/849)
+
+gRPC Proxy 过滤器（`dgp.filter.grpc.proxy`）现已支持 **gRPC Server
Reflection**，使得网关能够在不需要预编译 proto 文件的情况下动态解析和检查消息内容。
+
+## 概述
+
+gRPC Server Reflection 是一项允许 Pixiu 网关在运行时动态发现和解码 gRPC 服务定义的功能。这消除了在网关配置中维护
proto 文件的需要。
+
+### 核心特性
+
+- **三种反射模式**: 透传、反射和混合模式
+- **动态消息解码**: 在运行时解析消息，无需 proto 文件
+- **基于 TTL 的缓存**: 高效的描述符缓存，自动清理过期条目
+- **协议检测**: 同时支持 gRPC 和 Triple 协议
+- **优雅降级**: 混合模式提供自动回退到透传模式
+
+## 反射模式
+
+### 透传模式（Passthrough，默认）
+
+执行透明的二进制代理，不解码消息。
+
+**使用场景:**
+- 不需要消息检查的高吞吐场景
+- 仅基于服务/方法名称的简单路由
+
+**配置:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "passthrough" # 或省略（默认值）
+```
+
+### 反射模式（Reflection）
+
+使用 gRPC Server Reflection API 动态解码和检查消息内容。
+
+**使用场景:**
+- 基于内容的路由（根据消息字段路由）
+- 字段级别的过滤或转换
+- 完整消息检查的日志记录和调试
+
+**配置:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "reflection"
+ descriptor_cache_ttl: 300 # 5分钟缓存
+```
+
+### 混合模式（Hybrid）
+
+先尝试反射，失败时回退到透传模式。
+
+**使用场景:**
+- 反射支持程度不一的混合环境
+- 迁移场景（逐步启用反射）
+- 需要高可用的生产环境
+
+**配置:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ reflection_mode: "hybrid"
+ reflection_timeout: 5s
+```
+
+## 完整配置示例
+
+```yaml
+static_resources:
+ listeners:
+ - name: "grpc-gateway"
+ protocol_type: "GRPC"
+ address:
+ socket_address:
+ address: "0.0.0.0"
+ port: 8882
+ filter_chains:
+ filters:
+ - name: dgp.filter.network.grpcconnectionmanager
+ config:
+ route_config:
+ routes:
+ - match:
+ prefix: "/echo.EchoService/"
+ route:
+ cluster: "echo-grpc"
+ grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ # 反射模式（默认: "passthrough"）
+ reflection_mode: "reflection"
+
+ # 方法描述符缓存 TTL（秒）
+ descriptor_cache_ttl: 300
+
+ # 启用 Triple 协议检测
+ enable_protocol_detection: true
+
+ # 混合模式的反射超时
+ reflection_timeout: 5s
+
+ clusters:
+ - name: "echo-grpc"
+ lb_policy: "RoundRobin"
+ endpoints:
+ - socket_address:
+ address: 127.0.0.1
+ port: 50051
+ protocol_type: "GRPC"
+```
+
+## 配置字段
+
+| 字段 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `reflection_mode` | string | `"passthrough"` | 反射模式:
`"passthrough"`、`"reflection"` 或 `"hybrid"` |
+| `descriptor_cache_ttl` | int | `300` | 方法描述符缓存 TTL（秒） |
+| `enable_protocol_detection` | bool | `false` | 启用 Triple 协议检测 |
+| `reflection_timeout` | string | `"5s"` | 混合模式下等待反射的最大时间 |
+| `enable_tls` | bool | `false` | 启用后端连接的 TLS |
+| `tls_cert_file` | string | `""` | TLS 证书文件路径 |
+| `tls_key_file` | string | `""` | TLS 密钥文件路径 |
+| `keepalive_time` | string | `"300s"` | 后端连接的保活时间 |
+| `keepalive_timeout` | string | `"5s"` | 保活超时时间 |
+| `connect_timeout` | string | `"5s"` | 连接超时时间 |
+| `max_concurrent_streams` | uint32 | `0`（无限制） | 最大并发流数 |
+
+## 启用服务器反射
+
+要使用 `reflection` 或 `hybrid` 模式，你的后端 gRPC 服务器必须启用 Server Reflection。
+
+### Go (gRPC-Go)
+
+```go
+import (
+ "google.golang.org/grpc"
+ "google.golang.org/grpc/reflection"
+)
+
+func main() {
+ server := grpc.NewServer()
+
+ // 注册你的服务
+ echo.RegisterEchoServiceServer(server, &echoServer{})
+
+ // 启用服务器反射
+ reflection.Register(server)
+
+ // 启动服务器
+ lis, _ := net.Listen("tcp", ":50051")
+ server.Serve(lis)
+}
+```
+
+### Java (gRPC-Java)
+
+```java
+import io.grpc.Server;
+import io.grpc.ServerBuilder;
+import io.grpc.reflection.v1alpha.ServerReflectionGrpc;
+
+public class EchoServer {
+ public static void main(String[] args) throws Exception {
+ Server server = ServerBuilder
+ .forPort(50051)
+ .addService(new EchoServiceImpl())
+ // 启用服务器反射
+ .addService(ServerReflectionGrpc.newInstance())
+ .build()
+ .start();
+
+ server.awaitTermination();
+ }
+}
+```
+
+### Python (gRPC-Python)
+
+```python
+import grpc
+from grpc_reflection.v1alpha import reflection
+from concurrent import futures
+
+class EchoService(echo_pb2_grpc.EchoServiceServicer):
+ # ... 实现 ...
+
+def serve():
+ server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
+ echo_pb2_grpc.add_EchoServiceServicer_to_server(EchoService(), server)
+
+ # 启用服务器反射
+ reflection.enable_server_reflection(
+
service_names=[echo.DESCRIPTOR.services_by_name['EchoService'].full_name,
+ reflection.SERVICE_NAME],
+ server=server
+ )
+
+ server.add_insecure_port('[::]:50051')
+ server.start()
+ server.wait_for_termination()
+```
+
+## 模式对比
+
+| 特性 | 透传模式 | 反射模式 | 混合模式 |
+|------|---------|---------|---------|
+| **性能** | 最佳 | 良好 | 更好 |
+| **消息检查** | 否 | 是 | 是（可用时） |
+| **需要反射** | 否 | 是 | 可选 |
+| **回退支持** | N/A | 否 | 是 |
+
+## 描述符缓存
+
+反射模式使用基于 TTL 的缓存来存储从后端服务器获取的方法描述符。
+
+**推荐的 TTL 值:**
+- 开发环境: `60`（1分钟）
+- 测试环境: `300`（5分钟）
+- 生产环境: `1800`（30分钟）
+
+## Triple 协议检测
+
+Pixiu 支持 **Dubbo Triple 协议**，这是 Apache Dubbo 社区开发的 gRPC 兼容协议。
+
+**启用协议检测:**
+```yaml
+grpc_filters:
+ - name: dgp.filter.grpc.proxy
+ config:
+ enable_protocol_detection: true
+```
+
+## 故障排除
+
+### 问题: 反射模式返回 "service not found"
+
+**原因**: 后端服务器未启用 Server Reflection。
+
+**解决方案**: 在服务器上启用反射：
+```go
+reflection.Register(grpcServer)
+```
+
+### 问题: 混合模式回退到透传模式
+
+**原因**: 反射超时或反射服务不可用。
+
+**解决方案**:
+1. 检查后端是否启用了反射
+2. 增加 `reflection_timeout` 值
+3. 检查网络连接
+
+## 相关资源
+
+- [Issue #821](https://github.com/apache/dubbo-go-pixiu/issues/821) - 原始功能请求
+- [PR #849](https://github.com/apache/dubbo-go-pixiu/pull/849) - 实现详情
+-
[示例代码](https://github.com/apache/dubbo-go-pixiu-samples/tree/master/grpc/reflection)
- 完整的示例代码
+- [gRPC Server Reflection
Protocol](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) -
官方规范
