284 lines
7.2 KiB
Markdown
284 lines
7.2 KiB
Markdown
# 骏河屋抓取服务部署文档
|
|
|
|
本文档说明如何将 `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` 示例
|
|
|
|
```ini
|
|
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. 复制环境变量模板并修改：
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# 编辑 .env，重点修改 SURUGAYA_BEARER_TOKEN 与代理配置
|
|
```
|
|
|
|
3. 构建并启动容器：
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
4. 查看日志：
|
|
|
|
```bash
|
|
docker compose logs -f
|
|
```
|
|
|
|
### 4.2 说明
|
|
|
|
- `docker-compose.yml` 使用 `.:/app` 挂载宿主目录，因此 `venv` 被放置在 `/opt/venv`，避免被卷覆盖。
|
|
- 容器内 `SURUGAYA_BROWSER_CHANNEL` 已强制留空，使用 Playwright 自带的 Chromium。
|
|
- 时区设置为 `Asia/Tokyo`。
|
|
|
|
### 4.3 停止与重启
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d --build
|
|
```
|
|
|
|
## 5. 部署方式二：裸机/虚拟机
|
|
|
|
### 5.1 安装依赖
|
|
|
|
推荐使用 `uv` 作为包管理器：
|
|
|
|
```bash
|
|
# 安装 uv（若未安装）
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# 同步依赖（包含 dev 依赖）
|
|
uv sync --extra dev
|
|
|
|
# 安装 Chromium 浏览器
|
|
uv run playwright install chromium
|
|
```
|
|
|
|
若使用传统 pip：
|
|
|
|
```bash
|
|
python -m pip install -e ".[dev]"
|
|
python -m playwright install chromium
|
|
```
|
|
|
|
### 5.2 启动服务
|
|
|
|
```bash
|
|
# 方式 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`：
|
|
|
|
```ini
|
|
[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
|
|
```
|
|
|
|
启用并启动：
|
|
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable surugaya
|
|
sudo systemctl start surugaya
|
|
```
|
|
|
|
## 6. 部署方式三：Windows 本地开发
|
|
|
|
Windows 本地开发可使用提供的 PowerShell 启动脚本：
|
|
|
|
```powershell
|
|
.\start-server.ps1
|
|
```
|
|
|
|
可选参数：
|
|
|
|
- `-Port 31106`：指定端口。
|
|
- `-HostName 0.0.0.0`：指定监听地址。
|
|
- `-NoKillExisting`：端口占用时不自动结束旧进程。
|
|
- `-DryRun`：仅做检查，不实际启动。
|
|
|
|
## 7. 启动验证
|
|
|
|
### 7.1 健康检查
|
|
|
|
```bash
|
|
curl http://127.0.0.1:31106/health
|
|
```
|
|
|
|
### 7.2 API 鉴权测试
|
|
|
|
```bash
|
|
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. 若依赖有变更，重新同步：
|
|
|
|
```bash
|
|
uv sync --extra dev
|
|
```
|
|
|
|
3. Docker Compose 部署：
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d --build
|
|
```
|
|
|
|
4. 裸机部署：
|
|
|
|
```bash
|
|
sudo systemctl restart surugaya
|
|
```
|