使用.NET Cosmos SDK连接Azure Cosmos时如何配置代理？配置后报错如何解决？

架构老林

2026-9-27

问题原因

Cosmos DB SDK 默认使用ConnectionMode.Direct直连模式，该模式基于TCP协议直接与Cosmos DB后端节点通信，仅网关模式(ConnectionMode.Gateway)会走HTTP/HTTPS代理，你配置的WebProxy在直连模式下不生效，请求直接从本地出站被网络拦截，导致返回服务不可用错误。
代理配置缺失参数：如果你的企业代理需要身份认证，你当前的WebProxy没有配置对应凭证，代理会直接拒绝请求返回503错误。
企业代理未开放Cosmos DB端点的出站权限，请求到达代理后被拦截返回不可用。
企业代理开启了SSL/TLS流量拦截，.NET运行时不信任代理签发的自签名证书，导致TLS握手失败。

解决方法

首先强制指定CosmosClient使用网关模式，这是WebProxy生效的前提，修正后的配置代码如下：

var client = new CosmosClient(
    dbConfig.GetValue<string>("Endpoint"), 
    dbConfig.GetValue<string>("Key"), 
    new CosmosClientOptions()
    {
        // 必须显式指定网关模式，WebProxy仅在该模式下生效
        ConnectionMode = ConnectionMode.Gateway,
        WebProxy = new WebProxy("http://localhost:9000/", true)
        {
            // 若代理需要Windows域身份认证，使用默认凭证
            Credentials = CredentialCache.DefaultNetworkCredentials
            // 若代理需要独立账号认证，替换为实际账号密码
            // Credentials = new NetworkCredential("your-proxy-username", "your-proxy-password")
        }
    });

确认企业代理已经放通了你使用的Cosmos DB端点的443端口出站权限。
若存在代理SSL拦截问题，将代理的根CA证书导入到服务器的信任根证书存储中即可，测试环境可临时添加自定义HttpClient逻辑跳过证书校验（生产环境不推荐）：

new CosmosClientOptions()
{
    ConnectionMode = ConnectionMode.Gateway,
    WebProxy = new WebProxy("http://localhost:9000/", true),
    HttpClientFactory = () =>
    {
        var handler = new HttpClientHandler()
        {
            Proxy = new WebProxy("http://localhost:9000/", true),
            // 仅测试用，生产环境不要开启
            ServerCertificateCustomValidationCallback = (sender, cert, chain, sslPolicyErrors) => true
        };
        return new HttpClient(handler);
    }
}

内容的提问来源于stack exchange，提问作者Gerrit