tencentblueking 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 命令：
get_biz_internal_modulesearch_businesssearch_setcreate_setsearch_modulecreate_modulelist_biz_hosts_alllist_biz_hostslist_hosts_without_bizfind_host_biz_relationslist_biz_hosts_topotransfer_host_moduletransfer_host_across_biztransfer_host_to_idle_moduletransfer_host_to_fault_moduletransfer_host_to_recycle_moduletransfer_host_to_resource_poollist_resource_pool_hostsdelete_host
后续如果新增更多 cmdb 子命令，应继续追加到本 skill 的 ## Commands 章节，而不是拆成新的单命令 skill。
推荐工作流
- 先确认目标是否已经有现成
cmdb子命令。 - 如果已有现成子命令，优先使用该命令，而不是直接退回原始
bk-cli api。 - 首次调用或排障时，优先先加
--dry-run看最终 URL、headers 和 body。 - 如果现成子命令还不能覆盖你的目标接口，再退回
bk-cli api bk-cmdb ...。
输入约定
通用规则
- 大多数
cmdb命令都支持--stage、--header、--body；list_biz_hosts_all例外，不暴露--body。 - 当显式传入
--body '<json>'时，请求会以该 JSON 为准，不再使用命令自带的默认请求内容。 - 这些
cmdb命令通常要求可满足 app+user 的凭据；若当前 context 使用access_token，也可满足非空认证要求。
CSV 列表参数
当前 cmdb 的列表型输入统一优先使用 CSV 风格 flags：
--bk_biz_ids 1,2,3--bk_host_ids 100,200--bk_module_ids 20,30--fields bk_host_id,bk_host_innerip
--host_ips 规则
- 形态一：
10.0.0.1 - 形态二：
27:10.0.0.2 - 含义：
cloud_id:ip；未写前缀时默认cloud_id=0 - 只要有一个非法项，命令会直接报错，不会静默跳过
Commands
业务与拓扑
search_business
bk-cli cmdb search_business [--bk_biz_id <id> | --bk_biz_ids <id,id,...>] [flags]
- 未显式传
--body时，必须二选一提供--bk_biz_id或--bk_biz_ids - 默认
--fields bk_biz_id,bk_biz_name,bk_biz_maintainer,bk_biz_productor - 默认
--limit 500 - 默认
--supplier_account 0 - 调用路径：
POST /api/v3/open/biz/search/{supplier_account}/
get_biz_internal_module
bk-cli cmdb get_biz_internal_module --bk_biz_id <id> [--supplier_account 0]
- 获取业务内置模块（空闲机 / 故障机 / 待回收）
- 调用路径：
GET /api/v3/open/topo/internal/{supplier_account}/{bk_biz_id}
集群与模块
search_set
bk-cli cmdb search_set --bk_biz_id <id> [flags]
- 默认
--fields bk_set_id,bk_set_name - 默认
--limit 500 - 可选过滤：
--bk_set_name、--bk_set_id - 调用路径：
POST /api/v3/open/set/search/{supplier_account}/{bk_biz_id}
create_set
bk-cli cmdb create_set --bk_biz_id <id> --bk_set_name <name> [flags]
- 默认
bk_parent_id = bk_biz_id - 默认
set_template_id = 0 - 固定发送
default = 0 - 可选字段：
--bk_set_env、--bk_service_status、--bk_set_desc、--bk_capacity - 调用路径：
POST /api/v3/open/set/{bk_biz_id}
search_module
bk-cli cmdb search_module --bk_biz_id <id> --bk_set_id <id> [flags]
- 默认
--fields bk_module_id,bk_module_name - 默认
--limit 500 - 可选过滤：
--bk_module_name、--bk_module_id - 调用路径：
POST /api/v3/open/module/search/{supplier_account}/{bk_biz_id}/{bk_set_id}
create_module
bk-cli cmdb create_module --bk_biz_id <id> --bk_set_id <id> --bk_module_name <name> [flags]
- 默认
bk_parent_id = bk_set_id - 可选字段：
--bk_module_type、--operator、--bk_bak_operator、--service_template_id、--service_category_id - 调用路径：
POST /api/v3/open/module/{bk_biz_id}/{bk_set_id}
主机查询
list_biz_hosts_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/{bk_biz_id}/list_hosts
list_biz_hosts
bk-cli cmdb list_biz_hosts --bk_biz_id <id> [--host_ips 10.0.0.1,27:10.0.0.2]
- 固定字段：
bk_host_id,bk_host_innerip,bk_cloud_id,bk_host_name --host_ips用于按 IP 过滤主机- 调用路径：
POST /api/v3/open/hosts/app/{bk_biz_id}/list_hosts
list_hosts_without_biz
bk-cli cmdb list_hosts_without_biz [--host_ips 10.0.0.1,27:10.0.0.2]
- 查询所有业务范围内的主机
- 固定字段：
bk_host_id,bk_host_innerip,bk_cloud_id,bk_host_name,operator,bk_bak_operator - 调用路径：
POST /api/v3/open/hosts/list_hosts_without_app
find_host_biz_relations
bk-cli cmdb find_host_biz_relations --bk_host_ids 1,2,3
- 查询主机与业务 / 集群 / 模块关系
- 调用路径：
POST /api/v3/open/hosts/modules/read - 如果上游
data不是 list，CLI 会规范化输出为空数组[]
list_biz_hosts_topo
bk-cli cmdb list_biz_hosts_topo --bk_biz_id <id> [--host_ips 10.0.0.1]
- 查询业务主机及拓扑信息
- 固定字段：
bk_host_id,bk_host_innerip,bk_cloud_id - 调用路径：
POST /api/v3/open/hosts/app/{bk_biz_id}/list_hosts_topo
list_resource_pool_hosts
bk-cli cmdb list_resource_pool_hosts [flags]
- 可选：
--host_ips、--fields、--start、--limit - 固定分页排序：
page.sort = bk_host_id - 调用路径：
POST /api/v3/open/hosts/list_resource_pool_hosts
主机转移与删除
transfer_host_module
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
transfer_host_across_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
transfer_host_to_idle_module
bk-cli cmdb transfer_host_to_idle_module --bk_biz_id <id> --bk_host_ids 1,2
- 调用路径：
POST /api/v3/open/hosts/modules/idle
transfer_host_to_fault_module
bk-cli cmdb transfer_host_to_fault_module --bk_biz_id <id> --bk_host_ids 1,2
- 调用路径：
POST /api/v3/open/hosts/modules/fault
transfer_host_to_recycle_module
bk-cli cmdb transfer_host_to_recycle_module --bk_biz_id <id> --bk_host_ids 1,2
- 调用路径：
POST /api/v3/open/hosts/modules/recycle
transfer_host_to_resource_pool
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 - 请求会按接口要求发送
bk_host_id的逗号分隔字符串，例如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
常见错误
| 错误表现 | 常见原因 | 建议 |
|---|---|---|
one of bk_biz_id or bk_biz_ids is required when --body is not provided |
search_business 未传 --body，同时也没传 --bk_biz_id / --bk_biz_ids |
补一个业务过滤条件，或改为显式传 --body |
host_ips contains an invalid host entry |
--host_ips 里有非法 token |
改成 10.0.0.1,27:10.0.0.2 这种格式 |
bk_host_ids must be a comma-separated list of integers |
--bk_host_ids 含空值、非数字或负数 |
改成 1,2,3 这种格式 |
supplier_account cannot be empty |
--supplier_account 为空字符串 |
使用 0 或明确的 supplier account |
| 鉴权失败 / forbidden | 凭据不满足 open API 认证要求，或应用缺少权限 | 先看 shared skill 的认证规则，再核对当前 context 的凭据和权限 |