45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# 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 迁移脚本以建立最新库结构。
|