145 lines
12 KiB
Markdown
145 lines
12 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Troubleshooting
|
||
wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Troubleshooting
|
||
wiki_revision: 0a176fa4cf7f3bd6a2c6b11ae3c6a58453500c85
|
||
synchronized_at: 2026-10-05T02:28:58Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 故障排查
|
||
|
||
## 视频上传经 erpgo（2026-09-30）
|
||
|
||
先核对参数设置中的 erpgo 地址和 API Key。视频目录使用 Shopee 商品 ID；需 mp4、10—60 秒、宽高不超过 1280、文件不超过 30 MB。操作不确定时 SQLite 会保留原幂等键；重复点击只查询原操作，不会重新提交。`succeeded` 是 erpgo 对本次货憨憨视频关联的回读结果，Shopee 页面仍需人工验收。预览若出现 502 / `HHH_UPSTREAM_ERROR` / `stage=check`，界面提示“视频状态无法确认，上传未提交”并保留 requestId；此时 ERPGo 未确认货憨憨 `video` 字段，cmsp 不会发送 PUT。不能把字段缺失当成 `video: []`，排除上游回读问题后再手动重试。若返回 `VIDEO_ALREADY_PROCESSING`，等待 ERPGo 核对处理中标记及原操作，不新建幂等键。cmsp 的 ERPGo 客户端直连配置的服务地址，避免本机环境代理截断 MP4 PUT；若仍有 `NETWORK_ERROR`，按请求时段核对网络、代理入口、ERPGo 应用日志和原键操作查询。`VIDEO_OPERATION_NOT_FOUND` 不自动证明视频未提交，不删除本地记录或换键重放。运维用另一操作成功上传的视频不自动认领为 cmsp 原操作成功。确认上传后弹窗应立即关闭，上传按钮继续转圈直到当前调用结束。已有未决操作时，确认框显示“恢复原上传操作”，点击后只查询原键，不会重新上传或覆盖当前视频。列表“待确认”表示视频状态或本次操作结果尚未证实；即使货憨憨当前有视频，也要按原幂等键查询 ERPGo 操作状态。`processing/check/submitted` 不能改为已上传，尤其是商品此前已有其他操作的视频；等待 ERPGo 核对本次操作的素材归属，只有 `succeeded` 才更新本地完成状态。
|
||
|
||
|
||
## 全店铺同步与部分成功（2026-09-29，#26）
|
||
|
||
不选店铺点击“下载数据”先获取最新全部店铺，逐店串行查询；耗时随店铺及商品量增加，运行日志显示店铺序号和页数。完成汇总来自实际保存数量，与当前缺视频/未下载筛选的列表总数不同。
|
||
|
||
“同步部分完成”可展开失败店铺看错误；已成功店铺已保存，失败及未处理店铺原商品和任务状态保留。分页或落库失败不写该店部分结果；店铺列表成功时缓存可以刷新。不要清库、删除视频或重置上传状态，排除原因后选失败店铺手动重试。
|
||
|
||
API_KEY_INVALID、HHH_AUTH_FAILED、RATE_LIMITED、REQUEST_CANCELLED、NETWORK_ERROR、SERVICE_UNAVAILABLE、INTERNAL_ERROR 停止剩余店铺，不逐店重试全局错误。SHOP_ACCESS_DENIED、HHH_UPSTREAM_ERROR/TIMEOUT、INVALID_RESPONSE 和 LOCAL_SYNC_FAILED 等店铺错误记录后继续。不同店铺同内部ID冲突返回 INVALID_RESPONSE，不覆盖先成功的数据。
|
||
|
||
SYNC_IN_PROGRESS 表示已有商品同步，请等待结束；Go侧拒绝重叠请求。空店铺列表显示“没有可同步的店铺”，不删除旧商品。店铺查询失败则不开始商品查询，原缓存保留。
|
||
|
||
## 图搜成功但商品链接无法使用（2026-09-29）
|
||
|
||
程序优先使用 MTOP 返回的 `auctionURL`，不会丢弃原查询参数后重新按 ID 拼接。单个非法链接候选会跳过，不影响其他合法候选；如果所有候选都不可用，报“淘宝以图搜返回了无效商品链接”，检查经过脱敏的字段结构是否发生变化；只允许淘宝/天猫商品域名、`/item.htm` 和与候选匹配的唯一 `id`。不能关闭校验、盲信广告跳转域名或把完整响应/参数写入日志。缺少链接字段的旧响应仍兼容按 ID 打开。
|
||
|
||
保留原链接是进入路径调整，不代表浏览器已经处于淘宝搜索结果页，也不能证明平台风控缓解。受限提示仍按下方停止门处理。仅确认商品链接成功打开不足以证明视频属于当前商品或下载完成。
|
||
|
||
## 淘宝提示「当前访问存在异常」（2026-09-29）
|
||
|
||
先停止自动任务。程序检测到此提示或安全验证时应显示「淘宝访问受限」，整批停止并保留断点；不会将受限详情记为无视频，也不会自动重试。不要连续点击启动。
|
||
|
||
在同一个专属 Chrome 中手动检查正常商品详情；有安全验证时由使用者手动完成。若手动访问也受限，等待平台恢复并检查正常网络/浏览器环境。不能根据此提示确认具体触发原因，也没有本项目已验证的固定恢复时长。
|
||
|
||
三种停止原因：`risk_blocked` 是明确访问异常/安全验证；`login_required` 是登录或 token/session 失效；`risk_suspected` 是正常新详情连续无视频，属于保守停止，不能据此证明被平台封禁。恢复后手动启动，SQLite 已完成记录继续跳过。历史无视频状态不自动清空。
|
||
|
||
每次新启动或手动恢复仅首次处理打开「我的淘宝」，后续在当前页面检查，不再为检查跳转。当前页面守卫不主动证明服务器登录有效；MTOP 认证失效或详情异常仍会停批，首次成功不代表后续永久有效。显式登录检查按钮仍会打开「我的淘宝」。
|
||
|
||
先以默认候选 5、等待 10—20 秒小批量观察。增加等待仅降低访问负载，不保证解除限制；下载并发数只控制 CDN 文件，不增加淘宝页面并行度。
|
||
|
||
## erpgo 店铺与商品同步排查（2026-09-28）
|
||
|
||
先查看稳定 errorCode、HTTP 状态及 requestId。界面按错误码显示提示，不按中文上游消息分支，也不输出原始响应。失败店铺保留原商品和任务；全店模式保留已成功店铺，实时店铺列表成功后缓存可刷新。不要清库或删视频来修复连接问题。
|
||
|
||
| errorCode | 处理 |
|
||
|---|---|
|
||
| ERPGo_NOT_CONFIGURED | 参数设置填写 erpgo 服务地址与 API Key 并保存 |
|
||
| INVALID_ARGUMENT | 检查服务根地址、店铺参数；地址不能带账号、查询参数或片段 |
|
||
| API_KEY_INVALID（401） | 检查本机 Key 是否有效；不要把 Key 发进工单或日志 |
|
||
| SHOP_ACCESS_DENIED（403） | 检查 erpgo 当前账号是否包含该店铺 |
|
||
| HHH_AUTH_FAILED（502） | 在 erpgo 检查货憨憨账号配置与认证，不修改本机上传账号来修查询 |
|
||
| HHH_UPSTREAM_ERROR（502） | 保留 requestId，检查提供方；稍后手动重试，不紧密重试 |
|
||
| HHH_UPSTREAM_TIMEOUT（504） | 检查提供方与上游连接，稍后重试 |
|
||
| SERVICE_UNAVAILABLE（503） / NETWORK_ERROR | 检查服务地址、网络与服务状态 |
|
||
| RATE_LIMITED（429） | 稍后重试；提供方当前没有独立限流器，该码仅兼容后续契约 |
|
||
| INTERNAL_ERROR（500） / INVALID_RESPONSE | 带 requestId 联系维护者；非法页码、跨店记录、缺失 ID、非在售记录或超过分页上限不会作为完整同步 |
|
||
| LOCAL_SYNC_FAILED | 检查 SQLite 文件、目录权限与磁盘；商品和诊断事务回滚，原数据保留 |
|
||
| REQUEST_CANCELLED | 查询已取消，原数据保留 |
|
||
|
||
客户端单请求超时 150 秒；提供方上游 context 预算 120 秒、单次 HTTP 默认 30 秒。客户端不自动重试普通错误，也不自动回退直连。HTTP 重定向被拒绝，填写最终服务地址，避免把 X-API-Key 转发至其他主机。
|
||
|
||
本页面向接手维护的初级程序员。目标是快速定位问题归属，并说明什么情况下必须停下来找人。
|
||
|
||
## 排查顺序
|
||
|
||
出问题时按下面的顺序走，不要跳步，也不要一次改多个地方。
|
||
|
||
### 1. 先确认问题属于哪一层
|
||
|
||
| 现象 | 大概率归属 |
|
||
|---|---|
|
||
| 界面按钮点了没反应、表格不刷新 | 前端或 Go 侧事件推送 |
|
||
| 提示未登录、要求重新登录 | 淘宝登录态或货憨憨认证 |
|
||
| 搜不到同款商品 | 淘宝以图搜链路 |
|
||
| 搜到商品但没有视频 | 商品详情视频提取 |
|
||
| 视频下载失败或文件损坏 | 下载与 ffprobe 校验 |
|
||
| 上传后 Shopee 看不到视频 | 货憨憨上传链路或 Shopee 同步延迟 |
|
||
| 文档命令报错 | DevHarness 工具，见下方 |
|
||
|
||
### 2. 检查文档与工具类问题
|
||
|
||
| 现象 | 原因 | 处理 |
|
||
|---|---|---|
|
||
| `check --strict` 报缺少必需文件 | 文件被删或改名 | 从 Wiki 重新导出，不要手写镜像 |
|
||
| `check --strict` 报缺少章节 | Wiki 页面被改掉了固定标题 | 在 Wiki 恢复标题后重新同步 |
|
||
| 报 `wiki_revision 无效` | 镜像未同步或被手工编辑过 | 运行 `python dev_scripts/harness.py sync` |
|
||
| 同步中止并提示镜像有未提交改动 | 有人直接改了 `docs/` | 先确认改动来源，不要覆盖，处理完再同步 |
|
||
| 报缺少 Wiki 镜像 | `wiki-docs.json` 映射与实际文件不一致 | 先在工单确认映射变化，不自动传播删除或重命名 |
|
||
|
||
`docs/` 只能由同步工具生成。任何时候都不要先改本地镜像再反向覆盖 Wiki。
|
||
|
||
### 3. 检查专属 Chrome（计划，Go 实现后适用）
|
||
|
||
1. 状态文件中的 PID 是否还存在。
|
||
2. 该进程的命令行是否包含本程序的专属 `--user-data-dir`。
|
||
3. `http://127.0.0.1:<端口>/json/version` 是否可访问。
|
||
4. `http://127.0.0.1:<端口>/json/list` 是否存在 `type` 为 `page` 的目标。
|
||
|
||
四项任一不通过，就关闭专属 Chrome 后重新启动。不要在同一个 Profile 上再启动第二个实例。
|
||
|
||
### 4. 检查淘宝登录
|
||
|
||
先看程序返回的结构化结果，而不是猜：
|
||
|
||
- 缺失了哪些 Cookie 名称；
|
||
- 页面标题与最终地址；
|
||
- 命中了哪个阻断词。
|
||
|
||
命中「安全验证」或「验证码」时，由使用者在专属 Chrome 中手动完成验证，再点「我已完成登录」。程序不代替使用者完成验证。
|
||
|
||
### 5. 检查以图搜
|
||
|
||
按顺序看：HTTP 状态码 → 业务返回码 → 商品数量。
|
||
|
||
- 状态码非 200：网络或接口地址问题。
|
||
- 状态码 200 但业务返回码不含成功标记：检查固定错误分类；token/session 失效立即停批，不自动重签重试，用户手动处理后新启动。其他错误不输出完整返回正文。
|
||
- 成功但商品数为 0：多为主图不清晰或商品过于小众，建议更换主图，不是程序缺陷。
|
||
|
||
### 6. 检查下载
|
||
|
||
- 临时文件存在但 ffprobe 校验失败：视为下载失败，重试；连续失败记录视频地址后跳过。
|
||
- 目标文件已存在且非空：属于正常跳过，不是错误。
|
||
|
||
### 7. 检查上传
|
||
|
||
上传经 erpgo 视频接口：HTTP 202 仅表示已受理，待处理或 unknown 时保留 SQLite 操作键；再次操作只查询原键，不自动重传。请记录稳定 errorCode、requestId（不含凭据）并在工单排查。
|
||
|
||
## 必须停止的情况
|
||
|
||
遇到下列任何一种，立即停止修改，记录现象并交给项目负责人或 Agent 分析：
|
||
|
||
- 需要绕过淘宝验证码、滑块或其他安全验证；
|
||
- 需要把 Cookie、token、账号密码写入代码、日志、工单或文档；
|
||
- 需要在同一 Chrome Profile 上并发启动多个实例，或需要复制、打包、上传 Profile 目录；
|
||
- 改动会导致登录失效不再中断整批任务；
|
||
- 需要对真实店铺执行批量写入、覆盖或删除，且没有明确授权；
|
||
- 需要修改 SQLite 已有表结构或执行数据迁移；
|
||
- 出现真实账号、真实客户或生产数据被写入日志或提交的情况；
|
||
- 无法判断改动风险等级。
|
||
|
||
停止不等于失败。把现象、已确认事实和不确定的部分写清楚，比继续试更有价值。
|