surugaya/docs/DEPLOYMENT.md

骏河屋抓取服务部署文档

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

1. 概述

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

• 必须能运行 Chromium 浏览器（Playwright）。
• 目标站点受 Cloudflare 保护，建议使用日本 IP 代理以提高稳定性。
• 会话可存储在 Redis（跨实例复用）或进程内存（单实例）中。
• 默认监听 0.0.0.0:31106。

2. 部署要求

2.1 运行环境

• Python >= 3.12
• 支持 Docker 与 Docker Compose（推荐）
• 可访问日本 IP 的代理（推荐，非必须）
• 可选：Redis >= 5.0

2.2 端口

• 服务默认暴露 31106。
• 若修改端口，请同步调整 docker-compose.yml 的端口映射与 .env 中的 SURUGAYA_APP_PORT。

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 主机	多实例部署时建议配置

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

3.1 生产环境 .env 示例

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. 复制环境变量模板并修改：

   cp .env.example .env
   # 编辑 .env，重点修改 SURUGAYA_BEARER_TOKEN 与代理配置
   

3. 构建并启动容器：

   docker compose up -d --build
   

4. 查看日志：

   docker compose logs -f
   

4.2 说明

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

4.3 停止与重启

docker compose down
docker compose up -d --build

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

5.1 安装依赖

推荐使用 uv 作为包管理器：

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

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

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

若使用传统 pip：

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

5.2 启动服务

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

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

5.3 后台运行（systemd 示例）

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

[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

启用并启动：

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

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

Windows 本地开发可使用提供的 PowerShell 启动脚本：

.\start-server.ps1

可选参数：

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

7. 启动验证

7.1 健康检查

curl http://127.0.0.1:31106/health

7.2 API 鉴权测试

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，cf_clearance 等会话可在实例间共享。

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 内存持续增长

• 检查 SURUGAYA_BROWSER_RECYCLE_AFTER_CONTEXTS 与 SURUGAYA_BROWSER_RECYCLE_AFTER_SECONDS 是否被误关闭。
• 长时间运行后观察 logs/ 中浏览器回收日志。

10. 升级维护

1. 拉取最新代码。

2. 若依赖有变更，重新同步：

   uv sync --extra dev
   

3. Docker Compose 部署：

   docker compose down
   docker compose up -d --build
   

4. 裸机部署：

   sudo systemctl restart surugaya