tangwang / SearchEngine

DEPLOYMENT.md 6.64 KB

部署检查清单

完成情况

✅ 环境配置

  • [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: 一键启动（推荐）

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

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

方式2: 分步启动

# 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

CUSTOMER_ID=customer1
API_HOST=0.0.0.0
API_PORT=8000

服务端口

服务 端口 URL
Elasticsearch 9200 http://localhost:9200
Backend API 8000 http://localhost:8000
Frontend Web 8080 http://localhost:8080
API Docs 8000 http://localhost:8000/docs

测试流程

1. 环境测试

# 激活环境
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连接测试

# 直接测试
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. 数据导入测试

# 导入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_customer_config('customer1')
count = es_client.count(config.es_index_name)
print(f'Documents in index: {count}')
"

4. API测试

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

# 等待启动
sleep 5

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

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

5. 前端测试

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

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

故障排除

问题1: conda环境创建失败

症状: conda env create 报错

解决:

# 检查conda版本
conda --version

# 更新conda
conda update -n base conda

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

问题2: ES连接失败

症状: Failed to connect to Elasticsearch

解决:

# 检查ES状态
curl http://localhost:9200 -u essa:4hOaLaf41y2VuI8y

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

# 确认配置
cat .env | grep ES_

问题3: 模型下载慢

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

解决:

# 跳过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

解决:

# 查看占用端口的进程
lsof -i :8000  # 后端
lsof -i :8080  # 前端

# 杀掉进程
kill -9 <PID>

# 或修改.env中的端口

下一步

  1. 测试搜索功能

  2. 查看API文档

  3. 自定义配置

    • 编辑 config/schema/customer1_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个新文件

验证完成

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

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 - 详细使用说明