jp/surugaya

Fork 0

Files

T

q792602257 af8d3a859f 文档调整

2026-06-25 14:07:10 +08:00

10 KiB

Raw Blame History

骏河屋抓取服务部署文档

本文档说明如何将 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

下载 Windows 原生 Redis 二进制，例如 redis-windows/releases。
解压到 C:\jp-deploy\redis。
编辑 redis.windows.conf（可选）：
- 设置 requirepass your_redis_password。
- 设置 bind 0.0.0.0 或保持 127.0.0.1 按需监听。

启动：

cd C:\jp-deploy\redis
.\redis-server.exe redis.windows.conf

验证：

.\redis-cli.exe ping
# 若设置了密码
.\redis-cli.exe -a your_redis_password ping

Docker Compose 部署 Redis

在 docker-compose.yml 中增加 redis 服务，例如：

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` 示例

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 步骤

克隆仓库并进入项目根目录。
确保 Redis 已部署：
- 若使用 Docker Compose，请在 docker-compose.yml 中加入 Redis 服务（参考 2.3 Redis 部署）。
- 若使用外部 Redis，在 .env 中正确填写 SURUGAYA_REDIS_HOST 与密码。

复制环境变量模板并修改：

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

构建并启动容器：
```
docker compose up -d --build
```
查看日志：
```
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 前置条件：部署 Redis

裸机/虚拟机部署前，请先部署 Redis：

Windows：参考 2.3 Redis 部署中的 Windows 裸机方式。

Linux：安装并启动 Redis：

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

# 安装 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：

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

5.3 启动服务

# 方式 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：

[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 本地开发前，请先按 2.3 Redis 部署启动 Redis。

启动脚本：

.\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 一起部署，用于会话复用、与下游采购 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. 升级维护

拉取最新代码。
若依赖有变更，重新同步：
```
uv sync --extra dev
```

Docker Compose 部署：

docker compose down
docker compose up -d --build

裸机部署：
```
sudo systemctl restart surugaya
```

10 KiB Raw Blame History