surugaya/README.md

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

安装

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

启动

默认监听 0.0.0.0:31106。

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

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

python -m app.main

方式 2：使用 uvicorn

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

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

.\start-server.ps1

可选参数：

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

鉴权（Bearer Token）

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

建议在 .env 中设置：

• SURUGAYA_BEARER_TOKEN

示例（curl）：

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
• 代理（日本 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

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

详情

POST /api/item_detail

{
  "product_id": "985029623"
}