校园网络日志助手 — 技术白皮书
给专业网络运营人员看 — 让你能维护、能排障、能升级、能加新功能. 不是给老板的营销话术. 不是给运维试用员的速查表.
你是谁? 你为什么看这份 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. 不期待你按顺序读完, 按需查.
维护责任 (重要)
| 维护项 | 责任人 | 频率 |
|---|---|---|
| 本白皮书内容更新 | [李凯锋] (项目作者) | 每个新 phase 落地后追加 08-version-history.md |
| backend / frontend 日常 | 试用阶段 [李凯锋] 值班 | 每天看 log + 每周跑 unittest baseline |
| 真后端 fixture R(N) | 评估轮跑时 [李凯锋] 或试用 leader | 每轮 R(N) 自动入 git, 见 04 §4 |
| 安全 P0 真泄漏审计 | [运营团队] 季度 grep | 每季度 1 次 `git log —all -p | grep -E “key |
| Plugin v0.1.2 phase-prompt-guard | [李凯锋] | 任何新 lineage 起时更新 .claude-plugins/.../SKILL.md 的 blacklist/whitelist |
毕业转交流程: 见 08-version-history.md §转交清单.
项目快照 (2026-06-12 真值)
| 维度 | 真值 |
|---|---|
| Git commit 总数 | 144 |
| Backend 测试 baseline | 1850 (passed, 0 fail, 1 skip) |
| 真后端 fixture | 40 个 (R29-R37 主动发现 35 + R1-R5 按线索 5 + R-trial-* 试用轮) |
| Source-fix lineage | phase68 6 件 (A-F) + phase69 6 件 (A/A.1/B/C/D/E + F frontend) |
| Exit-patch lineage (反例) | phase67 8 件 (停手, 不再涨) |
| 主动发现问题 R37 verdict | READY 80/100 |
| 按线索发现问题 R1 verdict | NOT_OVERFIT 79/100 |
| 安全 P0 真泄漏 | 0 处 (filter-repo R31 已洗 + phase68.E 修源头) |
| Plugin | monitor-phase-workflow v0.1.2 (5 检查物理屏障) |
不在本白皮书范围
| 不写 | 看哪 |
|---|---|
| 试用运维用的”一张纸速查” | ../agent-handoff/midterm-stage-5-operator-trial/operator-trial-pack/ |
| 每个 phase 真凶详细 | ../agent-handoff/midterm-stage-5-operator-trial/phase-archive/ |
| R(N) 评估 doc | ../agent-handoff/midterm-stage-5-operator-trial/phase-archive/round-evaluations/ |
| 收口 doc | ../agent-handoff/midterm-stage-5-operator-trial/active-discovery-closeout.md + clue-discovery-closeout.md |
| 代码细节 | 直接 git show <commit> 或读 workspace/system_monitor/backend/ |
| LLM 模型本身 (DeepSeek 内部) | DeepSeek 官方 doc, 本系统不暴露 |
常见误解 (开篇先澄清)
-
“这是 AI 替代 ES/Grafana” → ❌ 错. AI 是在 ES 上做”聚合查询编排 + LLM 解释 + 业务影响识别”. ES 必须在, Grafana 你想用还能用.
-
“AI 自己会改网络配置” → ❌ 错. 安全三旗物理上禁止 (
raw_log_scan=false/preview_only=true/execution_enabled=false). AI 只能查, 给建议; 任何变更必须运维手动操作. -
“AI 推理结果 100% 准确” → ❌ 错. LLM 真凶判定 R34 测真率 ~80%, C endpoint rank1 真翻车率 71% (LLM 非确定性). 必须把 AI 视为参考工具, 不是决断工具.
-
“装一遍就能用, 不用维护” → ❌ 错. ES 数据源, LLM 模型 API, asset_registry 业务字典 都需要持续维护. 见 05 (operations).
-
“出问题就重启大法好” → ⚠️ 部分对. 重启 backend 能解决 60% 问题, 但有 5 类需精确排障, 见 06 (troubleshooting).
下一步: 01-overview.md