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 收口 |
| 当前 |
双主线技术阶段全收口, 运维试用决策窗口 |
– |
详见 08-version-history.md.
已知局限 (诚实标)#
| 局限 |
影响 |
状态 |
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 (部署架构 + 组件清单 + 端口表)