# 骏河屋抓取服务部署文档

本文档说明如何将 `jp-surugaya`（Surugaya Scraper Service）部署到生产或开发环境。

## 1. 概述

本项目是一个基于 Python FastAPI + Playwright 的 HTTP API 服务，用于抓取骏河屋（suruga-ya.jp）的搜索列表、商品详情及通知信息。生产部署的核心要点：

- 必须能运行 Chromium 浏览器（Playwright）。
- 目标站点受 Cloudflare 保护，建议使用日本 IP 代理以提高稳定性。
- **必须部署 Redis**：用于 Cloudflare 会话复用，以及与下游采购 worker（`jp_pruchase_zdh_5`）共享任务队列、通知与订单状态。
- 默认监听 `0.0.0.0:31106`。

## 2. 部署要求

### 2.1 运行环境

- Python >= 3.12
- 支持 Docker 与 Docker Compose（推荐）
- 可访问日本 IP 的代理（推荐，非必须）
- **必须：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` 自动加载。生产部署至少需要修改以下变量：

| 变量名 | 说明 | 生产建议 |
|---|---|---|
| `SURUGAYA_APP_HOST` | 监听地址 | `0.0.0.0` |
| `SURUGAYA_APP_PORT` | 监听端口 | `31106` |
| `SURUGAYA_APP_ENV` | 运行环境 | `prod` |
| `SURUGAYA_BEARER_TOKEN` | API 鉴权 Token | 必须替换为强随机字符串 |
| `SURUGAYA_BROWSER_HEADLESS` | 是否无头模式 | `true` |
| `SURUGAYA_BROWSER_CHANNEL` | 浏览器通道 | 容器内留空，使用 bundled Chromium |
| `SURUGAYA_PROXY_SERVER` | 代理地址 | 建议配置日本 IP 代理 |
| `SURUGAYA_PROXY_USERNAME` | 代理用户名 | 按需配置 |
| `SURUGAYA_PROXY_PASSWORD` | 代理密码 | 按需配置 |
| `SURUGAYA_REDIS_HOST` | Redis 主机 | **必须**，例如 `127.0.0.1` 或 `redis` |

完整示例见项目根目录 `.env.example`。

### 3.1 生产环境 `.env` 示例

```ini
SURUGAYA_APP_HOST=0.0.0.0
SURUGAYA_APP_PORT=31106
SURUGAYA_APP_ENV=prod
SURUGAYA_LOG_LEVEL=INFO

SURUGAYA_BEARER_TOKEN=your-strong-random-token-here

SURUGAYA_BROWSER_ENABLED=true
SURUGAYA_BROWSER_HEADLESS=true
SURUGAYA_BROWSER_CHANNEL=
SURUGAYA_BROWSER_KEEP_OPEN_ON_ERROR=false

SURUGAYA_PROXY_SERVER=http://your-jp-proxy:7890
SURUGAYA_PROXY_USERNAME=
SURUGAYA_PROXY_PASSWORD=

SURUGAYA_REDIS_HOST=redis
SURUGAYA_REDIS_PORT=6379
SURUGAYA_REDIS_PASSWORD=
SURUGAYA_REDIS_DB=0
```

## 4. 部署方式一：Docker Compose（推荐）

项目已提供 `Dockerfile` 与 `docker-compose.yml`，基于官方 Playwright Python 镜像构建，使用 `uv` 管理依赖。

### 4.1 步骤

1. 克隆仓库并进入项目根目录。
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、Redis 连接与代理配置
   ```

4. 构建并启动容器：

   ```bash
   docker compose up -d --build
   ```

5. 查看日志：

   ```bash
   docker compose logs -f
   ```

### 4.2 说明

- `docker-compose.yml` 使用 `.:/app` 挂载宿主目录，因此 `venv` 被放置在 `/opt/venv`，避免被卷覆盖。
- 容器内 `SURUGAYA_BROWSER_CHANNEL` 已强制留空，使用 Playwright 自带的 Chromium。
- 时区设置为 `Asia/Tokyo`。

### 4.3 停止与重启

```bash
docker compose down
docker compose up -d --build
```

## 5. 部署方式二：裸机/虚拟机

### 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` 作为包管理器：

```bash
# 安装 uv（若未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步依赖（包含 dev 依赖）
uv sync --extra dev

# 安装 Chromium 浏览器
uv run playwright install chromium
```

> 说明：`surugaya-common` 位于本仓库 `packages/surugaya_common` 目录下，通过 `tool.uv.workspace` 作为本地 workspace 包被引用。`uv sync` 会自动安装该本地包，无需额外配置私有索引。

若使用传统 pip：

```bash
python -m pip install -e ".[dev]"
python -m playwright install chromium
```

### 5.3 启动服务

```bash
# 方式 1：直接运行
python -m app.main

# 方式 2：使用 uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 31106
```

### 5.4 后台运行（systemd 示例）

创建 `/etc/systemd/system/surugaya.service`：

```ini
[Unit]
Description=Surugaya Scraper Service
After=network.target

[Service]
Type=simple
User=app
WorkingDirectory=/opt/jp_surugaya
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=/opt/jp_surugaya/.env
ExecStart=/opt/jp_surugaya/.venv/bin/python -m app.main
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

启用并启动：

```bash
sudo systemctl daemon-reload
sudo systemctl enable surugaya
sudo systemctl start surugaya
```

## 6. 部署方式三：Windows 本地开发

Windows 本地开发前，请先按 [2.3 Redis 部署](#23-redis-部署) 启动 Redis。

启动脚本：

```powershell
.\start-server.ps1
```

可选参数：

- `-Port 31106`：指定端口。
- `-HostName 0.0.0.0`：指定监听地址。
- `-NoKillExisting`：端口占用时不自动结束旧进程。
- `-DryRun`：仅做检查，不实际启动。

## 7. 启动验证

### 7.1 健康检查

```bash
curl http://127.0.0.1:31106/health
```

### 7.2 API 鉴权测试

```bash
curl -H "Authorization: Bearer <SURUGAYA_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -X POST "http://127.0.0.1:31106/api/search" \
  -d '{"search_word":"cat","category":"","page":1}'
```

## 8. 生产环境建议

### 8.1 代理与 IP

- 骏河屋对非日本 IP 访问可能触发更严格的 Cloudflare 挑战，建议稳定使用日本 IP 代理。
- 代理配置变更后需重启服务生效。

### 8.2 浏览器回收

长时间运行会导致 Chromium 内存累积，建议保留默认回收策略：

- `SURUGAYA_BROWSER_RECYCLE_AFTER_CONTEXTS=200`
- `SURUGAYA_BROWSER_RECYCLE_AFTER_SECONDS=3600`

如需关闭回收，可设为 `0`。

### 8.3 会话存储

- **Redis 是必选项**：本服务必须与 Redis 一起部署，用于会话复用、与下游采购 worker 共享任务与状态。
- 配置 Redis 后，`cf_clearance` 等会话可在实例间共享；未配置 Redis 时，部分接口（如 `/api/news`、`/api/trade`、任务投递）将不可用。

### 8.4 日志

生产环境默认写文件到 `logs/` 目录，支持按大小/时间切割与保留清理。`.env.example` 示例按 `100 MB` 切割、保留 `14 days`。可通过以下变量调整：

- `SURUGAYA_LOG_TO_FILE`
- `SURUGAYA_LOG_DIR`
- `SURUGAYA_LOG_ROTATION`
- `SURUGAYA_LOG_RETENTION`
- `SURUGAYA_LOG_COMPRESSION`

## 9. 故障排查

### 9.1 浏览器启动失败

- 确认已执行 `playwright install chromium`。
- 容器内确认 `SURUGAYA_BROWSER_CHANNEL=` 留空。
- Linux 服务器需安装系统依赖，Playwright 镜像已包含。

### 9.2 Cloudflare 验证反复失败

- 检查代理是否为日本 IP。
- 检查浏览器指纹配置与 stealth 是否启用（`SURUGAYA_BROWSER_STEALTH_ENABLED` 默认 `true`）。
- 查看日志中是否有 `cf_clearance` 获取成功/失败的记录。

### 9.3 端口占用

- 裸机部署时使用 `start-server.ps1` 会自动结束占用进程。
- Linux 可使用 `lsof -i :31106` 或 `ss -tlnp | grep 31106` 定位占用进程。

### 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/` 中浏览器回收日志。

## 10. 升级维护

1. 拉取最新代码。
2. 若依赖有变更，重新同步：

   ```bash
   uv sync --extra dev
   ```

3. Docker Compose 部署：

   ```bash
   docker compose down
   docker compose up -d --build
   ```

4. 裸机部署：

   ```bash
   sudo systemctl restart surugaya
   ```