1

Troubleshooting

ila edited this page 2026-09-02 11:56:43 +08:00

Table of Contents

• 故障排查
• 排查顺序
• 1. 先确认问题属于哪一层
• 2. 检查文档与工具类问题
• 3. 检查专属 Chrome（计划，Go 实现后适用）
• 4. 检查淘宝登录
• 5. 检查以图搜
• 6. 检查下载
• 7. 检查上传
• 必须停止的情况

故障排查

本页面向接手维护的初级程序员。目标是快速定位问题归属，并说明什么情况下必须停下来找人。

排查顺序

出问题时按下面的顺序走，不要跳步，也不要一次改多个地方。

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

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