如何用Node.js监控Couchbase XDCR复制状态与延迟

Couchbase XDCR（跨数据中心复制）是维持多活集群数据一致性的关键组件。它异步将源集群的文档变更复制到目标集群，适合异地灾备、读写分离和数据分发。但异步复制意味着存在天然延迟，网络抖动、目标写入阻塞或任务异常都会让复制进度慢慢落后，最终导致业务读到旧数据。因此对XDCR状态进行实时监控很有必要。本文基于Node.js构造一个轻量监控客户端，调用Couchbase管理REST接口获取XDCR任务指标，并实现轮询与阈值告警。

一、先理解XDCR监控的核心指标与REST接口

XDCR的复制过程可以理解为源集群持续读取变更日志，再把变更批量推送到目标集群。如果目标集群写入变慢、网络拥塞或者任务挂起，变更队列就会积压。因此监控不能只看任务是否处于running状态，还要关注几个关键数值：changes_left表示尚未复制到目标集群的变更数量，数值持续上升说明复制跟不上写入速度；docs_written表示已成功写入目标集群的文档数；docs_failed表示复制过程中失败的文档数；time_working表示当前批次已经花费的时间，通常用来估算延迟；percent_completeness则是任务完成度，长期低于100%往往意味着有持续积压。

Couchbase为管理操作暴露了REST接口，默认监听8091或18091端口。我们可以在任意一台能够访问集群管理端口的机器上，通过/pools/default/tasks路径获取所有任务信息。响应数据中会包含索引、查询、分析等各类任务，XDCR任务可以通过type字段为xdcr来过滤。接口使用HTTP Basic认证，需要提供管理员或具备只读权限的用户名和密码。下面是一个典型的XDCR任务响应片段。

{
  "type": "xdcr",
  "id": "9e0e5f4f8e1f2a3b4c5d6e7f8a9b0c01/beijing/tokyo",
  "status": "running",
  "stats": {
    "docs_written": 128391,
    "docs_failed": 0,
    "changes_left": 23,
    "time_working": 156,
    "percent_completeness": 99.98
  }
}

这个接口返回的是瞬时状态，适合做健康检查和短期异常探测。如果需要历史趋势分析，可以进一步使用/pools/default/stats/range接口拉取一段时间内的采样数据。不过对于大多数告警场景，先基于瞬时任务状态判断已经足够。

二、用Node.js编写XDCR状态采集客户端

Node.js内置的https和http模块足以完成HTTP请求，不必引入第三方依赖。采集客户端需要完成三件事：携带Basic认证头请求任务列表、判断响应状态、解析JSON并过滤出XDCR任务。考虑到生产环境可能使用自签名证书，可以在测试环境中关闭证书校验，但正式环境最好通过ca选项指定企业的CA证书，避免中间人攻击风险。

下面是一个可复用的XDCR任务获取函数。代码中设置了5秒超时，避免请求悬挂导致监控进程卡死。认证信息使用环境变量构建，避免把密码硬编码在源码仓库里。

const https = require('https');

const CB_HOST = process.env.CB_HOST || 'couchbase-node-1.internal';
const CB_PORT = process.env.CB_PORT || 18091;
const CB_USER = process.env.CB_USER || 'monitor_user';
const CB_PASS = process.env.CB_PASS || 'monitor_password';

const options = {
  hostname: CB_HOST,
  port: CB_PORT,
  path: '/pools/default/tasks',
  method: 'GET',
  headers: {
    'Authorization': 'Basic ' + Buffer.from(CB_USER + ':' + CB_PASS).toString('base64')
  },
  rejectUnauthorized: false
};

function fetchXDCRTasks() {
  return new Promise((resolve, reject) => {
    const req = https.request(options, (res) => {
      let data = '';
      res.on('data', chunk => data += chunk);
      res.on('end', () => {
        if (res.statusCode !== 200) {
          return reject(new Error('HTTP ' + res.statusCode));
        }
        try {
          const tasks = JSON.parse(data);
          const xdcrTasks = tasks.filter(t => t.type === 'xdcr');
          resolve(xdcrTasks);
        } catch (err) {
          reject(err);
        }
      });
    });

    req.on('error', reject);
    req.setTimeout(5000, () => req.destroy(new Error('request timeout')));
    req.end();
  });
}

拿到任务数组后，可以先做一次简单的控制台输出，观察每个任务的id和关键统计值。例如遍历任务并打印changes_left、docs_failed和time_working。如果输出中所有任务的changes_left都接近0，说明复制非常健康；若某个任务数值持续增长，就需要进一步排查目标集群或网络。

还需要注意，Couchbase REST接口返回的id通常包含集群名、源桶和目标桶等信息，例如clusterA/bucket1/clusterB。在监控日志中保留完整任务ID，有助于快速定位是哪一条复制链路出了问题。

三、轮询与阈值告警：让监控真正发挥作用

采集到状态只是第一步，监控必须能够自动判断异常并通知相关人员。轮询间隔建议控制在30秒到1分钟之间。XDCR状态变化相对平缓，过短的间隔会增加管理端口压力，过长则可能错过快速积压的窗口期。Node.js中可以使用setInterval执行定时任务，但要小心异步回调重叠。如果网络请求偶尔超过间隔时间，可能出现多个并发请求同时访问管理接口。更稳妥的做法是使用setTimeout递归调度，上一次请求完成后再安排下一次。

阈值判断逻辑需要根据业务允许的数据延迟来调整。下面给出一个简单的告警函数，它检查三个条件：待复制变更超过1万条、存在失败文档、当前批次耗时超过2分钟。任一条件满足就生成一条告警记录。

function evaluateXDCRHealth(tasks) {
  const alerts = [];

  for (const task of tasks) {
    const stats = task.stats || {};
    const changesLeft = stats.changes_left || 0;
    const docsFailed = stats.docs_failed || 0;
    const lag = stats.time_working || 0;

    if (changesLeft > 10000) {
      alerts.push({
        task: task.id,
        message: 'changes_left too high',
        changesLeft
      });
    }
    if (docsFailed > 0) {
      alerts.push({
        task: task.id,
        message: 'replication failures detected',
        docsFailed
      });
    }
    if (lag > 120000) {
      alerts.push({
        task: task.id,
        message: 'replication lag exceeds 2 minutes',
        lag
      });
    }
  }

  return alerts;
}

定时任务将采集和判断串联起来，当发现告警时输出结构化JSON。你可以把这段输出接到日志系统、HTTP Webhook或者消息队列中，实现短信、邮件、企业微信等通知渠道。

setInterval(async () => {
  try {
    const tasks = await fetchXDCRTasks();
    const alerts = evaluateXDCRHealth(tasks);
    if (alerts.length > 0) {
      console.warn(JSON.stringify({
        time: new Date().toISOString(),
        alerts
      }, null, 2));
      // 在这里调用 http 请求发送到告警平台
    } else {
      console.log('XDCR replication healthy');
    }
  } catch (err) {
    console.error('fetch xdcr failed', err.message);
  }
}, 30000);

实际使用中，建议把阈值配置和通知地址放到配置文件或环境变量中，避免每次调整都要改代码。如果XDCR偶尔因为网络抖动出现短暂积压，可以增加连续告警次数的判断，例如连续3次超过阈值才触发通知，减少误报。

四、生产环境监控的加固与扩展

当监控脚本要部署到生产环境时，安全性必须优先考虑。建议为XDCR监控单独创建一个只读账号，只授予读取任务和统计信息的权限，不要使用管理员账号。网络层面应限制监控主机的IP，只允许它访问集群管理端口。同时优先使用TLS加密管理流量，并在Node.js中正确配置ca选项或使用企业签发的证书。密码、主机地址等敏感信息通过环境变量注入，不要写入代码仓库。

如果基础设施中已经有Prometheus，可以直接让Node.js暴露一个文本指标接口，由Prometheus定期抓取。这样就不需要自己维护定时调度和存储逻辑。下面是一个简单的Prometheus导出器示例，将每个XDCR任务的待复制变更数输出为xdcr_changes_left指标。

const http = require('http');

http.createServer(async (req, res) => {
  try {
    const tasks = await fetchXDCRTasks();
    let body = '# HELP xdcr_changes_left pending changes\n';
    body += '# TYPE xdcr_changes_left gauge\n';

    for (const task of tasks) {
      const safeId = task.id.replace(/\W+/g, '_');
      const value = task.stats?.changes_left || 0;
      body += 'xdcr_changes_left{task=\"' + safeId + '\"} ' + value + '\n';
    }

    res.writeHead(200, {'Content-Type': 'text/plain; charset=utf-8'});
    res.end(body);
  } catch (err) {
    res.writeHead(500, {'Content-Type': 'text/plain; charset=utf-8'});
    res.end('xdcr monitor error: ' + err.message);
  }
}).listen(9100);

如果暂时没有Prometheus环境，也可以把指标写入InfluxDB或其他时序数据库，配合Grafana做可视化趋势图。长期来看，保存历史指标有助于分析XDCR延迟的周期性波动，比如每日业务高峰期复制积压是否明显增加，从而为扩容或调整复制策略提供依据。

最后还要考虑监控自身的可用性。监控脚本如果运行在单台机器上，一旦该机器宕机就失去了对XDCR的感知。生产环境建议使用进程管理工具如systemd或PM2保障脚本持续运行，并在多个机房部署监控实例，避免单一监控点失效。只有监控链路本身可靠，才能在XDCR出问题时及时预警，保护分布式数据架构的最终一致性。

Couchbase XDCRNode.js监控修改时间：2026-08-27 19:28:28