cmsp/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Troubleshooting wiki_revision: c91a79baab19786e491b46e8aceb2308a2ea49d5 synchronized_at: 2026-09-29T07:39:14Z

故障排查

图搜成功但商品链接无法使用（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. 检查上传

上传链路的接口契约尚未确认，出现问题时先记录请求与响应摘要（不含凭据），在工单中处理，不要在生产店铺上反复试。

必须停止的情况

遇到下列任何一种，立即停止修改，记录现象并交给项目负责人或 Agent 分析：

• 需要绕过淘宝验证码、滑块或其他安全验证；
• 需要把 Cookie、token、账号密码写入代码、日志、工单或文档；
• 需要在同一 Chrome Profile 上并发启动多个实例，或需要复制、打包、上传 Profile 目录；
• 改动会导致登录失效不再中断整批任务；
• 需要对真实店铺执行批量写入、覆盖或删除，且没有明确授权；
• 需要修改 SQLite 已有表结构或执行数据迁移；
• 出现真实账号、真实客户或生产数据被写入日志或提交的情况；
• 无法判断改动风险等级。

停止不等于失败。把现象、已确认事实和不确定的部分写清楚，比继续试更有价值。