# Surugaya Scraper Service

一个用于执行骏河屋（suruga-ya.jp）抓取任务的 HTTP API 服务。首版目标是技术验证：在 Cloudflare 保护场景下，稳定抓取搜索列表与商品详情，并支持 API 被并发调用。

## 功能概览

- FastAPI 提供 HTTP API
- Bearer Token 接口鉴权（通过 `Authorization: Bearer <token>` 请求头校验）
- Playwright 驱动浏览器访问目标站点
- Cloudflare 会话复用：自动获取并复用通过验证后的 Cookie（含 `cf_clearance`）
- 会话存储：优先 Redis（可选），未配置时自动退回进程内存

## 接口

- `GET /health`
- `POST /api/search`
- `POST /api/item_detail`

## 部署

生产环境及更多部署方式请参考 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。

## 安装

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

## 启动

默认监听 `0.0.0.0:31106`。

启动前建议先配置 `.env`（项目使用 pydantic-settings 自动读取同目录下的 `.env`）。

方式 1：直接运行入口（推荐）

```bash
python -m app.main
```

方式 2：使用 uvicorn

```bash
uvicorn app.main:app --host 0.0.0.0 --port 31106
```

方式 3：使用启动脚本（自动处理端口占用，推荐 Windows 本地开发）

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

可选参数：

- `-Port 31106`：指定端口
- `-HostName 0.0.0.0`：指定监听地址
- `-NoKillExisting`：检测到端口占用时直接报错，不自动结束旧进程
- `-DryRun`：只做检查不实际启动

## 鉴权（Bearer Token）

服务端从请求头 `Authorization` 取值，字符串替换掉前缀 `Bearer ` 后，与服务端配置的 token 做比较。

建议在 `.env` 中设置：

- `SURUGAYA_BEARER_TOKEN`

示例（curl）：

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

## 常用环境变量

- 服务：
  - `SURUGAYA_APP_HOST`（默认 `0.0.0.0`）
  - `SURUGAYA_APP_PORT`（默认 `31106`）
- 鉴权：
  - `SURUGAYA_BEARER_TOKEN`
- 浏览器回收（防止 Chromium 长时间运行内存累积导致 driver 掉线）：
  - `SURUGAYA_BROWSER_RECYCLE_AFTER_CONTEXTS`（默认 `200`，累计创建上下文达到该值后在空闲时主动重建浏览器，`0` 关闭）
  - `SURUGAYA_BROWSER_RECYCLE_AFTER_SECONDS`（默认 `3600`，浏览器运行超过该秒数后在空闲时主动重建，`0` 关闭）
- 代理（日本 IP）：
  - `SURUGAYA_PROXY_SERVER`（例：`http://127.0.0.1:7890`）
  - `SURUGAYA_PROXY_USERNAME`
  - `SURUGAYA_PROXY_PASSWORD`
- Redis（可选）：
  - `SURUGAYA_REDIS_HOST`（例：`127.0.0.1`，留空表示不使用 Redis）
  - `SURUGAYA_REDIS_PORT`（默认 `6379`）
  - `SURUGAYA_REDIS_PASSWORD`
  - `SURUGAYA_REDIS_DB`（默认 `0`）

## 请求示例

### 搜索

`POST /api/search`

```json
{
  "search_word": "cat",
  "category": "",
  "page": 2
}
```

### 详情

`POST /api/item_detail`

```json
{
  "product_id": "985029623"
}
```