# 部署检查清单

## 完成情况

✅ **环境配置**
- [x] .env 配置文件（包含ES、Redis、DeepL配置）
- [x] environment.yml (conda环境配置)
- [x] config/env_config.py (统一配置管理)
- [x] 代码已更新使用新配置

✅ **启动脚本**
- [x] setup.sh (环境设置)
- [x] start_all.sh (一键启动)
- [x] scripts/ingest.sh (数据导入)
- [x] scripts/start_backend.sh (后端服务)
- [x] scripts/start_frontend.sh (前端服务)

✅ **Web前端**
- [x] HTML界面 (frontend/index.html)
- [x] CSS样式 (frontend/static/css/style.css)
- [x] JavaScript逻辑 (frontend/static/js/app.js)
- [x] 前端服务器 (scripts/frontend_server.py)

✅ **文档**
- [x] USER_GUIDE.md (用户指南)
- [x] README.md (项目说明)
- [x] QUICKSTART.md (快速开始)
- [x] IMPLEMENTATION_SUMMARY.md (实现总结)

## 使用步骤

### 方式1: 一键启动（推荐）

```bash
cd /data/tw/SearchEngine
./start_all.sh
```

然后访问: http://localhost:6003

### 方式2: 分步启动

```bash
# 1. 环境设置
./setup.sh

# 2. 导入数据（1000条，快速测试）
./scripts/ingest.sh 1000 true

# 3. 启动后端（新终端）
./scripts/start_backend.sh

# 4. 启动前端（新终端）
./scripts/start_frontend.sh
```

## 系统要求

### 软件要求
- [x] Python 3.10
- [x] Conda (Miniconda/Anaconda)
- [x] Elasticsearch 8.18
- [ ] CUDA (可选，用于GPU加速)

### 配置要求
- [x] ES连接信息
- [x] DeepL API Key
- [ ] Redis连接（可选）

### 硬件要求
- 内存: 建议8GB+
- 磁盘: 10GB+ (包含模型文件)
- GPU: 可选（加速embedding生成）

## 配置信息

当前配置（.env文件）：
```
ES_HOST=http://localhost:9200
ES_USERNAME=essa
ES_PASSWORD=4hOaLaf41y2VuI8y

REDIS_HOST=localhost
REDIS_PORT=6479
REDIS_PASSWORD=BMfv5aI31kgHWtlx

DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed

TENANT_ID=tenant1
API_HOST=0.0.0.0
API_PORT=6002
```

## 服务端口

| 服务 | 端口 | URL |
|------|------|-----|
| Elasticsearch | 9200 | http://localhost:9200 |
| Backend API | 6002 | http://localhost:6002 |
| Frontend Web | 6003 | http://localhost:6003 |
| API Docs | 6002 | http://localhost:6002/docs |

## 测试流程

### 1. 环境测试

```bash
# 激活环境
source /home/tw/miniconda3/etc/profile.d/conda.sh
conda activate searchengine

# 检查Python
python --version  # 应该显示 Python 3.10.x

# 检查配置
python -c "from config.env_config import print_config; print_config()"
```

### 2. ES连接测试

```bash
# 直接测试
curl http://localhost:9200 -u essa:4hOaLaf41y2VuI8y

# Python测试
python -c "
from config.env_config import get_es_config
from utils.es_client import ESClient
es_config = get_es_config()
client = ESClient(hosts=[es_config['host']], username=es_config.get('username'), password=es_config.get('password'))
print('ES Connected:', client.ping())
"
```

### 3. 数据导入测试

```bash
# 导入100条测试数据（跳过embedding以加快速度）
./scripts/ingest.sh 100 true

# 检查导入结果
python -c "
from config.env_config import get_es_config
from utils.es_client import ESClient
from config import ConfigLoader

es_config = get_es_config()
es_client = ESClient(hosts=[es_config['host']], username=es_config.get('username'), password=es_config.get('password'))
config = ConfigLoader('config/schema').load_tenant_config('tenant1')
count = es_client.count(config.es_index_name)
print(f'Documents in index: {count}')
"
```

### 4. API测试

```bash
# 启动后端（后台）
nohup ./scripts/start_backend.sh > logs/backend.log 2>&1 &

# 等待启动
sleep 5

# 测试健康检查
curl http://localhost:6002/admin/health

# 测试搜索
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "消防", "size": 5}'
```

### 5. 前端测试

```bash
# 启动前端
./scripts/start_frontend.sh

# 然后在浏览器访问: http://localhost:6003
```

## 故障排除

### 问题1: conda环境创建失败

**症状**: `conda env create` 报错

**解决**:
```bash
# 检查conda版本
conda --version

# 更新conda
conda update -n base conda

# 重试创建
conda env create -f environment.yml
```

### 问题2: ES连接失败

**症状**: `Failed to connect to Elasticsearch`

**解决**:
```bash
# 检查ES状态
curl http://localhost:9200 -u essa:4hOaLaf41y2VuI8y

# 检查ES版本
curl http://localhost:9200 -u essa:4hOaLaf41y2VuI8y | grep version

# 确认配置
cat .env | grep ES_
```

### 问题3: 模型下载慢

**症状**: 首次运行时模型下载很慢或超时

**解决**:
```bash
# 跳过embedding快速测试
./scripts/ingest.sh 1000 true

# 或手动下载模型到指定目录
# TEXT_MODEL_DIR=/data/tw/models/bge-m3
# IMAGE_MODEL_DIR=/data/tw/models/cn-clip
```

### 问题4: 端口被占用

**症状**: `Address already in use`

**解决**:
```bash
# 查看占用端口的进程
lsof -i :6002  # 后端
lsof -i :6003  # 前端

# 杀掉进程
kill -9 <PID>

# 或修改.env中的端口
```

## 下一步

1. **测试搜索功能**
   - 打开 http://localhost:6003
   - 尝试不同的搜索查询
   - 测试布尔操作符

2. **查看API文档**
   - 访问 http://localhost:6002/docs
   - 了解所有可用的API端点

3. **自定义配置**
   - 编辑 `config/schema/tenant1_config.yaml`
   - 添加查询重写规则
   - 调整ranking表达式

4. **导入更多数据**
   - 导入完整的10000条数据
   - 生成embeddings以启用语义搜索

5. **性能优化**
   - 启用Redis缓存
   - 调整ES分片数量
   - 使用GPU加速

## 项目文件清单

**新增文件 (环境和启动相关)**:
- [x] .env - 环境配置
- [x] .env.example - 配置模板
- [x] environment.yml - Conda环境
- [x] config/env_config.py - 配置管理
- [x] setup.sh - 环境设置
- [x] start_all.sh - 一键启动
- [x] scripts/ingest.sh - 数据导入
- [x] scripts/start_backend.sh - 后端启动
- [x] scripts/start_frontend.sh - 前端启动
- [x] scripts/frontend_server.py - 前端服务器
- [x] frontend/index.html - 前端页面
- [x] frontend/static/css/style.css - 样式
- [x] frontend/static/js/app.js - 前端逻辑
- [x] USER_GUIDE.md - 用户指南
- [x] DEPLOYMENT.md - 本文件

**总计**: 14个新文件

## 验证完成

运行以下命令验证所有文件都已创建：

```bash
cd /data/tw/SearchEngine

# 检查关键文件
ls -la .env setup.sh start_all.sh
ls -la scripts/*.sh scripts/*.py
ls -la frontend/index.html
ls -la frontend/static/css/style.css
ls -la frontend/static/js/app.js

# 检查可执行权限
ls -l *.sh scripts/*.sh | grep "x"
```

所有文件应该都存在且脚本有执行权限。

## 支持联系

如有问题，请检查：
1. logs/backend.log - 后端日志
2. 浏览器控制台 - 前端错误
3. USER_GUIDE.md - 详细使用说明