Couchbase 作为分布式 NoSQL 文档数据库，在实际项目中经常需要把已有的 JSON 数据批量写入集群。手动通过 SDK 编写循环插入程序不仅开发成本高，而且在网络抖动、文档格式异常时缺乏成熟的容错机制。cbimport 是 Couchbase 官方随服务端或工具包发布的命令行实用程序，专门解决这类批量装载问题。它直接与服务端通信，利用多线程机制提升吞吐，并支持从本地文件、标准输入等多种来源读取数据。
cbimport 的核心工作模式与参数解析
cbimport 最常用的是 json 和 csv 两种数据集格式。当我们导入 JSON 数据时，应当显式指定 --format json。JSON 源文件可以是每行一个文档的 NDJSON（换行分隔 JSON），也可以是一个完整的 JSON 数组。工具通过 --dataset 参数接收文件路径，使用 --bucket 指明目标桶，--scope 与 --collection 可进一步定位集合。若未指定集合，数据会进入默认的 _default 集合。
在身份校验方面，需要通过 --cluster 设置连接地址，--username 和 --password 提供账号信息。对于自签名证书的测试环境，可附加 --insecure 跳过 TLS 校验。错误容忍度由 --errors-log 指定错误日志路径，配合 --threshold 定义最大错误比例，避免少量脏数据导致整个任务中断。下面是一段典型的导入命令示例：
cbimport json --cluster http://127.0.0.1:8091 --username admin --password secret --bucket travel --scope _default --collection hotels --dataset /data/hotels.ndjson --format lines --generate-key %type%-%id% --threads 4 --errors-log /tmp/cbimport_err.log
上述命令中 --format lines 表示源文件为换行分隔的 JSON 对象；--generate-key 利用文档内的字段组合生成文档 ID，避免主键冲突。若源是 JSON 数组，则应将 format 改为 array。线程数 --threads 一般设置为 CPU 核数的 1 到 2 倍，可在导入速度与集群负载间取得平衡。
JSON 源文件的准备与字段映射技巧
很多导入失败源于源文件结构不合预期。对于 lines 模式，每一个非空行必须能独立解析为一个 JSON 对象，不能包含换行符内的多行美化格式。若原始数据是从关系库导出的数组文件，建议先用 jq 等工具转换成 NDJSON，例如执行 jq -c '.[]' source.json > out.ndjson，其中 > 为 shell 重定向符号。转换后可用 head -n 1 out.ndjson 验证单行合法性。
当 JSON 文档中没有合适的唯一标识字段时，可以借助 --generate-key 的表达式能力。它支持 %field% 引用文档属性，也支持 #UUID# 自动生成随机键。如果希望保留原文档某个外键作为 ID 并添加前缀，可写为 hotel_%hid%。需要注意的是，生成键重复会触发替换或报错，取决于 --mode 参数：upsert 会覆盖，insert 遇重复即失败。以下示例展示如何用数组格式并指定插入模式：
cbimport json --cluster http://127.0.0.1:8091 --username admin --password secret --bucket travel --dataset /data/array.json --format array --mode insert --generate-key #UUID#
字段映射方面，cbimport 本身不做复杂的字段重命名，它原样写入文档。如果需要在导入前清洗字段，应当在生成源文件阶段完成，比如用 Python 脚本剔除空值、统一时间格式。这样既能利用 cbimport 的高性能通道，又保证了落库数据质量。对于超大规模数据，可把源文件按大小拆分，利用 --errors-log 分别记录每段错误，方便并行重试。
性能调优与常见故障排查
导入性能主要受网络延迟、集群写入容量和客户端线程数影响。在单机部署的测试环境，把 --threads 开到 8 以上往往能跑满磁盘 IO；但在生产集群，过高线程会压垮节点索引服务，建议从 4 开始梯度加压，并观察 Web 控制台的 ops 曲线。另外，如果目标桶开启了同步网关或触发器，批量导入可能引发大量下游事件，此时可临时调低线程或暂停相关功能。
常见故障中，证书错误表现为 TLS handshake failed，测试环境加 --insecure 即可，生产环境则应配置正确 CA。另一个是 JSON 解析错误，日志会指出具体行号，多半是源文件混入了 BOM 头或非标准引号。用 file 命令检查编码，用 sed 去除 BOM 可解决。当导入中途断网，cbimport 不会自动断点续传整个文件，但可通过拆分已成功部分来手动续做，结合错误日志中最后成功的键来切分源数据。
权限不足也会让导入直接退出，确保账号对目标桶有读写权限且角色包含 data_writer。如果集群启用了多租户分区，还必须指定正确的 --scope。最后，监控 --errors-log 中的条目数是否超过 --threshold，一旦超过工具会中止并报错，这时需要修复源数据后减小批次重跑，而不是盲目加大阈值掩盖问题。
与其他导入方案的对比及适用场景
相比使用 SDK 自写脚本，cbimport 的优势在于零编码、参数可控、官方维护。SDK 脚本灵活，可做复杂变换，但需处理批量批大小、重试退避等细节，新手容易写出低效循环。另一方案是 Couchbase 的 N1QL INSERT 语句配合文件函数，但这种方式依赖查询服务，不适合百万级装载。cbimport 走的是数据服务直写通道，延迟更低。
在适用场景上，初始化测试数据、迁移旧系统快照、定期全量同步都非常适合 cbimport。若业务要求增量且带变换逻辑，则应以消息队列加 SDK 消费为主。团队可将 cbimport 封装进运维镜像，作为数据重置的标准动作。理解了它的工作原理与限制，才能在大批量 JSON 入湖入桶时保持稳健与高效。