文档调整

docs/DEPLOYMENT.md

@@ -8,7 +8,7 @@
 
 - 必须能运行 Chromium 浏览器（Playwright）。
 - 目标站点受 Cloudflare 保护，建议使用日本 IP 代理以提高稳定性。
-- 会话可存储在 Redis（跨实例复用）或进程内存（单实例）中。
+- **必须部署 Redis**：用于 Cloudflare 会话复用，以及与下游采购 worker（`jp_pruchase_zdh_5`）共享任务队列、通知与订单状态。
 - 默认监听 `0.0.0.0:31106`。
 
 ## 2. 部署要求
@@ -18,13 +18,69 @@
 - Python >= 3.12
 - 支持 Docker 与 Docker Compose（推荐）
 - 可访问日本 IP 的代理（推荐，非必须）
-- 可选：Redis >= 5.0
+- **必须：Redis >= 5.0**（本服务强依赖 Redis，部署时必须同时部署）
 
 ### 2.2 端口
 
 - 服务默认暴露 `31106`。
 - 若修改端口，请同步调整 `docker-compose.yml` 的端口映射与 `.env` 中的 `SURUGAYA_APP_PORT`。
 
+## 2.3 Redis 部署
+
+本服务强依赖 Redis，用于：
+
+- 跨请求/跨实例复用通过 Cloudflare 后的会话（`cf_clearance`）。
+- 与下游采购 worker（`jp_pruchase_zdh_5`）共享采购任务队列、通知（news）与订单（trade）状态。
+- 作为 `/api/news`、`/api/trade`、任务投递等接口的数据源。
+
+因此部署 `jp_surugaya` 时必须**同时部署并启动 Redis**。
+
+### Windows 裸机部署 Redis
+
+1. 下载 Windows 原生 Redis 二进制，例如 [redis-windows/releases](https://github.com/redis-windows/redis-windows/releases)。
+2. 解压到 `C:\jp-deploy\redis`。
+3. 编辑 `redis.windows.conf`（可选）：
+   - 设置 `requirepass your_redis_password`。
+   - 设置 `bind 0.0.0.0` 或保持 `127.0.0.1` 按需监听。
+4. 启动：
+   ```powershell
+   cd C:\jp-deploy\redis
+   .\redis-server.exe redis.windows.conf
+   ```
+5. 验证：
+   ```powershell
+   .\redis-cli.exe ping
+   # 若设置了密码
+   .\redis-cli.exe -a your_redis_password ping
+   ```
+
+### Docker Compose 部署 Redis
+
+在 `docker-compose.yml` 中增加 `redis` 服务，例如：
+
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: surugaya-redis
+    restart: unless-stopped
+    command: redis-server --requirepass your_redis_password
+    networks:
+      - jp
+    ports:
+      - "6379:6379"
+    volumes:
+      - ./redis-data:/data
+
+  jp_surugaya:
+    # ... 原有配置
+    environment:
+      SURUGAYA_REDIS_HOST: redis
+      SURUGAYA_REDIS_PASSWORD: your_redis_password
+```
+
+> 生产环境建议将 Redis 数据目录持久化，并限制 `6379` 端口仅内网可访问。
+
 ## 3. 环境变量配置
 
 所有配置项均通过 `SURUGAYA_` 前缀的环境变量注入，也可写入项目根目录的 `.env` 文件，由 `pydantic-settings` 自动加载。生产部署至少需要修改以下变量：
@@ -40,7 +96,7 @@
 | `SURUGAYA_PROXY_SERVER` | 代理地址 | 建议配置日本 IP 代理 |
 | `SURUGAYA_PROXY_USERNAME` | 代理用户名 | 按需配置 |
 | `SURUGAYA_PROXY_PASSWORD` | 代理密码 | 按需配置 |
-| `SURUGAYA_REDIS_HOST` | Redis 主机 | 多实例部署时建议配置 |
+| `SURUGAYA_REDIS_HOST` | Redis 主机 | **必须**，例如 `127.0.0.1` 或 `redis` |
 
 完整示例见项目根目录 `.env.example`。
 
@@ -76,20 +132,23 @@ SURUGAYA_REDIS_DB=0
 ### 4.1 步骤
 
 1. 克隆仓库并进入项目根目录。
-2. 复制环境变量模板并修改：
+2. 确保 Redis 已部署：
+   - 若使用 Docker Compose，请在 `docker-compose.yml` 中加入 Redis 服务（参考 [2.3 Redis 部署](#23-redis-部署)）。
+   - 若使用外部 Redis，在 `.env` 中正确填写 `SURUGAYA_REDIS_HOST` 与密码。
+3. 复制环境变量模板并修改：
 
    ```bash
    cp .env.example .env
-   # 编辑 .env，重点修改 SURUGAYA_BEARER_TOKEN 与代理配置
+   # 编辑 .env，重点修改 SURUGAYA_BEARER_TOKEN、Redis 连接与代理配置
    ```
 
-3. 构建并启动容器：
+4. 构建并启动容器：
 
    ```bash
    docker compose up -d --build
    ```
 
-4. 查看日志：
+5. 查看日志：
 
    ```bash
    docker compose logs -f
@@ -110,7 +169,19 @@ docker compose up -d --build
 
 ## 5. 部署方式二：裸机/虚拟机
 
-### 5.1 安装依赖
+### 5.1 前置条件：部署 Redis
+
+裸机/虚拟机部署前，请先部署 Redis：
+
+- **Windows**：参考 [2.3 Redis 部署](#23-redis-部署) 中的 Windows 裸机方式。
+- **Linux**：安装并启动 Redis：
+  ```bash
+  sudo apt-get install redis-server
+  sudo systemctl enable redis-server --now
+  ```
+- 确认 `.env` 中的 `SURUGAYA_REDIS_HOST`、`SURUGAYA_REDIS_PORT`、`SURUGAYA_REDIS_PASSWORD` 配置正确。
+
+### 5.2 安装依赖
 
 推荐使用 `uv` 作为包管理器：
 
@@ -125,6 +196,8 @@ uv sync --extra dev
 uv run playwright install chromium
 ```
 
+> 说明：`surugaya-common` 位于本仓库 `packages/surugaya_common` 目录下，通过 `tool.uv.workspace` 作为本地 workspace 包被引用。`uv sync` 会自动安装该本地包，无需额外配置私有索引。
+
 若使用传统 pip：
 
 ```bash
@@ -132,7 +205,7 @@ python -m pip install -e ".[dev]"
 python -m playwright install chromium
 ```
 
-### 5.2 启动服务
+### 5.3 启动服务
 
 ```bash
 # 方式 1：直接运行
@@ -142,7 +215,7 @@ python -m app.main
 uvicorn app.main:app --host 0.0.0.0 --port 31106
 ```
 
-### 5.3 后台运行（systemd 示例）
+### 5.4 后台运行（systemd 示例）
 
 创建 `/etc/systemd/system/surugaya.service`：
 
@@ -175,7 +248,9 @@ sudo systemctl start surugaya
 
 ## 6. 部署方式三：Windows 本地开发
 
-Windows 本地开发可使用提供的 PowerShell 启动脚本：
+Windows 本地开发前，请先按 [2.3 Redis 部署](#23-redis-部署) 启动 Redis。
+
+启动脚本：
 
 ```powershell
 .\start-server.ps1
@@ -223,8 +298,8 @@ curl -H "Authorization: Bearer <SURUGAYA_BEARER_TOKEN>" \
 
 ### 8.3 会话存储
 
-- 单实例：不配置 Redis，会话退回到进程内存。
+- **Redis 是必选项**：本服务必须与 Redis 一起部署，用于会话复用、与下游采购 worker 共享任务与状态。
-- 多实例或需要跨进程复用：配置 Redis，`cf_clearance` 等会话可在实例间共享。
+- 配置 Redis 后，`cf_clearance` 等会话可在实例间共享；未配置 Redis 时，部分接口（如 `/api/news`、`/api/trade`、任务投递）将不可用。
 
 ### 8.4 日志
 
@@ -255,7 +330,13 @@ curl -H "Authorization: Bearer <SURUGAYA_BEARER_TOKEN>" \
 - 裸机部署时使用 `start-server.ps1` 会自动结束占用进程。
 - Linux 可使用 `lsof -i :31106` 或 `ss -tlnp | grep 31106` 定位占用进程。
 
-### 9.4 内存持续增长
+### 9.4 Redis 连接失败
+
+- 确认 Redis 服务已启动：`redis-cli ping`（Linux）或 `.\redis-cli.exe ping`（Windows）。
+- 检查 `.env` 中的 `SURUGAYA_REDIS_HOST`、`SURUGAYA_REDIS_PORT`、`SURUGAYA_REDIS_PASSWORD` 是否正确。
+- 确认防火墙未拦截 Redis 端口（默认 `6379`）。
+
+### 9.5 内存持续增长
 
 - 检查 `SURUGAYA_BROWSER_RECYCLE_AFTER_CONTEXTS` 与 `SURUGAYA_BROWSER_RECYCLE_AFTER_SECONDS` 是否被误关闭。
 - 长时间运行后观察 `logs/` 中浏览器回收日志。