AstroResearch/docs/troubleshooting.md

AstroResearch Troubleshooting / 常见问题与排障指南

在使用 AstroResearch 过程中可能遇到的问题及排障步骤如下：

---

1. 文献下载相关问题 (Download Issues)

1.1 下载任务遇到 "检测到 Cloudflare / 人机验证页面"

• 原因：部分出版商对频繁的自动化下载请求实施了高强度的 IP 拦截与 CF 校验。
• 解决方法：
  1. 系统目前已经实现每两次请求间随机延迟 maybe_delay() (500ms~2000ms)，以防行为过于机械化。
  2. 若拦截频繁，可以尝试在本地配置代理；或者检查 .env 中的 LIBRARY_DIR 路径是否正确。
  3. 对于 ADS Link Gateway 路由，若跳转至 validate.perfdrive.com，下载器内置了解码 ssc 提取直链的策略，该过程自动进行，如果由于其加密机制变更导致提取失效，系统控制台会输出 warn 日志。

1.2 官方 HTML (arxiv.org/html) 下载返回 404

• 原因：arXiv 官方 HTML 正文服务仅在 2023年12月 之后提交的论文中默认提供。对于老文献，直接请求官方 HTML 会返回 404。
• 解决机制：AstroResearch 的 download_arxiv_html_with_fallback 会在官方 HTML 请求失败时，自动无缝降级回退到 ar5iv.labs.arxiv.org 服务进行拉取。

---

2. 文献解析与翻译问题 (Parse & Translation Issues)

2.1 翻译请求返回空或报错 "LLM API KEY Missing"

• 原因：根目录下没有配置正确的 .env 文件，或者 LLM 提供的 Endpoint/Model 有误。
• 排查步骤：
  1. 确认项目根目录下存在 .env 且拥有 LLM_API_KEY 及 LLM_API_BASE 配置。
  2. 使用终端运行 cargo run，检查启动日志中是否有关于读取环境配置的警告信息。

2.2 PDF 解析缺少图表或公式损坏

• 原因：PDF 格式本身不支持结构化语义。直接提取文本会丢失公式和图表。
• 解决机制：
  1. 如果文献有 HTML/ar5iv 格式，系统会自动优先基于 HTML 解析，保留完美的 LaTeX 公式。
  2. 若该文献只有 PDF 格式，系统自动降级调用本地或远程的 MinerU PDF 图文大模型解析。请确保本地 MinerU 解析服务已按照 API 格式运行并在 .env 中正确填入 MINERU_API_URL。

---

3. 数据库与运行环境问题 (Runtime & DB Issues)

3.1 启动提示 "Database Migration Failed"

• 原因：本地 SQLite 数据库文件 astro_research.db 出现并发锁死或版本 schema 冲突。
• 解决方法：
  1. 备份并临时删除根目录下的 astro_research.db 数据库文件。
  2. 重新启动服务：cargo run，系统将重新执行 migrations/ 下的全部 SQL 迁移脚本以建立最新库结构。