1. 系统要求
- 操作系统：Linux（推荐 Ubuntu 18.04+）
- Conda：Miniconda3 或 Anaconda（用于 Python 环境隔离）
- Python：3.10（由 Conda 环境提供）
- 内存：建议 8GB+（含模型与 ES）
- 磁盘：10GB+（含模型与索引）
2. Python 运行环境
本项目历史上使用 Conda 管理环境；目前推荐使用 venv（更轻量、对 CI/容器更友好）。项目根目录下的 activate.sh 已升级为 优先激活 .venv，并兼容 Conda 回退，且会自动加载当前目录下的 .env（忽略注释与空行）。
2.1 venv（推荐）
首次创建 venv：
cd /data/saas-search
./scripts/create_venv.sh
source activate.sh
如需运行本地 embedding / 图像编码服务（torch/transformers 等依赖较重）：
cd /data/saas-search
INSTALL_ML=1 ./scripts/create_venv.sh
source activate.sh
日常使用：
cd /data/saas-search
source activate.sh
2.2 Conda（兼容旧流程）
activate.sh 会在未发现 .venv 时回退激活 Conda 环境 searchengine。若在新机器上部署，请先设置本机 Conda 路径再执行：
# 你的 conda 在 ~/anaconda3/bin/conda，则 CONDA_ROOT=~/anaconda3
export CONDA_ROOT=$HOME/anaconda3 # 或你的 Conda 安装路径（如 /home/ubuntu/anaconda3）
source activate.sh
新机器首次部署（创建 Conda 环境）：若本机尚未创建 searchengine 环境，任选其一：
- 方式 A（推荐，与 environment.yml 一致）：
bash cd /data/saas-search export CONDA_ROOT=$HOME/anaconda3 # 或你的 Conda 安装路径 conda env create -f environment.yml source activate.sh - 方式 B（仅 pip）：
bash conda create -n searchengine python=3.10 -y conda activate searchengine cd /data/saas-search pip install -r requirements.txt
之后日常使用执行 source activate.sh 即可（如需可先 export CONDA_ROOT=...）。
3. 外部服务与端口
| 服务 | 默认地址 | 说明 |
|---|---|---|
| Elasticsearch | http://localhost:9200 |
可通过 Docker 单节点启动 |
| MySQL | 120.79.247.228:3316 |
存放店匠 SPU/SKU 数据 |
| Redis（可选） | localhost:6479 |
Embedding/翻译缓存 |
示例：使用 Docker 启动 Elasticsearch
docker run -d \
--name elasticsearch \
-p 9200:9200 \
-e "discovery.type=single-node" \
-e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \
elasticsearch:8.11.0
4. 环境变量与 .env 模板
在项目根目录创建 .env，并根据环境替换敏感信息：
# MySQL
DB_HOST=120.79.247.228
DB_PORT=3316
DB_DATABASE=saas
DB_USERNAME=saas
DB_PASSWORD=P89cZHS5d7dFyc9R
# Elasticsearch
ES_HOST=http://localhost:9200
ES_USERNAME=saas
ES_PASSWORD=4hOaLaf41y2VuI8y
# Redis（可选）
REDIS_HOST=localhost
REDIS_PORT=6479
REDIS_PASSWORD=BMfv5aI31kgHWtlx
# DeepL 翻译
DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
# API
API_HOST=0.0.0.0
API_PORT=6002
5. 服务凭证速查
| 项目 | 值 |
|---|---|
| MySQL | host 120.79.247.228, port 3316, user saas, password P89cZHS5d7dFyc9R |
| Elasticsearch | host http://localhost:9200, user saas, password 4hOaLaf41y2VuI8y |
| Redis（可选） | host localhost, port 6479, password BMfv5aI31kgHWtlx |
| DeepL | c9293ab4-ad25-479b-919f-ab4e63b429ed |
所有凭证仅用于本地/测试环境，生产环境需替换并妥善保管。
6. 店匠数据源说明
saas-search 以 MySQL 中的店匠标准表为权威数据源：
shoplazza_product_spu：SPU 商品主表shoplazza_product_sku：SKU 变体表
shoplazza_product_sku 字段节选
| 字段 | 类型 | 描述 |
|---|---|---|
id |
bigint(20) | SKU 主键 |
spu_id |
bigint(20) | 对应 SPU |
shop_id |
bigint(20) | 店铺 ID |
shoplazza_product_id |
varchar(64) | 店匠商品 ID |
title |
varchar(500) | 变体标题 |
sku |
varchar(100) | SKU 编码 |
price |
decimal(10,2) | 售价 |
compare_at_price |
decimal(10,2) | 原价 |
option1/2/3 |
varchar(255) | 颜色/尺码等选项 |
inventory_quantity |
int(11) | 库存 |
image_src |
varchar(500) | 图片 |
tenant_id |
bigint(20) | 租户 |
create_time |
datetime | 创建时间 |
update_time |
datetime | 更新时间 |
deleted |
bit(1) | 逻辑删除标记 |
完整字段、索引映射与 ES 对应关系详见
INDEX_FIELDS_DOCUMENTATION.md。
7. 相关脚本
activate.sh（项目根目录）：激活 Conda 环境searchengine并加载.env，日常开发/部署以本脚本为准。scripts/mock_data.sh：一次性生成 Tenant1 Mock + Tenant2 CSV 数据并导入 MySQLscripts/ingest.sh <tenant_id> [recreate]：从 MySQL 写入 Elasticsearchrun.sh/restart.sh：服务启动/重启（内部会调用start_backend.sh等，同样使用CONDA_ROOT）
新机器部署：若 Conda 未安装在默认路径（如 /home/tw/miniconda3），请在执行上述脚本前设置 CONDA_ROOT。例如你的 conda 是 ~/anaconda3/bin/conda（即 /home/ubuntu/anaconda3/bin/conda），则设置：export CONDA_ROOT=$HOME/anaconda3。可将该行写入 ~/.bashrc 或部署说明。
更多脚本参数、日志与验证命令参见 Usage-Guide.md 与 测试数据指南.md。