cmsp/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Troubleshooting wiki_revision: dcbde6376c9810e59552bddc8c8732c19f94a1fd synchronized_at: 2026-09-28T09:47:40Z

故障排查

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 但业务返回码不含成功标记：多为签名或登录态问题，先重新读取 _m_h5_tk 重签一次。
• 成功但商品数为 0：多为主图不清晰或商品过于小众，建议更换主图，不是程序缺陷。

6. 检查下载

• 临时文件存在但 ffprobe 校验失败：视为下载失败，重试；连续失败记录视频地址后跳过。
• 目标文件已存在且非空：属于正常跳过，不是错误。

7. 检查上传

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

必须停止的情况

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

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

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