Sensu 6.15.0 Docker Compose 部署指南

目标：用 Docker Compose 部署 Sensu 6.15.0 监控管道（backend + agent 两个服务），完成初始化、被监控节点自动注册、check 事件端到端流转（含 proxy check 与故障恢复演练）、REST API 取证与数据持久化验证。本文全部命令与回显在 Ubuntu 22.04（Docker 28 + Compose v2）实测通过，部署目录 /opt/sensu-compose。

一、环境信息

操作系统：Ubuntu 22.04（x86_64，内核 5.15+）
Docker：28.x，Docker Compose v2（docker compose 子命令形态）
Sensu 版本：6.15.0（官方 deb 包构建号 7746，sensuctl version 实测回显 6.15.0+ee, build 9123ba5dc1a881ac522812512c9e46ba8b99d522, built 2026-10-12T10:24:41Z, built with go1.26.8）
实测部署目录：/opt/sensu-compose（含 docker-compose.yml、backend.yml、checks.yml、backend-data/、agent-data/）
端口规划：

宿主机端口	容器端口	用途
8131	3000	Web UI 端口（6.15.0 社区版无免费 UI，见 4.7 节实测说明）
8133	8080	REST API（sensuctl 与外部集成对接）
不映射	8081	agent 长连接端口，仅 compose 内网使用
不映射	2379/2380	内嵌 etcd 客户端/集群端口，仅容器内部使用

说明：8080/3000 在宿主机常被占用，本文统一映射到 8131/8133 高位端口；若读者环境这两个端口空闲，也可按官方模板直接映射 3000/8080。

二、镜像选型说明

Sensu 官方提供两种落地形态，本文实测采用第二种：

形态	说明	适用
官方镜像 `sensu/sensu:6.15.0`（Docker Hub）	单镜像包含 sensu-backend/sensu-agent/sensuctl 三个二进制，入口脚本内置初始化逻辑	可直连 Docker Hub 的环境
官方 deb 自建镜像	从官方软件仓库 packagecloud（`sensu/stable`）下载 `sensu-go-backend/agent/cli_6.15.0-7746_amd64.deb`，基于 `ubuntu:22.04` 构建	内网/镜像源受限环境，离线可复现

官方 deb 下载地址（实测可用，HTTP 200）与校验值（sha256sum 实测）：

https://packagecloud.io/sensu/stable/packages/ubuntu/jammy/sensu-go-backend_6.15.0-7746_amd64.deb/download.deb
https://packagecloud.io/sensu/stable/packages/ubuntu/jammy/sensu-go-agent_6.15.0-7746_amd64.deb/download.deb
https://packagecloud.io/sensu/stable/packages/ubuntu/jammy/sensu-go-cli_6.15.0-7746_amd64.deb/download.deb

f2848edec440f53345ff121b1131bc02666206e2999749e81a28f28a9384222c  sensu-go-agent_6.15.0-7746_amd64.deb
f9f55d6f9350a0bc426fcbc8a6cb70f4adeefe8633d4b518cb4aaa9ff00505cb  sensu-go-backend_6.15.0-7746_amd64.deb
a2d9ccebcd93be53a35b5af5b75fe567ae9c57ba0406ef5fd0df74071952a564  sensu-go-cli_6.15.0-7746_amd64.deb

自建镜像的 Dockerfile（实测构建通过）：

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl && rm -rf /var/lib/apt/lists/*
COPY sensu-go-backend_6.15.0-7746_amd64.deb sensu-go-agent_6.15.0-7746_amd64.deb sensu-go-cli_6.15.0-7746_amd64.deb /tmp/
RUN dpkg -i /tmp/*.deb && rm -f /tmp/*.deb

docker build -t sensu-local:6.15.0 .
# 实测输出（节选）：naming to docker.io/library/sensu-local:6.15.0 done

💡 说明：deb 包内二进制为 6.15.0+ee 构建（企业版构建号，商业特性由许可证解锁，社区功能免费可用），这是 Sensu 官方唯一分发渠道的统一形态，与 GitHub 仓库的 MIT 开源代码同源。镜像内含 curl，供后续 HTTP 探测型 check 使用。

三、前置条件

宿主机已安装 Docker 28+ 与 Compose v2（docker compose version 可执行）；
宿主机端口 8131/8133 空闲（ss -ltn | grep -E '8131|8133' 无输出即空闲）；
目录规划：/opt/sensu-compose 作为部署目录，数据子目录 backend-data/、agent-data/ 随 compose 自动生成；
如需从 Docker Hub 拉取官方镜像，确保可访问 Docker Hub 或配置镜像加速。

四、部署步骤

4.1 创建部署目录与 backend 配置文件

本节先建好目录骨架，backend 的配置以文件方式挂载进容器（比纯命令行旗标更易维护，键位详解见第七章）：

mkdir -p /opt/sensu-compose/backend-data /opt/sensu-compose/agent-data
cd /opt/sensu-compose
cat > backend.yml <<'EOF'
state-dir: /var/lib/sensu/sensu-backend
api-listen-address: "[::]:8080"
api-url: http://sensu-backend:8080
agent-host: "[::]"
agent-port: 8081
dashboard-host: "[::]"
dashboard-port: 3000
log-level: info
EOF

逐项说明：state-dir 是 backend 全部状态（内嵌 etcd 数据、bbolt 库）的落盘目录，必须持久化；api-listen-address 为 REST API 监听地址（默认 [::]:8080）；api-url 是集群内对外宣告的 API 地址（agent 场景填 backend 服务名）；agent-host/agent-port 为 agent 长连接监听（默认 8081）；dashboard-host/dashboard-port 为 Web UI 端口；log-level 控制日志级别（默认 info）。

4.2 编写 docker-compose.yml

services:
  sensu-backend:
    image: sensu-local:6.15.0
    container_name: sensu-6-15-backend
    hostname: sensu-backend
    command: sensu-backend start --config-file /etc/sensu/backend.yml
    volumes:
      - ./backend.yml:/etc/sensu/backend.yml:ro
      - ./backend-data:/var/lib/sensu/sensu-backend
    ports:
      - "8131:3000"
      - "8133:8080"
    networks: [sensu-net]

  sensu-agent:
    image: sensu-local:6.15.0
    container_name: sensu-6-15-agent
    hostname: web01
    command: sensu-agent start --backend-url ws://sensu-backend:8081 --subscriptions linux,web --name web01
    volumes:
      - ./agent-data:/var/lib/sensu
    depends_on: [sensu-backend]
    networks: [sensu-net]

networks:
  sensu-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

关键点解读：

backend 以 --config-file 读取挂载的 YAML 配置；数据目录 ./backend-data 挂到 state-dir 指定的容器路径，实现持久化；
agent 只需三个参数：--backend-url（WebSocket 连接，ws:// 明文，生产建议 TLS 的 wss://）、--subscriptions（订阅标签，服务端 check 按它匹配下发）、--name（实体名，省略时取主机名）；
ipam.subnet 显式指定内网网段，避免与宿主机其他 Docker 网络冲突（也可整段省略由 Docker 自动分配）。

4.3 启动与状态确认

cd /opt/sensu-compose
docker compose up -d

实测输出：

[+] Running 3/3
 ✔ Network compose_sensu-net     Created
 ✔ Container sensu-6-15-backend  Started
 ✔ Container sensu-6-15-agent    Started

等待约 10 秒后确认服务状态与 backend 就绪日志：

docker compose ps

NAME                 IMAGE               COMMAND                  SERVICE             CREATED              STATUS              PORTS
sensu-6-15-agent     sensu-local:6.15.0  "sensu-agent start --…"  sensu-agent         About a minute ago   Up About a minute
sensu-6-15-backend   sensu-local:6.15.0  "sensu-backend start …"  sensu-backend       About a minute ago   Up About a minute   0.0.0.0:8131->3000/tcp, [::]:8131->3000/tcp, 0.0.0.0:8133->8080/tcp, [::]:8133->8080/tcp

docker logs sensu-6-15-backend 2>&1 | grep -E 'ready to accept|starting webd' | tail -3

{"component":"backend","level":"warning","msg":"backend is running and ready to accept events","time":"2026-10-20T00:25:15Z"}
time="2026-10-20T00:25:15Z" level=warning msg="starting webd on address: [::]:3000" component=web
time="2026-10-20T00:25:15Z" level=warning msg="starting webd on address: [::]:3001" component=web

backend is running and ready to accept events 即 backend 就绪。此时 agent 尚无法注册（用户体系未初始化），继续 4.4。

4.4 初始化（sensu-backend init）

Sensu 的用户体系（admin 账号、agent 内置账号、默认集群角色）需要显式初始化创建。注意顺序：必须先启动 backend，再执行 init——sensu-backend init 本质是 etcd 客户端，去连接 backend 内嵌 etcd 的客户端端口（先 init 后 start 会报 no etcd endpoints are available，详见 11.2）：

docker compose exec -T sensu-backend \
  sensu-backend init --cluster-admin-username admin --cluster-admin-password q1w2e3r4 \
  --etcd-client-urls http://127.0.0.1:2379 --wait

实测输出（节选）：

{"component":"store","level":"info","msg":"successfully upgraded database","time":"2026-10-20T00:25:31Z","database_version":2}
{"component":"store","level":"info","msg":"migrating enterprise etcd database to a new version","time":"2026-10-20T00:25:31Z"}

参数说明：--cluster-admin-username/--cluster-admin-password 是初始管理员账号（本文按惯例取 admin/q1w2e3r4）；--etcd-client-urls 显式指向 IPv4 回环地址，避免 localhost 被解析成 IPv6 [::1] 而连接失败；--wait 让 init 持续重试直到 etcd 可用（首个启动周期内执行时必备）。init 幂等：重复执行在已初始化的库上直接返回。

💡 官方 sensu/sensu 镜像通过环境变量 SENSU_BACKEND_CLUSTER_ADMIN_USERNAME/PASSWORD 在入口脚本中自动完成上述 init（官方安装文档原文："If you are using Docker, initialization is included in this step when you start the backend"）。自建镜像无入口脚本，需像本节一样手动 init，两种方式结果等价。

4.5 配置 sensuctl 并验证用户与实体注册

sensuctl 是全部管理操作的入口，先让它连上 API（在 backend 容器内执行，生产环境也可装在任一运维机上）：

docker compose exec sensu-backend \
  sensuctl configure -n --username admin --password q1w2e3r4 --url http://127.0.0.1:8080

-n 为非交互模式。验证用户体系初始化结果：

docker compose exec sensu-backend sensuctl user list

  Username       Groups       Enabled
─────────── ──────────────── ──────────
  admin      cluster-admins   true
  agent      system:agents    true

admin 是刚创建的管理员，agent 是 init 自动创建的 agent 内置账号（agentd 用它与 backend 认证）。查看 agent 是否已注册为实体：

docker compose exec sensu-backend sensuctl entity list

   ID     Class    OS         Subscriptions                  Last Seen
──────── ─────── ─────── ──────────────────────────────── ────────────────────────────────
  web01   agent   linux   linux,web,entity:web01   2026-10-20 00:26:20 +0000 UTC

web01 已自动注册（agent 上线即注册，无需服务端预建），Subscriptions 中 entity:web01 是自动追加的实体专属订阅。

4.6 创建 check 并验证事件端到端流转

将三个检查以 YAML 声明后一次性创建：check_uptime 常规定时检查、check_api_health 代理检查（无 agent 的目标，事件归属到代理实体 sensu-api）、check_tmp_flag 用于演练故障→恢复：

cd /opt/sensu-compose
cat > checks.yml <<'EOF'
---
type: CheckConfig
api_version: core/v2
metadata:
  name: check_uptime
  namespace: default
spec:
  command: uptime
  subscriptions:
  - linux
  interval: 10
  publish: true
  timeout: 10
---
type: CheckConfig
api_version: core/v2
metadata:
  name: check_api_health
  namespace: default
spec:
  command: curl -s -o /dev/null -w '%{http_code}' http://sensu-backend:8080/health
  proxy_entity_name: sensu-api
  subscriptions:
  - linux
  interval: 15
  publish: true
  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
EOF
docker cp checks.yml sensu-6-15-backend:/tmp/checks.yml
docker compose exec sensu-backend sensuctl create -f /tmp/checks.yml

sensuctl create -f 成功时无输出（返回码 0）。约一个调度周期（10~15 秒）后查看事件列表：

docker compose exec sensu-backend sensuctl event list

   Entity          Check                                     Output                                Status   Silenced             Timestamp                             UUID
──────────── ────────────────── ───────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ───────────────────────────────────────
  sensu-api   check_api_health                                                               200        0   false      2026-10-20 00:26:49 +0000 UTC   f3ea69eb-8722-4b24-b229-d9cba11f0064
  web01       check_tmp_flag                                                                            1   false      2026-10-20 00:26:51 +0000 UTC   6b71df37-a27c-4821-aef5-2c5193276eda
  web01       check_uptime        00:26:44 up  8:39,  0 users,  load average: 1.39, 1.44, 1.51          0   false      2026-10-20 00:26:45 +0000 UTC   18e961f4-4019-4b3d-a8a7-37bc2f1c178a

  web01       keepalive          Keepalive last sent from web01 at 2026-10-20 00:26:43 +0000 UTC        0   false      2026-10-20 00:26:43 +0000 UTC   a5c42ced-fa43-4b01-bffc-d1d61bbc4400

三条链路全部按预期工作：

check_uptime：agent 本地执行 uptime，输出与状态 0（OK）随事件上报；
check_api_health：命令在 web01 上执行，但事件归属 proxy_entity_name 指定的代理实体 sensu-api（无 agent 目标的标准监控姿势），输出 200、状态 0；
check_tmp_flag：test -f /tmp/healthy 失败，状态 1（WARNING）——这就是一条真实的"故障"事件；
keepalive：agent 每 10 秒左右发送的心跳事件，用于实体存活监测。

单个事件详情（含执行历史）：

docker compose exec sensu-backend sensuctl event info web01 check_uptime

=== web01 - check_uptime
Entity:    web01
Check:     check_uptime
Output:     00:27:14 up  8:39,  0 users,  load average: 1.62, 1.49, 1.53
Status:    0
History:   0,0,0,0
Silenced:  false
Timestamp: 2026-10-20 00:27:15 +0000 UTC
UUID:      a553ed68-cfcc-4acb-abba-ef5cd710e1ce

4.7 故障恢复演练与 dashboard 端口实测

恢复演练：修复 check_tmp_flag 的故障条件（创建标志文件），等待下一个调度周期：

docker exec sensu-6-15-agent touch /tmp/healthy
sleep 12
docker compose exec sensu-backend sensuctl event list

   Entity          Check                                     Output                                Status   Silenced             Timestamp                             UUID
──────────── ────────────────── ───────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ───────────────────────────────────────
  sensu-api   check_api_health                                                               200        0   false      2026-10-20 00:27:04 +0000 UTC   ad777ff2-0595-40d8-a561-57531330922a
  web01       check_tmp_flag                                                                            0   false      2026-10-20 00:27:11 +0000 UTC   3ad1e2de-3e02-4b33-95d1-86d429a5a52d
  web01       check_uptime        00:27:14 up  8:39,  0 users,  load average: 1.62, 1.49, 1.53          0   false      2026-10-20 00:27:15 +0000 UTC   a553ed68-cfcc-4acb-abba-ef5cd710e1ce

  web01       keepalive          Keepalive last sent from web01 at 2026-10-20 00:27:03 +0000 UTC        0   false      2026-10-20 00:27:03 +0000 UTC   e5ed6b8d-a7b1-49ae-9846-ddb2dd9fbec7

check_tmp_flag 从 1 恢复为 0，故障→恢复的完整事件闭环验证通过。

dashboard 端口实测（重要提示）：官方安装文档仍写 ":3000 = Sensu web UI"，但 6.15.0 的 Web UI 属于商业特性（Release Notes 中 Web UI 更新全部标注 "Commercial feature"，开源仓库 v6.15.0 源码中已无 webd 实现、且 DeprecateDashboardFlags = true 标记旗标废弃）。社区版后端实测 :3000 对所有路径返回 400：

curl -s -i --max-time 10 http://127.0.0.1:8131/

HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
X-Frame-Options: deny
Date: Tue, 20 Oct 2026 00:16:08 GMT
Content-Length: 56

Client sent an API request to the web application port!

实测结论：/、/index.html、/graphql、带浏览器 Accept 头、SENSU_DASHBOARD_PREBUILT=true 环境变量等尝试均得到同一 400 响应。6.15.0 社区版的管理面 = sensuctl CLI + :8080 REST API（功能完整无阉割），请勿在选型时依赖免费 Web UI。若确需 UI，需评估 Sensu 商业许可或搭配第三方面板。

4.8 REST API 取证

JWT token 认证：GET /auth 换取 token（注意认证接口是 GET 而非 POST，POST 返回 405）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8133/auth | head -c 200

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTI0NTYzNTYsImp0aSI6IjRmMjE4NDIzMTc4YWE2YmE2YzQ4MzI1M2FjMDM0ZWQxIiwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MTMzIiwic3ViIjoiYWRtaW4iLCJncm91cHMiOlsiY2x1c3Rlci1hZG1pbnMiLCJzeXN0ZW06dXNlcnMiXSwicHJvdmlkZXIiOnsicHJvdmlkZXJfaWQiOiJiYXNpYyIsInByb3ZpZGVyX3R5cGUiOiIiLCJ1c2VyX2lkIjoiYWRtaW4ifSwiYXBpX2tleSI6ZmFsc2UsInNlc3Npb25faWQiOiJkMDY3OThhYjA5YWJiMjRiNGI2ODRkNjY2ZjdmMmNlMiJ9.NtFFa0aCzELmzjlznFqZ45Xx1XYAEVwB8s6DRzCIuio","expires_at":1792456356,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3OTI0OTkyNTYsImp0aSI6IjdjZDVhZTc3OWY3YjliOWE2MTk4MWUxYjY1YmNiOTk1IiwiaWF0IjoxNzkyNDU2MDU2LCJzdWIiOiJhZG1pbiIsImdyb3VwcyI6bnVsbCwicHJvdmlkZXJfaWQiOiIiLCJwcm92aWRlcl90eXBlIjoiIiwidXNlcl9pZCI6IiJ9LCJhcGlfa2V5IjpmYWxzZSwic2Vzc2lvbl9pZCI6ImQwNjc5OGFiMDlhYmIyNGI0YjY4NGQ2NjZmN2YyY2UyIn0.6G_mUZOPMN58mg5sKXNz6ZH6vXyt5lr4VyudGLx0Fz4"}

用 token 读事件（Authorization: Bearer 头 + JWT）：

TOKEN=$(curl -s -u admin:q1w2e3r4 http://127.0.0.1:8133/auth | python3 -c "import json,sys; print(json.load(sys.stdin)['access_token'])")
curl -s -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:8133/api/core/v2/events?limit=1' | head -c 400

[{"check":{"command":"curl -s -o /dev/null -w '%{http_code}' http://sensu-backend:8080/health","handlers":[],"high_flap_threshold":0,"interval":15,"low_flap_threshold":0,"publish":true,"runtime_assets":null,"subscriptions":["linux"],"proxy_entity_name":"sensu-api","check_hooks":null,"stdin":false,"subdue":null,"ttl":0,"timeout":10,"round_robin":false,"duration":0.008204718,"executed":1792456084,"h

API Key 认证（适合脚本长期使用，无 5 分钟过期问题）。先签发：

docker compose exec sensu-backend sensuctl api-key grant admin

Created: /api/core/v2/apikeys/e51d1fcf-186c-41e7-811b-17348ac9769d

路径末段 UUID 就是 API Key。注意认证头格式是 Authorization: Key，不是 Bearer（Bearer 仅用于 JWT；用错会得到 invalid credentials）：

curl -s -H "Authorization: Key e51d1fcf-186c-41e7-811b-17348ac9769d" 'http://127.0.0.1:8133/api/core/v2/events?limit=1' | python3 -m json.tool | head -12

{
    "check": {
        "command": "curl -s -o /dev/null -w '%{http_code}' http://sensu-backend:8080/health",
        "handlers": [],
        "high_flap_threshold": 0,
        "interval": 15,
        "low_flap_threshold": 0,
        "publish": true,
        "runtime_assets": null,
        "subscriptions": [
            "linux"
        ],
        "proxy_entity_name": "sensu-api",
        "check_hooks": null,
        "stdin": false,
        "subdue": null,
        "ttl": 0,
        "timeout": 10,
        "round_robin": false,
        "duration": 0.008204718,
        "executed": 1792456084,

再验证两个元信息端点：

curl -s http://127.0.0.1:8133/version

{"etcd":{"etcdserver":"3.6.13","etcdcluster":"3.6.0","storage":""},"sensu_backend":"6.15.0","api_groups":{"authentication/v2":"v2.0.0","bsm/v1":"v1.0.0","core/v2":"v2.21.6","core/v3":"v3.10.6","fallback_pipeline/v1":"v1.

curl -s http://127.0.0.1:8133/health | head -c 220

{"Alarms":null,"ClusterHealth":[{"MemberID":13195394291058371180,"MemberIDHex":"b71f75320dc06a6c","Name":"default","Err":"","Healthy":true}],"Header":{"cluster_id":2037210783374497686,"member_id":13195394291058371180,"ra

/version 确认版本与内嵌 etcd 版本；/health 的 ClusterHealth[].Healthy=true 是最常用的服务健康判据（脚本监控可直接依赖此端点）。

五、数据持久化说明

backend 状态：./backend-data:/var/lib/sensu/sensu-backend，其中 etcd/data|wal 是内嵌 etcd 的数据与预写日志，bbolt 库存放私有状态。资源定义（check/handler/用户/角色）与事件都存于内嵌 etcd，此目录即 Sensu 的全部"数据库"。
agent 状态：./agent-data:/var/lib/sensu，存放 agent 本地缓存（资产包等）。
实测验证：docker compose down 后删除容器、docker compose up -d 重建，实体与事件完整保留（重建后 sensuctl entity list 仍列出 web01，Last Seen 更新为最新心跳时间）。升级镜像版本时只需换 image 标签重建容器，数据不受影响。
备份即备份 backend-data/ 目录；恢复时停服放回目录后启动即可（内嵌 etcd 单成员模式，无额外恢复流程）。

六、环境变量表

本文实测的 compose 未用环境变量（自建镜像走显式 init），但官方镜像的初始化与行为开关依赖以下变量：

变量	默认值	说明
SENSU_BACKEND_CLUSTER_ADMIN_USERNAME	无（必填于首次 init）	初始管理员用户名，官方镜像启动时自动 init 用
SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD	无（必填于首次 init）	初始管理员密码
SENSU_DASHBOARD_PREBUILT	未设置	官方镜像标记 dashboard 资产预构建；实测对社区版 400 行为无影响
SENSU_ETCD_CLIENT_URLS	未设置	部分版本用于指定 init/管理面连接的 etcd 地址

⚠️ 敏感值处理：SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD 建议经 .env 文件（compose 同目录，加入 .gitignore）或 environment: 注入，避免明文进版本库。

七、配置参数说明

backend 支持"命令行旗标 + --config-file YAML"两种配置方式，键名同源（sensu-backend start --help 共 98 行旗标，节选核心项，默认值实测摘录）：

键（YAML）/旗标	默认值	说明
state-dir	无（必配）	状态与 etcd 数据目录，生产必挂持久卷
api-listen-address	`[::]:8080`	REST API 监听地址
api-url	http://localhost:8080	对外宣告的 API 地址，集群/多网卡环境必须显式
agent-host / agent-port	`[::]` / 8081	agent 连接监听
dashboard-host / dashboard-port	`[::]` / 3000	Web UI 监听（6.15 社区版无免费 UI）
log-level	info	panic/fatal/error/warn/info/debug
access-token-expiry	5m0s	API access token 有效期（sensuctl 频繁 401 时可调大）
api-request-limit	512000 字节	单次 API 请求体上限
agent-burst-limit / agent-rate-limit	0（不限）/ 0	agent 连接的突发/速率限制
assets-burst-limit / assets-rate-limit	100 / 1.39	后端侧资产拉取限速
etcd-* 系列旗标	单成员	内嵌 etcd 调参（心跳 300ms、选举超时 3000ms、配额 4GB 等）
disable-platform-metrics	true（6.15 起）	平台指标默认关闭（Release Notes 明确此变更防高基数磁盘耗尽）

agent 侧核心旗标（sensu-agent start --help 实测节选）：

旗标	默认值	说明
--backend-url	ws://127.0.0.1:8081	backend 地址，可给多个实现故障转移（逗号分隔或重复旗标）
--subscriptions	无	订阅标签列表，服务端 check 匹配依据
--name	主机名	实体名
--namespace	default	所属命名空间
--cache-dir	/var/lib/sensu/sensu-agent	资产与缓存目录
--deregister / --deregistration-handler	false / 无	agent 停止时是否自动注销实体
--redact	内置默认脱敏字段	日志与 API 中的敏感字段清单
--keepalive-interval / --keepalive-timeout	20s / 120s	心跳间隔与服务端判死阈值

生产配置模板（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 调到 1h 减少 sensuctl 重认证频率；agent 规模在数百节点内无需动 etcd 调参；超过千节点应直接部署 3 backend 集群（见 A1 篇架构章节与官方《Deploy Sensu》集群指南）。

八、配置文件挂载

backend.yml（只读挂载 /etc/sensu/backend.yml）：本文实测形态。修改后 docker compose restart sensu-backend 生效；
check 等资源文件（如本文 checks.yml）：不入容器配置，经 sensuctl create -f 写入存储。生产建议把资源 YAML 进 Git 仓库，CI 中批量 sensuctl create -f 实现配置即代码；
TLS 证书：backend/agent 的 TLS 旗标（--cert-file 等）同样支持 YAML 键，需要加密传输时改用 wss:// + 挂载证书文件。

九、等价 docker run 运行方式

不用 Compose 时，两条命令等价复现本文拓扑（须先创建同名网络）：

docker network create --driver bridge --subnet 10.89.58.0/24 sensu-net

docker run -d --name sensu-6-15-backend --hostname sensu-backend --network sensu-net \
  -p 8131:3000 -p 8133:8080 \
  -v /opt/sensu-compose/backend.yml:/etc/sensu/backend.yml:ro \
  -v /opt/sensu-compose/backend-data:/var/lib/sensu/sensu-backend \
  sensu-local:6.15.0 \
  sensu-backend start --config-file /etc/sensu/backend.yml

docker run -d --name sensu-6-15-agent --hostname web01 --network sensu-net \
  -v /opt/sensu-compose/agent-data:/var/lib/sensu \
  sensu-local:6.15.0 \
  sensu-agent start --backend-url ws://sensu-backend:8081 --subscriptions linux,web --name web01

与 Compose 版的差异：docker run 无 depends_on 启动顺序保障，需等 backend 就绪（/health 返回 200）后再启动 agent；其余行为完全一致。

十、常用运维命令

docker compose ps                          # 两服务状态
docker compose logs -f sensu-backend       # 跟踪 backend 日志（事件管道错误在此暴露）
docker compose restart sensu-backend       # 改配置后重启
docker compose stop && docker compose up -d   # 停止/恢复（数据保留）
docker compose down                        # 移除容器与网络（保留 backend-data/agent-data）
docker compose down -v                     # 连数据卷一起移除（本文用 bind mount，数据目录仍需手动删）

健康巡检三件套（全部实测可用）：

curl -s http://127.0.0.1:8133/health | grep -o '"Healthy":true'   # 集群健康
docker compose exec sensu-backend sensuctl event list              # 事件面
docker compose exec sensu-backend sensuctl entity list             # 实体存活

十一、常见问题（FAQ）

11.1 sensuctl 每隔几分钟就报 401 / "failed to request new request token"？

backend 的 access-token-expiry 默认 5 分钟，sensuctl 用 refresh token 续期；backend 重启或 refresh 失效时会看到：

Error: error putting resource #0 with name "check_uptime" and namespace "default" (/api/core/v2/namespaces/default/checks/check_uptime): PUT "/api/core/v2/namespaces/default/checks/check_uptime": failed to request new refresh token; client returned 'The server returned the error: 401 Unauthorized'

解决：重新 sensuctl configure，或将 backend 配置 access-token-expiry: 1h 调大有效期；脚本场景改用 API Key（Authorization: Key 头）规避。

11.2 先 init 后 start 报 "no etcd endpoints are available"？

{"component":"cmd","level":"error","msg":"error connecting to etcd endpoint: context deadline exceeded: connection error: desc = \"transport: Error while dialing: dial tcp [::1]:2379: connect: connection refused\"","time":"2026-10-20T00:10:38Z"}
time="2026-10-20T00:10:38Z" level=fatal msg="error executing sensu-backend" component=sensu-enterprise error="no etcd endpoints are available or cluster is unhealthy"

6.15 的 sensu-backend init 是 etcd 客户端，不会自行拉起内嵌 etcd。正确顺序：先 sensu-backend start（就绪日志 ready to accept events），再执行 init。另注意 localhost:2379 在容器内可能解析为 IPv6 [::1] 而内嵌 etcd 只绑了 127.0.0.1，init 时显式传 --etcd-client-urls http://127.0.0.1:2379 最稳妥。

11.3 agent 日志持续 "handshake failed with status 401: bad credentials"？

init 未执行（或执行失败）时，agent 内置账号 agent 不存在，握手被拒。完成 4.4 节初始化后 agent 会在数秒内自动重连成功，无需重启 agent。

11.4 dashboard 打不开，全部 400？

见 4.7 节：6.15.0 社区版 Web UI 属商业特性，:3000 固定返回 400 Client sent an API request to the web application port!。这不是部署错误；管理面请使用 sensuctl 与 REST API（本文 4.5~4.8 已覆盖全部日常操作）。

11.5 拉取官方镜像报 EOF？

Docker Hub 或加速源不稳定时的典型报错（failed to copy: httpReadSeeker: failed open: ... EOF）。本文的官方 deb 自建镜像方案即为此准备：deb 走 packagecloud（本环境实测直连可达），构建过程不依赖 Docker Hub。

十二、参考链接

官方安装文档（含 Docker/Compose 模板）：https://docs.sensu.io/sensu-go/latest/operations/deploy-sensu/install-sensu/
backend 参考配置：https://docs.sensu.io/sensu-go/latest/reference/backend/
agent 参考：https://docs.sensu.io/sensu-go/latest/reference/agent/
API Key 认证（Authorization: Key 头）：https://docs.sensu.io/sensu-go/latest/api/core/apikeys/
官方软件仓库：https://packagecloud.io/sensu/stable
官方镜像：https://hub.docker.com/r/sensu/sensu
本专栏相关：《Sensu 6.15.0 介绍与选型指南》《Sensu 6.15.0 配置参数详解》《Sensu 6.15.0 常用 CLI 命令详解》（同批次发布于 Sensu 专栏）