Init

README.md

@@ -0,0 +1,113 @@
+# 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`
+
+## 安装
+
+```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`
+- 代理（日本 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"
+}
+```