Keep 0.54.3 配置参数详解

目标：系统梳理 Keep（keephq/keep，开源 AIOps 告警管理平台）0.54.3 的全部配置入口——后端/前端环境变量按官方文档逐类整理并标注默认值，providers 预置（KEEP_PROVIDERS）、workflow 预置（KEEP_WORKFLOWS_DIRECTORY）与 workflow YAML 各字段均以实测验证。参数清单溯源官方配置文档（查询日期 2026-10-23），实测结论出自 0.54.3 版本真实服务器（部署过程见 《Keep Docker Compose 部署指南》）。

一、环境信息

阅读约定：标注「实测」的参数在 0.54.3 版本上真实跑通并给出回显/证据；其余参数的默认值与取值范围照录官方文档，未做破坏性验证的会在小节内说明。

二、前置条件

1. 已按 《Keep Docker Compose 部署指南》 完成 0.54.3 三服务栈部署，curl -s http://localhost:8148/healthcheck 返回 {}。
2. 已预置可用的 API Key（KEEP_DEFAULT_API_KEYS），能通过 curl -H "x-api-key: ..." 调用后端 API。
3. 实验产物目录统一约束在 /opt/data/quzuo/tmp/keep-alerts/（compose 文件与 state/ 持久化目录都在其中）。

三、参数查看与修改方式

Keep 没有集中式配置文件，配置入口有三类：

1. 环境变量（最主要）：后端与前端各自的容器环境变量。Compose 部署写在 docker-compose.yml 的 environment 段；docker run 部署用 -e 传入；K8s 部署写 ConfigMap/Deployment env。修改后需重启对应服务生效：

   docker compose restart keep-backend   # 后端参数
   docker compose restart keep-frontend  # 前端参数
   

2. 页面与 API：provider 连接、workflow、规则类（关联/映射/提取/维护窗口）配置存在数据库中，通过 UI 设置页或 REST API 增删改（这类不属于环境变量，重启即持久保留）。
3. CLI 本地配置：keep config new 生成的 ~/.keep.yaml 只保存 CLI 自己的连接参数（api_key / keep_api_url），是「客户端配置」，与服务端参数无关。

查看当前生效配置的实用手段（均在实测栈验证）：

# 查看容器实际注入的环境变量（排障第一手资料）
docker exec keep-0543-backend env | grep -E 'KEEP_|AUTH_|DATABASE_' 

# 查看后端当前运行的完整请求日志（JSON 格式，LOG_FORMAT=open_telemetry 默认样式）
docker compose logs --tail 5 keep-backend

# API 层验证参数效果：已安装 provider / 已注册 workflow / 自身指标
curl -s -H "x-api-key: q1w2e3r4-keep-demo-key" http://localhost:8148/providers | head -c 200
curl -s -H "x-api-key: q1w2e3r4-keep-demo-key" http://localhost:8148/workflows
curl -s -H "x-api-key: q1w2e3r4-keep-demo-key" http://localhost:8148/metrics | head -3

四、参数总览

0.54.3 官方文档的后端参数按功能分为 15 类、前端参数 4 类。总览如下（✅ = 本文有实测验证）：

五、核心参数分类详解

5.1 通用参数

SCHEDULER=false + CONSUMER=true 的拆分场景：多副本部署时只让一个实例跑定时调度，其余实例专职消费告警，避免 interval workflow 重复执行。单机默认全开即可（实测单机全开无异常）。

5.2 数据库参数

MySQL/PostgreSQL 切换示例（应用层无差别，历史数据不自动迁移）：

mysql+pymysql://keep:StrongPass@mysql:3306/keep
postgresql+psycopg2://keep:StrongPass@postgres:5432/keep

实测持久化证据：默认 SQLite 下运行后 state/db.sqlite3 实测 794624 字节，全部告警/workflow/凭据都在该单文件中。

5.3 认证参数

实测要点：NO_AUTH 模式 ≠ 免 API Key。页面浏览不需要登录，但 API 调用（含告警上报）必须带 x-api-key，否则 401 Missing API Key——这是实测中踩到的第一个配置坑（解法见部署篇 11.3 节）。预置 Key 与角色 RBAC 的关系：admin 角色拥有全部 scope，webhook 角色仅有 write:alert / write:incident。

5.4 密钥管理参数

FILE 模式实测落盘形态（每条凭据一个小文件，内容为连接参数 JSON）：

keep-cli-demo                     # KEEP_DEFAULT_API_KEYS 预置的 API Key
keep_console_09f66d0f96634ec8...  # CLI 手工连接的 console provider
keep_console_03092072a8ab409b...  # KEEP_PROVIDERS 预置的 console provider
keep_bash_f92d7d3a4d754024b3c...  # KEEP_PROVIDERS 预置的 bash provider

要点：凭据文件与 SQLite 库分离存放，备份 state/ 目录时两者一起带走；切到 DB 模式则凭据入库（备份更简单，但需保证数据库安全）。

5.5 资源预置参数（KEEP_PROVIDERS / KEEP_WORKFLOWS_DIRECTORY）

这组参数让 Keep 在启动时自动「开通」资源，替代手工在 UI 上逐个连接，是配置即代码（IaC）的关键入口。

KEEP_PROVIDERS：JSON 数组/对象声明预置连接，格式为 {"连接名": {"type": "provider类型", "authentication": {凭据字段}}}。实测值：

- KEEP_PROVIDERS={"console-yaml-prov":{"type":"console","authentication":{}},"bash-local":{"type":"bash","authentication":{}}}

实测验证（keep provider list，CLI 用法见《Keep 0.54.3 常用 CLI 命令与工具详解》）：

+----------------------------------+---------+-------------------+--------------+----------------------------+
|                ID                |   Type  |        Name       | Installed by |     Installation time      |
+----------------------------------+---------+-------------------+--------------+----------------------------+
| f92d7d3a4d754024b3c289db4b1eb43d |   bash  |     bash-local    |    system    | 2026-10-23T01:32:42.603161 |
| 09f66d0f96634ec8b9bd3c575d427ce4 | console |    console-demo   | admin@keephq | 2026-10-23T01:24:16.787161 |
| 03092072a8ab409ba41974670f4e7040 | console | console-yaml-prov |    system    | 2026-10-23T01:32:42.597398 |
+----------------------------------+---------+-------------------+--------------+----------------------------+

Installed by: system 即 KEEP_PROVIDERS 预置的连接（console-yaml-prov、bash-local），与 admin@keephq 手工连接的 console-demo 并列共存；且在 docker compose restart keep-backend 重启后依然存在（预置有幂等性，不会重复建）。

KEEP_WORKFLOWS_DIRECTORY：指向容器内目录，其中的 workflow YAML 启动时批量注册。实测 KEEP_WORKFLOWS_DIRECTORY=/state/workflows，目录内放 disk-critical-handler.yml 与 interval-logger.yml 两个文件，重启后端后 GET /workflows 返回 3 条（2 个预置 + 1 个此前 API 注册的）。配合 PROVISION_RESOURCES（默认 true）：设为 false 则关闭启动预置流程。

Compose 里写 JSON 环境变量的注意点：JSON 内层的双引号在 YAML 流式标量里可直接写；若值中含 $ 符号需写成 $$ 防止 Compose 变量插值。

5.6 实时推送参数（Pusher/Soketi 三方对齐）

对齐规则（实测排查心得）：后端 PUSHER_APP_ID/KEY/SECRET ≡ SOKETI_DEFAULT_APP_*；前端 PUSHER_APP_KEY ≡ SOKETI_DEFAULT_APP_KEY。前端 HOST/PORT 是给浏览器用的（填宿主地址），后端 HOST/PORT 是容器网络内的（填服务名）——同一个变量名在两端含义不同，是配置错误的最高发点。

5.7 AI 参数

注意 AI 功能还要求前端也配置同名 OPENAI_* 变量（官方文档 TIP 明确说明），AI 辅助写 workflow 等界面能力才能用。

5.8 日志与可观测参数

5.9 缓存、队列与限流参数

5.10 维护窗口参数

5.11 前端参数

5.12 workflow YAML 参数逐项（实测）

workflow 是 YAML 文件，顶层只有一个 workflow: 键，字段如下（✅ = 本文实测验证）：

triggers 四种类型：

triggers:
  - type: manual        # 手动触发（UI 点 Run / CLI workflow run）✅ 实测通过
  - type: interval      # 定时触发 ✅ 实测通过
    value: 10           # 秒数
  - type: alert         # 告警触发 ✅ 实测通过
    cel: source.contains("demo") && severity == "critical"   # CEL 过滤表达式 ✅ 实测通过
    filters:            # 旧式过滤（官方已标记 deprecated，不推荐）
      - key: severity
        value: critical
  - type: incident      # 事故创建/更新/解决时触发（本文未实测）
    on: [create, update]

实测 workflow 全文（interval + console 动作，文件置于 KEEP_WORKFLOWS_DIRECTORY 后重启后端加载）：

workflow:
  id: interval-logger
  name: Interval Logger
  description: Print a heartbeat log every 10 seconds to verify the scheduler.
  triggers:
    - type: interval
      value: 10
  actions:
    - name: heartbeat
      provider:
        type: console
        with:
          logger: true
          message: "Heartbeat from interval-logger workflow"

实测回显（docker logs keep-0543-backend 中每 10 秒一条，JSON 关键字段摘录）：

{"message": "Heartbeat from interval-logger workflow", "levelname": "INFO", "name": "console",
 "threadName": "WorkflowScheduler_1", "workflow_id": "ecc524d1-a07e-4a93-a2d9-daeec421cc69",
 "workflow_execution_id": "bf765e01-1481-48b9-acc6-a495b031d5b4", "tenant_id": "keep",
 "context": {"step_id": "heartbeat"}}

间隔精确（01:52:26 → 01:52:36 → 01:52:46 → …），WorkflowScheduler_1 线程名证明 SCHEDULER 默认开启生效。

实测 alert 触发 workflow（告警触发 + CEL 过滤 + console 动作 + mock 富化）：

workflow:
  id: disk-critical-handler
  name: Disk Critical Handler
  description: Handle critical disk alerts, log via console and enrich with owner and runbook.
  triggers:
    - type: alert
      cel: source.contains("demo") && severity == "critical"
  actions:
    - name: log-alert
      provider:
        type: console
        with:
          logger: true
          message: "Critical disk alert {{ alert.name }} on {{ alert.fingerprint }}"
    - name: enrich-alert
      provider:
        type: mock
        with:
          enrich_alert:
            - key: owner
              value: sre-team
            - key: runbook
              value: https://runbooks.example.com/disk

注入 source=["demo"]、severity="critical" 的告警后，workflow 自动执行：console 动作落日志、enrich_alert 将 owner=sre-team、runbook=https://runbooks.example.com/disk 写入告警对象（API 中该告警 enriched_fields 实测变为 ['owner','runbook']）。enrich_alert 的 disposable: true 表示临时富化（新告警到达即丢弃），实测未启用。

bash provider 实测（steps 执行宿主命令，stdout 回填 steps.步骤名.results.stdout）：

steps:
  - name: df-step
    provider:
      type: bash
      with:
        command: uptime

实测执行结果中 stdout 为标准 uptime 输出（{"stdout": " 01:34:46 up 3 days, 9:46, ...", "stderr": "", "return_code": 0}）。bash provider 仅限自托管环境使用。

六、生产配置模板

场景一：小团队评估（2C4G，单机）——默认栈即可：SQLite + NO_AUTH/DB 认证 + 零 AI。磁盘预留 10GB（镜像 4GB + 数据与日志）。核心仅三行：

- AUTH_TYPE=NO_AUTH
- KEEP_DEFAULT_API_KEYS=ci-bot:admin:<强随机密钥>
- DATABASE_CONNECTION_STRING=sqlite:////state/db.sqlite3?check_same_thread=False

场景二：多人团队生产（4C8G 起，MySQL + Redis）——数据落外部库、开启缓存、收紧认证：

- AUTH_TYPE=DB
- KEEP_JWT_SECRET=<64 位强随机>
- KEEP_DEFAULT_USERNAME=admin
- KEEP_DEFAULT_PASSWORD=<强密码>
- KEEP_FORCE_RESET_DEFAULT_PASSWORD=true
- DATABASE_CONNECTION_STRING=mysql+pymysql://keep:<密码>@mysql:3306/keep
- DATABASE_POOL_SIZE=10
- REDIS=true
- REDIS_HOST=redis
- SECRET_MANAGER_TYPE=DB
- KEEP_USE_LIMITER=true
- KEEP_LIMIT_CONCURRENCY=200/minute
- KEEP_STORE_RAW_ALERTS=false
- KEEP_METRICS=true
- LOG_LEVEL=INFO

磁盘：MySQL 独立规划（告警表增长与保留策略相关）；state/ 仍需持久化（workflow 与密钥）。

场景三：内网断网环境——在场景二基础上：镜像离线导入（docker save/docker load），关闭一切外联：前端 POSTHOG_KEY/NEXT_PUBLIC_SENTRY_DSN 留空，后端 POSTHOG_DISABLED=true、SENTRY_DISABLED=true、不配 OPENAI_API_KEY（或 OPENAI_BASE_URL 指向内网 LLM 网关）。

七、常见问题（实测排障实录）

7.1 NO_AUTH 下 API 仍 401：NOAUTH 只免「登录」，不免「API Key」。用 KEEP_DEFAULT_API_KEYS 预置后带 x-api-key 调用（详见部署篇 11.3 节实测）。

7.2 KEEP_PROVIDERS 的 JSON 写错导致后端起不来：JSON 必须合法且外层不带多余引号。实测稳妥写法是 Compose environment 列表项直接写 JSON（见 5.5 实测值）；若从 shell 注入，注意 $ 转义为 $$。写错时的典型表现为后端启动阶段抛 JSON 解析异常退出，docker compose logs keep-backend 可定位。

7.3 每次执行 compose 命令都提示 OPENAI_API_KEY not set：compose 里 - OPENAI_API_KEY=$OPENAI_API_KEY 从宿主环境取值所致，warning 无害（实测零 Key 全功能可用）。删除该行或配置 .env 即可消除。

7.4 改了 workflow YAML 不生效：预置目录中的文件在后端启动时加载，修改后需 docker compose restart keep-backend。UI 编辑器内保存的 workflow 入库 SQLite，与文件预置是两条路径，不要对同一 id 混用。

7.5 interval workflow 的执行记录查不到：实测 0.54.3 中 GET /workflows/executions 返回的列表未包含 interval 触发的执行（只查到 alert 触发的历史记录），但 interval workflow 确实在跑（容器日志每 10 秒输出心跳，见 5.12 实测）。结论：验证 interval workflow 以容器日志为准；这也是 CLI keep workflow runs list 同样查不到 interval 执行的原因（CLI 走同一 API）。

7.6 前端实时刷新失灵：按 5.6 对齐规则核对三方三元组；尤其区分前端 PUSHER_HOST（浏览器视角，填宿主地址）与后端 PUSHER_HOST（容器网络，填服务名）。

八、参考链接

• 官方配置文档（本文参数清单来源）：https://docs.keephq.dev/deployment/configuration
• 认证方式详解：https://docs.keephq.dev/deployment/authentication
• 资源预置文档：https://docs.keephq.dev/deployment/provision/overview
• Workflow 语法（triggers/enrichment 等）：https://docs.keephq.dev/workflows/overview
• 部署实测篇：《Keep Docker Compose 部署指南》
• 选型与架构：《Keep 介绍与选型指南》
• CLI 命令实测：《Keep 0.54.3 常用 CLI 命令与工具详解》