# 运行维护平台 — 技术架构与部署说明

## 1. 开发框架

### 1.1 技术栈

| 层 | 技术 | 版本 | 说明 |
|----|------|------|------|
| Web 框架 | Flask | 2.x | Python 轻量级 Web 框架，应用工厂模式 |
| 搜索引擎 | TF-IDF（自研） | — | 基于词频-逆文档频率的文本相似度搜索 |
| 向量搜索 | Embedding API（预留） | — | OpenAI 兼容 `/v1/embeddings`，当前关闭 |
| AI 分析 | GLM 系列（智谱） | glm-5.1 / glm-4-flash / glm-4-plus | 通过 OpenAI 兼容 API 调用 |
| 前端 | 原生 HTML/CSS/JS | — | 单页应用，SSE 流式输出，无前端框架 |
| 认证 | Flask Session | — | 服务端 Session + Werkzeug 密码哈希 |
| 缓存 | 文件缓存（自研） | — | JSON 文件 + TTL 过期清理 |
| 安全过滤 | 正则匹配（自研） | — | 危险命令检测 + 敏感信息脱敏 |
| 测试 | pytest | 9.x | 145 用例，覆盖率 85%~99% |
| 部署 | systemd + nohup | — | Linux 服务管理 |

### 1.2 项目结构

```
skill/code/web/                    # Web 服务（唯一开发源）
├── server.py                      # 入口：create_app() 应用工厂 + 启动（~150 行）
├── container.py                   # 依赖容器：单例 + config 集中
├── auth.py                        # UserManager 认证
├── decorators.py                  # login_required / admin_required / page_login_required
├── search_engine.py               # 搜索引擎（TF-IDF + Embedding 降级兜底）
├── safety_filter.py               # 安全过滤器
├── cache_manager.py               # 缓存管理器
├── config.json                    # 运行配置（模型/Embedding 开关等）
├── users.json                     # 用户数据
├── routes/                        # 路由层（Blueprint）
│   ├── platform.py                #   / 平台首页（模块卡片）
│   ├── auth.py                    #   /login /logout /api/user/info
│   ├── troubleshoot.py            #   /troubleshoot /api/troubleshoot /search /analyze /stream /health /projects /categories
│   ├── cache.py                   #   /api/cache/stats /clear
│   ├── export.py                  #   /api/export
│   └── submit.py                  #   /api/submit
├── services/                      # 业务层
│   ├── ai_service.py              #   build_prompt / call_claude_api / 流式
│   └── record_service.py          #   rebuild_search_index
├── utils/                         # 工具层
│   ├── modules.py                 #   模块清单声明 + get_modules()
│   ├── paths.py                   #   路径常量
│   ├── vector_builder.py          #   向量预计算脚本（预留）
│   ├── audit.py                   #   log_audit
│   ├── record_utils.py            #   入库纯函数
│   ├── logger.py                  #   通用日志
│   ├── error_codes.py             #   统一错误码
│   └── response.py                #   success/error 响应封装
└── templates/                     # Jinja2 模板
    ├── platform.html              #   平台首页（模块卡片）
    ├── index.html                 #   排查助手主页
    └── login.html                 #   登录页
```

### 1.3 架构设计

```
┌──────────────────────────────────────────────────────┐
│                    Flask App (create_app)             │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ platform  │  │   auth   │  │   troubleshoot    │  │
│  │ Blueprint │  │ Blueprint│  │    Blueprint      │  │
│  │  /        │  │ /login   │  │ /troubleshoot    │  │
│  │ (首页)    │  │ /logout  │  │ /api/troubleshoot│  │
│  │           │  │ /api/... │  │ /api/search      │  │
│  └──────────┘  └──────────┘  │ /api/analyze      │  │
│                                │ /api/health       │  │
│  ┌──────────┐  ┌──────────┐  └───────────────────┘  │
│  │  cache   │  │  export  │  ┌──────────┐           │
│  │ Blueprint│  │ Blueprint│  │  submit  │           │
│  └──────────┘  └──────────┘  │ Blueprint│           │
│                                └──────────┘           │
│  ┌──────────────────────────────────────────────┐    │
│  │              container.py（依赖容器）          │    │
│  │  get_search_engine / get_safety_filter /      │    │
│  │  get_cache_manager / get_config / get_skill_md│    │
│  └──────────────────────────────────────────────┘    │
│                                                      │
│  ┌──────────────────────────────────────────────┐    │
│  │              utils/（工具层）                   │    │
│  │  modules / paths / logger / error_codes /     │    │
│  │  response / audit / record_utils              │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘
```

**依赖方向**：routes/services → container → utils（单向，禁止反向）

### 1.4 模块注册机制

平台通过 `utils/modules.py` 声明式注册模块，首页动态渲染卡片：

```python
# 新增模块只需两步：
# 1. 在 modules.py 的 MODULES 列表追加声明
# 2. 在 server.py 注册对应 Blueprint

MODULES = [
    {"id": "troubleshoot", "name": "问题排查助手", "icon": "🔍", ...},
    {"id": "service-monitor", "name": "服务监控", "icon": "📊", "enabled": False, ...},
]
```

---

## 2. 服务器部署

### 2.1 服务器信息

| 项 | 值 |
|----|-----|
| 服务器 IP | `192.168.5.60` |
| SSH 用户 | `ubains` |
| SSH 密码 | 环境变量 `SSH_PASSWORD`（不硬编码） |
| 操作系统 | Linux（CentOS/Ubuntu） |
| Python | `python3` |
| 部署目录 | `/opt/troubleshoot/` |
| Web 目录 | `/opt/troubleshoot/web/` |
| 服务端口 | `8088` |
| 访问地址 | `http://192.168.5.60:8088` |

### 2.2 目录结构（服务器上）

```
/opt/troubleshoot/
├── web/                            # Flask 应用代码
│   ├── server.py                   # 启动入口
│   ├── container.py                # 依赖容器
│   ├── search_engine.py            # 搜索引擎
│   ├── config.json                 # 运行配置
│   ├── users.json                  # 用户数据
│   ├── routes/                     # 路由层
│   ├── services/                   # 业务层
│   ├── utils/                      # 工具层
│   ├── templates/                  # 前端模板
│   ├── cache/                      # 缓存目录（运行时生成）
│   ├── logs/                       # 日志目录
│   │   └── app.log                 #   通用日志
│   └── audit.log                   # 审计日志
├── 搜索索引.json                    # 知识库索引（357 条）
├── 问题记录/                        # 问题记录存储目录
└── SKILL.md                        # 排查技能参考文档
```

### 2.3 服务管理

#### 启动服务

```bash
cd /opt/troubleshoot/web
nohup python3 server.py > /tmp/troubleshoot.log 2>&1 &
```

#### 停止服务

```bash
pkill -f "python.*server.py"
```

#### 重启服务

```bash
pkill -f "python.*server.py" || true
sleep 2
cd /opt/troubleshoot/web
nohup python3 server.py > /tmp/troubleshoot.log 2>&1 &
```

#### 查看日志

```bash
# 启动日志
tail -f /tmp/troubleshoot.log

# 应用日志
tail -f /opt/troubleshoot/web/logs/app.log

# 审计日志
tail -f /opt/troubleshoot/web/audit.log
```

#### 健康检查

```bash
curl -s http://localhost:8088/api/health
# 期望：{"status":"ok","version":"1.3.0",...}
```

### 2.4 systemd 服务（可选，更规范）

如需开机自启，可配置 systemd：

```ini
# /etc/systemd/system/troubleshoot.service
[Unit]
Description=Troubleshoot AI Assistant
After=network.target

[Service]
Type=simple
User=ubains
WorkingDirectory=/opt/troubleshoot/web
ExecStart=/usr/bin/python3 /opt/troubleshoot/web/server.py
Restart=on-failure
RestartSec=5
Environment=FLASK_DEBUG=0
Environment=SECRET_KEY=your-secret-key-here

[Install]
WantedBy=multi-user.target
```

```bash
# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable troubleshoot
sudo systemctl start troubleshoot

# 管理
sudo systemctl status troubleshoot
sudo systemctl restart troubleshoot
sudo systemctl stop troubleshoot
```

### 2.5 部署流程

#### 自动部署（推荐）

```bash
# 在本地项目根目录执行（需设置 SSH_PASSWORD 环境变量）
cd deploy && SSH_PASSWORD='***' python upload_to_server.py
```

脚本会：
1. SSH 连接到 5.60
2. 上传代码文件和目录
3. 重启服务
4. 健康检查

> ⚠️ 脚本的健康检查 `[FAIL]` 是误报（sleep 3 秒不够），权威验证用 `verify_deployment.py`

#### 权威验证

```bash
cd deploy && python verify_deployment.py
```

#### 手动部署

```bash
# 1. 上传代码（scp 或其他方式）
scp -r skill/code/web/* ubains@192.168.5.60:/opt/troubleshoot/web/

# 2. SSH 到服务器重启
ssh ubains@192.168.5.60
pkill -f "python.*server.py" || true
sleep 2
cd /opt/troubleshoot/web
nohup python3 server.py > /tmp/troubleshoot.log 2>&1 &

# 3. 验证
sleep 15
curl -s http://localhost:8088/api/health
```

---

## 3. 环境配置

### 3.1 环境变量

| 变量 | 必需 | 说明 | 示例 |
|------|------|------|------|
| `SECRET_KEY` | 生产必需 | Flask Session 密钥 | 随机 64 位 hex |
| `CLAUDE_API_BASE` | 是 | AI API 地址 | `https://office.ubainsyun.com:8400` |
| `CLAUDE_API_KEY` | 是 | AI API 密钥 | `sk-xxx` |
| `SSH_PASSWORD` | 部署时 | 部署脚本 SSH 密码 | — |
| `FLASK_DEBUG` | 否 | 调试模式（生产设 0） | `0` |

### 3.2 config.json

```json
{
  "claude_api_base": "https://office.ubainsyun.com:8400",
  "claude_api_key": "在这里填写你的API密钥",
  "models": [
    {"id": "glm-4-flash", "name": "快速模式", "description": "5-10秒"},
    {"id": "glm-5.1", "name": "标准模式", "description": "20-50秒，推荐"},
    {"id": "glm-4-plus", "name": "深度模式", "description": "30-60秒"}
  ],
  "default_model": "glm-5.1",
  "embedding_enabled": false,
  "embedding_model": "text-embedding-3-small",
  "embedding_api_timeout": 10
}
```

---

## 4. 开发指南

### 4.1 本地开发

```bash
# 安装依赖
pip install flask pytest pytest-cov pytest-mock requests numpy

# 运行测试
cd skill/code && python -m pytest -v

# 启动服务（需先解决索引路径，见 CLAUDE.md 坑 2）
python skill/code/web/server.py
```

### 4.2 新增模块步骤

1. 在 `utils/modules.py` 的 `MODULES` 列表追加模块声明
2. 在 `routes/` 下新建 Blueprint 文件
3. 在 `server.py` 的 `create_app()` 注册 Blueprint
4. 在 `templates/` 下新建模块页面模板
5. 更新 `deploy/upload_to_server.py` 上传清单（如有新目录）
6. 测试 + 部署

### 4.3 代码分层约定

- **routes/** — 路由层：只做参数校验、调用 services、返回响应
- **services/** — 业务层：业务逻辑编排
- **utils/** — 工具层：纯函数、无副作用
- **container.py** — 单例与配置集中，不要在各模块重建模块级全局单例
- **依赖方向单向**：routes/services → container → utils
