diff --git a/docs/specs/v0.6.0/00-release-scope.md b/docs/specs/v0.6.0/00-release-scope.md index 8cc5373..8cf787b 100644 --- a/docs/specs/v0.6.0/00-release-scope.md +++ b/docs/specs/v0.6.0/00-release-scope.md @@ -85,11 +85,10 @@ v0.6.0 保持三个固定角色: 3. Playbook 执行可观测性和控制。 4. Custom Variables。 5. Worker Health。 -6. Integration Health。 -7. SLA 管理,待详细讨论。 -8. AI 质量评估,待详细讨论。 -9. 抑制规则,待详细讨论。 -10. Operations 页面整合,待详细讨论。 +6. SLA 管理,待详细讨论。 +7. AI 质量评估,待详细讨论。 +8. 抑制规则,待详细讨论。 +9. Operations 页面整合,待详细讨论。 SLA、AI 质量评估和抑制规则都是 v0.6.0 正式发布的阻断项,但必须限制为最小可用闭环。 diff --git a/docs/specs/v0.6.0/05-worker-health.md b/docs/specs/v0.6.0/05-worker-health.md index 93881fd..ec402bb 100644 --- a/docs/specs/v0.6.0/05-worker-health.md +++ b/docs/specs/v0.6.0/05-worker-health.md @@ -6,14 +6,13 @@ Status: Confirmed 让 Admin 不依赖 Docker CLI 或日志文件,就能判断后台 Worker 是否存活、正在做什么、是否失败以及业务积压情况。 -v0.6.0 最终监控六个逻辑 Worker: +v0.6.0 最终监控五个逻辑 Worker: 1. Agentic Module。 2. Case Analysis。 3. Playbook。 4. ELK Action。 5. Dashboard Cache。 -6. Integration Health。 监控粒度是逻辑进程类型,不是每个 Module/Playbook definition,也不是 Docker container ID。 @@ -115,7 +114,7 @@ Worker 启动: 5. 启动 heartbeat thread。 6. 进入主循环。 -这适用于所有六个正式 Worker。`--once` 是运维命令,不应长期占用 singleton lease;如果它会与正式 Worker 并行影响同一数据,需要显式决定是否短暂获取 lease,默认建议获取以避免并发。 +这适用于所有五个正式 Worker。`--once` 是运维命令,不应长期占用 singleton lease;如果它会与正式 Worker 并行影响同一数据,需要显式决定是否短暂获取 lease,默认建议获取以避免并发。 ## 6. States @@ -218,12 +217,6 @@ class WorkerIterationResult: - configured interval。 - cache missing 标记。 -### Integration Health - -- enabled target count。 -- Healthy/Unhealthy/Disabled counts。 -- current serial check progress(如果可安全获得)。 - Backlog 查询失败不应使 heartbeat 消失。API 行级 diagnostics 可返回 safe warning。 ## 9. Error safety @@ -290,7 +283,7 @@ Redis health storage 无法访问: - HTTP 503。 - 固定信息:`Worker health monitoring is unavailable.` -- 不返回六个伪造 Down 状态。 +- 不返回五个伪造 Down 状态。 API 不提供: @@ -333,15 +326,14 @@ API 不提供: ## 14. Compose changes -- 新增 Integration Health Worker 服务。 -- 六个 Worker 使用明确 command 和 log role。 +- 五个 Worker 使用明确 command 和 log role。 - 不挂载 Docker socket。 - 不通过 Web app 重启容器。 - Worker singleton 冲突应在日志中明确显示。 ## 15. Acceptance criteria -1. 六类 Worker 正常显示 Starting→Idle/Running。 +1. 五类 Worker 正常显示 Starting→Idle/Running。 2. 第二个同类型实例拒绝启动。 3. heartbeat 10 秒、30 秒过期行为正确。 4. 长 Running 任务保持 heartbeat,不被判 Stalled/Down。 diff --git a/docs/specs/v0.6.0/06-integration-health.md b/docs/specs/v0.6.0/06-integration-health.md deleted file mode 100644 index 4a3b793..0000000 --- a/docs/specs/v0.6.0/06-integration-health.md +++ /dev/null @@ -1,355 +0,0 @@ -# Integration Health - -Status: Confirmed - -## 1. Purpose - -通过独立定时 Worker 主动验证正式支持的外部集成和关键依赖,并在 Admin Operations 页面展示每个配置实例的当前状态。 - -该功能表达“最近一次轻量检查是否成功”,不保证所有业务查询、数据权限或具体动作都可用。 - -## 2. Targets - -定时检查: - -- Splunk singleton config。 -- ELK singleton config。 -- 每个 enabled OpenAI-compatible LLM Provider。 -- AlienVault OTX。 -- OpenCTI。 -- LDAP。 -- Redis。 -- S3-compatible object storage。 - -不检查 PostgreSQL;Web/API 本身已依赖 PostgreSQL。 - -大量 EnrichmentProvider 枚举值不等于可检查的官方集成。 - -## 3. Dedicated Worker - -新增 `run_integration_health_worker`: - -- 使用公共 `run_worker()`。 -- 作为第六类 singleton Worker 出现在 Worker Health。 -- 固定每 5 分钟检查一次。 -- 串行检查目标。 -- 单目标超时 10 秒。 -- 单项失败后继续其他目标。 -- iteration 中任一失败使 Integration Health Worker 本轮 `failure_count > 0`,因此 Worker 状态 Degraded。 - -页面加载不直接 fan-out 外部请求。 - -## 4. States - -持久状态只有: - -- Healthy -- Unhealthy -- Disabled - -附加 reason 表达细节: - -| Situation | State | Reason | -| --- | --- | --- | -| enabled, never checked | Unhealthy | never_checked | -| check running | 保持原状态 | transient `checking=true` | -| last check succeeded | Healthy | ok | -| last check failed | Unhealthy | normalized failure code | -| config disabled | Disabled | disabled | -| config incomplete/not configured | Disabled | not_configured | - -不使用 Unknown/Degraded/Checking 作为持久 state。 - -未配置和 Disabled 是中性状态,不算健康也不算故障。页面不计算整体 platform/integration status。 - -## 5. Data model - -建议模型 `IntegrationHealth`: - -| Field | Type | Notes | -| --- | --- | --- | -| id | UUID | primary key | -| integration_type | string enum | splunk/elk/llm/otx/opencti/ldap/redis/storage | -| config_object_id | nullable string | LLM Provider UUID;singleton/dependency 使用稳定 sentinel | -| display_name | string | safe display label | -| state | enum | Healthy/Unhealthy/Disabled | -| reason_code | string | normalized | -| message | string | fixed safe message | -| checking_started_at | nullable datetime | transient check marker | -| last_checked_at | nullable datetime | any completed check | -| last_success_at | nullable datetime | successful check | -| last_failure_at | nullable datetime | failed check | -| duration_ms | nullable integer | latest check | -| consecutive_failures | nonnegative integer | reset on success | -| updated_at | datetime | auto | - -Constraints: - -- unique `(integration_type, config_object_id)`,null/sentinel 处理必须稳定。 -- index `(state, integration_type)`。 -- 不保存完整 config、URL、username、Secret、response body。 - -只保存当前状态,不保存历史行或趋势。 - -## 6. Configuration synchronization - -### Create - -- 新 enabled config:创建 Unhealthy/never_checked。 -- 新 disabled config:创建 Disabled/disabled。 - -### Update - -相关配置字段改变: - -- Enabled:立即 Unhealthy/configuration_changed。 -- Disabled:Disabled/disabled。 -- 不保留旧 Healthy 到下一个检查。 - -现有 Settings 保存逻辑应在同一 transaction commit 后同步 health 状态。 - -### Delete - -- 多实例配置(例如 LLM Provider)删除时同步硬删除 health row。 -- singleton config 不删除;Disabled 时保留 Disabled row。 -- 配置 CRUD 自身继续由现有 AuditLog 追溯。 - -## 7. Check depth by target - -### LLM - -- 对每个 enabled Provider 发最小 Chat Completions 请求。 -- 验证 base URL、认证、model 和实际推理路径。 -- 限制最大 token,接受每 5 分钟极低但非零费用。 -- 不保存 prompt/response content。 - -### Splunk - -- 使用轻量认证管理/信息接口。 -- 不执行 SPL。 -- 不依赖 index、time field 或数据存在。 - -### ELK - -- 使用集群 info/health 或等价轻量认证接口。 -- 不搜索用户 index。 -- 不将 yellow 等集群业务状态自动扩展为复杂 Degraded;检查器应按能否满足现有连接需求返回 Healthy/Unhealthy,并在 reason code 中规范化。 - -### LDAP - -- 连接服务器。 -- 使用配置的 bind DN/password 进行 service bind。 -- 验证 search base 可访问。 -- 不保存或使用专用普通用户测试密码。 -- 没有 bind DN 时执行当前支持模式下可行的基础连接/search check。 - -### OTX/OpenCTI - -- 调用轻量身份/账户 endpoint。 -- 验证 Token。 -- 不执行 IOC 搜索。 - -### Redis - -- PING。 -- 读取安全的基础 INFO:版本、内存、连接状态。 -- 不写测试 key。 -- 不重复 Module stream backlog diagnostics。 - -### Object storage - -- 验证 endpoint、凭据和目标 bucket metadata/list 权限。 -- 不写入或删除 probe object。 - -## 8. Check service contract - -统一内部结果: - -```python -@dataclass(frozen=True) -class IntegrationCheckResult: - success: bool - reason_code: str - message: str - duration_ms: int -``` - -规范 reason_code 至少包括: - -- ok -- never_checked -- configuration_changed -- not_configured -- disabled -- authentication_failed -- timeout -- tls_error -- connection_refused -- dns_error -- invalid_response -- permission_denied -- service_unavailable -- unknown_error - -message 必须来自固定映射,不直接使用 exception message。 - -## 9. State update rules - -检查开始: - -- 设置 checking_started_at。 -- 不改变当前 state。 - -成功: - -- state=Healthy。 -- reason_code=ok。 -- last_checked_at/last_success_at=now。 -- consecutive_failures=0。 -- 清空 checking_started_at。 - -失败: - -- 第一次失败立即 state=Unhealthy。 -- last_checked_at/last_failure_at=now。 -- consecutive_failures += 1。 -- 保存 normalized reason/message。 -- 清空 checking_started_at。 - -Worker 崩溃遗留 checking_started_at 时,下次 Worker 可覆盖;持久 state 仍是上一次结果。 - -## 10. Manual Settings tests - -保留现有各配置页 Test: - -- 用于测试未保存或已保存配置。 -- 已保存配置的 Test 结果更新对应 IntegrationHealth。 -- 未保存临时配置的 Test 不更新 health。 -- Manual Test 继续写现有 AuditLog。 -- Unified Integration Health 页面不提供 Check Now。 - -普通业务调用的成功/失败永不更新 IntegrationHealth,避免查询输入、限流或业务权限错误污染集成状态。 - -## 11. API - -建议: - -`GET /api/settings/operations/integrations/` - -仅 Admin。 - -返回每个目标/配置实例的独立状态: - -```json -{ - "results": [ - { - "integration_type": "llm", - "config_object_id": "...", - "display_name": "OpenAI Production", - "state": "Healthy", - "reason_code": "ok", - "message": "The provider responded successfully.", - "checking": false, - "checking_started_at": null, - "last_checked_at": "...", - "last_success_at": "...", - "last_failure_at": null, - "duration_ms": 821, - "consecutive_failures": 0, - "settings_route": "/system/llm-providers/..." - } - ] -} -``` - -- 不返回 overall status。 -- 不返回 Secret、完整 endpoint、username 或 response preview。 -- API 只读取 PostgreSQL,不执行检查。 -- Redis target 的健康状态也是定时检查结果;与 Worker Health Redis 503 是不同语义。 - -## 12. Error safety - -UI/API 只显示: - -- normalized reason code。 -- 固定安全 message。 -- check time/duration。 - -禁止: - -- 原始 exception。 -- traceback。 -- response body。 -- URL query。 -- username。 -- API key/token/password。 - -完整异常进入 Integration Health Worker log,仍需遵循现有日志 Secret 规范。 - -## 13. Permissions and audit - -- 仅 Admin 可看 API/UI。 -- User/Viewer 403。 -- Scheduled check 不写 AuditLog。 -- 定时状态变化不写 AuditLog。 -- Manual saved-config Test 写现有 AuditLog。 -- 不发送 Inbox/Webhook 健康通知。 - -## 14. Frontend - -位置:`System Settings → Operations → Integration Health`。 - -- 与 Worker Health 独立表格/API。 -- 每 30 秒读取 PostgreSQL 当前状态。 -- 提供页面手动 Refresh,但不触发外部检查。 -- 展示 integration type/name/state/reason/last check/duration/consecutive failures。 -- Disabled/Not configured 可见且使用中性样式。 -- enabled never checked 显示 Unhealthy + Never checked。 -- checking 时保留原 state Tag并显示 Checking 辅助标记。 -- 行可跳转对应 Settings 页面。 -- 不显示 overall status。 -- 不提供 Check Now。 - -## 15. Worker Health interaction - -Integration Health Worker 自身: - -- 使用第六个 Worker type。 -- heartbeat/lease 遵循 Worker Health Spec。 -- 本轮任一集成失败时 WorkerIterationResult.failure_count > 0,Worker Health 显示 Degraded。 -- Integration 表显示具体失败目标。 -- Redis health target 失败可能同时导致 Worker 心跳不可用;此时 Worker Health API 可能 503,但 PostgreSQL 中最后 Integration Health 结果仍可显示。 - -## 16. Migration - -- 创建 IntegrationHealth 表。 -- 为现有配置生成初始行: - - enabled/configured → Unhealthy/never_checked。 - - disabled/incomplete → Disabled。 -- 不在 migration 中访问外部服务。 -- 添加 Integration Health Worker Compose service。 -- 更新 log role mapping。 - -## 17. Acceptance criteria - -1. Worker 每 5 分钟串行检查所有 eligible targets。 -2. 每项超时 10 秒,失败不阻止后续目标。 -3. 各目标使用已确认的轻量检查深度。 -4. enabled 首次检查前 Unhealthy/never_checked。 -5. 一次失败立即 Unhealthy,一次成功立即恢复。 -6. config 修改立即 configuration_changed。 -7. saved-config Test 更新状态,unsaved Test 不更新。 -8. 业务请求不更新状态。 -9. 删除 LLM Provider 同步删除 health row。 -10. API 不执行外部请求、不返回敏感信息。 -11. Admin-only 和 30 秒 UI 刷新正确。 -12. Worker 自身出现在 Worker Health。 - -## 18. Known tradeoffs - -- 没有历史趋势和整体状态。 -- 没有统一 Check Now。 -- LLM 检查产生持续小额调用成本。 -- 一次瞬时失败立即 Unhealthy,可能产生短暂抖动,但当前不发送通知。 -- 轻量管理接口 Healthy 不等于所有索引、模型能力或业务查询均正常。 diff --git a/docs/specs/v0.6.0/README.md b/docs/specs/v0.6.0/README.md index 55335de..6dcccbc 100644 --- a/docs/specs/v0.6.0/README.md +++ b/docs/specs/v0.6.0/README.md @@ -11,7 +11,6 @@ | [02-case-merge.md](02-case-merge.md) | Confirmed | 多源案件合并、数据迁移、只读源案件与幂等 | | [03-playbook-execution.md](03-playbook-execution.md) | Confirmed | Playbook Run、结构化 Stage、取消、重试与 Worker 语义 | | [05-worker-health.md](05-worker-health.md) | Confirmed | Redis 心跳、Worker 状态、积压指标与 Admin API | -| [06-integration-health.md](06-integration-health.md) | Confirmed | 定时集成检查、当前状态持久化与安全错误 | | [07-sla-management.md](07-sla-management.md) | Confirmed | TTD/TTA/TTR 时限、Severity 策略、通知和 Dashboard 达标率 | ## 待讨论 @@ -22,9 +21,8 @@ 1. 先完成 Case 状态机,再实现批量分诊和案件合并。 2. 完成 Playbook Run/Stage 后实现 Custom Variables。 -3. 完成通用 Worker Health 基础设施,再接入六类 Worker。 -4. 完成 Integration Health 数据层和 Worker,再实现 Operations 页面。 -5. 待剩余三个业务域定稿后,统一补齐 v0.6.0 验收规范。 +3. 完成通用 Worker Health 基础设施并接入五类 Worker,再实现 Operations 页面。 +4. 待剩余三个业务域定稿后,统一补齐 v0.6.0 验收规范。 ## Spec 使用规则 diff --git a/docs/specs/v0.6.0/TODO-remaining-domains.md b/docs/specs/v0.6.0/TODO-remaining-domains.md deleted file mode 100644 index ea5e3a5..0000000 --- a/docs/specs/v0.6.0/TODO-remaining-domains.md +++ /dev/null @@ -1,114 +0,0 @@ -# v0.6.0 remaining domain TODO - -Status: Not discussed - -本文件用于在另一台电脑或新会话中继续产品讨论。以下内容仅是讨论清单,不是已确认需求。 - -## TODO 1: AI quality evaluation - -Release blocking: Yes - -Goal: 用人工最终判断评估 AI 严重度、置信度、影响、优先级和 Verdict 的质量,形成可解释的反馈闭环。 - -需要逐项决定: - -- 评估对象是所有 AI 字段,还是先只做 Verdict/Severity。 -- 何时生成评价记录:字段修改、Case Close 或定时快照。 -- AI 输出与人工输出为空时如何处理。 -- 一次 Case 多次 AI 分析如何选择被评估版本。 -- 是否必须保存 model、provider、prompt slug/version 和 analysis job。 -- 指标使用 agreement rate、confusion matrix、precision/recall 还是更简单统计。 -- Verdict 多分类如何归并,Unknown/Insufficient Data 是否排除。 -- 分析师是否提供显式 thumbs up/down 和错误原因。 -- 是否允许抽样复核和争议标记。 -- 时间窗口、Provider、Model、Playbook/Trigger、Case category 等筛选维度。 -- 数据保留、历史不可变性和模型配置删除后的展示。 -- Dashboard/独立页面的信息架构。 -- 权限和匿名化要求。 -- 是否将反馈用于自动 prompt 优化;建议 v0.6.0 排除自动学习。 -- 审计、迁移和验收案例。 - -输出目标:`08-ai-quality-evaluation.md`。 - -## TODO 2: suppression rules - -Release blocking: Yes - -Goal: 在告警进入 Case 流程前降低已知噪声,同时保留可审计的命中记录,避免简单删除安全数据。 - -需要逐项决定: - -- Rule 匹配对象是原始 Webhook、标准化 Alert 字段还是 Module 输出。 -- 可匹配字段白名单以及 text/exact/list/CIDR/regex 运算符。 -- 多条件 AND/OR 能力和是否允许嵌套。 -- Rule 作用域:全局、Module、rule_id、产品或数据源。 -- 动作是 drop、mark suppressed、route to existing Case 还是不创建 Case。 -- 被抑制事件是否持久化;存储多少原始数据。 -- Rule 优先级、first-match 或 all-match。 -- Enabled、有效期、自动过期和命中计数。 -- 模拟/预览如何在历史样本上运行,是否必须先模拟再启用。 -- 如何防止一条宽泛 Rule 隐藏大量真实告警。 -- Admin/User/Viewer 权限;建议至少创建/修改仅 Admin。 -- 命中 AuditLog、Rule 变更审计和 Secret/PII 脱敏。 -- Module correlation 与 merged source routing 的执行顺序。 -- 列表、详情、命中历史和筛选 UX。 -- 数据库索引、性能目标和验收案例。 - -输出目标:`09-suppression-rules.md`。 - -## TODO 3: Operations Center - -Release blocking: Depends on final scope - -已确认的固定边界: - -- 位于 `System Settings → Operations`。 -- 包含 Worker Health 和 Integration Health 两个独立区块。 -- 仅 Admin 可访问。 -- Worker 每 10 秒刷新,Integration 每 30 秒刷新。 -- 不提供 Worker Restart、Run Now、日志读取或健康通知。 -- Integration 不提供统一 Check Now;保留各 Settings 页的 Test。 -- 不计算整体 Integration Health。 - -仍需决定: - -- 页面布局、过滤、排序、状态颜色和移动端是否考虑。 -- Worker backlog 的不同数据结构如何展示。 -- 如何从 Integration 行跳转到对应 Settings。 -- Redis 监控不可用时页面局部还是整体错误。 -- Operations 导航徽标是否显示异常数量。 -- 是否显示 Compose 修复命令,以及具体安全文本。 -- 空状态、加载状态和权限拒绝 UX。 -- API 聚合还是前端调用两个独立 API。 -- 前端组件复用和验收案例。 - -输出目标:`10-operations-center.md`。 - -## TODO 4: v0.6.0 acceptance - -Release blocking: Yes - -需要在所有功能 Spec 完成后定义: - -- 从 v0.5.2 生产备份副本升级的完整演练。 -- 全新 Docker Compose 安装。 -- medium 数据规模下的关键 API/页面性能阈值。 -- Admin/User/Viewer 权限矩阵回归。 -- Case 单条和批量状态机一致性。 -- 部分成功批量分诊、原子合并、幂等重试和 merged source 路由。 -- Playbook Pending/Running/终态、Cancel、Retry、Stage 和 Worker 崩溃恢复。 -- Custom Variables 的 Secret masking、Reveal audit 和 Module/Playbook 读取。 -- Worker Redis 故障、重复实例、优雅退出和心跳过期。 -- 所有正式集成的 Healthy/Unhealthy/Disabled 行为。 -- SLA、AI 质量评估和抑制规则端到端场景。 -- 备份、恢复和回滚演练。 -- 文档、release notes、已知限制和功能冻结条件。 -- P0/P1 缺陷门槛和 RC 观察周期。 - -输出目标:`11-release-acceptance.md`。 - -## Suggested continuation prompt - -在新电脑上可从下面的提示继续: - -> 阅读 `docs/specs/v0.6.0/README.md` 和 `TODO-remaining-domains.md`。已确认 Spec 不要重新讨论。从 AI quality evaluation 开始,一次只问一个决策问题,每个问题给出推荐答案;确认完成后依次处理 suppression rules、Operations Center 和 release acceptance。