pruchase_jhw/docs/DEPLOYMENT_WINDOWS.md

# Windows 裸机部署指南

> 本文档说明如何在 Windows 裸机环境下部署以下两个互相配合的服务，不依赖 Docker 或 WSL。
> 部署对象：
>
> - `jp_pruchase_zdh_5`：采购自动化 worker（浏览器自动化下单、定时抓取通知/订单、截图归档）。
> - `../jp_surugaya`：骏河屋抓取 API 服务（搜索/详情/通知/订单查询，并可向 Redis 投递采购任务）。
>
> 两个服务通过 **Redis** 共享任务队列与状态数据；Redis 由 `../jp_surugaya` 侧统一部署，本服务（采购 worker）只需配置连接信息。

---

## 1. 部署架构

```text
┌─────────────────────────────────────────────────────────────┐
│                        Windows 服务器                        │
│  ┌──────────────────┐         ┌──────────────────────────┐  │
│  │   jp_surugaya    │◄───────►│     Redis (Windows)      │  │
│  │   :31106         │         │     :6379                │  │
│  └──────────────────┘         └───────────┬──────────────┘  │
│           ▲                               │                 │
│           │ HTTP API                      │ Redis Stream    │
│           ▼                               ▼                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              jp_pruchase_zdh_5                       │  │
│  │  - 消费采购任务                                       │  │
│  │  - 浏览器自动化（Playwright）                          │  │
│  │  - 截图/录屏归档到 archives/                          │  │
│  │  - 截图查看 API :8080                                 │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

- **Redis**：由 `../jp_surugaya` 侧统一部署和维护，采购 worker 通过其连接信息接入。
- **jp_surugaya**：对外提供 HTTP API（默认 `0.0.0.0:31106`），内部通过 Redis 读写任务与抓取结果。
- **jp_pruchase_zdh_5**：不直接对外暴露业务端口，但内置截图查看 API（默认 `0.0.0.0:8080`），建议仅本地或内网访问。

---

## 2. 环境准备

### 2.1 操作系统

- Windows 10/11 64 位，或 Windows Server 2019/2022。
- 建议固定显示分辨率（例如 `1920x1080`），并保证登录会话处于交互式桌面环境（本地显示器或持续 RDP 会话）。

### 2.2 Python

- 安装 **Python 3.12+**（推荐从 [python.org](https://www.python.org/downloads/windows/) 下载）。
- 安装时勾选 **Add python.exe to PATH**。
- 验证：

```powershell
python --version
```

### 2.3 uv（推荐）

两个项目均使用 `uv` 作为包管理器。安装方式：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

安装完成后重启 PowerShell，并验证：

```powershell
uv --version
```

### 2.4 Redis 接入信息

Redis 由 `../jp_surugaya` 侧统一部署，本服务不需要单独安装 Redis。

部署采购 worker 前，只需确认以下信息：

- Redis 主机地址、端口、密码、DB 编号。
- 采购 worker 与 `../jp_surugaya` 必须访问同一个 Redis 实例。

若本地开发测试时需要临时 Redis，可另行准备 Windows 版 Redis 或 Memurai；生产环境建议统一使用 `../jp_surugaya` 提供的实例。

### 2.5 浏览器

两个项目都基于 Playwright。首次部署时安装 Chromium：

```powershell
uv run playwright install chromium
```

> 默认使用 Playwright 自带的 Chromium。若 `accounts.yaml` / `.env` 中指定了 `browser_channel=chrome`，请额外安装 Google Chrome 并确保其在系统 PATH 中可被找到。

### 2.6 FFmpeg（可选）

仅在需要开启任务级桌面录屏时安装：

1. 从 [ffmpeg.org](https://ffmpeg.org/download.html#build-windows) 下载 Windows build。
2. 解压后将 `bin` 目录加入系统 PATH。
3. 验证：

```powershell
ffmpeg -version
```

---

## 3. 目录规划示例

建议将两个仓库放在同一父目录下，便于统一管理：

```text
C:\jp-deploy\
├── jp_pruchase_zdh_5\      # 采购 worker
├── jp_surugaya\             # 抓取 API（含 Redis）
├── chrome-profile\          # 浏览器登录态持久化目录
│   ├── acc_01\
│   └── acc_02\
├── archives\                # 截图/录屏归档（可选，也可放在项目内）
└── logs\                    # 日志汇总（可选）
```

后续示例均基于以上目录。

---

## 4. 部署 jp_surugaya（抓取服务）

### 4.1 进入项目目录

```powershell
cd C:\jp-deploy\jp_surugaya
```

### 4.2 配置环境变量

复制示例文件：

```powershell
copy .env.example .env
```

编辑 `.env`，生产环境最小可用示例如下：

```ini
# 服务监听
SURUGAYA_APP_HOST=0.0.0.0
SURUGAYA_APP_PORT=31106
SURUGAYA_APP_ENV=prod

# 日志
SURUGAYA_LOG_LEVEL=INFO
SURUGAYA_LOG_TO_FILE=true
SURUGAYA_LOG_DIR=logs

# API 鉴权（必须替换为强随机字符串）
SURUGAYA_BEARER_TOKEN=REPLACE_WITH_STRONG_RANDOM_TOKEN

# 浏览器
SURUGAYA_BROWSER_ENABLED=true
SURUGAYA_BROWSER_HEADLESS=false
SURUGAYA_BROWSER_CHANNEL=
SURUGAYA_BROWSER_KEEP_OPEN_ON_ERROR=false

# 代理（建议日本 IP）
SURUGAYA_PROXY_SERVER=http://127.0.0.1:7890
SURUGAYA_PROXY_USERNAME=
SURUGAYA_PROXY_PASSWORD=

# Redis（与采购 worker 使用同一实例）
SURUGAYA_REDIS_HOST=127.0.0.1
SURUGAYA_REDIS_PORT=6379
SURUGAYA_REDIS_PASSWORD=
SURUGAYA_REDIS_DB=0
```

> 注意：
> - `SURUGAYA_APP_ENV` 要与采购 worker 的 `APP_ENV` 保持一致（推荐均为 `prod`），否则 Redis key 后缀不同，会导致通知/订单数据互相看不到。
> - 若不需要无头调试，Windows 裸机建议保持 `SURUGAYA_BROWSER_HEADLESS=false`，便于观察 Cloudflare 页面。

### 4.3 安装依赖与浏览器

```powershell
uv sync
uv run playwright install chromium
```

### 4.4 启动服务

项目已提供 PowerShell 启动脚本，推荐直接使用：

```powershell
.\start-server.ps1
```

可选参数：

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

如果不希望使用脚本，也可以手动启动：

```powershell
uv run python -m app.main
```

### 4.5 验证

```powershell
curl http://127.0.0.1:31106/health
```

测试带鉴权的搜索接口：

```powershell
curl -H "Authorization: Bearer REPLACE_WITH_STRONG_RANDOM_TOKEN" `
  -H "Content-Type: application/json" `
  -X POST "http://127.0.0.1:31106/api/search" `
  -d '{"search_word":"cat","category":"","page":1}'
```

---

## 5. 部署 jp_pruchase_zdh_5（采购 worker）

### 5.1 进入项目目录

```powershell
cd C:\jp-deploy\jp_pruchase_zdh_5
```

### 5.2 配置环境变量

复制示例文件为生产配置：

```powershell
copy .env.example .env.prod
```

编辑 `.env.prod`，生产环境最小可用示例如下：

```ini
APP_ENV=prod
LOG_LEVEL=INFO
LOG_DIR=./logs

# Redis（必须与 jp_surugaya 同一实例）
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 消费者标识（多 worker 部署时建议为每个实例设置唯一名称）
REDIS_CONSUMER_GROUP=purchase_group
REDIS_CONSUMER_NAME=purchase_worker_01

# Redis key 名称（与 jp_surugaya 共用，prod 环境不带 _dev 后缀）
# 这些 key 的默认值已由 surugaya-common 的 redis_keys 定义一致，通常无需显式覆盖
REDIS_STREAM_KEY=jp_surugaya_purchase_task
REDIS_DELAY_ZSET_KEY=jp_surugaya_trade_delay
REDIS_NEWS_HASH_KEY=jp_surugaya_news
REDIS_TRADE_FETCH_STREAM_KEY=jp_surugaya_trade_fetch
REDIS_TRADE_FETCH_CONSUMER_GROUP=surugaya_trade_fetch_group
REDIS_TRADE_FETCH_CONSUMER_NAME=surugaya_trade_fetch_worker

# 节点标识（用于 trade delay zset，最终 key 为 REDIS_DELAY_ZSET_KEY:NODE_ID）
NODE_ID=node_1

# 通知定时抓取
NEWS_FETCH_ENABLED=true
NEWS_FETCH_INTERVAL_SECONDS=300

# 浏览器
BROWSER_HEADLESS=false
BROWSER_EXECUTABLE_PATH=
BROWSER_KEEP_OPEN=false
LOGIN_PRECHECK_ENABLED=true

# 配置与资源路径
ACCOUNTS_CONFIG_PATH=./accounts.yaml
SCREENSHOT_DIR=./archives

# 任务上报（按需配置回调地址与签名密钥）
CALLBACK_URL=
APPID=
APP_SECRET=

# 通知配置（失败时发邮件）
NOTIFY_ENABLED=false
NOTIFY_CHANNELS=email
NOTIFY_ON_TASK_FAILED=true

MAIL_ENABLED=true
MAIL_SMTP_HOST=
MAIL_SMTP_PORT=465
MAIL_SMTP_USE_SSL=true
MAIL_SMTP_STARTTLS=false
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=JP Purchase Bot
MAIL_TO_ADDRESSES=ops@example.com
MAIL_SUBJECT_PREFIX=[JP-Purchase]
MAIL_TIMEOUT_SECONDS=10
```

> 注意：
> - Redis 实例由 `../jp_surugaya` 侧统一部署，本配置只需填写正确的连接信息。
> - `APP_ENV=prod` 时，Stream / Hash / ZSet 的 key 默认不带 `_dev` 后缀；若 `jp_surugaya` 与采购 worker 的 prod/dev 环境不一致，会出现通知/订单数据互相看不到、任务投递后无法消费等问题。
> - `REDIS_DELAY_ZSET_KEY` 最终使用的 key 为 `{REDIS_DELAY_ZSET_KEY}:{NODE_ID}`，因此 `NODE_ID` 必须与 `jp_surugaya` 调用 `/api/order/add_trade_monitor` 时传入的 `node_id` 保持一致。

### 5.3 配置账号

编辑项目根目录的 `accounts.yaml`。Windows 裸机部署示例：

```yaml
sites:
  surugaya:
    - account_id: "acc_01"
      username: "your_username@example.com"
      password: "your_password"
      # 使用绝对路径，建议使用正斜杠
      user_data_dir: "C:/jp-deploy/chrome-profile/acc_01"
      proxy: "http://127.0.0.1:7890"

    - account_id: "acc_02"
      username: "your_username2@example.com"
      password: "your_password2"
      user_data_dir: "C:/jp-deploy/chrome-profile/acc_02"
      proxy: "http://127.0.0.1:7890"

```

> 提示：
> - `user_data_dir` 用于持久化浏览器登录态；首次启动前确保目录已存在。
> - 如需清除登录态重新登录，直接删除对应目录即可。
> - 密码若为空字符串 `""`，系统会尝试使用已有 Cookie 登录。

### 5.4 安装依赖与浏览器

```powershell
uv sync
uv run playwright install chromium
```

> 说明：`jp_pruchase_zdh_5` 依赖的 `surugaya-common` 来自公开 PyPI 索引，其源码与发布源头位于 `../jp_surugaya/packages/surugaya_common`。如需本地调试或修改共享包，请在 `../jp_surugaya` 仓库中开发并重新安装/发布。

### 5.5 启动 worker

```powershell
$env:APP_ENV="prod"
uv run python -m src.main
```

启动后，worker 会：

1. 加载 `.env.prod` 与 `accounts.yaml`。
2. 预热所有已配置账号的浏览器上下文。
3. 执行登录预检（`LOGIN_PRECHECK_ENABLED=true`）。
4. 启动 Redis Stream 监听器、延迟任务监听器、订单抓取监听器、通知定时调度器。
5. 启动截图查看 API（`http://0.0.0.0:8080/`）。

### 5.6 验证

1. 查看日志输出，确认无配置错误。
2. 打开浏览器访问 `http://127.0.0.1:8080/`，应能看到截图查看器。
3. 向 Redis Stream 投递一条测试任务：

```powershell
redis-cli XADD jp_surugaya_purchase_task * task_id "task_test_001" topic "surugaya_tasks" purchase_account "acc_01" site_id "surugaya" record_video "0" payload "{\"item_list\":[{\"id\":\"m72275988725\",\"price_limit\":6500,\"number\":1}]}"
```

> 如果 Redis 设置了密码，请使用 `redis-cli -a your_password ...`。

---

## 6. 长期后台运行（可选）

Windows 裸机环境下，可采用以下方式让服务随系统启动并保持运行：

### 6.1 使用任务计划程序（Task Scheduler）

1. 创建基本任务，触发器选择“当用户登录时”或“启动时”。
2. 操作选择“启动程序”，程序路径填写 `powershell.exe`。
3. 参数示例（采购 worker）：

```text
-WindowStyle Hidden -Command "cd C:\jp-deploy\jp_pruchase_zdh_5; $env:APP_ENV='prod'; uv run python -m src.main"
```

4. 在“常规”选项卡中勾选“不管用户是否登录都要运行”时，服务将运行在 Session 0，可能导致 `pyautogui`、模板匹配、录屏等依赖桌面的功能失败。因此：

> **建议**：采购 worker 必须运行在**交互式用户会话**中（本地登录或持续 RDP 会话）。抓取 API 服务可运行在非交互式账户下。

### 6.2 使用 NSSM

[NSSM](https://nssm.cc/) 可将任意程序封装为 Windows 服务。仅建议用于 `jp_surugaya`；采购 worker 因需要桌面交互，不建议使用 NSSM。

---

## 7. 升级维护

1. 拉取最新代码（如使用 git）：

```powershell
cd C:\jp-deploy\jp_pruchase_zdh_5
git pull
```

2. 重新同步依赖：

```powershell
uv sync
```

3. 重启对应 PowerShell 窗口中的进程即可。

> 提示：采购 worker 在 Windows 上不支持通过内置 API（`POST /api/restart`）重启，修改 `accounts.yaml` 后请手动重启进程。

---

## 8. 常见问题

### 8.1 `uv sync` 失败，提示索引无法访问

- 确认部署机能正常访问 `https://git.jerryyan.net/api/packages/jp/pypi/simple`。
- 检查系统代理或防火墙是否拦截了该地址。
- 若企业内部网络需通过代理访问外网，请在执行 `uv sync` 前配置好 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量。

### 8.2 Playwright 启动浏览器失败

- 确认已执行 `uv run playwright install chromium`。
- 确认已安装 [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe)。
- 若指定了 `BROWSER_EXECUTABLE_PATH` 或 `SURUGAYA_BROWSER_CHANNEL=chrome`，确认 Chrome 已安装且路径正确。

### 8.3 模板匹配（Google Pay 确认按钮等）失败

- 确认当前屏幕分辨率与 `resources/images/` 下模板图的采集分辨率一致（推荐 `1920x1080`）。
- 若分辨率不同，请在当前分辨率下重新截取模板图并替换原文件。

### 8.4 端口被占用

- `31106` 被占用：先结束旧的 `python.exe` / `uvicorn` 进程，或修改 `.env` 中的 `SURUGAYA_APP_PORT`。
- `8080` 被占用：采购 worker 内置截图 API 默认使用 8080，若被其他程序占用，目前需修改源码中 `src/api/server.py` 的默认端口。

### 8.5 调用 `/api/search` 返回 403

检查请求头中的 `Authorization: Bearer <token>` 与 `.env` 中的 `SURUGAYA_BEARER_TOKEN` 是否一致。

### 8.6 采购 worker 收不到 jp_surugaya 投递的任务

检查两边 Redis 配置是否指向同一主机/端口/DB，并确认 `APP_ENV`（采购侧）与 `SURUGAYA_APP_ENV`（抓取侧）一致（例如都是 `prod`）。

### 8.7 账号登录态失效

删除该账号对应的 `user_data_dir` 目录，重启 worker 后会重新走登录流程。

---

## 9. 安全建议

- **不要**将 `8080` 端口直接暴露到公网；截图查看器与账号配置接口均无额外应用层鉴权。
- `31106` 若需对外提供，请通过反向代理并加鉴权（如 Nginx / Cloudflare Access / 企业 VPN）。
- `SURUGAYA_BEARER_TOKEN` 应使用至少 32 位的强随机字符串。
- 敏感信息（密码、Token、SMTP 密码）只存放在 `.env` / `accounts.yaml` 中，不要提交到 Git。
- 建议为日本站点使用稳定的日本 IP 代理，降低 Cloudflare 挑战频率。