项目

校园网络日志助手 — 技术白皮书 给专业网络运营人员看 — 让你能维护、能排障、能升级、能加新功能. 不是给老板的营销话术. 不是给运维试用员的速查表. 你是谁? 你为什么看这份 doc? 你的角色 推荐读法 首次接手项目 (从学生手里接) 顺序 01 → 02 → 04 → 05, 1 周内通读, 边读边按 SOP 跑一遍 日常运营维护 收藏 05 (operations) + 06 (troubleshooting), 出问题 grep 关键词翻 加新功能 / 改 backend 必读 07 (extension) + 08 (version-history), 不读教训 = 重蹈 R10-R28 覆辙 领导 / 评标方需要 overview 看 01 (~150 行, 15 分钟) 就够 debug 某个真字面 / error code 直接 grep 06 (troubleshooting) 关键词 8 章导航 # 章节 关键问题 大小 1 01-overview.md 这是什么? 跟 ELK/Grafana 有啥区别? ~150 行 2 02-architecture.md 组件怎么搭? 哪个端口? 谁连谁? ~300 行 (含 ASCII 部署图) 3 03-data-flow.md AI 真在做什么? 数据怎么流? ~400 行 (含 4 endpoint × 3 段输出详) 4 04-deployment.md 如何装机? 配置项怎么填? ~300 行 (含全 ENV 表) 5 05-operations-manual.md 日常运维 SOP (启停 / 看 log / 健康检查 / 备份) ~400 行 6 06-troubleshooting.md 出问题怎么排? error code 真表 ~500 行 7 07-extension-guide.md 加新功能怎么做? 改 backend 必做 SOP ~300 行 8 08-version-history.md 系统怎么演进到现在? 教训是什么? ~400 行 总 ~2750 行, ~70 页 A4. 不期待你按顺序读完, 按需查. ...

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 (自由文本输入). ...

02 - 部署架构 部署拓扑 (ASCII 图) ┌─────────────────────────────────────────────────────────────────────┐ │ 校内 GBU 网络环境 │ │ │ │ ┌──────────────┐ ┌────────────────┐ │ │ │ 运维浏览器 │──HTTP─→│ Frontend │ │ │ │ (admin role) │ 3002 │ Vite dev / │ │ │ └──────────────┘ │ Vue 3 SPA │ │ │ ↑ └────────┬───────┘ │ │ │ HMR/static reload │ │ │ │ │ axios POST /api/v1/log-assistant/* │ │ │ ↓ │ │ ┌─────┴────────────────────────────────────────────────────┐ │ │ │ Backend Flask (port 5000) │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ │ 51 API routes / log_assistant_api.py 主入口 │ │ │ │ │ │ - /dns/resolver-chain-triage (A) │ │ │ │ │ │ - /ai/multiround-triage (B, D) │ │ │ │ │ │ - /dhcp/ai-tool-triage (C) │ │ │ │ │ │ - /clue/diagnose (按线索) │ │ │ │ │ │ - /alerts /feedback /audit / ... │ │ │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ tool_ │ │ hypothesis_ │ │ business_ │ │ │ │ │ │ orchestrator │──→│ reasoner + │──→│ impact_ │ │ │ │ │ │ (14 工具) │ │ dhcp variant │ │ estimator │ │ │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ │ │ │ │ ↓ ↓ ↓ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ │ │ invariants / sanitizers / safety guards │ │ │ │ │ │ - report_status_invariants (15+ 守门) │ │ │ │ │ │ - sanitize (输出禁敏感字面) │ │ │ │ │ │ - safety_flags 三旗物理禁 │ │ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ └────┬────────────────┬───────────────────────┬───────────┘ │ │ │ │ │ │ │ ↓ ES DSL ↓ HTTP ↓ 读 yaml │ │ ┌─────────┐ ┌──────────────────┐ ┌────────────────────┐ │ │ │ ES 集群 │ │ 本地 LLM (主) │ │ asset_registry.yaml│ │ │ │ :9200 │ │ Qwen 等 校内部署 │←┐ │ 12 业务系统真值 │ │ │ │ via VPN │ │ │ │ │ servers.demo.json │ │ │ │ │ └──────────────────┘ │ │ topology.json │ │ │ │ index: │ │ └────────────────────┘ │ │ │ dns- │ │ fallback │ │ │ dnstap* │ ┌──────────────────┐ │ │ │ │ syslog- │ │ DeepSeek API │─┘ │ │ │ bras* │ │ v4-flash/v4-pro │ │ │ │ iaaa_* │ │ (云端 fallback) │ │ │ └─────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ 组件清单 Backend (Python 3.10+ Flask) 组件 路径 行数 职责 API 入口 workspace/system_monitor/backend/api/log_assistant_api.py 2600+ 51 个 HTTP route + dispatch 各 endpoint Assistant 业务模块 workspace/system_monitor/backend/assistant/*.py ~60 文件 14 工具 + 2 reasoner + clue_diagnostics + invariants + sanitizers Tool orchestrator workspace/system_monitor/backend/assistant/tool_orchestrator/ ~10 文件 multiround agent + plan validator + tool registry (DNS/DHCP) Asset registry workspace/system_monitor/backend/assistant/asset_registry*.py ~3 文件 yaml + ES 多源 merge 出 12 业务系统 + 21 subnet + 21 resolvers Sanitizer workspace/system_monitor/scripts/sanitize_fixture.py ~250 行 真后端 fixture 入库前脱敏真生产域名/IP/MAC Plugin (元工程) .claude-plugins/monitor-phase-workflow/ ~180 行 phase-prompt-guard 5 检查 (本项目专用, 不入全局) Frontend (Node 18+ Vue 3 Vite) 组件 路径 数 职责 Vue 3 SPA workspace/system_monitor/frontend/ 58 文件 用户 UI, 单页应用 主组件 LogAssistant frontend/src/components/logAssistant/ ~30 .vue 告警队列, 报告卡, 反馈按钮, 按线索输入 API client frontend/src/api/index.js ~1200 行 axios 包装 51 个 backend API Vite npm run dev (port 3002) – dev server HMR Vite build npm run build – 生产打包 (chunk-size warning 已知, 不阻塞) Database (SQLite, 本地) DB 路径 真用途 主 DB workspace/system_monitor/backend/diagnose/database/monitor.db 告警队列 / 反馈记录 / audit log / 网络设备表 临时 DB /tmp/claude-1000/tmpXXXX/monitor.db 单测真跑 (mtime 后即清) 真后端 fixture (历史回归基础) 目录 真值 用途 workspace/system_monitor/test_backup/fixtures_real_backend/ 35 个 R29-R37 JSON 主动发现路径回归 workspace/system_monitor/test_backup/fixtures_real_backend_clue/ 10 个 R1-R5 clue JSON 按线索路径回归 raw_* 前缀 gitignored 脱敏前真值, 入库前删 端口表 (生产部署必填) 服务 默认端口 真用 ENV 改 用途 Backend Flask 5000 (硬码, 改要动 backend/app.py) HTTP API Frontend Vite (dev) 3002 frontend/vite.config.js 开发用 SPA, 生产改 nginx 静态托管 Elasticsearch 9200 OPENCLAW_ES_URL (default http://10.10.1.147:9200) ES DSL 查询 本地 LLM (Qwen 等) [本地部署 url, e.g. http://10.10.x.x:8000] OPENCLAW_LOCAL_URL LLM 主推理 DeepSeek API HTTPS 443 OPENCLAW_DEEPSEEK_URL=https://api.deepseek.com LLM fallback 网络要求 流量方向 端口 协议 必须放通 运维浏览器 → Frontend 3002 HTTP 校内 Frontend → Backend 5000 HTTP 同机 / 校内 Backend → ES 9200 HTTP 跨校内 VPN, 见下文 Backend → 本地 LLM [本地端口] HTTP 校内, 同机房 Backend → DeepSeek API 443 HTTPS 必须出公网 (本地 LLM 挂时 fallback 救命) ES 跨 VPN 真值: 一些校内部署 ES 在另一个网段, 需 vpn.gbu.edu.cn SSL VPN. 测试时 curl http://10.10.1.147:9200/_cluster/health 真过才证明 backend 能连通. ...

03 - 数据流详解 AI 真在做什么? 怎么从 “运维点告警” 走到 “出诊断报告”? 总览数据流 运维操作 Backend 真做 数据真去向 ───────── ────────── ───────── [选告警 / 自由文本] ──→ alert envelope 或 clue parser ──→ context (resolver_ip + window) │ ↓ [_context_window 验时间窗合法] │ ↓ ┌─────────┴──────────┐ │ deterministic seed │ ← Phase 68.C: incident_window fallback │ plan (round 1) │ └────────┬───────────┘ │ ↓ [tool_plan_validator 校 args] │ ↓ ┌──────────────┴─────────────┐ │ 跑 ES 聚合 (8 DNS / 6 DHCP) │ → ES :9200 真返聚合数字 │ tool_orchestrator │ └──────────────┬─────────────┘ │ ↓ [tool_trace 记录] │ ↓ ┌──────────────┴─────────────┐ │ multiround: round 2 / 3 │ │ model planner (LLM) 决定 │ ← LLM 真调 │ 下一步跑哪几个工具 │ └──────────────┬─────────────┘ │ ↓ [agent_stop_policy 早停判定] │ ↓ ┌──────────────┴─────────────┐ │ build_multiround_report │ ← Phase 68.D 真凶: 这里生成 hypothesis │ (生成 root_cause_hypotheses)│ └──────────────┬─────────────┘ │ ↓ ┌──────────────┴─────────────┐ │ reasoner_factory 装回 │ ← Phase 68.D 加 post-build retry hook │ ai_reasoning 字段 │ └──────────────┬─────────────┘ │ ↓ ┌──────────────┴─────────────┐ │ asset_registry lookup │ ← Phase 68.B/F: asset_context.matched │ → business_impact │ 12 业务系统真识别 └──────────────┬─────────────┘ │ ↓ ┌──────────────┴─────────────┐ │ recommended_actions builder │ │ (3 tier: emergency/ │ │ mitigation/long_term) │ └──────────────┬─────────────┘ │ ↓ ┌──────────────┴─────────────┐ │ report_status_invariants │ ← 15+ 守门, 出口前最后验 │ + sanitizers + safety_flags │ (phase68.E sanitize CJK regex) └──────────────┬─────────────┘ │ ↓ JSON [Frontend Vue 真渲染] │ ↓ [运维看 3 段输出] 4 endpoint × 3 段输出真值 Endpoint A: DNS Resolver-Chain Triage (单端) 真请求: ...

04 - 装机 SOP 从 git clone 到运维真能用, 30-60 分钟. 出问题对照 06-troubleshooting.md. 系统要求 项 要求 真验 OS Linux Ubuntu 22.04+ (本项目真用), 其他 distro 理论可 lsb_release -a Python 3.10+ (本项目真用 3.10, 不用更老) python3 --version Node.js 18.x+ (Vue 3 + Vite 8 真需要) node --version npm 9.x+ npm --version Git 2.30+ (filter-repo 真需要) git --version 磁盘 5 GB+ (含 node_modules 127M + venv 55M + logs 累积) df -h RAM 2 GB+ (backend Flask 500MB + frontend Vite 200MB) free -m 网络 校内 + 出公网 (DeepSeek API fallback 救命) curl -I https://api.deepseek.com 4 步装机 步骤 1: clone 代码 + venv # 1. clone cd ~/code/project git clone <repo-url> cs-26spring-final-project cd cs-26spring-final-project # 2. 建 venv cd workspace/system_monitor python3 -m venv backend/.venv source backend/.venv/bin/activate pip install --upgrade pip pip install -r backend/requirements.txt # 验 backend/.venv/bin/python -c "import flask; print(flask.__version__)" # 期望: 3.1.3+ (本项目真用 3.1.3) 步骤 2: frontend 依赖 cd workspace/system_monitor/frontend npm install # 真返时间: ~30s (校内镜像) / 5 min (官方源) # 验 npm run build 2>&1 | tail -3 # 期望: ✓ built in N.NNs 步骤 3: 配置 .env.local (机密, 不入 git) cd workspace/system_monitor cp .env.local.example .env.local vim .env.local 必填项 (无这些 backend sys.exit(1)): ...

05 - 日常运维 SOP 出问题翻 06-troubleshooting.md. 本文是预防性日常. 每天做的事 (~5 分钟) 1. Health check cd /home/kk/code/project/cs-26spring-final-project # Backend 还在跑? pgrep -af "backend/app.py" | grep -v "bash -c" # 期望: 1 行真返 (PID + cmd) # Frontend dev (试用阶段) 还在跑? pgrep -af "vite" | grep -v "bash -c" # 期望: 1 行真返 (Vite dev server) # 生产 nginx 用 sudo systemctl status nginx 看 # Backend HTTP 响应 curl -s -o /dev/null -w "HTTP %{http_code}\n" --max-time 5 http://127.0.0.1:5000/api/v1/healthz # 期望: 200 / 401 / 404 (都算在跑); 000 = 死了重启 # Backend log tail (有无 OPENCLAW timeout / ES 5xx) tail -50 workspace/system_monitor/logs/backend-verify.log | grep -E "ERROR|Traceback|timeout|5xx" | tail -10 # 期望: 0 行或少量 retry warning 即可 2. 安全 grep (audit 真生产数据) # 真生产域名 grep (Phase 68.E sanitize 修源头后应 0) tail -500 workspace/system_monitor/logs/backend-verify.log | grep -cE "deepinstinctweb|gbu\.edu" || echo "0" # 期望: 0 (backend log 可能含真上游 ES 数据, 累积 0-5 行不算严重, > 50 行说明 sanitize 漏) # 真 MAC grep (RFC 1918/5737 占位 ✓ 真 MAC ❌) tail -500 workspace/system_monitor/logs/backend-verify.log | grep -cE "[0-9a-f]{2}(:[0-9a-f]{2}){5}" || echo "0" # 0 = 无真 MAC; > 0 需看是不是 02:00:00:* 占位 (Phase 67.A.1 sanitize 生成的, 合法) 3. 反馈表汇总 (试用阶段) # 看运维填了多少 curl -s --max-time 5 http://127.0.0.1:5000/api/v1/log-assistant/feedback/summary \ -H "Authorization: Bearer <admin_token>" | python3 -m json.tool # 期望真返: {"useful": N, "needs_more": M, "false_positive": K, ...} # 试用第 1 周末看是否 N+M+K > 0 (有真反馈) 每周做的事 (~30 分钟) 1. 跑 unittest baseline 验真 cd workspace/system_monitor PYTHONPATH=. ./backend/.venv/bin/python -m unittest discover test_backup 2>&1 | tail -5 # 期望: Ran 1850 tests in NN.NNs OK (skipped=1) # 真退 = 真有 phase 改源破回归, 立即: # 1. git log --oneline 最近 5 commit 看改了啥 # 2. 还原到上一个 PASS 的 commit # 3. 起 phase 修真凶 2. 跑 R(N) 评估轮 (验真后端真稳定) cd workspace/system_monitor ./scripts/run_round_evaluation.sh r-week<N> 6 步 pipeline 真跑: ...

06 - 真排障手册 直接 Ctrl+F 搜你看到的真字面 (error code / log 关键词). 5 类紧急情况 + 全 degraded_reason 真表 + 真后端 trace 看法. 紧急程度 4 档 档 真症状 响应时间 升级 🚨 P0 紧急 系统完全死 / 真泄漏发现 / 真安全事件 < 5 min 立即 SSH 上去, 见下 §5 类紧急 ⚠ P1 重要 AI 报告字面错 / 关键 endpoint degraded < 30 min 看 backend log + grep degraded_reason 📝 P2 一般 某场景偶发 false_positive / UI 体验差 < 1 day 收集反馈, 起 phase 💡 P3 改进 运维建议加新功能 试用结束汇总 起 preliminary doc 5 类紧急情况 (P0) 紧急 1: backend 完全不响应 真症状: ...

07 - 扩展指南 加新功能 / 改 backend / 加新检测家族. 必读 — 不读会重蹈 R10-R28 19 轮覆辙. 改 backend 必做 SOP 任何 backend .py 改动 (新加功能 / 修 bug / 改 LLM prompt) 走以下 6 步: Step 1: 起 phase 前先调查 (不允许直接动手) 找真凶 - 不靠猜, 靠 venv 实测 + 真后端 fixture 复现: cd workspace/system_monitor # 跑某真后端 fixture 验真凶现状 PYTHONPATH=. ./backend/.venv/bin/python -c " import json d = json.load(open('test_backup/fixtures_real_backend/r37_b_dns_multi.json')) # 真验你怀疑的字段... " grep 同源 lineage 件数 - 决定该改源头还是出口补丁: ...

08 - 版本演进 + 教训 按问题 → 方案 → 教训 写, 不是 feature flow. 让你看懂为什么系统长成现在这样. 阶段 1: ES 接通 + 安全边界 (Phase 3-17, 2026-04) 问题 运维不会写 ES DSL, 想用自然语言查 DNS/DHCP 异常. 方案 Backend 封装 4 个聚合 query API (DNS failure summary / DHCP message summary / 失败 drilldown / top X) 安全三旗物理禁止 (raw_log_scan=false / preview_only=true / execution_enabled=false) 真后端 ES 用聚合不读 raw 文档 教训 没有, 这阶段真凶链路简单, 0 出口补丁 阶段 2: AI 加层 (Phase 32-37, 2026-05) 问题 聚合数字给运维但他还要解释 (“失败率 35.73% 说明啥?”), 想 LLM 把数字翻成自然语言. ...