# grpc::UNAVAILABLE：没有健康的上游端点

- **ID:** `communication/grpc-unavailable-no-healthy-upstream`
- **领域:** communication
- **类别:** network_error
- **错误码:** `UNAVAILABLE`
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

gRPC 客户端无法连接，因为负载均衡器或服务注册中心报告目标服务没有健康的后端实例。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| gRPC 1.48 | active | — | — |
| Envoy 1.26 | active | — | — |
| Kubernetes 1.28 | active | — | — |
| Istio 1.18 | active | — | — |

## 解决方案

1. ```
   Verify backend health via `kubectl get endpoints -n <namespace> <service-name>` or equivalent service registry query. Then restart unhealthy pods: `kubectl rollout restart deployment/<deployment-name> -n <namespace>`.
   ```
2. ```
   Add a retry with backoff in the gRPC client using a middleware like `grpc_retry` in Go: `import "github.com/grpc-ecosystem/go-grpc-middleware/retry"; opts := []grpc_retry.CallOption{grpc_retry.WithMax(3), grpc_retry.WithBackoff(grpc_retry.BackoffLinear(100 * time.Millisecond))}`
   ```
3. ```
   Increase the readiness probe threshold in the Kubernetes deployment spec: `readinessProbe.periodSeconds: 10` and `failureThreshold: 5` to allow slower-starting backends more time to become healthy.
   ```

## 无效尝试

- **Restart the client application to force a new connection** — Restarting the gRPC client does not fix the root cause of unhealthy backends; the client will re-encounter the same error until the backend pool recovers. (95% 失败率)
- **Disable TLS/SSL on the gRPC channel** — Disabling TLS removes encryption but does not address backend health; the error stems from upstream unavailability, not protocol negotiation. (85% 失败率)
- **Change the target port to 443 or another arbitrary number** — Changing to a random port bypasses the correct service endpoint, making the situation worse by connecting to a non-existent service. (90% 失败率)