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)

Frontend (Node 18+ Vue 3 Vite)

Database (SQLite, 本地)

真后端 fixture (历史回归基础)

端口表 (生产部署必填)

网络要求

ES 跨 VPN 真值: 一些校内部署 ES 在另一个网段, 需 vpn.gbu.edu.cn SSL VPN. 测试时 curl http://10.10.1.147:9200/_cluster/health 真过才证明 backend 能连通.

数据卷 (生产部署必规划)

部署模式

当前: 单机演示模式 (试用阶段)

┌──────────────────────────┐
│ 学生 / 助手开发机        │
│ (Linux Ubuntu 22.04)     │
│                          │
│ - Backend Flask :5000    │
│ - Frontend Vite :3002    │
│ - SQLite (本地文件)      │
│ - 通过 SSL VPN 连远端 ES │
│                          │
│ 用户从浏览器访问 :3002  │
└──────────────────────────┘

适合: 试用 / demo / 课程项目.

不适合: 7×24 生产 (Flask dev server 单进程, 没 systemd 守护, 没负载均衡).

推荐生产部署模式 (未来转生产时)

┌──────────┐    ┌─────────────┐    ┌──────────┐
│ 运维浏览器│───→│ nginx :443  │───→│ Flask    │
│          │    │ (静态 SPA + │    │ gunicorn │
└──────────┘    │  反代 :5000)│    │ :5000    │
                └─────────────┘    │ × 4 workers│
                                    └─────┬────┘
                                          │
                                    ┌─────┴────┐
                                    │ systemd  │
                                    │ 守护进程  │
                                    └──────────┘

升级路径:

1. npm run build 出 dist/, 用 nginx 静态托管 (/var/www/log-assistant/)
2. Flask 用 gunicorn -w 4 -b 0.0.0.0:5000 app:app 替代 python backend/app.py
3. systemd unit 文件守护 backend + nginx
4. SQLite → PostgreSQL (告警量大时)
5. HTTPS via nginx + Let’s Encrypt

详见 04-deployment.md §生产部署.

安全边界 (物理禁止)

3 旗硬码在每个 API response 顶层:

SAFETY_FLAGS = {
    "raw_log_scan": False,    # 不直读 ES raw 日志, 只看聚合
    "preview_only": True,     # 所有建议只是预览
    "execution_enabled": False, # 物理禁运维变更
}

任何 backend 改不允许动这 3 旗 (feedback_bitter_lessons_r10_r37 红线 2). 单测 + invariant 双守 (test_phase*_safety.py 系列 + report_status_invariants.py 验出口字段).

详见 03-data-flow.md §安全旗位.

跨模块依赖图

clue_diagnostics
  ├─ clue_parser_v2 (LLM 抽时间窗 + 真凶)
  ├─ clue_qa_planner (15 步 deterministic plan)
  ├─ clue_template_planner
  ├─ dns_diagnostics → dns_report_v2 → dns_failure_drilldown
  ├─ dhcp_diagnostics → dhcp_report_v2 → dhcp_failure_drilldown
  └─ live_query_guard (LIVE_MAX_WINDOW + ALLOW_WIDE_WINDOW)

tool_orchestrator
  ├─ multiround_agent (3 round × 8 tool envelope)
  ├─ dns_tool_registry (8 DNS 工具)
  ├─ dhcp_tool_registry (6 DHCP 工具)
  ├─ tool_plan_validator (LLM plan 校验)
  ├─ agent_stop_policy (sufficient_evidence 早停)
  └─ plan_trace (model/deterministic_seed 出处审计)

hypothesis_reasoner (DNS) + dhcp_hypothesis_reasoner
  ├─ asset_registry → asset_registry_builder (yaml + 多 ES 源 merge)
  ├─ business_impact_estimator + dhcp_business_impact_estimator
  └─ hypothesis_reasoner_schema (输出 schema 强校验)

invariants (出口守门)
  ├─ report_status_invariants (15+ 条)
  ├─ cross_protocol_report_builder
  └─ degraded_reason 推断

修任何 backend .py 前先看依赖图. 红线 6: 不动 phase68.A-F / phase69.A-F 已落改动任何字符 (详见 07-extension §改 backend SOP).

下一步: 03-data-flow.md (4 endpoint × 3 段输出详 + LLM 调用链)