Doclib Error Handling Gap Review¶
本文总结当前 doclib 在报错、错误码、错误处理和重试方面的代码现状、已处理事项和剩余问题。目标是给后续实现任务提供可落地的边界,而不是替代正式错误码规格。
范围:
mineru/errors.pymineru/doclib/app.pymineru/doclib/server.pymineru/doclib/client.pymineru/doclib/services/*mineru/doclib/background/*
不纳入范围:
mineru/doclib/OLD/*- mineru.net 远端 API 的完整错误规格
- parser/tool 层内部 backend 错误细分
当前已处理¶
E-001 全局错误码注册¶
状态: 已处理。
当前 mineru/errors.py 已补充 doclib 当前会持久化或抛出的主要错误码,包括:
stat_failedingest_failedmetadata_failedscan_failedparse_emptyparse_json_write_failedno_accessible_filequality_tier_unavailablescan_not_foundwatch_not_foundrule_not_found
同时新增 registered_error_codes(),用于测试和后续 telemetry / 文档生成复用。
剩余风险:
- 当前测试中的 doclib 错误码集合仍是手写列表,不是从代码或 schema 自动生成。后续新增错误码时,仍可能忘记注册。
建议:
- P1 增加静态检查或更集中的错误码定义模块,让写入 DB 的错误码只能来自统一常量。
E-002 HTTP 状态码映射统一¶
状态: 已处理。
当前 mineru/errors.py 提供 http_status_for(code, error_type),doclib/app.py 和 doclib/server.py 复用同一套 HTTP 状态码规则。
当前关键规则:
| code / type | HTTP |
|---|---|
invalid_request_error |
400 |
| not found 类 code | 404 |
authentication_error |
401 |
permission_error |
403 |
rate_limit_error |
429 |
engine_error |
503 |
api_error |
500 |
已修正:
- watch 缺失使用
watch_not_found。 - rule 缺失使用
rule_not_found。 - scan 缺失使用
scan_not_found。
剩余风险:
internal_error仍会把原始异常 message 暴露给客户端。- SDK client 抛出的
MineruError不保留 HTTP status code。
当前仍存在的问题¶
E-003 ingest 失败不自动重试,但缺少显式恢复入口¶
状态: 部分解决,仍需设计。
当前代码语义:
- ingest worker 只领取:
sha256 IS NULLstatus = activeerror_code IS NULL- 任何已有
files.error_code的 file 都不会被 ingest worker 自动重试。 file_permission_denied、stat_failed、ingest_failed都会阻止自动领取。
这是有意设计: 默认不重试,只有明确有重试意义的错误才重试。
剩余问题:
- P0 没有显式 retry ingest 入口。
ingest_failed且文件mtime/size未变化时,普通 scan/refresh 会保留错误态。- 用户或 Agent 无法表达“我知道文件没变,但现在想重新尝试 ingest”。
建议:
retry_ingest_failures()不进入 P0,放到 P1 再讨论。- 如果实现,应作为显式命令或 API,而不是 worker 自动重试。
- 推荐命令方向:
mineru scan <path>仍只做文件状态刷新。- 另设显式 retry 行为,例如
mineru retry ingest <path>或mineru cleanup/retry子命令,避免 scan 语义膨胀。
完成边界:
- 能按 path / watch / all 选择失败 file。
- 只清除允许重试的
files.error_code。 - 不重试
file_permission_denied/stat_failed,除非先 refresh 后状态已恢复。 - 输出被重试、被跳过、仍失败的数量。
E-004 ingest 错误缺少 retryability 元数据¶
状态: 未处理。
当前 DB 只有:
files.error_codefiles.error_msg
没有:
retryableerror_stageerror_atretry_countnext_retry_at
在当前“默认不自动重试”的策略下,retry_count 和 next_retry_at 可以暂缓。但 error_stage 和 error_at 对状态解释有价值。
建议:
- P0 可暂不加字段。
- P1 如果 telemetry / status 需要更好的错误解释,再增加:
files.error_atparses.error_atscans.error_at
E-005 parse worker 外层兜底会丢失阶段信息¶
状态: 未处理。
当前 ParseService.process_doc() 已经能写入一些精确错误:
no_accessible_fileparse_emptyparse_json_write_failed- parse-server 相关错误
但如果异常发生在以下阶段:
- FTS 更新
- docs metadata 更新
- 其他未被局部捕获的持久化阶段
最终可能被 parse_worker.py 外层兜底统一写成:
parse_failed
问题:
- 失去阶段信息。
- 难以判断错误是否来自解析引擎、索引、DB 或输出 JSON。
建议:
- 将 parse 完成后的持久化阶段拆出明确错误码:
parse_fts_update_failedparse_doc_metadata_update_failedparse_persist_failed- 这些错误应进入
mineru/errors.py注册。
完成边界:
- 每个 parse 后处理阶段失败时写不同 code。
- 不把非解析引擎错误泛化成
parse_failed。 - 测试覆盖 FTS 和 docs metadata 更新失败。
E-006 parse failed 没有显式 retry 语义¶
状态: 未处理。
当前行为:
pending/parsing任务 lock 超时后可以重新被 worker 领取。failed是终态。- 后续同一文件再次 parse 时,可能创建新的 batch。
问题:
- 没有明确的
retry parseAPI 或 CLI。 - 不同错误的可重试性不同,但当前都只是
status=failed。
建议:
- 先不做自动 retry。
- 后续如果加显式 retry,应区分:
- 可重试:
engine_unavailable、parse_server_unavailable、parse_json_write_failed - 不应直接重试:
tier_mismatch、no_accessible_file - 需要人工判断:
parse_failed
完成边界:
- retry 不覆盖旧 done batch。
- retry 创建新的 parse batch 或重置指定 failed batch,需要二选一并文档化。
- retry 结果必须按 parse id 查询,不能被旧 done 结果掩盖。
E-007 服务启动时 parsing 任务被置 failed 但缺少错误码¶
状态: 未处理。
当前 doclib app startup 会将遗留的 parsing parse row 改成 failed,并清理 lock。
问题:
- 没有写入明确
error_code/error_msg。 - 用户只能看到 failed,不知道是服务重启中断、worker 崩溃,还是解析本身失败。
建议:
- 使用明确错误码,例如:
parse_interrupted- 注册到
mineru/errors.py。 - message 可为
Parse interrupted by server restart.
完成边界:
- startup 恢复逻辑写入
error_code=parse_interrupted。 - 测试覆盖 app startup recovery。
E-008 compaction 仍有 DB / JSON 不一致风险¶
状态: 基本解决,残留一项。
已落地(mineru/doclib/background/compaction.py):
- JSON-first / DB-after:
_write_compacted_json_files先完整写入临时 JSON(*.tmp-*),全部成功后用os.replace原子提升为最终 JSON,之后才更新 DB parse rows。 - 任一源 JSON 损坏时放弃本轮压缩(
_load_batch_payloads返回None),旧 done rows 与旧 JSON 保持可读。 - 旧 JSON 只在新缓存和数据库均就绪后删除(
_delete_obsolete_json_files)。 - 异常不吞: 写 JSON 失败清理临时文件并放弃本轮,不破坏旧状态。
残留风险:
- DB 侧
DELETEdone / superseded rows 与INSERTcompacted rows 仍是多条独立db.execute,未包在单个 transaction 中(compaction 中 "atomic replace" 段)。进程在该段中途退出时,DB 可能出现 rows 部分替换的状态。
后续建议:
- 将 compaction 的 DB
DELETE+INSERT包进单个 transaction。
E-009 watch loop 异常不可观测¶
状态: 解决一半。
已落地(mineru/doclib/background/watch.py):
- initial scan fallback 异常和 watch task 异常退出都会
logger.error并带exc_info记录 watch_id、path 和异常,不再静默pass。
残留:
watches表仍没有错误字段,scan task 记录也未复用为 watch 失败摘要。- 用户无法从
mineru server status或 API 知道某个 watch 已经异常退出,watch 可能失效但没有结构化错误。
建议:
- 为
watches增加错误字段,或复用 scan task 记录 watch scan 失败: error_codeerror_msglast_error_at- watch task 异常退出时应更新 watch 状态或创建 scan failed 记录。
E-010 removable device 恢复后没有自动 rescan¶
状态: 已解决。
当前 mineru/doclib/background/device_monitor.py 在 removable watch root 恢复可访问时:
- 把 watch status 改回 active。
- 把 unreachable files 改回 active。
- 随即通过
scan_svc.create_scan(..., kind=watch, source=system, watch_id=...)创建一次 watch scan,由该 scan 重新发现 deleted / changed / new / stat error。
恢复事件只 enqueue scan,不在同步遍历中扫描所有文件。
E-011 scan failed 没有 retry 策略¶
状态: 设计上暂可接受,仍需文档明确。
当前行为:
- scan 异常会写:
scans.status=failederror_code=scan_failederror_msg- failed scan 不自动重试。
问题:
- 对 manual scan,这是合理的。
- 对 watch initial scan / internal scan,是否应自动 retry 尚未明确。
建议:
- P0 先保持 manual scan 不自动 retry。
- watch/internal scan 是否 retry,放到 watch 可靠性设计中统一处理。
完成边界:
- 文档明确 scan failed 是否需要用户重新发起。
- 如果 watch scan 自动 retry,需要防止重复创建 scan task。
E-012 internal_error 暴露原始异常文本¶
状态: 未处理。
当前 doclib/app.py 和 doclib/server.py 的 unexpected exception handler 会将 str(exc) 放入 error response。
风险:
- 可能暴露本地路径。
- 可能暴露 SQL 或内部实现细节。
- 未来如果 HTTP API 暴露给外部客户端,不适合作为默认行为。
建议:
- 默认 response 使用通用 message。
- 详细异常只写日志。
- 需要 debug 时通过配置开启详细错误。
完成边界:
internal_error.message默认不包含 traceback、SQL、绝对路径。- 日志仍保留完整异常。
- 测试覆盖 unexpected exception response。
E-013 SDK client 不保留 HTTP 状态码和可操作信息¶
状态: 未处理。
当前 DoclibClient 收到 error envelope 后会抛 MineruError(code, message, param)。
问题:
- 不保留 HTTP status。
- 不保留
retryable。 - 不保留
user_action。 - 未来 CLI 需要输出下一步建议时信息不足。
建议:
- 短期不改异常结构。
- 后续统一错误模型时增加:
status_coderetryableuser_actionrequest_id
完成边界:
- SDK client 能保留 response status code。
- CLI 能根据错误输出稳定建议,而不是解析 message。
E-014 scan_interrupted 写入 DB 但未注册进全局错误码表¶
状态: 未处理。
当前 server startup 恢复逻辑会把上次被中断的 scan 置为 failed,并写入 error_code="scan_interrupted":
mineru/doclib/app.pystartup 段:UPDATE scans SET ... error_code = COALESCE(error_code, 'scan_interrupted') ...mineru/doclib/services/scan_svc.py中同样使用该码。
但 mineru/errors.py 没有注册 scan_interrupted:
- 不在
_ERROR_TYPE_MAP中,无 error type 映射。 - 不在 HTTP 状态映射中。
问题:
- 若该错误码经 API / SDK 返回给调用方,会落到默认分类而不是明确定义的 error type。
- 违反 E-001 建立的"所有稳定错误码统一注册"约定。
建议:
- 在
mineru/errors.py注册scan_interrupted(归入internal_error类,HTTP 500),并同步更新docs/next/errors.md。
当前错误处理原则¶
文件级错误¶
写入位置: files.error_code / files.error_msg
适用范围:
- 文件路径可访问性。
- stat / permission 问题。
- ingest 阶段无法完成的 file 级错误。
当前原则:
deleted/unreachable是文件状态,不是 file error。- permission/stat error 不应标记为 deleted。
- worker 不主动重试已有 file error。
文档级错误¶
写入位置: docs.error_code / docs.error_msg
适用范围:
- 内容身份
sha256级别的问题。 - 当前主要用于 metadata 提取失败。
当前原则:
metadata_failed不阻断入库。- metadata 后续被更高质量 parse 纠正后,可以清除 doc error。
Parse batch 错误¶
写入位置: parses.error_code / parses.error_msg
适用范围:
- 某个
sha256 + tier + page_range批次的问题。 - parse-server 不可用。
- parse 返回空。
- parsed JSON 写入失败。
当前原则:
- failed parse batch 不自动重试。
- 后续 parse 请求可以创建新 batch。
- done batch 只有在对应 parsed JSON 存在时才参与覆盖判断。
Scan task 错误¶
写入位置: scans.error_code / scans.error_msg
适用范围:
- 一次 scan task 的执行失败。
当前原则:
- scan 和 ingest 职责分离。
- scan done 不表示 ingest done。
- scan failed 不自动 retry。
建议优先级¶
| 优先级 | 项目 | 原因 |
|---|---|---|
| P0 | E-007 startup interrupted parse 错误码 | 当前 failed 无原因,不利于 Agent 判断 |
| P0 | E-012 internal_error 信息泄漏 | 错误响应契约应尽早稳定 |
| P1 | E-008 compaction DB rows 替换未包单事务 | JSON-first 已落地,残留 DB 段一致性风险 |
| P1 | E-003 显式 retry ingest 入口 | P0 不做,需要先定 CLI/API 形态 |
| P1 | E-005 parse 后处理阶段错误码 | 提升诊断能力 |
| P1 | E-009 watch 异常可观测 | logger.error 已落地;缺结构化 watch 错误字段 |
| P1 | E-014 scan_interrupted 注册进错误码表 | 已写入 DB 但未进 errors.py |
| P1 | E-013 SDK 错误增强 | 依赖整体错误模型扩展 |
| P2 | E-004 error_at / retry metadata | 可随 telemetry/status 一起做 |
| P2 | E-011 scan retry 策略 | 当前可接受手动重试 |
下一步建议¶
建议先处理 E-014 scan_interrupted 注册进错误码表(改动小、边界清晰),随后处理 E-008 残留的 compaction DB 单事务问题。
原因:
- compaction JSON-first 已经落地,剩余问题是最接近真实数据损坏的一项。
- 它和已经修复的
parse_json_write_failed属于同类问题。 - 修复边界清晰,可以用单元测试验证。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU