Sensu 6.15.0 配置参数详解

目标：把 Sensu 6.15.0 的三张配置面——backend 服务端（旗标/backend.yml）、agent 客户端（旗标/agent.yml/环境变量）、check 等资源对象（CheckConfig 字段）——逐条讲透。全部行为与回显在 6.15.0（build 7746）Compose 环境（见部署篇）实测验证，默认值摘自 sensu-backend start --help / sensu-agent start --help 实测输出。

一、参数总览：三张配置面与生效方式

三张面的优先级：agent 侧为 旗标 > 环境变量 > 配置文件；但"实体是否纳入哪个订阅"最终由 backend 存储的实体配置裁决（3.2 节实测）。

二、backend 参数详解

2.1 核心参数表（默认值实测摘录）

💡 技术拓展：api-url 与 api-listen-address 是两个容易被混淆的参数——前者是"宣告给集群成员与 agent 的地址"（相当于对外名片），后者是"实际监听套接字"。单机部署两者可以不一致（如监听 [::]:8080、宣告 http://sensu.example.com:8080）；集群部署时 api-url 错误会导致成员间无法互访，是 3 backend 集群部署最常见的首障点。

2.2 日志级别实测：log-level 的代价

把 log-level 从 info 改为 debug 并重启 backend，实测 30 秒内产生 648 条 debug 日志，内容主要是内嵌 etcd 底层的 bbolt 事务记录：

{"level":"debug","time":"2026-10-20T00:34:57Z","logger":"bbolt","caller":"backend/backend.go:685","msg":"Starting a new transaction [writable: true]"}
{"level":"debug","time":"2026-10-20T00:34:57Z","logger":"bbolt","caller":"bbolt@v1.4.3/db.go:756","msg":"Starting a new transaction [writable: true] successfully"}

结论：debug 级别仅适合短时排障，生产长期开启会带来可观磁盘写入与日志噪音；info 足以覆盖"事件接收（eventd received event）、管道执行（pipelined）、服务启停"等关键链路。

2.3 配置容错行为实测：YAML 宽松、CLI 严格

在 backend.yml 中加入一个不存在的键 bad-key-example: whatever 后重启：backend 正常启动（/health 返回 200，事件照常流转）——YAML 配置文件对未知键静默忽略。而同样的错误用 CLI 旗标传入则立即失败：

sensu-backend start --bad-flag-x

time="2026-10-20T00:35:46Z" level=fatal msg="error executing sensu-backend" component=sensu-enterprise error="unknown flag: --bad-flag-x"

sensu-agent start --bad-flag-x

{"component":"agent","error":"unknown flag: --bad-flag-x","level":"fatal","msg":"error executing sensu-agent","time":"2026-10-20T00:35:46Z"}

运维含义：YAML 方式的拼错键名不会被提示（如把 state-dir 写成 state_dir 会静默丢失该配置），改配置文件后应养成"重启前用 sensuctl/日志复核关键值"的习惯；CLI 方式则天然 fail-fast。

三、agent 参数详解

3.1 核心参数表（默认值实测摘录）

对应的 YAML 键即旗标名去 --（如 backend-url、subscriptions），实测的 agent.yml：

name: web01
namespace: default
backend-url:
  - ws://sensu-backend:8081
subscriptions:
  - linux
  - web
  - db
cache-dir: /var/lib/sensu/sensu-agent

启动方式：sensu-agent start --config-file /etc/sensu/agent.yml，实测日志确认加载成功：

{"component":"agent","level":"info","msg":"configuration successfully validated","time":"2026-10-20T00:36:04Z"}

3.2 实体配置优先级实测（重要）

Sensu 6.x 引入了"实体配置"（entity config）机制：backend 会把存储中的实体配置主动推送给 agent（agent 日志可见 message received ... type: entity_config）。实测结论：一旦实体已在 backend 注册，其订阅等属性以 backend 存储为准，agent 本地的修改（配置文件或 SENSU_SUBSCRIPTIONS 环境变量）不再生效。

对照实验（同一 agent，三种方式全部实测）：

运维含义：

• 改已有 agent 的订阅，正确姿势是改服务端：sensuctl entity update <name>（交互式）或经 API PUT /api/core/v2/entity/<name>，改完 backend 会把新配置推送给 agent；
• "删实体让它重新注册"只在 agent 进程重启后才会按本地配置生成新订阅；
• 这也解释了很多迁移场景的怪现象：换配置文件后"订阅怎么改都不变"——不是配置没生效，是被服务端实体配置覆盖了。

四、CheckConfig 资源参数详解

4.1 核心字段表（实测口径）

4.2 check_hooks 的 6.15 新结构（易踩坑）

老教程（5.x~6.x 早期）的写法是 HookList 对象数组：

check_hooks:
- type: warning
  hooks:
  - collect-diag

该写法在 6.15.0 会解析失败，实测三种错误回显（经 sensuctl create -f 与直连 API 各验证一遍）：

resource 0: json: cannot unmarshal string into Go struct field CheckConfig.check_hooks of type []string
resource 0: json: cannot unmarshal object into Go struct field CheckConfig.check_hooks of type map[string][]string
resource 0: json: cannot unmarshal object into Go struct field CheckConfig.check_hooks of type []v2.HookList

6.15 的正确结构是"数组，每个元素为 {严重级别: [hook 名列表]} 映射"：

check_hooks:
- warning:
  - collect-diag

实测通过后，事件 JSON 的 hooks 数组中可看到 hook 执行明细：

"hooks": [{"metadata": {"name": "collect-diag", "namespace": "default"},
  "command": "sh -c 'echo hook-fired-ok'",
  "duration": 0.001610176, "executed": 1792457321,
  "output": "hook-fired-ok\n", "status": 0}]

注意：sensuctl event info 的表格视图不展示 hook 输出（实测仅有 Output/Status/History 等行），需经 API 查看事件 JSON 才能看到 hooks[].output——排障时别在 CLI 表格里找。

4.3 完整可用的 check 资源模板（实测文件）

以下即本文实测通过的三段式资源文件（hook + handler + check 引用），可直接 sensuctl create -f 复用：

---
type: HookConfig
api_version: core/v2
metadata:
  name: collect-diag
  namespace: default
spec:
  command: sh -c 'echo hook-fired-ok'
  timeout: 10
---
type: Handler
api_version: core/v2
metadata:
  name: log-events
  namespace: default
spec:
  type: pipe
  command: cat >> /var/lib/sensu/sensu-backend/handled.log
  timeout: 10
---
type: CheckConfig
api_version: core/v2
metadata:
  name: check_tmp_flag
  namespace: default
spec:
  command: test -f /tmp/healthy
  subscriptions:
  - linux
  interval: 10
  publish: true
  timeout: 10
  handlers:
  - log-events
  check_hooks:
  - warning:
    - collect-diag

端到端实测结果：check 持续失败（status 1）→ warning hook 每次执行（hooks[].output = "hook-fired-ok"）→ 事件送 log-events handler，backend 侧执行 cat >>，事件 JSON 全文落盘到 backend-data/handled.log（宿主机 bind mount 目录直接可见，8.3KB 实测）。

五、生产参数模板

5.1 backend.yml（4C8G、SSD、数百节点内）

state-dir: /var/lib/sensu/sensu-backend
api-url: http://sensu.example.com:8080
log-level: info
access-token-expiry: 1h
agent-burst-limit: 100
agent-rate-limit: 0

参数依据：access-token-expiry 从 5m 调到 1h，减少 sensuctl/自动化的重认证频率（5m 默认值实测会频繁触发 401，见部署篇 FAQ）；agent-burst-limit 给突发接入（如大批量节点重启后同时重连）一个 100 的削峰阀；agent 数百节点内无需动 etcd 调参，超千节点直接上 3 backend 集群。

5.2 agent.yml（生产节点）

name: web01
namespace: default
backend-url:
  - wss://sensu.example.com:8081
  - wss://sensu2.example.com:8081
subscriptions:
  - linux
  - web
deregister: false

参数依据：双 backend-url 实现故障转移；生产走 wss://（TLS 由 cert-file/trusted-ca-file 支撑）；deregister 按节点生命周期取舍——弹性云节点 true（自动注销），稳态虚机 false（避免误删历史数据）。

5.3 指标与告警分流的 check 模板

---
type: CheckConfig
api_version: core/v2
metadata:
  name: check_mem_metrics
  namespace: default
spec:
  command: free -m
  subscriptions: [linux]
  interval: 30
  timeout: 10
  output_metric_format: nagios_perfdata
  output_metric_handlers: [influxdb]

（influxdb handler 需另行以 asset 方式安装官方 sensu-influxdb-handler，见命令篇。）

六、常见问题（FAQ）

6.1 check_hooks 按老教程写法创建报错？

见 4.2：6.15 已把 check_hooks 从 [{type, hooks}] 改为 [{"级别": [hook 名]}]。报错形如 cannot unmarshal string into Go struct field CheckConfig.check_hooks of type []string 时，先检查结构而不是字段名。

6.2 sensuctl 频繁 401、refresh token 失效？

backend access-token-expiry 默认 5 分钟，backend 重启会使已签发的 refresh token 失效。处理：重新 sensuctl configure；长期方案调大 access-token-expiry（如 1h）或脚本改用 API Key 认证（Authorization: Key 头，无过期问题）。

6.3 改了 agent 订阅为什么不生效？

见 3.2：已注册实体以 backend 存储的实体配置为准。用 sensuctl entity update 服务端修改，或删实体并重启 agent 让其按本地配置重新注册。

6.4 timeout 触发后状态为什么是 CRITICAL 而不是 WARNING？

实测 Execution timed out 事件 status=2。Sensu 把"超时"视为比"命令返回 1"更严重的情况（命令可能已失控），排障时注意别把超时事件按 warning 分级路由。

6.5 backend.yml 改了个键但行为没变？

YAML 未知键静默忽略（2.3 实测），先确认键名拼写与官方参考一致（- 连字符而非下划线），再确认改后是否重启了进程。

七、参考链接

• backend 参考（旗标全集）：https://docs.sensu.io/sensu-go/latest/reference/backend/
• agent 参考：https://docs.sensu.io/sensu-go/latest/reference/agent/
• check 参考：https://docs.sensu.io/sensu-go/latest/reference/checks/
• hooks 参考：https://docs.sensu.io/sensu-go/latest/reference/hooks/
• 本专栏相关：《Sensu 6.15.0 介绍与选型指南》《Sensu 6.15.0 Docker Compose 部署指南》《Sensu 6.15.0 常用 CLI 命令详解》（同批次发布于 Sensu 专栏）