<!-- gitea-wiki-mirror:start -->
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
<!-- gitea-wiki-mirror:end -->

# 故障排查

## 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 已有表结构或执行数据迁移；
- 出现真实账号、真实客户或生产数据被写入日志或提交的情况；
- 无法判断改动风险等级。

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