# UNAVAILABLE: SSL目标名称覆盖不匹配：期望'service.example.com'但收到'backend.internal'

- **ID:** `grpc/ssl-target-name-override-mismatch`
- **领域:** grpc
- **类别:** tls_error
- **验证级别:** ai_generated
- **修复率:** 87%

## 根因

gRPC客户端SSL/TLS目标名称覆盖（通过'grpc.ssl_target_name_override'）与服务器TLS证书的通用名称（CN）或主题备用名称（SAN）不匹配，导致握手失败。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| gRPC v1.61.0 | active | — | — |
| gRPC-Go v1.63.0 | active | — | — |
| OpenSSL 1.1.1w | active | — | — |

## 解决方案

1. ```
   更新客户端的SSL目标名称覆盖：将'grpc.ssl_target_name_override'设置为服务器证书中的确切CN/SAN（如'backend.internal'）；在Python中：'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'。
   ```
2. ```
   使用正确的SAN重新生成服务器TLS证书：在主题备用名称中包含'service.example.com'和'backend.internal'以匹配客户端覆盖；重启服务器以加载新证书。
   ```
3. ```
   完全移除覆盖：如果客户端目标URL与证书的CN/SAN匹配，省略'grpc.ssl_target_name_override'以使用自动主机名验证；确保DNS正确解析。
   ```

## 无效尝试

- **** — Disabling SSL verification entirely ('grpc.ssl_target_name_override='') exposes the connection to man-in-the-middle attacks and may not resolve if the server enforces TLS. (80% 失败率)
- **** — Changing the server's hostname in the client target URL without updating the override value causes a different mismatch; the error persists if the override still points to the old name. (85% 失败率)
- **** — Regenerating the server certificate with the same mismatched name doesn't fix the client-side override; the client must be updated to match the new certificate name. (90% 失败率)