Azure proxy host is unknown - 如何解决此 Elasticsearch 异常 | Easysearch | 分布式搜索引擎

适用版本： 6.8-8.9

1. 错误异常的基本描述 #

Azure proxy host is unknown 是 Elasticsearch 在初始化 Azure Blob Storage 仓库（snapshot repository）时抛出的配置异常。当 Elasticsearch 尝试解析 azure.client.<name>.proxy.host 中配置的代理主机名却无法获得有效 IP 地址时，就会触发此错误。该异常会直接阻止 Azure 仓库的创建或恢复，导致快照功能完全不可用。

常见现象 #

创建或修改 Azure snapshot repository 时返回 400 或 500 错误，仓库无法注册成功。
Elasticsearch 日志中出现 SettingsException: Azure proxy host is unknown，且通常伴随 UnknownHostException 或 DNS 解析失败的堆栈信息。
使用 GET _snapshot/<repo_name> 查看仓库状态时返回错误或超时。
如果代理配置是全局生效的，可能导致所有依赖该 Azure client 的仓库操作全部失败。

典型报错与异常栈 #

典型日志形态如下：

SettingsException: Azure proxy host is unknown
Caused by: java.net.UnknownHostException: proxy.example.com
    at org.elasticsearch.common.settings.SettingsException: Azure proxy host is unknown
    at org.elasticsearch.repositories.azure.AzureStorageService.createClient(AzureStorageService.java)
    ...

在部分场景中，还可能看到如下补充信息：

Caused by: java.net.UnknownHostException: unable to resolve host "proxy.local": No address associated with hostname

2. 为什么会发生这个错误 #

Azure proxy host is unknown 的本质原因是：Elasticsearch 在初始化 Azure 客户端时，无法将配置的代理主机名解析为有效的 IP 地址。常见原因包括：

代理主机名拼写错误：配置文件中 proxy.host 的值存在笔误，例如将 proxy.internal 误写为 proyx.internal，或填写了不存在的域名。
DNS 解析失败：Elasticsearch 节点所在网络环境的 DNS 服务器无法解析该主机名，例如内网 DNS 未配置对应记录，或节点使用了错误的 DNS 服务器。
代理主机名格式非法：proxy.host 被配置为空字符串、null、仅包含空格，或使用了不被允许的字符（如 /、# 等），导致 URL 构造失败。
环境切换后配置未同步：在开发/测试/生产环境之间迁移配置时，代理主机名是某个环境的内部地址，切换到新环境后该地址不可达且无法解析。
代理配置启用了但主机未填写：proxy.type 和 proxy.port 已配置，但 proxy.host 遗漏未填，Elasticsearch 尝试用空值初始化代理地址时抛出异常。
容器或 Kubernetes 环境下 DNS 策略问题：Elasticsearch 运行在 Pod 中，Pod 的 DNS 策略（dnsPolicy）未正确配置，导致无法解析集群外或宿主机网络中的代理主机名。

3. 如何排查和解决这个异常 #

建议按以下顺序进行排查：

确认报错时间点和上下文：查看 Elasticsearch 日志，找到 Azure proxy host is unknown 出现的准确时间，确认触发该错误的具体操作（如创建仓库、更新仓库、节点重启等）。
检查 Azure client 代理配置：查看 elasticsearch.yml 或相关配置中 azure.client.<name>.proxy.host 的当前值，确认是否存在拼写错误或格式问题。
在节点侧验证 DNS 解析：登录 Elasticsearch 所在节点，使用 nslookup <proxy-host> 或 dig <proxy-host> 验证该主机名是否可解析；如果是容器环境，进入容器内部执行相同操作。
验证网络连通性：确认代理主机是否真实存在且可达，使用 ping <proxy-host> 或 telnet <proxy-host> <proxy-port> 检查网络连通性。
检查是否需要代理：如果当前网络环境不需要通过代理访问 Azure，应移除整组 proxy.* 配置，而不是保留一个无效的主机名。
确认代理类型与端口匹配：proxy.type（如 http、socks、direct）必须与 proxy.host 和 proxy.port 同时正确配置，缺一不可。
修复后重新验证仓库：修改配置后，调用 PUT _snapshot/<repo_name> 重新注册仓库，或使用 GET _snapshot/<repo_name> 验证仓库状态是否恢复正常。

排查时需要注意的问题 #

不要仅依赖 Elasticsearch 日志中的 UnknownHostException，必须同时检查节点的 /etc/resolv.conf 和 DNS 服务器配置，确认解析路径是否正确。
如果 Elasticsearch 以容器方式运行，注意容器内的 DNS 解析能力与宿主机可能不同，应进入容器内部验证，而不是仅在宿主机上测试。
修改 elasticsearch.yml 后需要重启节点才能生效，若使用滚动重启，注意观察每个节点重新加入集群后仓库状态是否一致。

4. 如何解决这个错误 #

常用修复思路 #

修正代理主机名：将 proxy.host 改为正确且可解析的主机名或 IP 地址。如果代理服务使用 IP 地址，可以直接填写 IP 以避免 DNS 解析问题。
```
azure.client.default.proxy.host: proxy.internal.corp
azure.client.default.proxy.port: 3128
azure.client.default.proxy.type: http
```

移除不必要的代理配置：如果当前网络环境不需要代理即可访问 Azure Blob Storage，直接删除 proxy.* 相关配置：

# 删除以下配置
# azure.client.default.proxy.host: ...
# azure.client.default.proxy.port: ...
# azure.client.default.proxy.type: ...

为不同环境维护独立配置：开发、测试、生产环境应使用各自的配置文件或配置模板，避免将某一环境的代理地址直接复制到其他环境。
在容器环境中显式配置 DNS：如果是 Kubernetes 部署，确保 Pod 的 dnsPolicy 配置正确，必要时在 spec.template.spec 中显式设置 dnsConfig：
```
spec:
  dnsPolicy: ClusterFirst
  dnsConfig:
    searches:
      - internal.corp
```

后续注意事项与推荐建议 #

在变更 Azure 仓库配置前，建议先在任意数据节点上执行 nslookup <proxy-host> 确认解析结果，避免将不可用的主机名写入配置。
对 Azure 仓库的代理配置建立变更记录，包括修改时间、修改人、修改原因和目标值，便于后续回溯和问题定位。
如果代理服务本身存在高可用需求，建议使用代理集群的 VIP 或内网负载均衡地址作为 proxy.host，而不是某个单点主机名。
定期审查 elasticsearch.yml 中的 Azure client 配置，清理已下线或不再使用的代理设置，防止遗留配置在环境变更后引发问题。

借助 INFINI 产品提升排障效率 #

INFINI Console 可协助查看集群健康状态、节点分布和日志时间线，帮助快速定位异常出现的时间窗口和影响范围。
INFINI Gateway 可作为 Elasticsearch 请求链路中的观测层，记录所有仓库相关请求的上下文，辅助排查代理链路变更对快照功能的影响。

5. 小结 #

Azure proxy host is unknown 虽然报错信息简短，但其根因通常指向代理主机名配置错误或 DNS 解析不可用。处理该异常时，应优先从节点侧的 DNS 解析验证入手，确认代理主机名是否真实可达；若无需代理则应直接移除相关配置，避免引入不必要的依赖。通过建立环境隔离的配置管理规范和变更前的解析验证机制，可以有效防止此类问题在生产环境中反复出现。

附：日志上下文 #

SettingsException: Azure proxy host is unknown
Caused by: java.net.UnknownHostException: proxy.example.com
    at org.elasticsearch.repositories.azure.AzureStorageService.createClient(AzureStorageService.java)
    at org.elasticsearch.repositories.azure.AzureRepository.createBlobStore(AzureRepository.java)
    ...

标签

Azure proxy host is unknown - 如何解决此 Elasticsearch 异常