# 1688 智能采购询价机器人 — 运维文档

## 1. 部署要求

### 1.1 系统要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | macOS / Linux / Windows | macOS / Ubuntu 22.04+ |
| Node.js | 18.x+ | 20.x LTS |
| 内存 | 2 GB | 4 GB+ （Chromium 占用较大） |
| 磁盘 | 1 GB | 5 GB+（含浏览器缓存和图片） |
| 网络 | 访问 1688.com、Supabase、LLM API | 稳定的国内网络 |
| 显示器 | 非无头模式需要 | Headless 模式可无显示器 |

### 1.2 外部服务依赖

| 服务 | 用途 | 获取方式 |
|------|------|----------|
| Supabase | 数据库 & 状态存储 | https://supabase.com 创建项目 |
| LLM API | 意图识别（OpenAI 兼容） | DeepSeek / 智谱 / 通义千问 / OpenAI |
| 1688.com | 采购平台 | 需要有效的 1688 账号 |

---

## 2. 安装部署

### 2.1 首次部署

```bash
# 1. 克隆代码
git clone <repo-url>
cd playwright_1688_yueyue_chatbot

# 2. 在仓库根目录安装 pnpm workspace 依赖
pnpm install

# 3. 安装 Playwright 浏览器
pnpm exec playwright install chromium

# 4. 创建环境变量文件
cp .env.example .env   # 如果有模板，否则手动创建
# 编辑 .env 填入实际配置（见下方配置说明）

# 5. 初始化数据库
# 在 Supabase SQL Editor 中依次执行：
#   sql/006_customer_service_chats.sql
#   sql/007_chat_messages.sql

# 6. 登录 1688（保存浏览器登录态）
pnpm --dir chatbot run login
```

### 2.2 环境变量配置

`.env` 文件必需的变量：

```bash
# ===== 必填 =====
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_service_key=eyJhbGci...your-service-role-key

LLM_API_KEY=sk-your-api-key
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# ===== 选填（含默认值） =====
HEADLESS=0                  # 1=无头模式（服务器部署推荐开启）
RESULT_LIMIT=10             # 每次搜索结果数量
WORKER_BATCH_SIZE=5         # Worker 每轮处理任务数
WORKER_IDLE_SEC=30          # 队列空时等待秒数
KEEP_BROWSER_OPEN=0         # 1=运行完保持浏览器
CONTACT_MERCHANTS=1         # 1=自动联系商家
```

> **安全提醒**：`.env` 文件包含敏感凭据，不要提交到版本控制。确保 `.gitignore` 中包含 `.env`。

### 2.3 更新部署

```bash
git pull origin main
pnpm install                         # 若依赖有变化
pnpm exec playwright install chromium # 若 Playwright 升级
```

---

## 3. 日常运维

### 3.1 标准工作流程

#### 一、初始化询价批次

```bash
# 前提：Supabase procurement_materials 表中已有待采购清单
pnpm --dir chatbot run chat:init
```

此命令会：
- 读取采购清单中的材料
- 在 1688 搜索每个材料
- 创建对话任务 → 发送 Round 1 话术
- 关注终端输出，确认发送成功

#### 二、启动巡检 Worker

```bash
pnpm --dir chatbot run chat:worker
```

Worker 会持续运行，循环执行：
1. 拉取 `PENDING_SEND` 任务 → 发送消息
2. 拉取到期的 `WAITING_REPLY` 任务 → 检查回复 → LLM 分析 → 推进状态
3. 队列空时休眠（默认 30 秒后再次检查）

> **注意**：Worker 是长时间运行的进程，建议使用 PM2 或 systemd 管理（见第 4 节）。

### 3.2 登录态维护

1688 登录态保存在 `.browser/1688-profile/` 目录中。

**登录态过期的表现**：
- 终端提示跳转到登录页
- 脚本调用 `promptForManualLogin()` 等待用户手动登录

**刷新登录态**：

```bash
pnpm --dir chatbot run login
```

**建议**：每 1-2 天检查一次登录态是否有效。可在 Worker 空闲时重新登录。

### 3.3 监控与告警

#### 查看 Worker 日志

```bash
# 直接运行
pnpm --dir chatbot run chat:worker 2>&1 | tee logs/worker-$(date +%Y%m%d).log

# 使用 PM2（推荐）
pm2 logs chat-worker
```

#### 关键指标监控

通过 Supabase 查询监控：

```sql
-- 各状态任务统计
SELECT status, COUNT(*) FROM customer_service_chats
GROUP BY status ORDER BY COUNT(*) DESC;

-- 今日处理量
SELECT status, COUNT(*) FROM customer_service_chats
WHERE updated_at >= CURRENT_DATE
GROUP BY status;

-- 等待超过 24 小时的任务
SELECT id, merchant_name, title, last_interacted_at
FROM customer_service_chats
WHERE status = 'WAITING_REPLY'
  AND last_interacted_at < NOW() - INTERVAL '24 hours';

-- 各轮次通过率
SELECT current_round,
  COUNT(*) FILTER (WHERE status LIKE 'R%_PASSED' OR status = 'COMPLETED') AS passed,
  COUNT(*) FILTER (WHERE status = 'REJECTED') AS rejected,
  COUNT(*) AS total
FROM customer_service_chats
GROUP BY current_round ORDER BY current_round;
```

---

## 4. 进程管理

### 4.1 使用 PM2 管理（推荐）

```bash
# 安装 PM2
pnpm add -g pm2

# 启动 Worker
pm2 start src/chat-worker.js --name chat-worker --node-args="--env-file=.env"

# 查看状态
pm2 status

# 查看日志
pm2 logs chat-worker

# 重启
pm2 restart chat-worker

# 停止
pm2 stop chat-worker

# 开机自启
pm2 startup
pm2 save
```

### 4.2 使用 systemd 管理（Linux 服务器）

创建 `/etc/systemd/system/chat-worker.service`：

```ini
[Unit]
Description=1688 Chat Worker
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/opt/playwright_1688_yueyue_chatbot
ExecStart=/usr/bin/node src/chat-worker.js
Restart=on-failure
RestartSec=10
EnvironmentFile=/opt/playwright_1688_yueyue_chatbot/.env

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable chat-worker
sudo systemctl start chat-worker
sudo systemctl status chat-worker
journalctl -u chat-worker -f   # 查看日志
```

---

## 5. 故障排查

### 5.1 常见问题

#### 登录态失效

**现象**：脚本检测到登录页 URL，提示手动登录。

**解决**：
```bash
pnpm --dir chatbot run login
# 手动完成登录和验证码，按 Enter 保存
```

#### 旺旺 iframe 加载失败

**现象**：`getChatFrame()` 超时报错。

**可能原因**：
- 网络不稳定
- 1688 页面改版导致 iframe 选择器变化
- 浏览器缓存异常

**解决**：
1. 检查网络连接
2. 清理浏览器缓存：删除 `.browser/1688-profile/` 后重新 `pnpm --dir chatbot run login`
3. 检查 `wangwang-rpa.js` 中的选择器是否与最新页面匹配

#### LLM API 调用失败

**现象**：`analyzeReply()` 报错或返回空结果。

**解决**：
1. 检查 `.env` 中 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 配置
2. 手动测试 API：
   ```bash
   curl -X POST "$LLM_BASE_URL/chat/completions" \
     -H "Authorization: Bearer $LLM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"'$LLM_MODEL'","messages":[{"role":"user","content":"hello"}]}'
   ```
3. 检查 API 余额是否充足

#### Supabase 连接失败

**现象**：报 `FetchError` 或 401 错误。

**解决**：
1. 确认 `SUPABASE_URL` 和 `SUPABASE_service_key` 正确
2. 确认 Supabase 项目处于活跃状态（免费版会自动暂停）
3. 检查数据库表是否已创建

#### Worker 处理缓慢

**可能原因**：
- `WORKER_BATCH_SIZE` 设置过小
- 大量任务处于 `WAITING_REPLY` 但尚未到期
- 浏览器实例占用过多内存

**解决**：
1. 适当增大 `WORKER_BATCH_SIZE`（注意内存占用）
2. 检查任务状态分布（SQL 见 3.3 节）
3. 定期重启 Worker 释放内存

#### 被 1688 风控

**现象**：频繁弹出验证码、滑块、账号受限提示。

**预防措施**：
- 不要设置 `HEADLESS=1`（有头模式更不易触发风控）
- 保持合理的操作间隔（`human.js` 中已内置随机延迟）
- `WORKER_BATCH_SIZE` 不要设置过大
- 避免短时间内联系过多商家
- 必要时更换 IP 或账号

### 5.2 数据修复

#### 重置卡住的任务

```sql
-- 将超过 2 小时未更新的 WAITING_REPLY 任务重新放入队列
UPDATE customer_service_chats
SET next_check_time = NOW(), retry_count = 0
WHERE status = 'WAITING_REPLY'
  AND updated_at < NOW() - INTERVAL '2 hours';
```

#### 重新发送被误标的任务

```sql
-- 将被误标为 REJECTED 的任务重新加入发送队列
UPDATE customer_service_chats
SET status = 'PENDING_SEND', retry_count = 0
WHERE id = 'your-task-id';
```

#### 清理超时任务

```sql
-- 统计超时任务
SELECT COUNT(*) FROM customer_service_chats
WHERE status = 'TIMEOUT_REJECTED';

-- 若需重试超时任务
UPDATE customer_service_chats
SET status = 'PENDING_SEND', retry_count = 0,
    current_round = current_round  -- 保持当前轮次
WHERE status = 'TIMEOUT_REJECTED'
  AND batch_id = 'your-batch-id';
```

---

## 6. 数据备份

### 6.1 数据库备份

```bash
# 使用 Supabase CLI 导出数据
supabase db dump -f backup-$(date +%Y%m%d).sql

# 或直接用 pg_dump
pg_dump "$DATABASE_URL" > backup-$(date +%Y%m%d).sql
```

### 6.2 浏览器配置备份

```bash
# 备份登录态
tar -czf browser-profile-$(date +%Y%m%d).tar.gz .browser/
```

### 6.3 定时备份（crontab）

```bash
# 每天凌晨 3 点备份数据库
0 3 * * * cd /opt/playwright_1688_yueyue_chatbot && supabase db dump -f backups/db-$(date +\%Y\%m\%d).sql
```

---

## 7. 性能调优

### 7.1 Worker 参数调优

| 参数 | 说明 | 建议值 |
|------|------|--------|
| `WORKER_BATCH_SIZE` | 每轮处理任务数 | 3-10（取决于内存和网络） |
| `WORKER_IDLE_SEC` | 空闲等待秒数 | 30-60 |
| `RESULT_LIMIT` | 搜索结果数量 | 5-15（越多越慢） |

### 7.2 资源控制

- **内存**：每个 Chromium 实例约占 200-500 MB，避免同时打开过多
- **网络**：旺旺聊天 iframe 加载较慢，确保网络稳定
- **磁盘**：定期清理 `.browser/1688-profile/` 中的缓存文件和 `output/images/` 中的旧图片

### 7.3 并发限制

当前架构为单 Worker 串行处理，不支持多实例并发运行（会导致同一浏览器配置冲突）。如需提升吞吐量：

1. 为每个实例准备独立的浏览器配置目录
2. 使用不同的 1688 账号
3. 通过 `batch_id` 分配任务，避免重复处理

---

## 8. 安全事项

### 8.1 凭据管理

- `.env` 文件不得提交到 Git（确保在 `.gitignore` 中）
- `SUPABASE_service_key` 是高权限密钥，严格保密
- `LLM_API_KEY` 定期轮换
- 1688 账号密码避免明文存储在脚本中

### 8.2 网络安全

- Supabase 建议开启 RLS（Row Level Security）
- 如在服务器部署，限制 `.env` 文件权限：`chmod 600 .env`
- 避免在公共网络环境下运行（凭据可能泄露）

### 8.3 合规注意

- 控制询价频率，遵守 1688 使用条款
- 不要对同一商家频繁发送相同消息
- `human.js` 中的随机延迟已内置反滥用保护，不要绕过

---

## 9. 目录清理

定期清理以下目录，防止磁盘空间不足：

```bash
# 清理 3 天前的商品图片
find output/images/ -type f -mtime +3 -delete

# 清理浏览器缓存（需重新登录）
rm -rf .browser/1688-profile/Default/Cache
rm -rf .browser/1688-profile/Default/Code\ Cache

# 清理 PM2 日志
pm2 flush
```

---

## 10. 版本与依赖

| 依赖 | 版本 | 说明 |
|------|------|------|
| `playwright` | ^1.53.2 | 浏览器自动化 |
| `@supabase/supabase-js` | ^2.49.4 | Supabase 客户端 |
| `dotenv` | ^16.4.7 | 环境变量加载 |
| Node.js | 18+ (ESM) | 运行时 |

更新依赖：

```bash
pnpm update
pnpm exec playwright install chromium   # Playwright 升级后需重新安装浏览器
```
