# OmniShopAgent  centOS 8 部署指南

## 一、环境要求

| 组件 | 要求 |
|------|------|
| 操作系统 | CentOS 8.x |
| Python | 3.12+（LangChain 1.x 要求 3.10+） |
| 内存 | 建议 8GB+（Milvus + CLIP 较占内存） |
| 磁盘 | 建议 20GB+（含数据集） |

## 二、快速部署步骤

### 2.1 一键环境准备（推荐）

```bash
cd /path/to/shop_agent
chmod +x scripts/*.sh
./scripts/setup_env_centos8.sh
```

该脚本会：
- 安装系统依赖（gcc、openssl-devel 等）
- 安装 Docker（用于 Milvus）
- 安装 Python 3.12（conda 或源码编译）
- 创建虚拟环境并安装 requirements.txt

### 2.2 手动部署（分步执行）

#### 步骤 1：安装系统依赖

```bash
sudo dnf install -y gcc gcc-c++ make openssl-devel bzip2-devel \
    libffi-devel sqlite-devel xz-devel zlib-devel curl wget git
```

#### 步骤 2：安装 Python 3.12

**方式 A：Miniconda（推荐）**

```bash
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 按提示安装后
conda create -n shop_agent python=3.12
conda activate shop_agent
```

**方式 B：从源码编译**

```bash
sudo dnf groupinstall -y 'Development Tools'
cd /tmp
wget https://www.python.org/ftp/python/3.12.0/Python-3.12.0.tgz
tar xzf Python-3.12.0.tgz
cd Python-3.12.0
./configure --enable-optimizations --prefix=/usr/local
make -j $(nproc)
sudo make altinstall
```

#### 步骤 3：安装 Docker

```bash
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable docker && sudo systemctl start docker
sudo usermod -aG docker $USER
# 执行 newgrp docker 或重新登录
```

#### 步骤 4：创建虚拟环境并安装依赖

```bash
cd /path/to/shop_agent
python3.12 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -r requirements.txt
```

#### 步骤 5：配置环境变量

```bash
cp .env.example .env
# 编辑 .env，至少配置：
# OPENAI_API_KEY=sk-xxx
# MILVUS_HOST=localhost
# MILVUS_PORT=19530
# CLIP_SERVER_URL=grpc://localhost:51000
```

## 三、数据准备

### 3.1 下载数据集

```bash
# 需先配置 Kaggle API：~/.kaggle/kaggle.json
python scripts/download_dataset.py
```

### 3.2 启动 Milvus 并索引数据

```bash
# 启动 Milvus
./scripts/run_milvus.sh

# 等待就绪后，创建索引
python scripts/index_data.py
```

## 四、启动服务

### 4.1 启动脚本说明

| 脚本 | 用途 |
|------|------|
| `start.sh` | 主启动脚本：启动 Milvus + Streamlit |
| `stop.sh` | 停止所有服务 |
| `run_milvus.sh` | 仅启动 Milvus |
| `run_clip.sh` | 仅启动 CLIP（图像搜索需此服务） |
| `check_services.sh` | 健康检查 |

### 4.2 启动应用

```bash
# 方式 1：使用 start.sh（推荐）
./scripts/start.sh

# 方式 2：分步启动
# 终端 1：Milvus
./scripts/run_milvus.sh

# 终端 2：CLIP（图像搜索需要）
./scripts/run_clip.sh

# 终端 3：Streamlit
source venv/bin/activate
streamlit run app.py --server.port=8501 --server.address=0.0.0.0
```

### 4.3 访问地址

- **Streamlit 应用**：http://服务器IP:8501
- **Milvus Attu 管理界面**：http://服务器IP:8000

## 五、生产部署建议

### 5.1 使用 systemd 管理 Streamlit

创建 `/etc/systemd/system/omishop-agent.service`：

```ini
[Unit]
Description=OmniShopAgent Streamlit App
After=network.target docker.service

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/shop_agent
Environment="PATH=/path/to/shop_agent/venv/bin"
ExecStart=/path/to/shop_agent/venv/bin/streamlit run app.py --server.port=8501 --server.address=0.0.0.0
Restart=on-failure

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

```bash
sudo systemctl daemon-reload
sudo systemctl enable omishop-agent
sudo systemctl start omishop-agent
```

### 5.2 使用 Nginx 反向代理（可选）

```nginx
server {
    listen 80;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:8501;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 5.3 防火墙

```bash
sudo firewall-cmd --permanent --add-port=8501/tcp
sudo firewall-cmd --permanent --add-port=19530/tcp
sudo firewall-cmd --reload
```

## 六、常见问题

### Q: Python 3.12 编译失败？
A: 确保已安装 `openssl-devel`、`libffi-devel`，或直接使用 Miniconda。

### Q: Docker 权限不足？
A: 执行 `sudo usermod -aG docker $USER` 后重新登录。

### Q: Milvus 启动超时？
A: 首次启动需拉取镜像，可能较慢。可检查 `docker compose logs -f standalone`。

### Q: 图像搜索不可用？
A: 需单独启动 CLIP 服务：`./scripts/run_clip.sh`。

### Q: 健康检查？
A: 执行 `./scripts/check_services.sh` 查看各组件状态。