azure proxy port or host have been set but proxy type is not defined - Azure 代理配置缺少类型如何解决 | Easysearch | 分布式搜索引擎

适用版本： 6.8-8.9

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

Azure Proxy port or host have been set but proxy type is not defined 表示在配置 Elasticsearch 的 Azure 快照仓库（Snapshot Repository）时，代理配置不完整：设置了 proxy.host 或 proxy.port，但没有设置 proxy.type，导致 Azure 客户端无法构建合法的代理对象而抛出异常。

常见现象 #

创建或更新 Azure 快照仓库时返回 400 Bad Request 状态码。
Elasticsearch 启动时加载 Azure 仓库配置失败。
快照操作无法执行，报代理配置错误。
在日志中看到 SettingsException 异常信息。

典型报错与异常栈 #

典型错误信息如下：

SettingsException: Azure Proxy port or host have been set but proxy type is not defined.

底层异常栈通常类似：

SettingsException: Azure Proxy port or host have been set but proxy type is not defined.
    at org.elasticsearch.repositories.blobstore.ElasticsearchBlobStoreRepositoryIntegTestCase.handleRequest(...)
    at org.elasticsearch.common.settings.SettingsException.throwIfCloseable(...)
    at org.elasticsearch.cloud.blobstore.ElasticsearchAzureBlobStore.lambda$createClient$0(...)

在 Elasticsearch 日志文件中可能会出现：

[ERROR][o.e.r.b.ElasticsearchAzureBlobStore] [node_name] failed to create Azure client
SettingsException[Azure Proxy port or host have been set but proxy type is not defined.]

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

Azure Proxy port or host have been set but proxy type is not defined 异常由以下几种原因导致：

代理配置不完整：在 elasticsearch.yml 或仓库设置中配置了 azure.client.default.proxy.host 或 azure.client.default.proxy.port，但忘记配置 azure.client.default.proxy.type。
配置迁移遗漏：从其他环境复制配置时，只复制了部分代理参数。
模板渲染问题：使用自动化工具（如 Terraform、Ansible）渲染配置时，代理类型变量未正确赋值。
误以为可选：错误认为 proxy.type 是可选参数，实际上当 host 或 port 存在时，proxy.type 是必填的。
配置覆盖问题：多个配置源（如 elasticsearch.yml、命令行参数、动态设置）相互覆盖，导致代理类型丢失。

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

建议按以下步骤进行排查：

排查步骤 #

检查 Azure 客户端代理配置

# 查看当前 Azure 客户端配置
curl -X GET "localhost:9200/_cluster/settings?include_defaults=true&flat_settings=true" | grep -i azure

# 或者查看 elasticsearch.yml 文件
grep -i "azure.client" /etc/elasticsearch/elasticsearch.yml

验证代理配置的完整性

检查以下配置项是否同时存在：

azure.client.default.proxy.host: "proxy.example.com"
azure.client.default.proxy.port: 3128
azure.client.default.proxy.type: "http"  # 必须设置！

查看完整的仓库配置

# 查看所有仓库配置
curl -X GET "localhost:9200/_snapshot?pretty"

# 查看特定 Azure 仓库配置
curl -X GET "localhost:9200/_snapshot/my_azure_repo?pretty"

检查 Elasticsearch 启动日志

grep -i "azure.*proxy" /var/log/elasticsearch/elasticsearch.log | tail -20

排查时需要注意的问题 #

proxy.type 的有效值为 direct、http 或 socks，通常设置为 http。
如果不需要代理，应该同时移除 proxy.host 和 proxy.port，而不是只移除其中一个。
Azure 仓库配置可以在 elasticsearch.yml 中静态配置，也可以通过 API 动态创建仓库时指定。

4. 如何解决这个错误 #

常用修复思路 #

补齐代理类型配置

在 elasticsearch.yml 中添加：

azure.client.default.proxy.host: "proxy.example.com"
azure.client.default.proxy.port: 3128
azure.client.default.proxy.type: "http"  # 添加这一行

或者通过 API 更新集群设置：

curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d '{
  "persistent": {
    "azure.client.default.proxy.type": "http"
  }
}'

如果不需要代理，移除代理配置

curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d '{
  "persistent": {
    "azure.client.default.proxy.host": null,
    "azure.client.default.proxy.port": null,
    "azure.client.default.proxy.type": null
  }
}'

完整的 Azure 仓库创建示例

curl -X PUT "localhost:9200/_snapshot/my_azure_repo" -H 'Content-Type: application/json' -d '{
  "type": "azure",
  "settings": {
    "client": "default",
    "container": "my-container",
    "base_path": "snapshots",
    "proxy.host": "proxy.example.com",
    "proxy.port": 3128,
    "proxy.type": "http"
  }
}'

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

代理配置的三个参数（host、port、type）应该作为一个整体来处理，要么全部设置，要么全部不设置。
在配置管理工具（如 Ansible、Terraform）中，使用变量校验确保代理参数的完整性。
在变更代理配置后，建议创建一个测试仓库来验证配置是否正确。
如果使用 SOCKS 代理，将 proxy.type 设置为 socks。

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

INFINI Console 可以可视化查看和管理 Elasticsearch 集群的快照仓库配置。通过 Console 的仓库管理界面，可以快速检查 Azure 仓库的代理配置是否完整，避免因配置错误导致快照失败。Console 还提供快照历史查看和恢复测试功能，帮助验证代理配置是否正常工作。
INFINI Gateway 部署在 Elasticsearch 前端时，虽然不直接处理 Azure 仓库的代理配置，但可以对快照相关的 API 请求进行监控。当快照操作因代理配置错误而失败时，Gateway 的请求日志可以帮助快速定位失败原因。此外，Gateway 的流量监控功能可以帮助评估快照数据传输的网络使用情况。

5. 小结 #

Azure Proxy port or host have been set but proxy type is not defined 是一个配置完整性问题，本质原因是代理配置参数不完整。解决这个问题的关键是：

确保代理配置的三个参数（host、port、type）同时设置或同时不设置；
根据代理类型正确设置 proxy.type 的值（http 或 socks）；
在不需要代理时，清理所有代理相关的配置项。

通过 INFINI Console 进行配置可视化管理，可以更高效地发现和修复此类配置不完整的问题。

参考文档 #

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

if (proxyType.equals(Proxy.Type.DIRECT) && ((proxyPort != 0) || Strings.hasText(proxyHost))) {
 throw new SettingsException("Azure Proxy port or host have been set but proxy type is not defined.");
}

标签

azure proxy port or host have been set but proxy type is not defined - Azure 代理配置缺少类型如何解决