cs-note/hhs/gRPC/3. 服务端实现/10-健康检查与反射.md

---
tags: [gRPC, Go, Health Check, Debug, Reflection]
create time: 2026-05-11 16:00
---

# 健康检查与反射

## 概述

生产级 gRPC 服务需要具备两大能力：**可观测性**（知道服务是否存活）和 **可调试性**（了解服务暴露了哪些 API）。gRPC 生态提供了两个独立的内置模块来解决这些问题：

- **Health Check v1 API** — 标准协议层健康探针，供 K8s / LB / 运维工具查询服务状态
- **Server Reflection** — 开发阶段的内省机制，允许客户端动态枚举所有 service、method 和 message 定义

这两个功能完全独立、可分别启用。核心原则是：**生产环境必须开 Health Check、关闭 Reflection**。

> [!question] 为什么不用 HTTP health endpoint？
> 你可以同时暴露 HTTP 和 gRPC health，但用 gRPC 统一的好处是：不需要维护两套协议、负载均衡器可以直接用 gRPC probe、而且 gRPC Health Check 支持 Watch 模式实现实时监控。如果你只有 gRPC 服务而没有 HTTP sidecar，那 gRPC health 就是唯一选择。

## Health Check Protocol Buffer

gRPC 官方定义了标准 Health Check proto，位于 grpc-go 源码树中（Go 包路径 `google.golang.org/grpc/health/grpc_health_v1`），无需单独下载 .proto 文件：

> [!tip] 其他语言如何引用？
> Health Check proto 也开源在 [`grpc/grpc-proto`](https://github.com/grpc/grpc-proto/tree/master/grpc/health/v1) 仓库。protobuf / Java / Python 等语言的客户端可以直接克隆该仓库并使用 `protoc` 编译，或通过 maven / pip 等包管理器引入对应 stub。

```protobuf
syntax = "proto3";
package grpc.health.v1;

message HealthCheckRequest {
  string service = 1;
}

message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
    SERVICE_UNKNOWN = 3;
    UNAVAILABLE = 4;
  }
  ServingStatus status = 1;
}

service Health {
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}
```

> [!tip] ServingStatus 的含义
> - **SERVING**: 服务正常对外提供 RPC
> - **NOT_SERVING**: 服务拒绝新请求（正在关机、依赖断裂等）
> - **SERVICE_UNKNOWN**: 查询的 service name 未注册
> - **UNAVAILABLE**: 内部错误导致无法判断状态

两个端点的区别：

| 端点 | 类型 | 用途 |
|------|------|------|
| `Check` | Unary RPC | 瞬时查询，适合 liveness/readiness probe |
| `Watch` | Server Streaming | 持续监听状态变化，适合 dashboard / alerting |

## 在 Go 中实现 Health Service

```go
import (
    "google.golang.org/grpc/health"
    "google.golang.org/grpc/health/grpc_health_v1"
)

func main() {
    s := grpc.NewServer()

    // 创建 health server 实例
    healthServer := health.NewServer()

    // 按 service name 注册健康状态
    healthServer.SetServingStatus("user.v1.UserService", grpc_health_v1.HealthCheckResponse_SERVING)
    healthServer.SetServingStatus("order.v1.OrderService", grpc_health_v1.HealthCheckResponse_SERVING)

    // root service "" 表示整个进程级别的健康状态
    healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)

    // 挂载到 gRPC server —— 这一步自动启用了 Check 和 Watch
    grpc_health_v1.RegisterHealthServer(s, healthServer)
}
```

> [!note] 关于 `RegisterHealthServer`
> 调用此方法后，Check 和 Watch 两个 RPC 都会自动注册到你的 server 上。**不需要手动编写任何 Watch handler** —— `health.NewServer()` 内部使用 watcher map + channel 实现了完整的 Watch 逻辑。你只需要调用 `SetServingStatus(key, status)` 来更新状态即可。

关键细节：

- `""` （空字符串）表示整个进程级别的健康状态，是 K8s 最常用的探测目标
- `"user.v1.UserService"` 这种带 package 的路径可以精确到某个具体 service
- `SetServingStatus` 可随时调用，不需要重启 server

> [!warning] 常见误区：不要手写 Watch handler
> 有些教程展示了手写的 Watch stream loop，但那是不必要的——官方库已实现完毕。除非你有极其特殊的需求（比如自定义状态变更事件源），否则直接用 `health.NewServer()` 提供的默认行为即可。

## Health Check 使用场景

### Kubernetes Probe

```yaml
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: my-service
    readinessProbe:
      grpc:
        port: 50051
        service: ""       # 对应 SetServingStatus("", SERVING)
      initialDelaySeconds: 5
      periodSeconds: 10
    livenessProbe:
      grpc:
        port: 50051
        service: ""
      failureThreshold: 3
```

Kubernetes 原生支持 gRPC probe，直接调用 `grpc_health_v1.Health.Check` 即可，无需额外的 HTTP endpoint。

> [!tip] Readiness vs Liveness
> - **Readiness probe**: 决定是否将流量接入 Pod。建议设置合理的 `initialDelaySeconds`，避免启动期间被误杀。
> - **Liveness probe**: 决定是否需要重启 Pod。不要用它检测临时性故障，否则会导致不必要的重启循环。

### Load Balancer 摘机判断

负载均衡器（如 Envoy）支持 gRPC health checking protocol。当服务返回 `NOT_SERVING` 时，LB 会自动将该实例从后端池中摘除。

```yaml
# Envoy lb_config —— 仅示意，完整配置参考 Envoy docs
common_lb_config:
  health_check:
    grpc: {}           # 使用 gRPC health check protocol
    timeout: 5s
    interval: 10s
    unhealthy_threshold: 3
    healthy_threshold: 2
```

### 蓝绿部署流程

```mermaid
sequenceDiagram
    participant K8s as "K8s Scheduler"
    participant HP as "Health Probe"
    participant HS as "Health Server"
    participant SS as "Serving Status"
    participant LB as "Load Balancer"

    K8s->>HP: Every 10s Call Check("")
    HP->>HS: rpc Check(service="")
    HS->>SS: query status
    SS-->>HS: SERVING
    HS-->>HP: HealthCheckResponse{SERVING}
    HP-->>K8s: OK

    alt service shutdown begins
        K8s->>SS: SetServingStatus("", NOT_SERVING)
        Note over K8s,SS: draining pods or rolling update
        HP->>HS: rpc Check(service="")
        HS->>SS: query status
        SS-->>HS: NOT_SERVING
        HS-->>HP: HealthCheckResponse{NOT_SERVING}
        HP-->>K8s: FAIL x3 -> restart/drain
    end

    style OK fill:#00D866,color:#fff
    style FAIL fill:#EE5A24,color:#fff
```

## Server Reflection

启用 reflection 后，外部工具可以通过 gRPC 协议枚举所有 service、method、message 定义。这在开发和测试阶段非常有用。

```go
// 方式 A：显式注册（推荐，可读性好）
import "google.golang.org/grpc/reflection"
reflection.Register(s)

// 方式 B：blank import（利用 init() 自动注册）
import _ "google.golang.org/grpc/reflection"
```

启用 reflection 后可以做这些操作：

- 枚举所有已注册的 services 和 methods
- 查看 message 的字段类型和编号
- 构造请求进行交互式测试
- IDE 自动补全 gRPC call

> [!warning] 生产环境务必关闭 Reflection
> **Reflection 开启后存在多重安全隐患**：
> 1. **API 枚举**：攻击者可以获取全部 service、method 名称，了解业务逻辑结构
> 2. **Message Schema 泄露**：暴露所有 message 的字段类型和编号，辅助构造恶意请求
> 3. **无需认证**：Reflection RPC 本身没有鉴权机制，任何能连接 gRPC port 的请求都能使用
>
> 如果需要在生产环境调试，考虑使用专门的 tracing / metrics / audit logging 方案替代。

## 调试命令示例

安装 [grpcurl](https://github.com/fullstorydev/grpcurl) 后可直接使用：

```bash
# 列出所有已注册的服务
grpcurl -plaintext localhost:50051 list

# 输出：
# grpc.health.v1.Health
# user.v1.UserService
# order.v1.OrderService

# 查看某个服务的完整定义
grpcurl -plaintext localhost:50051 describe user.v1.UserService

# 查看 message 结构
grpcurl -plaintext localhost:50051 describe user.v1.CreateUserRequest

# 调用 RPC（注入 request body）
grpcurl -plaintext \
    -d '{"name":"test","email":"test@example.com"}' \
    localhost:50051 user.v1.UserService/CreateUser

# 调用 Health Check
grpcurl -plaintext -d '{"service":""}' \
    localhost:50051 grpc.health.v1.Health/Check

# 输出：
# {
#   "status": "SERVING"
# }
```

## Production Setup

生产环境的正确姿势：开启 health check，关闭 reflection。

```go
func NewProdServer() *grpc.Server {
    s := grpc.NewServer(
        grpc.Creds(credentials.NewTLS(tlsConfig)),
        grpc.MaxRecvMsgSize(16*1024*1024),
        grpc.ChainUnaryInterceptor(logging.Unary(), auth.Unary()),
    )

    // 注册业务 service
    registerServices(s)

    // Health check always on in production
    hs := health.NewServer()
    hs.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
    grpc_health_v1.RegisterHealthServer(s, hs)

    // NO reflection in production!
    // reflection.Register(s) // <-- commented out

    return s
}
```

对比表格：

| 环境 | Reflection | Health Check | Reason |
|------|-----------|--------------|--------|
| Local Dev | On | Optional | 方便调试 |
| Staging | Optional | On | 接近生产行为 |
| Production | Off | On | 安全 + 运维需求 |

## Watch 端点的高级用法

`Watch` 是一个 server streaming 端点，比 unary `Check` 强大得多：**客户端建立连接后，服务器会在状态变化时主动推送新值，而无需客户端反复轮询**。

在 Go 中获取 Watch 流非常简单——只需调用 `grpc_health_v1.NewHealthClient` 然后执行 `Watch` RPC：

```go
// Client 端：订阅 root service 的健康状态变化
client := grpc_health_v1.NewHealthClient(conn)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

watchStream, err := client.Watch(ctx, &grpc_health_v1.HealthCheckRequest{
    Service: "",
})
if err != nil {
    log.Fatal(err)
}

for {
    resp, err := watchStream.Recv()
    if err != nil {
        log.Printf("watch error: %v", err)
        return
    }
    log.Printf("status changed to: %s\n", resp.Status)
    // → SERVING → NOT_SERVING → SERVING ...
}
```

应用场景：

- **Metrics 采集器**：实时消费状态变化，更新 prometheus histogram
- **Dashboard**：前端 WebSocket 推送背后可以用 gRPC Watch 替代
- **Alerting System**：检测到 NOT_SERVING 时立即触发告警，比轮询更高效

```mermaid
sequenceDiagram
    participant Obs as "Observer (Prometheus / Dashboard)"
    participant HS as "Health Server"
    participant Store as "Serving Status Map"

    Obs->>HS: Watch(service="") → stream created
    HS->>Store: Register watcher with channel
    Store-->>HS: Immediate: SERVING
    HS-->>Obs: Send(SERVING)

    Note over Store: Later... admin triggers shutdown

    Store->>HS: Notify all watchers: NOT_SERVING
    HS-->>Obs: Send(NOT_SERVING)

    Note over Obs: Alert fires within one notification cycle

    Obs->>HS: Close stream (context cancelled)
    HS->>Store: Unregister watcher
```

## 生产环境故障排查

部署后遇到问题？以下是高频场景的速查表：

> [!faq] Probe 一直失败 (NOT_SERVING)，但服务实际正常运行
> **原因**：可能是启动速度太快，probe 在初始化完成之前就发起探测。解决：增大 `initialDelaySeconds`，或在初始化完成后才调用 `SetServingStatus("", SERVING)`。

> [!faq] 为什么 Check 返回 SERVING 但接口实际不可用？
> **原因**：`SetServingStatus` 只在内存中标记状态，不会检查依赖服务（DB、Redis 等）是否可用。如果需要深度健康检查，应该在 `Check` handler 中主动校验依赖项后再返回 `NOT_SERVING`。

> [!faq] 切换服务版本时，老版本还在收流量
> **原因**：K8s 删除 Pod 需要时间。正确做法是先调 `SetServingStatus("", NOT_SERVING)` 通知 LB 摘机，等业务请求归零后，再执行 Pod 删除。这叫 **graceful drain**。

```go
// graceful drain 示例：Shutdown hook
func GracefulStop(server *grpc.Server, healthServer *health.Server) {
    // Step 1: 告诉 health check 我们不再 serving
    healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_NOT_SERVING)

    // Step 2: 停止接收新连接（但不中断已有请求）
    server.GracefulStop()
}
```

## 关联笔记

- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册]]
- [[hhs/gRPC/3. 服务端实现/09-Streaming Handler]]