azure proxy type has been set but proxy host or port is not defined - Azure 代理类型已设置但缺少主机或端口如何解决 | Easysearch | 分布式搜索型数据库

适用版本： 6.8-8.9

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

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

常见现象 #

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

典型报错与异常栈 #

典型错误信息如下：

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

底层异常栈通常类似：

SettingsException: Azure Proxy type has been set but proxy host or port is not defined.
    at org.elasticsearch.cloud.blobstore.ElasticsearchAzureBlobStore.validateProxySettings(...)
    at org.elasticsearch.cloud.blobstore.ElasticsearchAzureBlobStore.createClient(...)
    at org.elasticsearch.repositories.azure.AzureRepository.createBlobStore(...)

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

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

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

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

代理类型已设置但缺少主机或端口：在 elasticsearch.yml 或仓库设置中配置了 azure.client.default.proxy.type，但忘记配置 azure.client.default.proxy.host 或 azure.client.default.proxy.port。
配置迁移遗漏：从其他环境复制配置时，只复制了部分代理参数。
模板变量未赋值：使用自动化工具（如 Terraform、Ansible）渲染配置时，代理主机或端口变量未正确赋值。
端口设置为 0：proxy.port 设置为 0 或默认值，被判定为无效端口。
主机名为空字符串：proxy.host 设置为空字符串或仅包含空白字符。

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

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

排查步骤 #

检查 Azure 客户端代理配置

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

# 或者查看 elasticsearch.yml 文件
grep -A3 -B3 "azure.client.*proxy" /etc/elasticsearch/elasticsearch.yml

验证代理配置的完整性

检查以下配置项是否完整：

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

查看完整的仓库配置

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

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

检查 Elasticsearch 启动日志

grep -i "azure.*proxy.*not defined" /var/log/elasticsearch/elasticsearch.log

排查时需要注意的问题 #

proxy.type 的有效值为 direct、http 或 socks，当设置为 http 或 socks 时，必须同时提供 host 和 port。
proxy.port 必须是有效的端口号（1-65535），值为 0 会被视为未设置。
proxy.host 不能是空字符串或仅包含空白字符。

4. 如何解决这个错误 #

常用修复思路 #

补齐代理主机和端口配置

在 elasticsearch.yml 中添加：

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

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

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

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

curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d '{
  "persistent": {
    "azure.client.default.proxy.type": null,
    "azure.client.default.proxy.host": null,
    "azure.client.default.proxy.port": 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.type": "http",
    "proxy.host": "proxy.example.com",
    "proxy.port": 3128
  }
}'

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

代理配置的三个参数（type、host、port）应该作为一个整体来处理，要么全部设置，要么全部不设置。
在配置管理工具（如 Ansible、Terraform）中，使用变量校验确保代理参数的完整性。
测试代理连接是否正常工作：

# 测试代理是否可达
curl -x http://proxy.example.com:3128 -I https://storage.azure.com

如果使用 SOCKS 代理，将 proxy.type 设置为 socks，并确保 SOCKS 代理服务正常运行。

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

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

5. 小结 #

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

确保代理配置的三个参数（type、host、port）同时设置或同时不设置；
确认 proxy.host 和 proxy.port 的值是有效的；
在不需要代理时，清理所有代理相关的配置项。

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

参考文档 #

附：日志上下文 #

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

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

标签

azure proxy type has been set but proxy host or port is not defined - Azure 代理类型已设置但缺少主机或端口如何解决