feat: 集成 Obscura 进程内无头浏览器、极致编译瘦身 profile 与词典内存优化

- 下载器 Obscura 后备通道拆分为条件编译双路径:
    进程内模式 (obscura-inprocess feature) 通过 spawn_blocking + 单线程
    runtime 驱动 V8 直接抓取;默认外部命令行模式通过 bin/obscura 子进程调用
  - Cargo.toml 新增 obscura-browser/obscura-net 可选依赖与 release-min profile
    (LTO + strip + opt-level="s",二进制 17→8.3 MB,VSZ 1.27G→302M)
  - 词典加载后 shrink_to_fit() 释放预留容量,降低常驻内存
  - README 与 deployment.md 扩写 Obscura 双模式部署及低配服务器优化指南
  - 新增 Obscura mock 集成测试,补齐测试 fixture 字段
This commit is contained in:
fmq
2026-06-12 11:15:29 +08:00
parent 8cc2b74abc
commit 2a5b1c0c91
8 changed files with 1283 additions and 29 deletions
+87 -4
View File
@@ -50,14 +50,97 @@ cargo build --release --bin health_check
```bash
./astroresearch
```
5. 进程将默认在后台启动并监听 `http://localhost:8000` 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。
5. 进程将默认在后台启动并监听 `http://localhost:8000` 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。
---
## 4. 环境变量配置 (Environment Variables)
## 4. Obscura 两种抓取后备部署模式选择 (Obscura Deployment Modes)
系统集成了 `Obscura` 无头浏览器框架来作为遭遇 WAF/Cloudflare 反爬时的自动后备抓取通道。系统支持以下两种编译与部署模式:
### 模式 A:外部命令行模式 (默认,推荐)
该模式将主 Web 服务与 V8 浏览器运行引擎相隔离,最适合常规生产环境。它拥有最快的编译时间,且进程隔离确保无头浏览器内核异常(如 OOM 或 Panic)不会拖垮主服务器。
1. **编译主服务**
```bash
cargo build --release
```
2. **下载/配置外部二进制**
从 GitHub Releases 下载编译好的 `obscura-x86_64-linux.tar.gz` 压缩包,解压后将 `obscura` 和 `obscura-worker` 两个二进制文件放到项目根目录的 `bin/` 目录下:
```bash
mkdir -p bin/
# 放入 bin/obscura 和 bin/obscura-worker,并赋予执行权限
chmod +x bin/obscura bin/obscura-worker
```
3. **运行**
```bash
./target/release/astroresearch
```
当遭遇 WAF 拦截时,主进程将自动通过异步子进程调用 `./bin/obscura` 进行抓取。
### 模式 B:进程内集成模式 (In-Process Feature)
该模式将整个无头浏览器及 V8 运行引擎直接静态链接编译进单个二进制文件中。这免去了在服务器分发和配置外部可执行程序的步骤,提供了“零配置”的部署体验。
> [!WARNING]
> 由于需要静态链接 C++ 编写的 V8 引擎,**首次编译会额外多耗时 1 到 3 分钟**,且最终编译生成的**单体可执行文件体积会膨胀约 80MB**。
1. **启用 Feature 编译**
在构建时指定 `--features obscura-inprocess` 特性标记:
```bash
cargo build --release --features obscura-inprocess
```
2. **运行**
```bash
./target/release/astroresearch
```
主服务运行期间,无需在磁盘中放置任何 `bin/obscura` 二进制。当触发反爬时,系统会在后台的专有阻塞线程池上通过独立包装的单线程 runtime 驱动进程内 V8 浏览器内核直接抓取。
---
## 5. 极致内存与体积优化部署 (Ultra-Low Memory & Size Optimization)
对于运行在低配/低内存服务器(如 1核512M 或 1核1G 实例)的环境,系统内置了可选的编译与运行时优化策略。
> [!NOTE]
> 极致内存与体积优化编译配置(`release-min`)和“进程内集成模式 (In-Process Feature)”在**技术上可以完全兼容并共同启用**,但它们在**优化目标(指标)上是相互抵消(矛盾)的**。
> 如果启用了进程内 V8 特性,C++ 静态链接库本身占用的 80MB+ 空间将无法被剔除,导致无法达成极致轻量化(~8.3MB)的体积指标;且 V8 运行时堆内存也会带来额外的物理内存开销。因此,为追求极致低资源消耗,建议在低配服务器上采用**“模式 A:外部命令行模式”**。
>
> 如果你执意要在**进程内浏览器集成下尽可能对其体积和依赖进行优化**,可以组合使用 `--profile` 与 `--features` 参数进行编译和运行:
> ```bash
> # 编译并打包优化后的进程内单二进制文件:
> cargo build --profile release-min --features obscura-inprocess
>
> # 编译并直接运行:
> cargo run --profile release-min --features obscura-inprocess
> ```
### 优化指标对比:
* **二进制执行文件大小**:由 `17.0 MB` 压缩至 **`8.3 MB`**(缩减约 51%)。
* **启动物理常驻内存 (RSS)**:由 `34.8 MB` 降至 **`32.9 MB`**(得益于词典加载后的容量自动收缩)。
* **虚拟内存 (VSZ)**:由 `1.27 GB` 降至 **`302 MB`**(缩减约 76%)。
* **数据段内存 (VmData)**:由 `60.1 MB` 降至 **`26.5 MB`**(缩减约 55%)。
### 部署优化步骤:
1. **使用优化 Profile 进行编译**
在项目根目录下,使用内置的 `release-min` 编译配置:
```bash
cargo build --profile release-min
```
编译完成后的执行文件位于 `target/release-min/astroresearch`。该配置开启了 LTO(链接时优化)、剥离了调试符号,并在生成时进行了大小优化。
2. **限制运行时异步线程数**
默认情况下,异步运行时 Tokio 会根据系统的 CPU 核心数(例如 16 核)创建对应数量的 Worker 线程,这会带来很多虚拟/物理内存浪费。启动服务时,可通过注入 `TOKIO_WORKER_THREADS=1` 环境变量限制线程池大小:
```bash
PORT=8000 TOKIO_WORKER_THREADS=1 ./astroresearch
```
---
## 6. 环境变量配置 (Environment Variables)
| 变量名 | 必需 | 默认值 | 说明 |
|:---|:---|:---|:---|
| :--- | :--- | :--- | :--- |
| `DATABASE_URL` | 否 | `sqlite://library/astro_research.db` | SQLite 数据库连接 URL |
| `ADS_API_KEY` | 是 | - | NASA ADS API 访问 Token |
| `LLM_API_KEY` | 是 | - | 大语言模型 API Key |
@@ -74,7 +157,7 @@ cargo build --release --bin health_check
---
## 5. 健康检查与维护 (Health Check)
## 7. 健康检查与维护 (Health Check)
部署后可定期运行健康检查工具排查馆藏一致性问题: