前言

@TOC

一、先说说为啥非动 MongoDB 不可

背景得先唠两句。不然我后头为啥这么选库，你看着会发懵。

我们这摊业务，是典型"烟囱式"一点点堆出来的。关系库管业务数据，MongoDB 存半结构化的日志和商品快照。Redis 扛缓存，后来眼红向量检索想加上，再后来还想塞点 GIS。每来一类新数据，得，又立一根新烟囱。

最闹心的是数据一致性。老实说，商品基本信息在关系库里富文本和那堆乱七八糟的属性在 MongoDB。缓存又是 Redis 一摊。改个价，对不住三个地儿都得写。补偿逻辑写到后头，我自己瞅代码都犯恶心。

机器资源也糟践得让人心疼。不过，MongoDB 那台服务器，CPU 常年 % 上下晃悠。内存倒让 WiredTiger 霸着不撒手，一想匀一点给别人，就门儿都没有。关系库那边还时不时抽风来个 burst，资源对不上号。各搞各的独立部署，硬件钱等于花了两遍。

运维这块，全是泪. 团队得同时养三拨人——懂关系库的、懂 Mongo 的、懂缓存的——每套库还各配一套备份、监控、告警。一出事三份日志对着扒，定位个毛病能熬一整宿。

You 想想，只把 MongoDB 换成另一个国产文档库。上面这些破事一件都摆不平，无非是把旧烟囱重新刷了遍漆。按理说，我真正惦记的是"收敛": 能不能一个引擎。把关系、文档、向量、GIS 全塞进去，让库与库之间再也别来回倒腾数据。这才是后来定 KES 的根本理由。

二、兼容这俩字，到底掺没掺水

KES 这版不太一样。它走的是"协议级兼容". 说人话：它在数据库进程里头硬给自己实现了一套 MongoDB 的通信协议，对外就监听 Mongo 的老本行端口。应用还是拿原来的 Mongo 驱动去连，它自己把报文拆开消化掉；应用层压根不知道，对面坐着的是不是 Mongo DB.

应用层 : 原 Mongo 驱动
/ Spring Data 等
协议层 :
← 应用以为连的是
语法层 : Mongo-parser
存储层 : 文档 / 关系 / 向量 / GIS ...

This setup lets you keep almost all application code intact—just point driver at new host/port.

三、动手前。我先给自己泼了三盆冷水

• 性能并非零成本代价！ 至于写操作，KES 在内部用关系表来存放 BSON，需要转换层；压测显示一样 10 万条插入从几毫秒变成数十毫秒甚至上百毫秒；UPDATE 更是慢到翻倍。
• “代码修改”并不是零改动：驱动版本需匹配，需要在连接字符串中加 ?directConnection=true&authMechanism=SCRAM-SHA-1;要注意哪些命令/功能未被支持。如果忽略这些细节，你会发现即使连通，也会出现功能缺失或错误行为。
• 验证比迁移更难：连通性 OK 并不等于行为完全一致；需要拿真实流量回放验证 CRUD 与聚合逻辑是否一致，包括边界类型等细节。

四、initdb：第一锹土

# 初始化实例
initdb -U system -m <兼容模式标识> -D /data/kes_data
# 开启服务
kingbase -D /data/kes_data -p <端口>
# 验证
ksql -U system -p test

五、kingbase.conf 里那四个坑死人的配置

# ===== kingbase.conf 关键配置 =====
enable_protocol_compat = on # 必须开启协议兼容
extension_protocol_port = <端口> # 与旧程序冲突时请改
documentdb_core.bsonUseEJson = on # 开启 EJson 序列化
shared_preload_libraries = 'kdb_cron,kdb_documentdb_core,kdb_documentdb'

• If you forget any of se four lines。mongosh will never connect.
• The order of shared_preload_libraries matters—documentdb must come after its core.
• A restart is required after changing kingbase.conf.
• The extension port cannot clash with an existing Mongo instance.
• bsonUseEJson must be on for cross-driver type compatibility.
• If you skip enabling protocol compatibility you’ll see handshake failures even if networking works.

六、一句 cascade，救了老张一命

CREATE EXTENSION documentdb CASCADE;ALTER USER system WITH PASSWORD 'xxxx';\dx -- 查看
列表是否包含 documentdb 和 documentdb_core

• The CASCADE keyword automatically pulls in dependent extensions like documentdb_core and kdb_cron。saving manual work.

七、mongosh 连上的那一刻，我差点信了

mongosh "mongodb://system:xxxx@:/test?其实，maxPoolSize=50&directConnection=true&authMechanism=SCRAM-SHA-1"
const db = this.getDb;await db.collection.insertMany();await db.collection.createIndex;await db.collection.find.toArray;如果查询正常返回，则说明协议兼容已成功。

• Add directConnection=true to avoid replica‑set topology discovery errors.

八、搬家，两条道，看家当多大

• Mongodump + Mongorestore：Certainly simplest when data volume is modest . Example commands:

mongodump --host old_host --port old_port -d old_db -c products -o /backup/dump
mongorestore --host new_host --port new_port \
--username system --password xxxx \
--aunticationMechanism SCRAM-SHA-1 \
/backup/dump/old_db/products.bson

Dual‑write + gradual cutover：Migrate a hot table by first syncing all existing rows。n enable dual‑write so new writes go to both old and new databases until data converges. After that gradually shift read traffic from old to new while monitoring consistency.
sql
-- Example pseudo code for dual write:
INSERT INTO new_products SELECT * FROM old_products;-- In application layer:
if {
insertIntoOld;insertIntoNew;}
The key pitfall here is building indexes only after bulk load – orwise each insert forces an index update which kills performance.

九、说好的“代码呢”。我真没敢全信

• You must change connection string in your app configuration to point at KES: yaml 说到spring，data: mongodb: 再看uri，mongodb://system:@:/test?directConnection=true&authMechanism=SCRAM-SHA-1 Only this one line truly changes your application code logic .