ai-saas / saas-customer-assistant

DEPLOY_CENTOS8.md 6.26 KB

ShopAgent CentOS 8 部署指南

一、环境要求

组件 要求
操作系统 CentOS 8.x
Python 3.12+（LangChain 1.x 要求 3.10+）
内存 建议 4GB+
磁盘 建议 10GB+

二、快速部署步骤

2.1 一键环境准备（推荐）

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：安装系统依赖

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（推荐）

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：从源码编译

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

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

步骤 4：配置环境变量

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 数据集：

# 需先配置 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 启动应用

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（不通过脚本），可参考：

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：

[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

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

5.2 使用 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 防火墙

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，同时保持统一的启动方式、端口与日志位置。