Asfmq 8cc2b74abc feat: 手动上传绕防爬、下载错误诊断与健康检查工具；模块化重构 API 与批量同步

后端：
  - 将 handlers.rs (1338行) 拆分为 helpers/papers/notes/sync 四模块
  - 将 batch_sync.rs 拆分为 batch/{mod,meta,asset} 三模块
  - 新增 POST /api/upload 多部件文件上传接口
  - 新增 POST /api/no_resource 标记文献"无全文资源"
  - 新增 GET/POST /api/active_bibcode 追踪活跃文献
  - StandardPaper 结构体扩展 pdf_error / html_error 错误诊断字段
  - download.rs 记录下载失败详情至数据库
  - 新增 health_check 二进制工具，支持只读扫描与 --fix 自动修复
  - 移除 scratch/ 目录、recovered_handlers.rs 及调试日志

  前端：
  - 新建 CustomSelect 可复用组件，替换全部原生 select
  - LibraryPanel：同步按钮反馈动画、下载失败/无资源状态筛选与计数、
    文献类型筛选、状态优先排序、搜索一键清空
  - 详情弹窗：错误诊断展示、手动 PDF/HTML 上传区、无资源标记/恢复
  - SearchPanel：扩展文献类型徽章、下载失败状态提示
  - SyncPanel：同步启动乐观 UI 更新、日志容器内自动滚动
  - Tab 状态 localStorage 持久化、弹窗 z-index 修复

2026-06-11 22:56:36 +08:00

3.1 KiB

Raw Blame History

AstroResearch Deployment Guide / 部署指南

AstroResearch 的后端服务是由 Rust 编译出的单执行文件，它内置托管了前端 React 的静态构建资源，因此生产部署十分简单。

1. 系统要求与环境依赖 (Requirements)

操作系统：Linux / macOS / Windows
运行环境：
- Node.js (v18+) 用以构建前端 React 资源
- Rust (1.75+) 用以编译后端 Axum 进程
- SQLite (自动内置，无需单独部署)

2. 生产构建步骤 (Production Build Steps)

步骤 1：构建 React 前端静态资源

进入 dashboard 文件夹，安装依赖并执行编译命令。编译产物会自动输出在 dashboard/dist 目录下：

cd dashboard
npm install
npm run build

步骤 2：编译 Rust 后端二进制文件

返回项目根目录，通过 Cargo 构建 Release 版本的执行文件。编译后的程序会内置链接 dashboard/dist 下的全部静态资源：

cd ..
cargo build --release

编译产物位于 target/release/astroresearch。

步骤 3（可选）：编译健康检查工具

如需在目标服务器上运行馆藏健康度诊断与修复：

cargo build --release --bin health_check

编译产物位于 target/release/health_check。

3. 服务部署与启动 (Running in Production)

将编译出来的 target/release/astroresearch 二进制文件部署到目标服务器。
在二进制文件同一目录下，创建并填写 .env 环境变量配置文件（可从根目录的 .env.example 复制模板）。
确保本地相对路径下拥有天文对照词典文件 dictionary.txt。
运行后端服务：
```
./astroresearch
```
进程将默认在后台启动并监听 http://localhost:8000 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。

4. 环境变量配置 (Environment Variables)

变量名	必需	默认值	说明
`DATABASE_URL`	否	`sqlite://library/astro_research.db`	SQLite 数据库连接 URL
`ADS_API_KEY`	是	-	NASA ADS API 访问 Token
`LLM_API_KEY`	是	-	大语言模型 API Key
`LLM_API_BASE`	否	`https://api.openai.com/v1`	大语言模型 API 基础地址
`LLM_MODEL`	否	`gpt-4o-mini`	翻译大模型名称
`QINIU_AK`	否	-	七牛云 Access Key
`QINIU_SK`	否	-	七牛云 Secret Key
`QINIU_BUCKET`	否	-	七牛云存储空间名
`QINIU_DOMAIN`	否	-	七牛云外链 CDN 域名
`MINERU_API_URL`	否	-	MinerU PDF 解析远程 API 地址
`MINERU_API_KEY`	否	-	MinerU API Token
`LIBRARY_DIR`	否	`./library`	本地文献馆藏根目录
`PORT`	否	`8000`	后端服务监听端口

5. 健康检查与维护 (Health Check)

部署后可定期运行健康检查工具排查馆藏一致性问题：

# 只读扫描（不修改任何数据）
./health_check

# 自动修复（清理损坏文件、重置无效路径）
./health_check -- --fix

详见排障指南 §4.2。

3.1 KiB Raw Blame History Unescape Escape