Sensu 6.15.0 常用 CLI 命令详解
Sensu 6.15.0 常用 CLI 命令详解：sensuctl 6.15.0 命令树逐条实测——configure/config view/dump/create/delete/env 等基础命令，check execute（ad-hoc 触发）、event resolve、silenced 生命周期、asset add（Bonsai 拉取+runtime_assets 懒加载闭环）、user/role/role-binding/api-key（含只读账号读写越权实证）、cluster health 等集群命令，并实测 license 未授权、tessen 残留命令、delete -f 需带 spec 等真实细节。
Sensu 6.15.0 常用 CLI 命令详解
目标：把 sensuctl（Sensu 管理命令行）6.15.0 的命令树逐条实测讲清：每条命令给语法与真实回显。测试环境为部署篇的 Compose 栈（backend 容器内执行
sensuctl，已sensuctl configure -n --username admin --password q1w2e3r4 --url http://127.0.0.1:8080）。sensuctl version实测回显6.15.0+ee, build 9123ba5dc1a881ac522812512c9e46ba8b99d522, built 2026-10-12T10:24:41Z, built with go1.26.8。
一、命令树总览
sensuctl --help 实测输出（6.15.0 顶层共 41 条命令，按用途分组）：
| 分组 | 命令 |
|---|---|
| 连接与配置 | configure、config、env、login、logout、command |
| 资源批量操作 | create、delete、dump、edit、prune、describe-type |
| 监控对象 | check、entity、event、asset、handler、hook、filter、mutator、silenced、namespace、pipeline、fallback_pipeline、secret |
| 用户与权限 | user、role、cluster-role、role-binding、cluster-role-binding、api-key、auth |
| 集群与平台 | cluster、license、tessen、loglevel、version、completion |
通用全局旗标（所有命令可用）：--api-url（API 地址）、--api-key（API Key 认证，适合脚本）、--namespace（限定命名空间）、--config-dir/--cache-dir（配置与缓存目录，多账号切换用）、--format（tabular/yaml/json 包装格式）、--timeout（默认 15s）。
二、连接与配置类命令
2.1 sensuctl configure（连接初始化）
sensuctl configure -n --username admin --password q1w2e3r4 --url http://127.0.0.1:8080
-n（--non-interactive）跳过问答；不带旗标则进入交互向导。配置写在其 --config-dir（默认 ~/.config/sensu/sensuctl）。token 由 GET /auth 签发，默认 5 分钟过期（backend access-token-expiry），过期后 sensuctl 自动用 refresh token 续期，backend 重启会使续期失败报 401——重新 configure 即可。
2.2 sensuctl config view / env / completion
sensuctl config view
=== Active Configuration
API URL: http://127.0.0.1:8080
Namespace: default
Format: tabular
Timeout: 15s
Username: admin
JWT Expiration Timestamp: 1792457220
sensuctl env
export SENSU_API_URL="http://127.0.0.1:8080"
export SENSU_NAMESPACE="default"
export SENSU_FORMAT="tabular"
export SENSU_API_KEY=""
env 输出可直接 eval 注入脚本环境；completion bash 输出 shell 补全脚本（source <(sensuctl completion bash) 生效）。
三、资源批量操作类命令
3.1 sensuctl create（声明式创建/更新）
sensuctl create -f checks.yml
成功无输出（退出码 0）。资源文件为"包裹格式"（type/api_version/metadata/spec），create 语义是替换式更新——同名资源整体覆盖，因此 YAML 里漏写的字段会被重置为默认，这是最需要警惕的坑（例如忘了写 handlers 就会把已有 handler 清空）。支持 file://、http(s):// 与 STDIN。
💡 6.15 结构注意：check_hooks 等字段的 JSON 结构与老版本教程不同（
[{"warning": ["hook名"]}]），写错时报错形如cannot unmarshal string into Go struct field CheckConfig.check_hooks of type []string，且错误信息对结构的提示有误导性——排障时以"数组内放映射、映射键为严重级别"为准（详见配置篇 4.2）。
3.2 sensuctl delete（按文件删除）
sensuctl delete -f del.yml
实测要点：文件必须带 spec 块，只有 type/api_version/metadata 会报 no spec provided：
type: CheckConfig
api_version: core/v2
spec:
metadata:
name: check_publish_off
namespace: default
实测输出 DEL_FILE_OK，sensuctl check list 确认资源消失。
3.3 sensuctl dump（全量导出，GitOps 素材）
sensuctl dump checks --format yaml | head -8
type: CheckConfig
api_version: core/v2
metadata:
created_by: admin
labels:
sensu.io/managed_by: sensuctl
name: check_api_health
namespace: default
资源类型名用复数短名（checks/entities/events/handlers/…，全表见 sensuctl describe-type），可一次 dump 多类：sensuctl dump checks,entities --format yaml。备份或 CI 同步时的标准输出格式。
3.4 sensuctl describe-type（类型速查）
sensuctl describe-type core/v2.CheckConfig
Fully Qualified Name Short Name API Version Type Namespaced
─────────────────────── ──────────── ───────────── ───────────── ─────────────
core/v2.CheckConfig checks core/v2 CheckConfig true
不带参数执行列出全部可用资源类型（含 enterprise 的 bsm/datastore 等）。
四、监控对象命令逐条精讲
4.1 check（check 定义管理 + ad-hoc 触发）
子命令：list/info/create/update/delete/set-hooks/remove-hooks/execute。
sensuctl check list
Name Command Interval Cron Timeout Subscriptions Handlers Assets Namespace
─────────────── ──────────────────────────────────────────────────────── ────────── ────── ───────── ─────────────── ────────── ──────── ───────────
check_api_health curl -s -o /dev/null -w '%{http_code}' http://…:8080/health 15 10 linux default
check_http_health http-check --url http://sensu-backend:8080/health 30 15 linux default
check_tmp_flag test -f /tmp/healthy 10 10 linux log-events default
check_uptime uptime 10 10 linux default
ad-hoc 立即触发（不用等调度周期）：
sensuctl check execute check_uptime --subscriptions linux --reason "manual adhoc test"
Issued
--subscriptions 可临时覆盖执行范围；--reason 记录触发原因（审计友好）。check delete NAME --skip-confirm 删除（实测 Deleted；不加 --skip-confirm 会交互确认）。
4.2 entity（实体管理）
子命令：list/info/update/delete。
sensuctl entity list
ID Class OS Subscriptions Last Seen
──────── ──────── ──────── ─────────────────────────────── ────────────────────────────────
sensu-api proxy entity:sensu-api N/A
web01 agent linux linux,web,entity:web01 2026-10-20 00:44:47 +0000 UTC
entity info web01 --format yaml 输出完整实体对象；entity delete web01 --skip-confirm 删除后 agent 存活期内会自动重注册（详见配置篇 3.2 的实体配置优先级规则）；entity update 为交互式改订阅/标签，是改"已注册 agent 订阅"的正确入口。
4.3 event（事件查询与处置）
子命令：list/info/delete/resolve。
sensuctl event list
Entity Check Output Status Silenced Timestamp UUID
──────────── ────────────────── ───────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ───────────────────────────────────────
sensu-api check_api_health 200 0 false 2026-10-20 00:43:19 +0000 UTC c4927ddd-cc22-412f-87bc-6cdceeab9ffe
web01 check_tmp_flag 1 false 2026-10-20 00:43:20 +0000 UTC 1af876c3-f84e-4414-8a3b-2acaee1463ac
web01 check_uptime 00:43:15 up 8:55, 0 users, load average: 1.52, 1.60, 1.58 0 false 2026-10-20 00:43:15 +0000 UTC 5b7e04f6-e1b9-4642-9b8f-0bda4a582f4a
web01 keepalive Keepalive last sent from web01 at 2026-10-20 00:43:13 +0000 UTC 0 false 2026-10-20 00:43:13 +0000 UTC 862a3170-3512-4d2c-b0ec-01e6ee106975
要点：状态码 0/1/2/≥3 对应 OK/WARNING/CRITICAL/UNKNOWN；表格视图不展示 hook 输出（event info web01 check_tmp_flag 只有 Output/Status/History/Silenced/Timestamp/UUID 七行），hook 执行结果要看事件 JSON 的 hooks[] 字段（经 API 或 event info --format yaml 可取）。
处置命令 resolve（把当前故障事件标记为已处理）：
sensuctl event resolve web01 check_tmp_flag
Resolved
实测语义：resolve 只作用于当前事件快照（状态立即归 0），下一个调度周期 check 仍失败时会产生新的故障事件——它是"人工确认+静默等待"的组合拳第一步，抑制后续告警要配合 silenced（4.8）。
4.4 asset（运行时依赖管理，Bonsai 生态入口）
sensuctl asset add sensu/http-checks:0.5.0
You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["sensu/http-checks"].
sensuctl asset list
Name URL Hash
──────────────────── ───────────────────────────────────────────────────────────────────── ──────────
sensu/http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_darwin_amd64.tar.gz 38e6cb8
sensu/http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_amd64.tar.gz bc5fc3b
…（共 6 个平台构建，含 windows/arm64/armv7/386）
实测完整闭环：asset add 从 Bonsai 解析出 6 个平台构建 → check 声明 runtime_assets: [sensu/http-checks] → agent 首次调度该 check 时懒加载下载对应平台包并执行，实测事件输出：
http-check OK: HTTP Status 200 for http://sensu-backend:8080/health Status: 0
版本号必须合法 semver（sensu/monitoring-plugins:2.2.0-check_cpu 实测报 Malformed version）。资产名格式 组织/资产名:版本，Bonsai 资产目录 https://bonsai.sensu.io。
4.5 handler（事件处置器）
sensuctl handler list
实测通过 YAML 创建的 pipe handler（type: pipe、command: cat >> /var/lib/sensu/sensu-backend/handled.log）在 check_tmp_flag 每次失败时触发，事件 JSON 全文追加到文件（bind mount 下宿主机可直接读）。子命令 list/info/create/update/delete；handler 类型 pipe/tcp/udp/set，set 用于编排多个 handler。
4.6 hook（检查钩子）
sensuctl hook list
HookConfig 定义（command: sh -c 'echo hook-fired-ok'）经 check 的 check_hooks: [{"warning": ["collect-diag"]}] 挂接后，实测每次 check 落入 warning 时执行，输出出现在事件 JSON 的 hooks[].output（"hook-fired-ok\n"，status 0）。子命令 list/info/create/update/delete。
4.7 filter（事件过滤器）
sensuctl filter create critical-only --action allow --expressions "event.check.status == 2"
sensuctl filter list
Name Action Expressions
──────────────── ──────── ────────────────────────────
critical-only allow (event.check.status == 2)
表达式语言为 jewelscript，--action allow/deny 控制放行/拦截；内建过滤器（is_incident、not_during 等）无需自建。
4.8 silenced（静默管理）
sensuctl silenced create --subscription entity:web01 --check check_tmp_flag --reason "maintenance window" --expire 600
sensuctl silenced list
Name Subscription Check Begin Expiration ExpireOnResolve Creator Reason Namespace
────────────────────────────── ────────────── ──────────────── ────────────────────── ───────────────── ───────────────── ───────── ──────────────────── ────────────
entity:web01:check_tmp_flag entity:web01 check_tmp_flag 2026-10-20T00:51:14Z 2026-10-20T01:01:14Z false admin maintenance window default
实测：静默创建后 10 分钟内该实体+check 的事件在 event list 中 Silenced 列显示 true（handler 将跳过通知）；删除按"名称"（即 订阅:check 组合串）执行：
sensuctl silenced delete entity:web01:check_tmp_flag --skip-confirm
Deleted
--expire -1（默认）表示永不自动过期；--expire-on-resolve 在事件恢复时自动清除静默；只静默整个订阅时不传 --check 即可。
4.9 namespace（命名空间）
sensuctl namespace create ops-ns && sensuctl namespace list && sensuctl namespace delete ops-ns --skip-confirm
Created
Name
────────────────
default
ops-ns
sensu-system
Deleted
默认命名空间为 default；sensu-system 是系统级命名空间（keepalive 等内部事件）。全局旗标 --namespace 切换操作目标。
五、用户与权限命令
5.1 user（账号生命周期）
sensuctl user create ops01 --password "Ops123456!" # 创建
sensuctl user disable ops01 --skip-confirm # 禁用（实测 Enabled 列变 false）
sensuctl user reinstate ops01 # 复用（实测 Reinstated）
sensuctl user change-password ops01 -c "Ops123456!" -p "NewPass123!" # 改密（-c 当前密码必填）
sensuctl user list
Username Groups Enabled
─────────── ──────────────── ──────────
admin cluster-admins true
agent system:agents true
ops01 true
实测细节：change-password 必须同时给 -c/--current-password 与 -p/--new-password，缺当前密码直接报错（Error: current password must be provided）；disable 用 --skip-confirm 跳确认，reinstate 为交互确认（echo y | 可脚本化）。
5.2 role / role-binding（命名空间级 RBAC 三件套）
sensuctl role create viewer-ops --verb get,list --resource events,entities,checks
sensuctl role-binding create viewer-ops-binding --role viewer-ops --user ops01
sensuctl role list && sensuctl role-binding list
Created
Name Namespace Rules
──────────────── ──────────── ──────────
system:pipeline default 1
viewer-ops default 1
Name Namespace Cluster Role Role Subjects
───────────────────── ──────────── ────────────── ───────────────── ───────────
system:pipeline default system:pipeline 1
viewer-ops-binding default viewer-ops 1
注意旗标名是 --verb（单数，可用逗号分隔多个值）与 --resource，不是 --verbs/--resources（实测报 unknown flag: --verbs）。集群级对应 cluster-role/cluster-role-binding，语法一致。
权限边界实证：用 ops01 在独立配置目录连接后实测——只读角色可 event list（正常输出表格），执行写操作被拒：
sensuctl check delete check_publish_off --skip-confirm --config-dir /tmp/ops01-config
Error: unauthorized to perform action
5.3 api-key（脚本认证首选）
sensuctl api-key grant admin
sensuctl api-key list
Created: /api/core/v2/apikeys/e51d1fcf-186c-41e7-811b-17348ac9769d
Name Username Created At
─────────────────────────────────────── ────────── ────────────────────────────────
e51d1fcf-186c-41e7-811b-17348ac9769d admin 2026-10-20 00:27:44 +0000 UTC
a098ff1d-15e2-43a8-9595-b7c51b51e33d admin 2026-10-20 00:28:23 +0000 UTC
路径末段 UUID 即 Key。调用 API 时认证头是 Authorization: Key <uuid>（Bearer 头仅用于 JWT；实测用错会返回 invalid credentials）。sensuctl 自身也可直接用：全局旗标 --api-key <uuid> 免去 5 分钟 token 过期问题。
六、集群与平台类命令
sensuctl cluster health
=== Etcd Cluster ID: 1c45a069f3a1d796
ID Name Error Healthy
─────────────────── ───────── ─────── ──────────
b71f75320dc06a6c default true
sensuctl cluster id
sensuctl cluster member-list
sensu cluster id: "13ef8631-9c0e-4aa9-bbe9-cecdf85cdc41"
=== Etcd Cluster ID: 1c45a069f3a1d796
ID Name Peer URLs Client URLs
───────────────── ───────── ─────────────────────── ────────────────────────
b71f75320dc06a6c default http://127.0.0.1:2380 http://localhost:2379
单成员即单 backend；member-add/member-remove/member-update 用于扩缩 etcd 成员（对应多 backend 集群部署）。
其余平台命令实测结论：
sensuctl license info→Error: not found：未安装企业许可证时的状态（deb 包为 EE 构建号，商业特性按需解锁，社区功能免许可可用）；sensuctl tessen list→unknown command "list"：Tessen 数据上报已在近期版本彻底移除，该命令组只剩壳（配置篇与选型篇有详述）；sensuctl loglevel view --component agentd等可在线查看/调整 backend 各组件运行时日志级别，免重启排障；sensuctl mutator list、sensuctl pipeline list、sensuctl secret：管道增强类资源，语法与 check/handler 一致（list/info/create/delete）。
七、常见问题（FAQ）
7.1 命令执行突然 401？
access token 默认 5 分钟过期 + backend 重启导致 refresh 失效（实测报 failed to request new refresh token; client returned 'The server returned the error: 401 Unauthorized'）。重新 sensuctl configure，或全局改用 --api-key。
7.2 删除类命令卡在确认？
所有交互确认都可用 --skip-confirm 跳过（entity delete、check delete、user disable、silenced delete、namespace delete 均实测）；个别命令（如 user reinstate）无该旗标，用 echo y | 管道注入。
7.3 create -f 成功但字段"丢了"？
create 是替换式更新：YAML 未写的字段被重置为默认。更新前先 sensuctl check info <name> --format yaml（或 dump）取全量，改完再提交；CI 中建议以 dump 导出为唯一事实源。
7.4 输出格式怎么选？
全局 --format tabular|yaml|json（或 --format wrapped-json）：人看用 tabular，管道加工用 yaml/json；配合 --all-namespaces 可跨命名空间导出。
八、参考链接
- sensuctl 官方参考：https://docs.sensu.io/sensu-go/latest/sensuctl/reference/
- API Key 认证：https://docs.sensu.io/sensu-go/latest/api/core/apikeys/
- Bonsai 资产仓库：https://bonsai.sensu.io
- 本专栏相关：《Sensu 6.15.0 介绍与选型指南》《Sensu 6.15.0 Docker Compose 部署指南》《Sensu 6.15.0 配置参数详解》（同批次发布于 Sensu 专栏）