admin9webs
322b7737eb
来源：紫鸟帮助中心/博客/主站资讯 + HubStudio API 文档/帮助中心 + 三个官方 skill 仓库。 只入库 Markdown 与元数据；原始 HTML 与 tarball 留在本机。
142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
# 前置条件与排障
|
||
|
||
> 本文件是 ziniao-webdriver-doc 的 Level 2 参考文档。
|
||
> 仅在需要了解权限开通、账号配置、常见问题排查时加载。
|
||
|
||
## 概述
|
||
|
||
使用紫鸟 WebDriver 前需完成权限开通和环境准备。本文档覆盖权限申请、账号配置和常见问题排查。
|
||
|
||
## 1. 开通 WebDriver 权限
|
||
|
||
首次使用 WebDriver 时，需先在紫鸟开放平台开通权限。
|
||
|
||
详细步骤见官方文档：[如何开通webdriver权限](https://open.ziniao.com/docSupport?docId=99)
|
||
|
||
## 2. 客户端版本要求
|
||
|
||
| 操作系统 | 最低版本 |
|
||
|---------|---------|
|
||
| Windows | 紫鸟 V5 (5.X.X.X) 或 V6 (6.16.0.126+) |
|
||
| macOS | 紫鸟 V6 (6.15.0.44+) |
|
||
| Linux | 紫鸟 V6 (6.25.3.3+) |
|
||
|
||
## 3. 环境准备清单
|
||
|
||
### 3.1 关闭主进程
|
||
|
||
启动 WebDriver 前**务必**确保紫鸟浏览器主进程已完全关闭，避免端口占用或冲突。
|
||
|
||
### 3.2 清理残留进程
|
||
|
||
紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），不清理直接重启会导致端口占用、反复失败。**每次启动前和失败后重试前，都必须执行清理。**
|
||
|
||
已知的紫鸟相关进程名：`ziniao`、`ZiNiao`、`ziniao.exe`、`ZiNiaoBrowser` 等（不同版本命名可能不同，建议用模糊匹配）。
|
||
|
||
清理命令：
|
||
|
||
```bash
|
||
# Windows (PowerShell)
|
||
Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force
|
||
|
||
# macOS / Linux
|
||
pkill -f ziniao || true
|
||
```
|
||
|
||
验证清理结果：
|
||
|
||
```bash
|
||
# Windows (PowerShell) — 应无输出
|
||
Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' }
|
||
|
||
# macOS / Linux — 应无输出
|
||
pgrep -f ziniao
|
||
```
|
||
|
||
### 3.3 创建自动化专用账号
|
||
|
||
- 创建专用的自动化成员账号（命名建议：`自动化_Robot`）
|
||
- 正式使用前验证该账号能否正常登录紫鸟浏览器客户端
|
||
|
||
### 3.4 配置账号权限
|
||
|
||
**问题场景**：自动化账号登录后无法获取店铺列表。
|
||
|
||
**解决方案**：
|
||
1. 登录企业管理后台
|
||
2. 检查该账号的权限配置
|
||
3. 授予查看对应账号/店铺的权限
|
||
4. 建议新建包含此权限的自定义角色并分配给自动化账号
|
||
|
||
### 3.5 超时设置
|
||
|
||
将所有 HTTP 请求的超时时间设为 **120 秒或以上**，因为启动店铺环境可能耗时较长。
|
||
|
||
### 3.6 系统资源管理
|
||
|
||
- 启动店铺窗口 CPU 消耗较大
|
||
- 根据设备配置合理控制并发启动数量
|
||
- 建议错开各任务的启动时间，避免瞬时负载过高
|
||
|
||
### 3.7 ChromeDriver 版本管理
|
||
|
||
> **关键：紫鸟内核版本 ≠ 系统 Chrome 版本。** 必须根据 `startBrowser` 返回的 `core_version` 匹配 ChromeDriver，不能使用系统 Chrome 对应的版本。
|
||
|
||
**匹配规则：**
|
||
- `core_version` 格式为 `X.Y.Z.W`（如 `119.1.0.16`），取第一段 `X` 作为大版本号
|
||
- 下载该大版本号对应的 ChromeDriver（如大版本 `119` → ChromeDriver 119.x）
|
||
|
||
**下载地址：**
|
||
- Chrome for Testing：https://googlechromelabs.github.io/chrome-for-testing/
|
||
- JSON API（便于自动化脚本解析）：https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json
|
||
|
||
**本地缓存建议：**
|
||
|
||
```
|
||
chromedriver_cache/
|
||
├── 119/
|
||
│ └── chromedriver.exe # 对应 core_version 119.x
|
||
├── 120/
|
||
│ └── chromedriver.exe # 对应 core_version 120.x
|
||
└── ...
|
||
```
|
||
|
||
自动化脚本应实现以下逻辑：
|
||
1. 从 `startBrowser` 响应中提取 `core_version` 大版本号
|
||
2. 检查缓存目录 `chromedriver_cache/{major_version}/` 是否存在
|
||
3. 若不存在，从 Chrome for Testing 下载对应版本并解压到缓存目录
|
||
4. 使用缓存中的 ChromeDriver 路径连接 Selenium
|
||
|
||
## 4. 通信注意事项
|
||
|
||
1. 请求/响应均为 JSON 格式，收发消息统一 UTF-8 编码
|
||
2. HTTP 模式下超时时长必须 ≥120 秒
|
||
3. 调用任何接口后务必检查 `statusCode`（0 表示成功），**出错时优先读取 `err` 字段获取中文错误描述**，这是最有价值的排障信息
|
||
4. **启动后必须首先调用 `updateCore` 接口**（需携带凭据），否则打开店铺可能出现内核缺失
|
||
5. **务必确保 HTTP 客户端以 UTF-8 解码响应体**，否则 `err` 中的中文会乱码，严重影响错误定位（Python `requests` 库需设置 `response.encoding = 'utf-8'`）
|
||
6. 所有标记"需凭据"的接口（`updateCore`、`getBrowserList`、`startBrowser`、`stopBrowser`、`ClearOnline`）每次调用都必须携带 company/username/password
|
||
|
||
## 5. 常见问题
|
||
|
||
| 现象 | 可能原因 | 解决方案 |
|
||
|------|---------|---------|
|
||
| 连接接口失败 | 客户端未启动完成 | 轮询 updateCore 直到连接成功 |
|
||
| getBrowserList 返回 -10003 | 未开通权限或未关闭登录验证 | 检查权限开通状态 |
|
||
| getBrowserList 返回 -10013 | 新设备未授权 | 调用 applyAuth 进行设备授权 |
|
||
| 店铺列表为空 | 账号无店铺权限 | 在企业管理后台配置角色权限 |
|
||
| startBrowser 返回 -10006 | 上次启动未完成 | 等待或调用 stopBrowser 后重试 |
|
||
| startBrowser 返回 7 | 内核缺失 | 确保先调用 updateCore 等待成功 |
|
||
| Selenium 连接失败 | ChromeDriver 版本不匹配 | 根据 core_version 下载匹配版本 |
|
||
| 请求超时 | 超时设置过短 | 设置超时 ≥120 秒 |
|
||
| 多账号冲突 | 端口/缓存冲突 | V5 使用 `--multip` + `--enforce-cache-path` |
|
||
| updateCore 返回错误 | 未携带凭据（company/username/password） | 所有需凭据的接口必须携带完整凭据 |
|
||
| err 字段内容乱码 | HTTP 响应体未以 UTF-8 解码 | 设置 `response.encoding = 'utf-8'` 或用 `response.content.decode('utf-8')` |
|
||
| 重启失败 / 端口占用 | 上次失败后残留紫鸟进程 | 清理所有紫鸟相关进程后重试（见§3.2） |
|
||
| Selenium 连接失败（版本不匹配） | 使用了系统 Chrome 对应的 ChromeDriver | 必须根据紫鸟 `core_version` 大版本号下载匹配的 ChromeDriver（见§3.7） |
|
||
|
||
## 6. 技术支持
|
||
|
||
如在对接过程中遇到问题，可通过以下渠道获取支持：
|
||
- 微信添加紫鸟生态管家，备注 "紫鸟webdriver"
|
||
- 官方 FAQ：https://open.ziniao.com/docSupport?docId=257
|