Skip to content

无人值守模式

Jump to bottom
404tk edited this page May 7, 2026 · 3 revisions

场景定位

ctk 除了交互式 REPL，也提供无人值守 CLI（headless mode）：单条命令完成"枚举 / 创删账户 / 列桶 / 下发命令 / 角色绑定 / 凭据轮换"等动作，便于编排到 CI、验证脚本、Runbook、定时任务里。

无人值守模式与 REPL 共用同一套 provider / payload 实现，差异只在入口与输出：

  • 入口：通过 ctk <provider> <action> 或 ctk <action> -P <profile> 触发，无需进入 REPL
  • 输出：--json 切换为结构化 JSON（适合 SIEM 摄取与脚本消费），默认仍是 REPL 同款表格 / 文本
  • 退出码：明确区分 success / partial / approval / config error / unsupported，便于编排判断

⚠️ 责任使用：headless 模式下脚本不会替你判断资产范围、合规边界与命令安全。把 --yes 写进 CI 之前，请明确该验证流程的目标实例 / 资源 / 身份均已显式授权。

命令形态

ctk                           # 进入 REPL
ctk -h | --help               # 帮助
ctk -v                        # 版本
ctk <provider> <action> [args] [flags]                                  # 显式提供 provider
ctk <action> [args] (-P <profile> | --creds <file> | --stdin) [flags]   # provider 由凭据来源推断

Action 速查

所有 action 都是对应 payload 的快捷形式；--metadata 不与 action 共用（除非通过 REPL 路径直接走 payload）。

资源枚举

Action 对应 payload 用法 说明
ls [resource[,resource...]] cloudlist 列出云资源 不带参数 = 全量；带参数限定类别（balance,host,bucket,...）

写态验证（敏感动作，需 -y）

Action 对应 payload 用法 说明
useradd <username> <password> iam-user-check 创建测试 IAM 用户
userdel <username> iam-user-check 删除测试 IAM 用户
roleadd <principal> <role> [scope] role-binding-check 给身份绑定角色 / 策略 scope 可选（Azure RBAC / GCP project IAM 用）
roledel <principal> <role> [scope] role-binding-check 解绑
expose <bucket> <level> bucket-acl-check 把桶设为公开级 ACL level: public-read / public-read-write / 别名
unexpose <bucket> bucket-acl-check 撤回为 private
keyadd <principal> iam-credential-check 为身份签发长期凭据 输出含 secret，注意保管
keydel <principal> <credentialID> iam-credential-check 撤销凭据
shell <instance-id> <cmd...> -r <region> (-sh | -cmd) instance-cmd-check 单条命令下发 必须带 -r；-sh 走 shell 解释器，-cmd 直接 exec

只读检视

Action 对应 payload 用法 说明
bls [bucket] bucket-check 列出 bucket 对象 不带参数 = list all
bcnt [bucket] bucket-check 统计 bucket 对象数 不带参数 = total all
rolels <principal> role-binding-check 列出身份当前已绑定的角色 / 策略
bacl [bucket] bucket-acl-check 审计桶 ACL 当前状态
keyls <principal> iam-credential-check 列出身份的长期凭据

action 是否在某 provider 上可用，由该 provider 实现的能力接口决定。运行不支持的组合会以退出码 5 报错（<provider> does not support <payload>）。

凭据来源

headless 模式下提供四种互斥的凭据来源，按优先级生效：

  1. -P <profile> / --profile <profile> —— 从已落盘的 会话缓存中按 note 或 UUID 取出。最常用，配合 REPL 里 note <id> <name> 可以给会话起易记名字。
  2. --creds <file> —— 读取一个本地 JSON 文件，格式见下；适合 CI 把凭据挂成 secret 文件。
  3. --stdin —— 从 stdin 读取同样格式的 JSON；适合 vault/secrets manager 的 ... | ctk ... 管道。
  4. 直接传 -k/-s/-r/--clientId 等 provider flag —— 即时凭据，不落盘也不缓存。

--profile / --creds / --stdin 三者会推断 provider，因此可以省略 <provider> 位置参数；-k/-s 等单独使用时必须显式给出 <provider>。

凭据 JSON 文件格式

字段名与 set <key> <value> 对应，一份完整示例：

{
  "provider":   "tencent",
  "accesskey":  "AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE",
  "secretkey":  "Gu5t9xGARNpq86cd98joQYCN3EXAMPLE",
  "token":      "",
  "region":     "ap-guangzhou",
  "version":    "Global"
}

Azure 改用四元组：provider=azure + clientId / clientSecret / tenantId / subscriptionId。GCP 用 provider=gcp + base64Json（base64 后的 service account JSON）。UCloud 用 provider=ucloud + 标准 AK/SK + 可选 projectId。

文件权限建议 0600，避免与他人共享宿主机时泄露。

通用 flags

Flag 作用
--json 切换为 JSON 输出。当前 9 个 payload 全部已实现 ResultProducer，均可走 --json
--quiet 关闭 debug 日志，processbar 仍然到 stderr
-y, --yes 显式授权敏感动作（useradd / userdel / shell / roleadd / roledel / expose / unexpose / keyadd / keydel），缺失则不在 TTY 下直接以退出码 3 拒绝执行
--metadata <value> 直接覆盖 metadata（与 action 互斥，主要给验证脚本兜底）

退出码

Code 含义
0 全部成功
2 部分失败（例如 cloudlist 某些 region 失败但仍有产出）
3 敏感操作未获 --yes 授权
4 配置错误（缺参数、JSON 解析失败、profile 不存在等）
5 当前 provider 不支持该 payload

编排时建议按 0 / 2 / 其他 三档判定：成功、部分成功、需要人介入。

典型用法

资产清单导出（CI 友好）

ctk tencent ls -P lab-tencent --json --quiet > inventory-tencent.json
echo "exit: $?"   # 0 全成功 / 2 部分失败
# 仅取 host 与 bucket 两个类别
ctk tencent ls host,bucket -P lab-tencent --json

创建 / 清理测试 IAM 用户

ctk tencent useradd ctk-validation-user "$(pwgen -s 24 1)" -P lab-tencent -y
# … 跑检测验证 …
ctk tencent userdel ctk-validation-user                    -P lab-tencent -y

角色绑定 / 解绑（验证权限变更检测）

ctk azure roleadd 11111111-2222-3333-4444-000000000099 Reader \
    /subscriptions/<sub>/resourceGroups/lab -P lab-azure -y
ctk azure rolels  11111111-2222-3333-4444-000000000099 -P lab-azure --json
ctk azure roledel 11111111-2222-3333-4444-000000000099 Reader \
    /subscriptions/<sub>/resourceGroups/lab -P lab-azure -y

桶 ACL 暴露面验证

ctk aws bacl                              -P lab-aws --json    # 审计当前 ACL
ctk aws expose ctk-validation public-read -P lab-aws -y         # 切公开（仅 Lab 桶）
ctk aws unexpose ctk-validation           -P lab-aws -y         # 撤回 private

长期凭据生命周期

ctk aws keyls  ctk-bot                          -P lab-aws --json
ctk aws keyadd ctk-bot                          -P lab-aws -y
ctk aws keydel ctk-bot AKIA... -P lab-aws -y

存储桶遥测验证

ctk huawei bls               -P lab-huawei              # 全部 bucket
ctk huawei bls my-validation -P lab-huawei              # 单 bucket
ctk huawei bcnt              -P lab-huawei --json       # 仅统计

单实例下发命令

ctk tencent shell ins-xxxxx123 "id && hostname" -r ap-chengdu -sh -P lab-tencent -y
ctk tencent shell ins-xxxxx123 "uname -a"        -r ap-chengdu -cmd -P lab-tencent -y

Stdin 凭据 + 即时调用（vault 集成示例）

vault kv get -format=json secret/cloud/lab-aws \
  | jq '{provider:"aws", accesskey:.data.data.k, secretkey:.data.data.s, region:"us-east-1"}' \
  | ctk ls --stdin --json

与 REPL 的互通

  • 通过 REPL 跑过一次 run 后产生的会话，可直接被 headless 用 -P <note> 调用：在 REPL 里 note 1 lab-tencent 之后，shell 里 ctk tencent ls -P lab-tencent 即可生效
  • --creds 文件可以由 REPL 的 sessions 列表手工导出，也可以由配置管理工具直接渲染
  • headless 与 REPL 共享 ~/.config/cloudtoolkit/config.yaml，common.timeout_minutes / cloudlist / iam-user-check / rds-account-check 等字段在两边都生效

注意事项

  • 在非 TTY 环境（CI / 管道）下，敏感动作必须通过 -y 显式授权；-y 不会自动转嫁到 nested confirm
  • cloudlist 走 --json 时，部分失败仍会返回完整 result，并以退出码 2 标记
  • --profile 不存在时退出码 4，且会提示 profile not found: <name>，便于 CI fail-fast
  • roleadd / roledel 在不同云上的 scope 语义不同：Azure 走 ARM scope（/subscriptions/<sub>/...）、GCP 走 project ID、AWS scope 字段保留未用

Clone this wiki locally