wkcli db

wkcli db 是面向一个 WuKongIM 节点数据目录的本地离线工具。它不会连接集群节点，也不会读取 Controller、Raft 或运行时全局状态。默认从只读查询开始；只有 import 会写 WKDB 存储。

不要操作在线数据目录

info 只读不可变标识文件，可以在节点运行时使用；其他精确检查应针对已停止节点、文件系统快照或复制出的数据目录。在线文件可能持续变化，不能形成一致证据；import 必须使用明确的离线目标，并在写入前完成 dry run 与备份。

使用示例前先安装 wkcli。数据库全局参数位于 wkcli db 之后、具体操作之前。

操作类别

命令	源数据访问	额外写入	视图范围
`info`	只读版本标识，不打开数据库	仅标准输出	单节点数据格式与创建程序
`query` / `repl`	只读	仅标准输出	单节点元数据与消息存储
`export`	只读	写 `--output` bundle 目录	单节点可导出的 bundle-v1 数据
`diff`	两端只读	仅标准输出	两个离线节点目录的 bundle-v1 数据差异
`import`	读取 bundle	写离线目标 WKDB	bundle 支持的数据类型

全局参数必须放在命令前，命令专属参数放在命令后。

查看数据版本

以下功能从 v3.0.0-beta.13 起提供，请使用配套版本的服务端和工具。

wkcli db --data-dir ./node-1 info
wkcli db --data-dir ./node-1 --format json info
wkcli db --config ./wukongim.toml info

每个全新空节点目录会自动生成 DATA-FORMAT.json。迁移生成的目标目录也会记录，创建程序为迁移工具。文件中的 format（当前 wukongim-v3）和 format_version（当前 1）描述数据格式；created_by 保存创建程序、版本、提交和构建来源，created_at 保存创建时间。普通软件升级与重复导入不会改写这些信息。

返回状态	含义
`registered`	标识有效，当前工具支持该格式
`unregistered`	目录存在但没有标识；不会推断为 v2 或 v3，也不猜测创建程序
`unsupported`	标识可读取，但当前程序不支持该格式，服务端会拒绝启动

info 不打开数据库、不获取数据库锁、不创建或修改目录，可在节点运行时查询。路径不存在或文件损坏会报错；查询成功只表示读取了标识，不代表业务数据已校验。使用节点根目录或配置文件，不要传 --meta-path、--message-path、--hash-slot-count。

已有非空目录（包括外部 Controller 状态目录）不会自动补登记，仍沿用既有存储检查。完整目录备份、快照及迁移分发须保留该文件；逻辑 bundle 和集群备份使用各自的格式版本，恢复时保留目标节点自身的创建记录。更早、不认识此标识的服务端不能据此保证安全回退。

定位存储

wkcli db --data-dir ./node-1 --hash-slot-count 256 query "show tables"
wkcli db --config ./wukongim.toml query "select * from meta.user limit 20"

--data-dir 按当前节点布局推导 slotmeta 与 messages；
--meta-path、--message-path 可以显式覆盖路径；
--config 从 TOML 读取路径和哈希槽数量，WK_ 环境变量仍会覆盖文件值；
--hash-slot-count 必须与源数据所属集群一致。WuKongIM 的物理哈希槽数量为 256。

记录节点 ID、集群 ID、数据复制/快照时间、服务端版本和目录校验值，避免比较错目标。

只读查询

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  query "select * from meta.user where uid='u1'"

wkcli db --data-dir ./node-1 \
  query "select * from message.channels limit 20"

wkcli db --data-dir ./node-1 \
  query "select * from message.message where channel_key='g1:2' limit 50"

包含 uid 或 channel_id 等分区键时，工具会推导对应哈希槽；没有分区键的查询会在本节点文件上进行有界扫描。limit 是整次查询总行数，不会对每个哈希槽重复应用。大结果使用返回的游标继续分页，不支持 offset：

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  query "select * from meta.user limit 100 cursor '<next_cursor>'"

使用 --format table|json|jsonl 控制输出。JSONL 会在数据行之后输出最终 stats 记录，其中包含 has_more 和 next_cursor。

导出 bundle

wkcli db --data-dir ./node-1 --hash-slot-count 256 \
  export --output ./wkdb-dump

export 以只读方式打开源存储，只写输出目录。WKDB Import Bundle v1 包含清单和 JSONL 文件，可覆盖受支持的用户、设备、频道、订阅关系、普通 membership、CMD membership、频道最新序号和消息数据，并为文件记录行数与 SHA-256。

它不会聚合其他节点、创建在线一致性快照、导出增量、包含 Controller/Raft/运行时状态，也不是 Manager 备份归档。需要覆盖已有输出目录时，先核对路径再显式添加 --overwrite。

导入 bundle

先只验证 bundle，不打开可写目标：

wkcli db --data-dir ./node-new --hash-slot-count 256 \
  import --input ./wkdb-dump --dry-run

通过校验后，针对新建或明确清空的离线目标执行：

wkcli db --data-dir ./node-new --hash-slot-count 256 \
  import --input ./wkdb-dump --require-empty

import 是唯一写 WKDB 存储的命令。它不加入集群、不迁移 Controller 或 Raft 状态，也不保证把单节点 bundle 变成完整集群。写入前应保存目标副本、确认 bundle 版本与哈希槽数量、使用 --require-empty 防止意外合并，并在启动任何节点前执行离线 diff。

比较两个离线目录

wkcli db --hash-slot-count 256 diff \
  --source-data-dir ./node-old \
  --target-data-dir ./node-new

wkcli db --hash-slot-count 256 diff \
  --source-data-dir ./node-old \
  --target-data-dir ./node-new \
  --mode full

默认 summary 比较行和 payload 校验值；full 还会散列消息 payload 字节。相等时退出 0，确认存在差异时退出 2。退出码必须与标准错误一起保存，避免把配置或读取错误误判为数据差异。

与集群恢复的边界

wkcli db bundle 适合节点本地的离线检查和受控数据转移，不替代 Manager 备份与恢复。集群恢复还必须验证集群身份、归档、任务以及全部 256 个物理哈希槽，并通过维护状态下的原子切换或回滚流程。

wkcli db

本页内容