bk-cli cmdb — CMDB 能力使用说明

用于通过 bk-cli cmdb 调用 CMDB open API 的高频系统子命令。

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../bk-cli-shared/SKILL.md。共享 skill 负责认证、context、tenant、stage、dry-run、verbose、header/body 和通用请求规则；本 skill 只补充 cmdb 命令自己的语义与输入约定。

当前覆盖范围

当前 skill 覆盖这些高频 cmdb 命令：

• getbizinternal_module
• search_business
• search_set
• create_set
• search_module
• create_module
• listbizhosts_all
• listbizhosts
• listhostswithout_biz
• findhostbiz_relations
• listbizhosts_topo
• transferhostmodule
• transferhostacross_biz
• transferhosttoidlemodule
• transferhosttofaultmodule
• transferhosttorecyclemodule
• transferhosttoresourcepool
• listresourcepool_hosts
• delete_host

后续如果新增更多 cmdb 子命令，应继续追加到本 skill 的 ## Commands 章节，而不是拆成新的单命令 skill。

推荐工作流

1. 先确认目标是否已经有现成 cmdb 子命令。
2. 如果已有现成子命令，优先使用该命令，而不是直接退回原始 bk-cli api。
3. 首次调用或排障时，优先先加 --dry-run 看最终 URL、headers 和 body。
4. 如果现成子命令还不能覆盖你的目标接口，再退回 bk-cli api bk-cmdb ...。

输入约定

通用规则

• 大多数 cmdb 命令都支持 --stage、--header、--body；listbizhosts_all 例外，不暴露 --body。
• 当显式传入 --body '<json>' 时，请求会以该 JSON 为准，不再使用命令自带的默认请求内容。
• 这些 cmdb 命令通常要求可满足 app+user 的凭据；若当前 context 使用 access_token，也可满足非空认证要求。

CSV 列表参数

当前 cmdb 的列表型输入统一优先使用 CSV 风格 flags：

• --bkbizids 1,2,3
• --bkhostids 100,200
• --bkmoduleids 20,30
• --fields bkhostid,bkhostinnerip

--host_ips 规则

• 形态一：10.0.0.1
• 形态二：27:10.0.0.2
• 含义：cloudid:ip；未写前缀时默认 cloudid=0
• 只要有一个非法项，命令会直接报错，不会静默跳过

Commands

业务与拓扑

search_business

bk-cli cmdb search_business [--bk_biz_id <id> | --bk_biz_ids <id,id,...>] [flags]

• 未显式传 --body 时，必须二选一提供 --bkbizid 或 --bkbizids
• 默认 --fields bkbizid,bkbizname,bkbizmaintainer,bkbizproductor
• 默认 --limit 500
• 默认 --supplier_account 0
• 调用路径：POST /api/v3/open/biz/search/{supplier_account}/

getbizinternal_module

bk-cli cmdb get_biz_internal_module --bk_biz_id <id> [--supplier_account 0]

• 获取业务内置模块（空闲机 / 故障机 / 待回收）
• 调用路径：GET /api/v3/open/topo/internal/{supplieraccount}/{bkbiz_id}

集群与模块

search_set

bk-cli cmdb search_set --bk_biz_id <id> [flags]

• 默认 --fields bksetid,bksetname
• 默认 --limit 500
• 可选过滤：--bksetname、--bksetid
• 调用路径：POST /api/v3/open/set/search/{supplieraccount}/{bkbiz_id}

create_set

bk-cli cmdb create_set --bk_biz_id <id> --bk_set_name <name> [flags]

• 默认 bkparentid = bkbizid
• 默认 settemplateid = 0
• 固定发送 default = 0
• 可选字段：--bksetenv、--bkservicestatus、--bksetdesc、--bk_capacity
• 调用路径：POST /api/v3/open/set/{bkbizid}

search_module

bk-cli cmdb search_module --bk_biz_id <id> --bk_set_id <id> [flags]

• 默认 --fields bkmoduleid,bkmodulename
• 默认 --limit 500
• 可选过滤：--bkmodulename、--bkmoduleid
• 调用路径：POST /api/v3/open/module/search/{supplieraccount}/{bkbizid}/{bkset_id}

create_module

bk-cli cmdb create_module --bk_biz_id <id> --bk_set_id <id> --bk_module_name <name> [flags]

• 默认 bkparentid = bksetid
• 可选字段：--bkmoduletype、--operator、--bkbakoperator、--servicetemplateid、--servicecategoryid
• 调用路径：POST /api/v3/open/module/{bkbizid}/{bksetid}

主机查询

listbizhosts_all

bk-cli cmdb list_biz_hosts_all --bk_biz_id <id> [--bk_set_id <id>] [--bk_module_id <id>] [--page_limit 500]

• 命令会自动循环拉取所有分页结果并聚合返回
• 不暴露 --body
• dry-run 只预览第一页请求，并在 data.pagination 里补充分页元数据
• 调用路径：POST /api/v3/open/hosts/app/{bkbizid}/list_hosts

listbizhosts

bk-cli cmdb list_biz_hosts --bk_biz_id <id> [--host_ips 10.0.0.1,27:10.0.0.2]

• 固定字段：bkhostid,bkhostinnerip,bkcloudid,bkhostname
• --host_ips 用于按 IP 过滤主机
• 调用路径：POST /api/v3/open/hosts/app/{bkbizid}/list_hosts

listhostswithout_biz

bk-cli cmdb list_hosts_without_biz [--host_ips 10.0.0.1,27:10.0.0.2]

• 查询所有业务范围内的主机
• 固定字段：bkhostid,bkhostinnerip,bkcloudid,bkhostname,operator,bkbakoperator
• 调用路径：POST /api/v3/open/hosts/listhostswithout_app

findhostbiz_relations

bk-cli cmdb find_host_biz_relations --bk_host_ids 1,2,3

• 查询主机与业务 / 集群 / 模块关系
• 调用路径：POST /api/v3/open/hosts/modules/read
• 如果上游 data 不是 list，CLI 会规范化输出为空数组 []

listbizhosts_topo

bk-cli cmdb list_biz_hosts_topo --bk_biz_id <id> [--host_ips 10.0.0.1]

• 查询业务主机及拓扑信息
• 固定字段：bkhostid,bkhostinnerip,bkcloudid
• 调用路径：POST /api/v3/open/hosts/app/{bkbizid}/listhoststopo

listresourcepool_hosts

bk-cli cmdb list_resource_pool_hosts [flags]

• 可选：--host_ips、--fields、--start、--limit
• 固定分页排序：page.sort = bkhostid
• 调用路径：POST /api/v3/open/hosts/listresourcepool_hosts

主机转移与删除

transferhostmodule

bk-cli cmdb transfer_host_module --bk_biz_id <id> --bk_host_ids 1,2 --bk_module_ids 20,30 [--is_increment]

• 业务内主机转模块
• 调用路径：POST /api/v3/open/hosts/modules

transferhostacross_biz

bk-cli cmdb transfer_host_across_biz --src_bk_biz_id <id> --dst_bk_biz_id <id> --bk_host_ids 1,2 --bk_module_id 20

• 跨业务转主机
• 调用路径：POST /api/v3/open/hosts/modules/across/biz

transferhosttoidlemodule

bk-cli cmdb transfer_host_to_idle_module --bk_biz_id <id> --bk_host_ids 1,2

• 调用路径：POST /api/v3/open/hosts/modules/idle

transferhosttofaultmodule

bk-cli cmdb transfer_host_to_fault_module --bk_biz_id <id> --bk_host_ids 1,2

• 调用路径：POST /api/v3/open/hosts/modules/fault

transferhosttorecyclemodule

bk-cli cmdb transfer_host_to_recycle_module --bk_biz_id <id> --bk_host_ids 1,2

• 调用路径：POST /api/v3/open/hosts/modules/recycle

transferhosttoresourcepool

bk-cli cmdb transfer_host_to_resource_pool --bk_biz_id <id> --bk_host_ids 1,2 [--bk_module_id 50]

• 上交主机到资源池
• 调用路径：POST /api/v3/open/hosts/modules/resource

delete_host

bk-cli cmdb delete_host --bk_host_ids 100,200

• 删除资源池中的主机
• 调用路径：DELETE /api/v3/open/hosts/batch
• 请求会按接口要求发送 bkhostid 的逗号分隔字符串，例如 100,200

例子

# 先看 dry-run
bk-cli cmdb search_set --bk_biz_id 2 --bk_set_name web --dry-run

# 聚合业务下所有主机
bk-cli cmdb list_biz_hosts_all --bk_biz_id 2 --page_limit 200

# 只查指定云区域和 IP 的主机
bk-cli cmdb list_biz_hosts --bk_biz_id 2 --host_ips 0:10.0.0.1,27:10.0.0.2

# 把主机批量转到指定模块
bk-cli cmdb transfer_host_module \
  --bk_biz_id 2 \
  --bk_host_ids 1,2 \
  --bk_module_ids 20,30

什么时候退回 bk-cli api

下面这些情况更适合直接用原始 API：

• 目标接口还没有对应 cmdb 子命令
• 需要完全自定义 query/body，而不想受现成 flags 语义约束
• 需要先验证完整 method/path/body/header，再逐步收敛成高层命令

示例：

bk-cli api bk-cmdb POST /api/v3/open/hosts/modules \
  --body '{"bk_biz_id":2,"bk_host_id":[1,2],"bk_module_id":[20],"is_increment":false}' \
  --dry-run

常见错误