mcli 管理接口(HTTP)#
本页介绍通过 mcli 的 HTTP 管理命令完成应用生命周期管理与分区路由查询,以及复制与备份管理命令和 TCP 数据面命令。
前置条件#
mudud服务端正在运行。HTTP 管理端口可访问(默认
127.0.0.1:8300)。
大多数管理命令通过 --http-addr <host:port> 指定目标服务器。
命令一览#
列出已安装应用#
mcli --http-addr 127.0.0.1:8300 app-list
安装应用包#
mcli --http-addr 127.0.0.1:8300 app-install --mpk target/wasm32-wasip2/release/wallet.mpk
查看应用过程列表#
mcli --http-addr 127.0.0.1:8300 app-detail --app wallet
查看单个过程详情#
--proc 必须与 --module 一起使用。
mcli --http-addr 127.0.0.1:8300 app-detail --app wallet --module wallet --proc create_user
卸载应用#
mcli --http-addr 127.0.0.1:8300 app-uninstall --app wallet
查看服务拓扑#
mcli --http-addr 127.0.0.1:8300 server-topology
分区路由查询#
按精确 key 路由:
mcli --http-addr 127.0.0.1:8300 partition-route --rule-name user_rule --key user-100
按范围路由:
mcli --http-addr 127.0.0.1:8300 partition-route --rule-name user_rule --start 100 --end 200
多列 key 示例:
mcli --http-addr 127.0.0.1:8300 partition-route --rule-name order_rule --key tenant-1,order-100
数据面命令(TCP)#
这些命令连接 TCP 协议端点(--addr,默认 127.0.0.1:9527)。请求体可以用内联 JSON(--json)或 JSON 文件(--json-file;用 - 从 stdin 读取)提供。
SQL 示例假定已安装含 users(id) 表的 demo 应用。原始 KV 请求必须提供有效会话 OID:{ "h": 高64位, "l": 低64位 };原始 invoke 必须提供 session_id(u64 数字或十进制 u128 字符串)及编码后的过程参数。下列 ID 与负载是占位示例,不会创建会话。通常应使用 app-invoke 自动建立会话并按描述符转换参数。
执行 SQL 查询或命令#
mcli --addr 127.0.0.1:9527 command --json '{"app_name":"demo","sql":"SELECT id FROM users"}'
写入键值项#
mcli --addr 127.0.0.1:9527 put --json '{"oid":{"h":0,"l":1},"key":"k","value":"v"}'
读取键#
mcli --addr 127.0.0.1:9527 get --json '{"oid":{"h":0,"l":1},"key":"k"}'
扫描键范围#
mcli --addr 127.0.0.1:9527 range --json '{"oid":{"h":0,"l":1},"start_key":"a","end_key":"z"}'
以原始请求调用过程#
invoke 通过 TCP 发送原始过程请求。带类型的变体是 app-invoke(见客户端),它先通过 HTTP 获取过程描述符,再通过 TCP 调用。
mcli --addr 127.0.0.1:9527 invoke --json '{"session_id":"1","procedure_name":"app/mod/proc","procedure_parameters":{}}'
复制管理#
Raft 成员管理与主从故障切换命令。它们作用于目标节点的 HTTP 管理端点。
向 raft 组添加节点#
节点默认以 voter 加入;添加 --learner 以 learner 加入(只复制不投票;之后用 promote-learner 提升)。
mcli --http-addr 127.0.0.1:8300 repl add-node --node-id 4 --host 10.0.0.4 --port 19530
mcli --http-addr 127.0.0.1:8300 repl add-node --node-id 4 --host 10.0.0.4 --port 19530 --learner
从 raft 组移除节点#
mcli --http-addr 127.0.0.1:8300 repl remove-node --node-id 4
将 learner 提升为 voter#
mcli --http-addr 127.0.0.1:8300 repl promote-learner --node-id 4
将本节点提升为流复制 primary#
提升要求提供 fencing 证明:--fencing-cmd <命令> 会先在本地执行(经 sh -c),失败则中止提升且不接触服务器;或者用 --yes 显式确认旧 primary 已被 fence。两个选项互斥。
mcli --http-addr 127.0.0.1:8301 repl promote --fencing-cmd ./fence-old-primary.sh
mcli --http-addr 127.0.0.1:8301 repl promote --yes
跟随新的流复制 primary#
--primary 是新 primary 的复制地址(host:port)。
mcli --http-addr 127.0.0.1:8300 repl follow --primary 10.0.0.2:19527 --primary-node-id 2
查看复制状态#
默认输出 JSON;--table 渲染为分节表格。
mcli --http-addr 127.0.0.1:8300 repl status
mcli --http-addr 127.0.0.1:8300 repl status --table
备份与恢复#
基础备份与逻辑导出通过 HTTP 管理端点在运行中的服务器上执行;restore 与 pitr 为离线命令,不接触服务器。[backup] 配置与磁盘布局见备份与恢复。
执行基础备份#
要求服务器配置 [backup] backup_dir。
mcli --http-addr 127.0.0.1:8300 backup create --label daily-1
列出基础备份#
mcli --http-addr 127.0.0.1:8300 backup list
校验基础备份#
mcli --http-addr 127.0.0.1:8300 backup verify --label daily-1
删除基础备份#
mcli --http-addr 127.0.0.1:8300 backup delete --label daily-1
恢复基础备份(离线)#
将基础备份加归档 WAL 重放到 --target-dir,直至归档末尾。
mcli restore --label daily-1 --backup-dir /backups --archive-dir /wal-archive --target-dir /restored
时间点恢复(离线)#
与 restore 类似,但在目标点停止。--lsn、--time、--xid 必须且只能提供一个。
mcli pitr --label daily-1 --backup-dir /backups --archive-dir /wal-archive --target-dir /recovered --time 1700000000000
执行逻辑导出#
在服务器上写出 <dir>/<label>.zip(--dir 是服务器端路径)。
mcli --http-addr 127.0.0.1:8300 dump --label daily-1 --dir /dumps
执行逻辑导入#
默认跳过已存在的同名表;传入 --drop 则删除并重建同名表。
mcli --http-addr 127.0.0.1:8300 restore-logical --label daily-1 --dir /dumps
mcli --http-addr 127.0.0.1:8300 restore-logical --label daily-1 --dir /dumps --drop
参数约束#
app-detail:--proc必须与--module一起使用。partition-route:--key与--start/--end二选一,不可同时使用。command/put/get/range/invoke/app-invoke:--json与--json-file必须且只能提供一个。repl promote:--fencing-cmd与--yes互斥;必须提供其一。pitr:--lsn、--time、--xid互斥;必须且只能提供一个。
返回结果#
默认输出格式化 JSON。
添加
--compact输出紧凑 JSON。出错时命令返回非 0,并在 stderr 输出错误原因。