# 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 启动脚本说明（当前版本推荐）

  
  | 脚本 | 用途 |
  |------|------|

  | `scripts/service.sh` | 统一的服务管理脚本：启动 / 停止 / 重启 / 查看状态，内置 Conda 环境激活与日志重定向 |
  
  > 说明：早期版本的 `start.sh` / `stop.sh` / `check_services.sh` 已整合为 `scripts/service.sh`，建议在新环境一律使用该脚本。

  
  ### 4.2 启动应用
  
  ```bash

  cd /path/to/shop_agent

  # 后台启动（推荐）
  ./scripts/service.sh start
  
  # 查看状态
  ./scripts/service.sh status
  
  # 停止服务
  ./scripts/service.sh stop
  
  # 本地调试：前台运行（Ctrl+C 停止）
  ./scripts/service.sh run
  ```
  
  `service.sh` 内部会：
  
  - 自动激活约定的 Conda 环境（默认：`CONDA_BASE=$HOME/miniconda3`，`CONDA_ENV=aishopping-py312`，可通过环境变量覆盖）；
  - 统一启动 `streamlit run app.py`；
  - 将标准输出与错误输出分别写入 `logs/streamlit.log` 和 `logs/streamlit_error.log`。
  
  端口与 Host 的优先级为：
  
  - 端口：`STREAMLIT_PORT` 环境变量 > `.env`/环境变量中的 `APP_PORT`（`Settings.app_port`）> 默认 `6008`；
  - Host：`STREAMLIT_HOST` 环境变量 > 默认 `0.0.0.0`。
  
  如需直接运行 Streamlit（不通过脚本），可参考：
  
  ```bash
  source venv/bin/activate   # 或激活对应 Conda 环境
  streamlit run app.py --server.port=6008 --server.address=0.0.0.0

  ```
  
  ### 4.3 访问地址
  

  - **Streamlit 应用**：`http://服务器IP:<PORT>`（默认可按 `http://服务器IP:6008` 访问，或通过 Nginx 反代到 80/443 端口）

  
  ## 五、生产部署建议
  
  ### 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: 可通过访问 `/admin/health`、`/indexer/health` 等接口检查搜索服务健康状况；应用本身可通过 `scripts/service.sh status` 和日志文件（`logs/streamlit.log`、`logs/streamlit_error.log`）排查问题。
  
  ---
  
  ## 七、从旧环境迁移到新环境的建议步骤
  
  1. **同步代码与依赖**
     - 在新机器上拉取最新仓库；
     - 按本文档第 2 章创建 Python/Conda 环境并安装 `requirements.txt`。
  2. **迁移配置**
     - 从旧机器复制 `.env`（注意脱敏），或基于 `.env.example` 在新机器重新填写；
     - 核对并按需修改：
       - 大模型相关：`OPENAI_API_KEY`、`OPENAI_API_BASE_URL`（如有）、模型名称等；
       - 搜索服务相关：`SEARCH_API_BASE_URL`、`SEARCH_API_TENANT_ID`；
       - 应用参数：`APP_PORT`、数据目录路径等。
  3. **首次启动（前台调试）**
     - 在新环境中执行 `./scripts/service.sh run`；
     - 确认页面可访问、搜索与对话功能正常；
     - 如出现异常，优先查看 `logs/streamlit_error.log` 与 `logs/streamlit.log`。
  4. **正式后台运行**
     - 使用 `./scripts/service.sh start` 启动服务，并结合本章 `systemd` / Nginx 示例将服务纳入统一运维体系；
     - 配合防火墙与反向代理配置，完成对外访问。
  
  通过以上步骤，可以在不同机器之间稳定迁移 ShopAgent，同时保持统一的启动方式、端口与日志位置。