01 - 系统概览
一句话定位
校园网络日志助手 = ES 之上的”聚合查询编排 + LLM 解释 + 业务影响识别”中间层. 让运维不写 ES DSL, 用自然语言诊断 DNS/DHCP 故障.
不是什么
| 误解 | 真值 |
|---|---|
| “替代 ELK” | ❌. ES 必须在底层, 本系统不存日志 |
| “替代 Grafana” | ❌. 本系统不画 metric 时序图, 只做”问题诊断” |
| “ChatGPT 套壳问答” | ❌. 真接你的 ES, 真用 14 个白名单 ES 聚合 query, LLM 只编排不直接读 raw |
| “AI 自动修网络” | ❌. 安全三旗物理禁止 (execution_enabled=false). AI 只给建议, 运维手动改 |
是什么
| 真能力 | 真做法 |
|---|---|
| 主动发现问题 | 滚动告警扫描 (10 分钟/次, 看过去 15 分钟 DNS/DHCP 失败率), 越阈值出告警进队列, 运维点告警出 AI 报告 |
| 按线索发现问题 | 运维输入自由文本 “教学区今天 DNS 慢”, LLM 抽时间窗+真凶域名+IP, 跑 14 工具真聚合, 出诊断报告 |
| 业务影响识别 | asset_registry yaml 维护 12 个业务系统 IP 映射, 报告里直接说”影响统一认证 / 校园门户 / 教务系统 …” 而非 “172.16.x.x” |
| 安全边界 | raw_log_scan=false (不直读 raw 日志), preview_only=true (建议预览不执行), execution_enabled=false (禁运维变更) |
跟 ELK / Grafana / Prometheus 对比
| 系统 | 职责 | 跟本系统关系 |
|---|---|---|
| Elasticsearch | 存日志 + 提供 DSL 查询 | 本系统必依赖. 跑在 ES 上层. ES 挂了本系统 fallback 到 2012 历史样本数据 (会显红色 banner) |
| Logstash / Filebeat | 日志采集进 ES | 本系统不管. 假设 ES 里 dns-dnstap-* syslog-bras-* iaaa_app_baseinfo index 已 ready |
| Kibana | ES 探索性查询 + 仪表盘 | 平行存在. 运维想直接看 raw 日志去 Kibana, 想出诊断报告来本系统 |
| Grafana | 时序 metric 图 (CPU/QPS/latency) | 不冲突. Grafana 看趋势, 本系统看故障根因. 后续可能加 Grafana datasource 把本系统报告嵌进面板 |
| Prometheus | metric 采集 + 告警规则 | 平行. 本系统的滚动告警是基于 ES 聚合不是 Prometheus rule |
| Sentry / 自建告警 | 应用层错误告警 | 不重叠. 本系统是网络层 (DNS/DHCP) 不是应用层 |
何时该用 / 不该用
✅ 该用本系统
- 学生反映 “网慢”, 想 10 分钟内定位是 DNS / DHCP / 上游 / 业务系统
- 告警平台报了一堆”DNS 失败 N 次”, 想 AI 帮把同根因的合并 + 给业务影响
- 新员工不会写 ES DSL, 想用中文问 “上周三晚上 OA 打不开”
- 想审计 AI 真凶判定准确度 (跑 R(N) 真后端评估)
❌ 不该用本系统
- 想看 CPU / 内存 / 带宽时序图 → 用 Grafana
- 想 grep 某条原始 syslog → 用 Kibana
- 想自动修复某个故障 (重启 nginx) → 用 Ansible / 自建脚本, 本系统物理禁止变更
- 想做 SIEM 安全审计 → 用 Splunk / ELK + SIEM 插件, 本系统只看 DNS/DHCP 不看安全事件
核心能力清单 (4 endpoint × 3 段输出)
4 个真后端 endpoint
| 端 | URL | 用法 |
|---|---|---|
| A | POST /api/v1/log-assistant/dns/resolver-chain-triage | DNS 单端深度诊断 (给定 resolver_ip + 时间窗, 出报告) |
| B | POST /api/v1/log-assistant/ai/multiround-triage (protocol=dns) | DNS 多轮排障 (AI 自己决定跑哪几个工具) |
| C | POST /api/v1/log-assistant/dhcp/ai-tool-triage | DHCP 单工具诊断 (5 个 DHCP 聚合查询并跑) |
| D | POST /api/v1/log-assistant/ai/multiround-triage (protocol=dhcp) | DHCP 多轮排障 |
加按线索路径 POST /api/v1/log-assistant/clue/diagnose (自由文本输入).
每个 endpoint 真返 3 段输出
| 段 | 字段路径 | 内容 |
|---|---|---|
| AI 推理 | report.ai_reasoning.{available, hypotheses, reasoning_summary, confidence_delta} | LLM 真给的根因假设 + 自然语言解释 |
| 业务影响 | report.business_impact.{asset_context, affected_business_systems, affected_zones, headline_summary} | 资产识别 + 12 业务系统真在场名字 + 影响区域 + 时段 |
| 建议动作 | report.recommended_actions[*].{title, tier, body} | 3-tier 分层 (emergency / mitigation / long_term) |
每段都含 safety_flags={raw_log_scan: false, preview_only: true, execution_enabled: false} 真在场.
详见 03-data-flow.md.
数据来源
| 来源 | 真用途 | 哪个 phase 接的 |
|---|---|---|
ES dns-dnstap-* index | DNS 查询/响应聚合 | Phase 15-17 |
ES syslog-bras-* index | DHCP 消息聚合 | Phase 15-17 |
ES iaaa_app_baseinfo index | 业务系统 IP 反查 | Phase 36 (auto extract) |
asset_registry.yaml | 12 业务系统 + resolver 资产字典 | Phase 32, Phase 68.B 真接对齐 |
servers.demo.json | 业务系统真域名映射 (脱敏占位) | Phase 36 |
topology.json | 网段 zone 标签 | Phase 36 |
| DeepSeek API (云端) + 本地 LLM (优先) | LLM 推理 | Phase 32-34 |
AI 模型清单
| 模型 | 用途 | 何时调 |
|---|---|---|
| 本地 LLM (Qwen 等校内部署) | 主 LLM, 排障推理 | 默认走这个 (OPENCLAW_REASONING_PRIMARY=local-onprem) |
| DeepSeek v4-flash / v4-pro (云端) | Fallback | 本地 LLM 连不上时自动切 (Phase 34 双源接通) |
重要: DeepSeek 官方 model 名是 deepseek-v4-flash / deepseek-v4-pro (2026/07/24 起 deepseek-chat/reasoner 弃用). 配置时不要用老名字.
演进至今 (2026-06-12) 关键 milestone
| 时间 | Milestone | commit |
|---|---|---|
| Phase 15-17 (2026-04) | ES 真接通 + 安全边界确立 | — |
| Phase 32-37 (2026-05) | LLM 加层 + 多轮排障 + 业务影响 + 跨告警关联 | — |
| Phase 49 (2026-05) | 按线索路径基础 (15 步 deterministic plan + LLM enrich) | — |
| R10-R28 (2026-06 早) | phase67 8 件出口字面 caveat 补丁堆积, P0 总数持平 (反例) | — |
| R28-R37 (2026-06-11/12) | phase68 6 件 source-fix lineage 改源头, P0 -1 总分 +30 | 4b11fa0 收口 |
| R1 (2026-06-12) | 按线索 phase69 A-F 6 commit 真凶 5 层修源头, 老师 case 1 真凶 100% 匹配 | 04a8d4c 收口 |
| 当前 | 双主线技术阶段全收口, 运维试用决策窗口 | — |
已知局限 (诚实标)
| 局限 | 影响 | 状态 |
|---|---|---|
DHCP business_impact.asset_context.matched=False 持续 | DHCP 端报告业务影响段为空 | 已知遗留 (phase69.G 候选), 试用反馈决定起不起 |
| LLM C endpoint rank1 翻车率 71% | DHCP 单工具诊断的根因排序不稳定 | LLM 非确定性本质, 试用前必须明示运维 “rank1 是参考不是确定” |
| 168h (7 天) 聚合性能未真验 | 老师真问 7 天大窗口可能超 backend 180s timeout | hard cap 168h 已加, 等老师真示例验 |
| ES 数据源抖动时 fallback 到 2012 演示样本 | 报告基于历史数据, 不反映当下 | phase69.B data_freshness_warning critical banner 真告知 + frontend phase69.E 真渲染 |
| 真后端 fixture 35 个 (主动) + 5 个 (按线索), 覆盖率不广 | 极端场景可能没覆盖 | 鼓励试用期间累积新场景入库 |
详见 08-version-history.md §已知遗留.
下一步: 02-architecture.md (部署架构 + 组件清单 + 端口表)