From 3c299899c345c1048051117cd305dc512d3616ca Mon Sep 17 00:00:00 2001 From: Jerry Yan <792602257@qq.com> Date: Thu, 25 Jun 2026 13:43:39 +0800 Subject: [PATCH] =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 + docs/DEPLOYMENT.md | 283 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 287 insertions(+) create mode 100644 docs/DEPLOYMENT.md diff --git a/README.md b/README.md index 68dd203..270c486 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ - `POST /api/search` - `POST /api/item_detail` +## 部署 + +生产环境及更多部署方式请参考 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。 + ## 安装 ```bash diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..9f7c61c --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,283 @@ +# 骏河屋抓取服务部署文档 + +本文档说明如何将 `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 " \ + -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 + ```