salrashid123/grpc_health_proxy

grpc_health_proxy 镜像文档

镜像概述

grpc_health_proxy 是一款轻量级协议转换工具，核心功能是将HTTP健康检查请求转换为符合gRPC健康检查标准协议（grpc.health.v1.Health）的请求，并转发至后端gRPC服务。该镜像旨在解决仅支持HTTP协议的监控系统、容器编排平台（如Kubernetes）与gRPC服务间的健康检查协议不兼容问题，提供便捷的跨协议健康状态探测能力。

核心功能和特性

• 协议转换：支持将HTTP GET请求（如/health）转换为gRPC健康检查RPC调用（Check方法）
• 标准兼容：严格遵循gRPC健康检查协议规范，兼容所有实现该标准的gRPC服务
• 灵活配置：通过环境变量自定义后端地址、监听端口、服务名称等关键参数
• 轻量级部署：镜像体积精简，启动速度快，资源占用低，适合容器化环境
• TLS支持：可选启用TLS加密与后端gRPC服务通信，保障传输安全

使用场景和适用范围

• Kubernetes环境：为gRPC服务提供HTTP类型的存活/就绪探针，满足Kubernetes健康检查要求
• 监控系统集成：适配仅支持HTTP协议的监控工具（如Prometheus、Zabbix、Nagios），实现gRPC服务健康状态采集
• 服务网格补充：作为服务网格（如Istio）的辅助组件，为不支持gRPC健康检查的边缘节点提供探测接口
• 开发测试：快速验证gRPC服务健康检查接口可用性，无需编写专用gRPC客户端

使用方法和配置说明

基础部署（docker run）

通过以下命令启动代理服务，将HTTP请求转发至指定gRPC服务：

bash
docker run -d \
  --name grpc-health-proxy \
  -p 8080:8080 \
  -e GRPC_BACKEND=my-grpc-service:50051 \
  -e LISTEN_PORT=8080 \
  docker.xuanyuan.run/salrashid123/grpc_health_proxy

核心配置参数

带TLS加密的部署示例

若后端gRPC服务启用TLS，需挂载CA证书并配置TLS参数：

bash
docker run -d \
  --name grpc-health-proxy-tls \
  -p 8080:8080 \
  -e GRPC_BACKEND=secure-grpc-service:50051 \
  -e LISTEN_PORT=8080 \
  -e TLS_ENABLED=true \
  -e TLS_CA_CERT=/certs/ca.crt \
  -v /local/certs:/certs \  # 挂载本地证书目录至容器
  salrashid123/grpc_health_proxy

Docker Compose配置示例

创建docker-compose.yml文件，定义代理服务与后端gRPC服务的联动部署：

yaml
version: '3.8'
services:
  proxy:
    image: docker.xuanyuan.run/salrashid123/grpc_health_proxy
    ports:
      - "8080:8080"
    environment:
      - GRPC_BACKEND=grpc-service:50051
      - LISTEN_PORT=8080
      - HEALTH_SERVICE=user-service
    depends_on:
      - grpc-service

  grpc-service:
    image: docker.xuanyuan.run/your-org/your-grpc-service:latest  # 后端gRPC服务镜像
    ports:
      - "50051:50051"
    command: ["./server", "--health-check"]  # 假设服务启动时启用健康检查接口

健康检查验证

服务启动后，通过HTTP请求验证代理功能：

bash
# 发送HTTP健康检查请求
curl http://localhost:8080/health

# 预期响应（健康状态）：HTTP 200 OK
# 预期响应（不健康状态）：HTTP 503 Service Unavailable

响应状态说明：

• 200 OK：后端gRPC服务健康（对应gRPC健康检查SERVING状态）
• 503 Service Unavailable：后端服务不健康（NOT_SERVING）或无法连接
• 400 Bad Request：请求格式错误或配置参数无效