From 05a30ae00100b94fe1d756357294dc0c356239b8 Mon Sep 17 00:00:00 2001 From: tangwang Date: Thu, 19 Mar 2026 15:23:21 +0800 Subject: [PATCH] docs --- README.md | 31 +++++++++++++++++++++++-------- docs/DEPLOY_CENTOS8.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 82 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 7d3a12d..ffdc728 100644 --- a/README.md +++ b/README.md @@ -111,17 +111,26 @@ cp .env.example .env 若需本地商品图（如侧边栏「Similar」用本地图），可准备 `data/images/` 下的图片资源；图像风格分析不依赖该目录。 -### 启动 +### 启动与日志 ```bash -# 推荐 -./scripts/start.sh +# 推荐：使用服务脚本（含 Conda 环境激活与日志管理） +./scripts/service.sh start # 后台启动 +./scripts/service.sh status # 查看状态 +./scripts/service.sh stop # 停止 -# 或 +# 本地调试：前台运行（Ctrl+C 停止） +./scripts/service.sh run + +# 也可直接运行 Streamlit（需自行激活虚拟环境） streamlit run app.py ``` -默认访问 `http://localhost:8501`。商品搜索依赖外部 Search API，请在 `.env` 中配置 `SEARCH_API_BASE_URL` 与 `SEARCH_API_TENANT_ID`。 +- 端口优先级：`STREAMLIT_PORT` 环境变量 > `app.config.settings.app_port` > 默认 `6008`。 +- Host 默认为 `0.0.0.0`，可通过 `STREAMLIT_HOST` 覆盖。 +- 日志目录：`logs/streamlit.log`（标准输出）、`logs/streamlit_error.log`（错误输出，由 `scripts/service.sh` 统一管理）。 + +默认访问 `http://:`（本地通常是 `http://localhost:6008`）。商品搜索依赖外部 Search API，请在 `.env` 中配置 `SEARCH_API_BASE_URL` 与 `SEARCH_API_TENANT_ID`。 ### 部署 @@ -140,7 +149,13 @@ CentOS 8 等部署说明见 **[docs/DEPLOY_CENTOS8.md](docs/DEPLOY_CENTOS8.md)** | `SEARCH_API_TENANT_ID` | 租户 ID | 见 config.py | | `SEARCH_PRODUCTS_LIMIT` | 单次搜索返回条数上限 | 20 | -更多见 `app/config.py`。 +更多配置项见 `app/config.py` 中的 `Settings`，包括： + +- OpenAI 相关：`openai_model`、`openai_vision_model`、`openai_use_reasoning`、`openai_reasoning_effort`、`openai_api_base_url` 等。 +- 应用运行：`app_host`、`app_port`、`debug`、`log_level`。 +- 数据路径：`raw_data_path`、`processed_data_path`、`image_data_path` 等。 + +配置加载优先级（高 → 低）：**代码初始化参数 > 项目根目录下 `.env` > 系统环境变量 > 默认值**，其中 `.env` 会覆盖同名系统环境变量（见 `Settings.settings_customise_sources`）。 ## 项目结构（概览） @@ -157,9 +172,9 @@ shop_agent/ │ └── ... ├── app.py # Streamlit UI、流式渲染、引用解析与商品卡片 ├── docs/ -│ └── 技术实现报告.md # 详细设计与实现说明 +│ └── 技术实现报告.md # 详细设计、Prompt 与架构说明 ├── scripts/ -│ └── start.sh +│ └── service.sh # 统一的启停脚本（start/stop/status/run） ├── .env.example ├── requirements.txt └── README.md diff --git a/docs/DEPLOY_CENTOS8.md b/docs/DEPLOY_CENTOS8.md index d71df34..bceec8d 100644 --- a/docs/DEPLOY_CENTOS8.md +++ b/docs/DEPLOY_CENTOS8.md @@ -91,28 +91,53 @@ python scripts/download_dataset.py ## 四、启动服务 -### 4.1 启动脚本说明 +### 4.1 启动脚本说明（当前版本推荐） | 脚本 | 用途 | |------|------| -| `start.sh` | 主启动脚本：启动 Streamlit | -| `stop.sh` | 停止 Streamlit | -| `check_services.sh` | 健康检查 | +| `scripts/service.sh` | 统一的服务管理脚本：启动 / 停止 / 重启 / 查看状态，内置 Conda 环境激活与日志重定向 | + +> 说明：早期版本的 `start.sh` / `stop.sh` / `check_services.sh` 已整合为 `scripts/service.sh`，建议在新环境一律使用该脚本。 ### 4.2 启动应用 ```bash -# 方式 1：使用 start.sh（推荐） -./scripts/start.sh +cd /path/to/shop_agent -# 方式 2：直接运行 -source venv/bin/activate -streamlit run app.py --server.port=8501 --server.address=0.0.0.0 +# 后台启动（推荐） +./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:8501 +- **Streamlit 应用**：`http://服务器IP:`（默认可按 `http://服务器IP:6008` 访问，或通过 Nginx 反代到 80/443 端口） ## 五、生产部署建议 @@ -176,4 +201,27 @@ A: 确保已安装 `openssl-devel`、`libffi-devel`，或直接使用 Miniconda A: 检查 `.env` 中 `SEARCH_API_BASE_URL` 和 `SEARCH_API_TENANT_ID` 配置，确保网络可访问搜索服务。 ### Q: 健康检查？ -A: 执行 `./scripts/check_services.sh` 查看各组件状态。 +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，同时保持统一的启动方式、端口与日志位置。 -- libgit2 0.21.2