跨服务器将.NET连接至Couchbase的方法及故障排查

问题核心 #

你的代码存在异步阻塞风险，同时可能伴随网络配置或Couchbase服务端设置问题，导致连接一直处于加载状态。以下是针对性的修复方案：

一、修复代码中的异步阻塞问题 #

构造函数中使用Task.Run().Wait()容易引发死锁（尤其是在依赖注入容器初始化场景下），应该改用异步工厂模式初始化Couchbase连接：

public class CouchbaseService : ICouchbaseService
{
    public ICluster Cluster { get; private set; }
    public ICouchbaseCollection TodoCollection { get; private set; }

    // 私有构造函数，强制通过工厂方法初始化
    private CouchbaseService() { }

    public static async Task<CouchbaseService> CreateAsync()
    {
        var service = new CouchbaseService();
        await service.InitializeAsync();
        return service;
    }

    private async Task InitializeAsync()
    {
        var CB_HOST = Environment.GetEnvironmentVariable("CB_HOST") ?? "172.16.x.xxx";
        var CB_USER = Environment.GetEnvironmentVariable("CB_USER") ?? "Administrator";
        var CB_PSWD = Environment.GetEnvironmentVariable("CB_PSWD") ?? "Batara12345";

        Console.WriteLine($"Connecting to couchbase://{CB_HOST} with {CB_USER}");

        // 添加超时配置，避免无限等待
        var options = new ClusterOptions()
            .WithCredentials(CB_USER, CB_PSWD)
            .WithTimeout(TimeSpan.FromSeconds(10));

        try
        {
            Cluster = await Couchbase.Cluster.ConnectAsync($"couchbase://{CB_HOST}", options);
            var bucket = await Cluster.BucketAsync("TodoAppBucket");
            // 等待桶就绪，确保连接完成
            await bucket.WaitUntilReadyAsync(TimeSpan.FromSeconds(5));
            TodoCollection = bucket.DefaultCollection();
        }
        catch (CouchbaseException ex)
        {
            Console.WriteLine($"Couchbase连接失败：{ex.Message}");
            throw;
        }
    }
}

二、排查网络与Couchbase服务端配置 #

• 端口开放检查：确保开发服务器防火墙开放以下端口（客户端服务器需能访问）：
  • 8091：控制台端口
  • 8092：数据服务端口
  • 11210/11211：KV存储端口
  • 18091/18092：HTTPS对应端口（如果启用加密）
• 修正连接字符串：不要在couchbase://后添加8091，该端口是控制台端口，客户端连接默认使用KV端口，正确格式为couchbase://172.16.x.xxx
• 配置Couchbase外部IP：登录Couchbase控制台，进入Settings > Network，设置节点的External IP为开发服务器的可访问IP，避免集群返回内部不可访问的节点地址给客户端

三、依赖注入中的使用方式 #

如果使用DI容器（比如ASP.NET Core），需要注册异步工厂：

// Program.cs
builder.Services.AddScoped<ICouchbaseService>(async sp =>
{
    return await CouchbaseService.CreateAsync();
});

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