# ShopAgent CentOS 8 部署指南

  
  ## 一、环境要求
  
  | 组件 | 要求 |
  |------|------|
  | 操作系统 | CentOS 8.x |
  | Python | 3.12+（LangChain 1.x 要求 3.10+） |

  | 内存 | 建议 4GB+ |
  | 磁盘 | 建议 10GB+ |

  
  ## 二、快速部署步骤
  
  ### 2.1 一键环境准备（推荐）
  
  ```bash
  cd /path/to/shop_agent
  chmod +x scripts/*.sh
  ./scripts/setup_env_centos8.sh
  ```
  
  该脚本会：
  - 安装系统依赖（gcc、openssl-devel 等）

  - 安装 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：创建虚拟环境并安装依赖

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

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

  
  ```bash
  cp .env.example .env
  # 编辑 .env，至少配置：
  # OPENAI_API_KEY=sk-xxx

  # SEARCH_API_BASE_URL=http://120.76.41.98:6002
  # SEARCH_API_TENANT_ID=162

  ```
  

  ## 三、数据准备（可选）

  
  ### 3.1 下载数据集
  

  如需图片风格分析功能，可下载 Kaggle 数据集：
  

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

  ## 四、启动服务
  
  ### 4.1 启动脚本说明
  
  | 脚本 | 用途 |
  |------|------|

  | `start.sh` | 主启动脚本：启动 Streamlit |
  | `stop.sh` | 停止 Streamlit |

  | `check_services.sh` | 健康检查 |
  
  ### 4.2 启动应用
  
  ```bash
  # 方式 1：使用 start.sh（推荐）
  ./scripts/start.sh
  

  # 方式 2：直接运行

  source venv/bin/activate
  streamlit run app.py --server.port=8501 --server.address=0.0.0.0
  ```
  
  ### 4.3 访问地址
  
  - **Streamlit 应用**：http://服务器IP:8501

  
  ## 五、生产部署建议
  
  ### 5.1 使用 systemd 管理 Streamlit
  
  创建 `/etc/systemd/system/omishop-agent.service`：
  
  ```ini
  [Unit]

  Description=ShopAgent Streamlit App

  After=network.target

  
  [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 --reload
  ```
  
  ## 六、常见问题
  
  ### Q: Python 3.12 编译失败？
  A: 确保已安装 `openssl-devel`、`libffi-devel`，或直接使用 Miniconda。
  

  ### Q: Search API 连接失败？
  A: 检查 `.env` 中 `SEARCH_API_BASE_URL` 和 `SEARCH_API_TENANT_ID` 配置，确保网络可访问搜索服务。

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