# 部署指南 - 问题排查助手 Web 服务

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 部署指南 |
| 创建日期 | 2026-07-11 |
| 适用对象 | 运维人员 |
| 状态 | 已完成 |

---

## 一、部署环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows Server 2016+ / Linux |
| Python | 3.8+ |
| 内存 | ≥ 2GB |
| 磁盘 | ≥ 500MB（知识库） |
| 网络 | 内网可访问 |

---

## 二、部署步骤

### 2.1 安装依赖

```bash
cd .claude/skills/Troubleshoot/code
pip install -r requirements.txt
```

依赖列表：
- flask >= 2.3.0
- openpyxl >= 3.1.0
- jieba >= 0.42.1
- scikit-learn >= 1.3.0
- requests >= 2.31.0

### 2.2 配置 Claude API

编辑 `code/web/config.json`：

```json
{
  "claude_api_base": "https://your-api-endpoint",
  "claude_api_key": "your-api-key",
  "claude_model": "glm-5.1",
  "system_types": [...]
}
```

> ⚠️ **重要**：`claude_api_key` 必须配置，否则服务将使用 mock 模式（返回模拟响应）。

### 2.3 启动服务

**Windows（方式一）**：
```batch
双击 code/start.bat
```

**Windows（方式二）**：
```powershell
cd code/web
$env:PYTHONIOENCODING="utf-8"
python server.py
```

**Linux**：
```bash
cd code/web
PYTHONIOENCODING=utf-8 python server.py
```

### 2.4 验证服务

访问：`http://<服务器IP>:8088`

看到以下页面表示启动成功：
- 标题：🔍 问题排查助手
- 副标题：基于 357 条历史问题记录 · AI 智能分析 · 安全过滤

---

## 三、生产环境部署（推荐）

生产环境建议使用 `waitress`（Windows）或 `gunicorn`（Linux）：

### Windows - waitress

```bash
pip install waitress
```

修改 `server.py` 底部：
```python
from waitress import serve
serve(app, host='0.0.0.0', port=8088)
```

### Linux - gunicorn

```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8088 server:app
```

---

## 四、开机自启动

### Windows - 任务计划程序

1. 打开"任务计划程序"
2. 创建基本任务
3. 触发器：计算机启动时
4. 操作：启动程序
   - 程序：`python.exe` 完整路径
   - 参数：`server.py`
   - 起始位置：`code/web` 完整路径

### Linux - systemd

创建 `/etc/systemd/system/troubleshoot.service`：

```ini
[Unit]
Description=Troubleshoot Web Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/troubleshoot/web
Environment=PYTHONIOENCODING=utf-8
ExecStart=/usr/bin/python3 server.py
Restart=always

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

启用服务：
```bash
systemctl enable troubleshoot
systemctl start troubleshoot
```

---

## 五、防火墙配置

开放 8088 端口：

**Windows**：
```powershell
netsh advfirewall firewall add rule name="Troubleshoot Web" dir=in action=allow protocol=tcp localport=8088
```

**Linux（firewalld）**：
```bash
firewall-cmd --permanent --add-port=8088/tcp
firewall-cmd --reload
```

---

## 六、常见问题

### Q1: 启动报错"搜索索引不存在"

**原因**：索引文件未生成或路径不正确。

**解决**：
```bash
cd code
python build_index.py
```

### Q2: 页面显示但搜索无结果

**原因**：索引文件为空或损坏。

**解决**：重新生成索引。

### Q3: AI 分析返回模拟响应

**原因**：`claude_api_key` 未配置。

**解决**：编辑 `config.json` 填写正确的 API 密钥。

### Q4: Windows 控制台乱码

**原因**：默认 GBK 编码。

**解决**：
```powershell
$env:PYTHONIOENCODING="utf-8"
python server.py
```

---

## 七、维护说明

### 日志位置

- 审计日志：`code/web/audit.log`
- 服务日志：控制台输出

### 更新知识库

1. 更新 Excel 源文件：`Docs/PRD/问题知识库/问题反馈跟踪表.xlsx`
2. 运行转换：`python code/xlsx_to_md.py`
3. 重建索引：`python code/build_index.py`
4. 重启服务

---

## 八、联系支持

如有问题，请联系研发组。