bk-cli paas — 蓝鲸 PaaS 应用部署能力

用于通过 bk-cli paas 调用蓝鲸 PaaS 应用、模块、部署、日志、进程、环境变量和增强服务相关 API。

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

当前覆盖范围

当前 skill 覆盖以下命令：

• getminimalapp_list
• getappinfo
• listappmodules
• getrepobranches
• getdeploymentslist
• streamshistoryevents
• list_processes
• moduleenvreleased_info
• moduleenvreleased_state
• searchstandardlogwithpost
• create_module
• getdeploymentresult
• deploywithmodule
• createcloudnative_app
• listconfigvars
• getconfigvar
• setconfigvar_value
• listmoduleservices
• bind_service
• getserviceinstancebymodule
• unbind_service

输入约定

• 这些接口都要求应用认证 + 用户认证 + 接口资源权限。调用前需要确保当前 context 的凭据同时满足应用身份和用户身份，并且对应应用已申请这些 API 的接口权限。
• 应用 ID 使用 PaaS 应用 app_code，部分接口按上游原始参数名使用 code。
• 模块名使用 PaaS 模块名称；未指定模块时，通常使用默认模块 default。相关命令已把 module 或 module_name 默认值设为 default。
• 环境参数使用接口原始参数名：env 或 environment，常见值为 stag 或 prod。写操作默认先用 stag，除非用户明确要求 prod。
• deploywithmodule、createmodule、createcloudnativeapp、setconfigvarvalue、bindservice 等复杂请求体通过共享 --body '<json>' 传入；查看完整结构可运行 bk-cli paas <action> -h --body-schema。

常用工作流

1. 用 getminimalapp_list 定位应用 ID。
2. 用 getappinfo 确认应用类型、语言、模块和最近部署时间。
3. 用 listappmodules 确认模块名；用户未指定时优先使用 default。
4. 代码仓库部署前用 getrepobranches 取得 name / type / revision，填入 deploywithmodule 的 --body。
5. 部署后用 getdeploymentslist 找部署任务，再用 streamshistoryevents 查看日志流。
6. 需要看运行态时，用 moduleenvreleasedstate、listprocesses 或 searchstandardlogwithpost。
7. 需要管理环境变量时，用 listconfigvars、getconfigvar、setconfigvar_value。
8. 需要管理增强服务绑定时，用 listmoduleservices、bindservice、getserviceinstancebymodule、unbindservice。
9. 需要创建云原生应用或模块时，分别使用 createcloudnativeapp 或 createmodule。

Commands

getminimalapp_list

bk-cli paas get_minimal_app_list
bk-cli paas get_minimal_app_list --app_status normal --source_origin 1

• 获取当前用户有权限的 App 简明信息列表。
• 调用路径：GET /bkapps/applications/lists/minimal
• 常看字段：results[].application.code、results[].application.name。

getappinfo

bk-cli paas get_app_info --app_code bk-demo

• 查看应用信息。写操作前先调用一次确认 appcode，创建模块前确认 application.type 为 cloudnative。
• 调用路径：GET /bkapps/applications/{app_code}/
• 常看字段：application.type、application.language、application.modules、application.lastdeployeddate。

listappmodules

bk-cli paas list_app_modules --app_code bk-demo
bk-cli paas list_app_modules --app_code bk-demo --source_origin 1

• 查看应用下所有模块。
• 调用路径：GET /bkapps/applications/{app_code}/modules/
• 多模块应用先确认用 default 还是其他模块；is_default=true 表示默认模块。

getrepobranches

bk-cli paas get_repo_branches --app_code bk-demo
bk-cli paas get_repo_branches --app_code bk-demo --module default

• 获取应用模块的代码仓库分支信息。
• 调用路径：GET /bkapps/applications/{app_code}/modules/{module}/repo/branches/
• 返回中 results[].name 对应部署 body 的 versionname，results[].type 对应 versiontype，results[].revision 可填入 revision。
• 纯镜像应用没有仓库；遇到仓库相关错误时改走镜像部署路径，不要反复重试该接口。

getdeploymentslist

bk-cli paas get_deployments_list --app_code bk-demo
bk-cli paas get_deployments_list --app_code bk-demo --environment prod --limit 12 --offset 0

• 获取应用模块部署历史，默认模块为 default。
• 调用路径：GET /bkapps/applications/{app_code}/modules/{module}/deployments/lists/
• 可选 query：environment、operator、limit、offset。
• 返回中 results[].id 或 results[].deploymentid 可作为 streamshistoryevents 的 channelid。

streamshistoryevents

bk-cli paas streams_history_events --channel_id 22d0e9c8-9cfc-45a5-b5a8-718137c515db
bk-cli paas streams_history_events --channel_id 22d0e9c8-9cfc-45a5-b5a8-718137c515db --last_event_id 10

• 获取部署日志流，channel_id 通常就是部署任务 ID。
• 调用路径：GET /streams/{channelid}/historyevents
• 有频控，约每用户 60 秒 10 次；不要 tight loop。

list_processes

bk-cli paas list_processes --app_code bk-demo --env stag
bk-cli paas list_processes --app_code bk-demo --module default --env prod --release_id 123

• 获取应用环境所有进程与实例信息。
• 调用路径：GET /bkapps/applications/{app_code}/modules/{module}/envs/{env}/processes/list/
• 常看字段：replica、实例 Running / ready、重启次数。

moduleenvreleased_info

bk-cli paas module_env_released_info \
  --code bk-demo \
  --environment prod

• 查询应用模块环境部署信息，默认模块为 default。
• 调用路径：GET /bkapps/applications/{code}/modules/{modulename}/envs/{environment}/releasedinfo/

moduleenvreleased_state

bk-cli paas module_env_released_state \
  --code bk-demo \
  --environment prod

• 查询应用模块环境部署状态，比 moduleenvreleasedinfo 多 isofflined、默认访问入口等信息。
• 调用路径：GET /bkapps/applications/{code}/modules/{modulename}/envs/{environment}/releasedstate/
• 常看字段：isofflined、exposedlink.url、defaultaccessentrance.url。从未发布过时上游可能返回 APPNOTRELEASED。

searchstandardlogwithpost

bk-cli paas search_standard_log_with_post \
  --app_code bk-demo \
  --body '{"query":{"query_string":"","terms":{"environment":["stag"]}}}'

bk-cli paas search_standard_log_with_post \
  --app_code bk-demo \
  --module default \
  --time_range customized \
  --start_time '2026-08-24 10:00:00' \
  --end_time '2026-08-24 11:00:00' \
  --body '{"query":{"query_string":"error","terms":{"environment":["prod"],"process_id":["web"]}}}'

• 查询应用标准输出日志，默认模块为 default，默认查询最近 1h。
• 调用路径：POST /bkapps/applications/{appcode}/modules/{module}/log/standardoutput/list/
• 可选 query：timerange、starttime、endtime、limit、scrollid。
• 过滤环境和进程时放在 body 的 query.terms 中，例如 environment 或 process_id。

create_module

bk-cli paas create_module \
  --app_code bk-demo \
  --body '{"name":"api","source_config":{"source_init_template":"dj2_with_auth","source_origin":2},"bkapp_spec":{"build_config":{"build_method":"buildpack"}}}'

• 为云原生应用创建模块。调用前先用 getappinfo 确认应用类型为 cloud_native。
• 调用路径：POST /bkapps/applications/{app_code}/modules/
• 请求体必填字段：name、sourceconfig、bkappspec；常见 buildpack 场景还需在 bkappspec.buildconfig.buildmethod 填 buildpack。完整结构见 bk-cli paas createmodule -h --body-schema。

getdeploymentresult

bk-cli paas get_deployment_result \
  --app_code bk-demo \
  --deployment_id 12345

• 查询部署任务结果，默认模块为 default。
• 调用路径：GET /bkapps/applications/{appcode}/modules/{module}/deployments/{deploymentid}/result/

deploywithmodule

bk-cli paas deploy_with_module \
  --app_code bk-demo \
  --env prod \
  --body '{"revision":"{commit_id}","version_type":"branch","version_name":"master"}'

• 触发支持多模块的 App 部署，默认模块为 default。
• 调用路径：POST /bkapps/applications/{app_code}/modules/{module}/envs/{env}/deployments/
• 请求体字段：revision 为源码仓库版本号，可选；versionname 为 branch 或 tag 名称，必填；versiontype 为版本类型，必填，svn 支持 trunk/tag，git 支持 branch。

createcloudnative_app

bk-cli paas create_cloud_native_app \
  --body '{"code":"bk-demo","name":"bk-demo","source_config":{"source_origin":1,"source_repo_url":"https://github.com/octocat/helloWorld.git","source_repo_auth_info":{},"source_dir":"","source_init_template":"docker"},"bkapp_spec":{"build_config":{"build_method":"dockerfile","dockerfile_path":"Dockerfile"}}}'

• 创建云原生应用。
• 调用路径：POST /bkapps/cloud-native/
• 请求体根字段：code、name、sourceconfig、bkappspec 必填；apptenantmode、authcode、ispluginapp、advancedoptions 按需传入。
• sourceconfig.sourceorigin 表示源码来源，常见值：1 为已授权代码仓库；6 对应上游 SourceOrigin.CNATIVE_IMAGE，表示仅托管镜像的云原生应用。
• bkappspec.buildconfig.buildmethod 支持 buildpack、dockerfile、customimage；dockerfile 场景通常需要 dockerfilepath，customimage 场景需要 image_repository 且通常需要 processes。

listconfigvars

bk-cli paas list_config_vars --app_code bk-demo
bk-cli paas list_config_vars --app_code bk-demo --module default

• 查看应用模块的环境变量列表，默认模块为 default。
• 调用路径：GET /bkapps/applications/{appcode}/modules/{module}/configvars/

getconfigvar

bk-cli paas get_config_var --app_code bk-demo --config_var_key FOO
bk-cli paas get_config_var --app_code bk-demo --module default --config_var_key FOO

• 通过 key 查询单个环境变量，默认模块为 default。
• 调用路径：GET /bkapps/applications/{appcode}/modules/{module}/configvars/{configvarkey}/

setconfigvar_value

bk-cli paas set_config_var_value \
  --app_code bk-demo \
  --config_var_key FOO \
  --body '{"environment_name":"stag","value":"bar","description":"demo config","is_sensitive":false}'

• 通过 key 创建或更新环境变量，默认模块为 default。
• 调用路径：POST /bkapps/applications/{appcode}/modules/{module}/configvars/{configvarkey}/
• 请求体必填字段：environmentname；取值常见为 stag、prod 或 global_。新建变量时同时传 value。
• 敏感变量设置 is_sensitive=true，查询结果中的值可能由上游掩码。

listmoduleservices

bk-cli paas list_module_services --app_code bk-demo
bk-cli paas list_module_services --app_code bk-demo --module default

• 查看应用模块的增强服务，默认模块为 default。
• 调用路径：GET /bkapps/applications/{app_code}/modules/{module}/services/
• 返回通常会按已绑定、共享和未绑定服务分组；绑定前可从未绑定服务中确认 service_id。

bind_service

bk-cli paas bind_service \
  --body '{"code":"bk-demo","service_id":"svc-uuid","module_name":"default"}'

• 绑定应用模块与增强服务。
• 调用路径：POST /services/service-attachments/
• 请求体必填字段：code、serviceid；modulename 不传时由上游按默认模块处理，建议显式传 default。
• 需要指定服务方案时传 planid，需要分环境方案时传 envplanidmap。

getserviceinstancebymodule

bk-cli paas get_service_instance_by_module \
  --app_code bk-demo \
  --service_id svc-uuid

• 查看应用模块与增强服务的绑定关系详情，默认模块为 default。
• 调用路径：GET /bkapps/applications/{appcode}/modules/{module}/services/{serviceid}/

unbind_service

bk-cli paas unbind_service \
  --app_code bk-demo \
  --service_id svc-uuid

• 解绑应用模块与增强服务，默认模块为 default。
• 调用路径：DELETE /bkapps/applications/{appcode}/modules/{module}/services/{serviceid}/
• 解绑是写操作，真实执行前建议先加 --dry-run 确认 app、module 和 service_id。