10 KiB
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Troubleshooting wiki_revision: 3d7d777fd2dc91801cdf56499c0314f303feeb1e synchronized_at: 2026-09-30T03:11:24Z
故障排查
视频上传经 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: []，排除上游回读问题后再手动重试。
全店铺同步与部分成功（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 实现后适用）
- 状态文件中的 PID 是否还存在。
- 该进程的命令行是否包含本程序的专属
--user-data-dir。 http://127.0.0.1:<端口>/json/version是否可访问。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 已有表结构或执行数据迁移；
- 出现真实账号、真实客户或生产数据被写入日志或提交的情况；
- 无法判断改动风险等级。
停止不等于失败。把现象、已确认事实和不确定的部分写清楚，比继续试更有价值。