如何在Golang架构中使用Grpc-health实现探针健康检查-Golang-PHP中文网

必须在gRPC Server启动前注册健康检查服务，因为registry启动后冻结，延迟注册会静默失败导致探针返回SERVICE_UNKNOWN；需在server.Serve()前调用RegisterHealthServer，并通过SetServingStatus动态更新真实业务状态。

如何在golang架构中使用grpc-health实现探针健康检查

Grpc-health-check 服务端注册为什么必须在 gRPC Server 启动前完成

因为 grpc_health_v1.NewHealthServer 返回的是一个实现了 HealthServer 接口的实例，它需要通过 RegisterHealthServer 注册到 gRPC Server 的 service registry 中；如果 Server 已启动，registry 就被冻结，后续注册会静默失败（无 panic，但探针始终返回 SERVICE_UNKNOWN）。

实操建议：

在调用 server.Serve() 之前，确保已执行 grpc_health_v1.RegisterHealthServer(server, healthServer)
推荐把 health server 初始化和注册封装进初始化函数，例如：NewGRPCServer() 内部统一处理
若使用 grpc.Creds() 或拦截器，health service 同样受其影响——比如启用了 mTLS，health 探针也必须带有效证书，否则直接拒绝连接

gRPC Health Check Protocol 的三种状态含义与客户端行为差异

SERVING、NOT_SERVING、UNKNOWN 不只是语义区别，Kubernetes 或 Envoy 等 caller 会据此做不同决策：K8s readiness probe 默认只把 SERVING 视为成功，其余都触发重启或摘流量；而 UNKNOWN 往往意味着健康检查服务本身未就绪（比如还没注册），不是业务逻辑问题。

常见错误现象：

curl -v “http://localhost:8080/healthz” 返回 503，但 gRPC Check 方法返回 UNKNOWN → 说明 health service 没注册或没监听
业务服务已 panic，但 Check(&grpc_health_v1.HealthCheckRequest{Service: “xxx”}) 仍返回 SERVING → 因为默认实现不感知业务状态，需手动设置
调用 Watch 流式接口时 client 长连接卡住 → 多数因 server 端未正确 close stream 或 context 超时设置不合理

如何让 health check 反映真实业务状态（非默认静态响应）

默认 grpc_health_v1.NewHealthServer 返回的是一个“永远返回 SERVING”的 stub；要联动业务状态，必须自己实现 HealthServer 接口，并维护一个可更新的状态变量（如 atomic.Value 或带锁 map）。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

实操建议：

定义一个全局 healthStatus 变量，类型为 *grpc_health_v1.HealthCheckResponse_ServingStatus，初始设为 SERVING
在关键初始化步骤（DB 连接池 ready、cache warmup 完成）后，用 atomic.StorePointer 更新状态
在自定义 Check 方法中，读取该变量并返回对应 status；注意不要在 Check 中做耗时操作，否则阻塞 probe

示例片段：

func (s *customHealthServer) Check(ctx context.Context, req *grpc_health_v1.HealthCheckRequest) (*grpc_health_v1.HealthCheckResponse, error) {
	status := atomic.LoadPointer(&s.status)
	return &grpc_health_v1.HealthCheckResponse{Status: *(*grpc_health_v1.HealthCheckResponse_ServingStatus)(status)}, nil
}

Kubernetes 中 grpc_health_probe 二进制为什么不能直接替换 livenessProbe.command

grpc_health_probe 是专为 gRPC health check 设计的 CLI 工具，它底层调用的是 Check 方法而非 HTTP；如果直接写成 command: ["/bin/grpc_health_probe", "-addr=:9000"]，会因容器内缺少该二进制而失败——它不在标准 Go 镜像里，也不是 OS 包管理器预装项。

正确做法：

构建阶段显式 COPY 或 go install github.com/grpc-ecosystem/grpc-health-probe/cmd/grpc_health_probe
确保 binary 具有可执行权限（chmod +x），且路径在 PATH 中或写绝对路径
务必指定 -rpc-timeout（默认 10s），否则 K8s probe timeout 小于该值时会误判失败；建议设为 5s 并匹配 pod 的 timeoutSeconds
若服务启用了 TLS，必须加 -tls 和 -tls-server-name，否则连接直接被拒绝