# AstroResearch Deployment Guide / 部署指南

AstroResearch 支持两种部署方式：**Docker 容器化部署**（推荐，零依赖）和**传统源码编译部署**。

---

## 1. Docker 部署（推荐）

Docker 部署无需安装 Rust/Node.js 工具链，一键启动。提供两种镜像模式。

### 快速开始

```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API Key

# 2. 启动 (Mode A — 推荐日常使用)
docker compose up -d

# 3. 访问
open http://localhost:8000
```

### 两种镜像模式对比

|                       | Mode A (`Dockerfile`) | Mode B (`Dockerfile.modeB`)                    |
| --------------------- | ----------------------- | ------------------------------------------------ |
| **镜像大小**    | ~23 MB                  | ~87 MB                                           |
| **基础镜像**    | `alpine:3.21`         | `distroless/cc-debian12:nonroot`               |
| **libc**        | musl (静态链接)         | glibc (动态链接)                                 |
| **二进制体积**  | ~12 MB                  | ~59 MB                                           |
| **二进制包含**  | Rust + C 依赖           | Rust + C + V8 + BoringSSL                        |
| **运行时依赖**  | 无 (静态链接)           | `libc` + `libstdc++` + `libgcc_s` (已内置) |
| **空闲内存**    | ~8.6 MiB                | ~8.7 MiB                                         |
| **Obscura**     | 外部`bin/` bind mount | 编译在二进制内                                   |
| **容器 Shell**  | 有 (`/bin/sh`)        | 无 (distroless)                                  |
| **Healthcheck** | `wget` TCP probe      | 编排层替代                                       |

---

### Mode A：Alpine 外部 Obscura（推荐日常使用）

镜像最小（23 MB），Obscura 作为外部二进制通过 bind mount 注入，可独立更新。

**构建：**

```bash
docker build -t astroresearch:latest .
```

**运行：**

```bash
docker run -d --name astro -p 8000:8000 --env-file .env \
  -v ./library:/app/library \
  -v ./logs:/app/logs \
  -v ./skills:/app/skills:ro \
  -v ./bin:/app/bin:ro \
  astroresearch:latest
```

> `bin/` 目录需包含编译好的 Obscura 二进制文件（`obscura` 和 `obscura-worker`）。

**docker-compose.yml（已内置）：**

```yaml
services:
  astroresearch:
    build:
      context: .
    image: astroresearch:latest
    container_name: astroresearch
    restart: unless-stopped
    ports:
      - “${PORT:-8000}:8000”
    env_file:
      - .env
    environment:
      - LOG_FORMAT=json
      - LOG_OUTPUTS=stdout
    volumes:
      - ./library:/app/library
      - ./logs:/app/logs
      - ./skills:/app/skills:ro
      - ./bin:/app/bin:ro
```

---

### Mode B：Distroless 进程内 Obscura（全功能单体）

Obscura (V8 + BoringSSL) 编译在二进制内，单容器零外部二进制依赖。适合对外交付的一键部署包。

**前置条件：**

```bash
mkdir -p libs
git clone https://github.com/h4ckf0r0day/obscura libs/obscura
```

**构建：**

```bash
docker build -f Dockerfile.modeB -t astroresearch-all:latest .
```

**运行：**

```bash
docker run -d --name astro -p 8000:8000 --env-file .env \
  -v ./library:/app/library \
  -v ./logs:/app/logs \
  -v ./skills:/app/skills:ro \
  astroresearch-all:latest
```

> Mode B 基于 [Distroless](https://github.com/GoogleContainerTools/distroless) 构建，无 Shell/包管理器，安全性更高但无法 `docker exec` 进入调试。

---

### 国内网络加速

默认启用镜像加速（`USE_MIRRORS=1`），海外构建可通过 build-arg 禁用：

```bash
docker build --build-arg USE_MIRRORS=0 -t astroresearch:latest .
```

**加速源：**

| 工具       | 镜像                       |
| ---------- | -------------------------- |
| npm        | `registry.npmmirror.com` |
| Alpine apk | `mirrors.aliyun.com`     |
| Debian apt | `mirrors.ustc.edu.cn`    |

---

### 持久化数据卷

| 容器路径         | 说明                                      | 推荐权限       |
| ---------------- | ----------------------------------------- | -------------- |
| `/app/library` | SQLite 数据库 + PDF/HTML 全文             | 读写           |
| `/app/logs`    | 应用日志（仅`LOG_OUTPUTS=file` 时写入） | 读写           |
| `/app/skills`  | Agent 技能文件 (SKILL.md)                 | 只读 (`:ro`) |
| `/app/bin`     | Obscura 外部二进制（仅 Mode A）           | 只读 (`:ro`) |

> **注意**：bind mount 目录的宿主权限必须允许容器内用户（uid 65532）写入。如遇 `Permission denied`，在宿主执行 `chown -R 65532 ./library ./logs`。

---

## 2. 传统源码编译部署

### 系统要求

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

### 构建步骤

**步骤 1：构建前端**

```bash
cd dashboard
npm install
npm run build
```

产物位于 `dashboard/dist/`。

**步骤 2：编译后端**

```bash
cd ..
cargo build --release
```

产物位于 `target/release/astroresearch`。

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

```bash
cargo build --release --bin health_check
```

### 启动

```bash
cp .env.example .env   # 编辑填入 API Key
./target/release/astroresearch
# 监听 http://localhost:8000
```

---

## 3. Obscura 两种部署模式

系统集成 `Obscura` 无头浏览器框架，用于绕过 WAF/Cloudflare 反爬。支持两种模式：

### 模式 A：外部命令行 (默认)

Obscura 作为独立二进制运行，与主进程隔离。适合常规生产环境。

| 部署方式         | 步骤                                                  |
| ---------------- | ----------------------------------------------------- |
| **Docker** | `docker compose up -d`（自动 bind mount `./bin`） |
| **源码**   | 下载 obscura 到`bin/`，赋予执行权限后启动           |

二进制安装（源码部署时）：

```bash
mkdir -p bin/
# 下载 obscura 和 obscura-worker 到 bin/，赋予执行权限
chmod +x bin/obscura bin/obscura-worker
```

### 模式 B：进程内集成

Obscura (V8 + BoringSSL) 编译进二进制，单文件零外部依赖。

| 部署方式         | 构建命令                                                           |
| ---------------- | ------------------------------------------------------------------ |
| **Docker** | `docker build -f Dockerfile.modeB -t astroresearch-all:latest .` |
| **源码**   | `cargo build --release --features obscura-inprocess`             |

> 源码编译 Mode B 需先克隆 [Obscura 源码](https://github.com/h4ckf0r0day/obscura) 到 `libs/obscura/`。同时需要 `binutils`（`nm` + `objcopy`）和 `libclang-dev` 作为构建依赖。

---

## 4. 极致内存与体积优化

对于低配服务器（如 1核512M），系统提供 `release-min` 编译配置。

> `release-min` 与 Mode B 可共同启用，但效果有限——V8/BoringSSL 静态库占用的 ~50MB 无法被 LTO 消除。追求极致轻量建议用 **Mode A + release-min** 组合。

**优化指标 (Mode A, release-min)：**

| 指标            | release | release-min | 降幅 |
| --------------- | ------- | ----------- | ---- |
| 二进制大小      | 17.0 MB | 8.3 MB      | 51%  |
| 启动 RSS        | 34.8 MB | 32.9 MB     | 5%   |
| 虚拟内存 (VSZ)  | 1.27 GB | 302 MB      | 76%  |
| 数据段 (VmData) | 60.1 MB | 26.5 MB     | 55%  |

```bash
# 源码编译
cargo build --profile release-min

# Docker（已默认使用 release-min）
docker build -t astroresearch:latest .
```

**限制 Tokio 线程数：**

```bash
PORT=8000 TOKIO_WORKER_THREADS=1 ./astroresearch
```

---

## 5. 环境变量

| 变量名                      | 必需 | 默认值                                      | 说明                             |
| :-------------------------- | :--- | :------------------------------------------ | :------------------------------- |
| `DATABASE_URL`            | 否   | `sqlite:///app/library/astro_research.db` | SQLite 连接 URL                  |
| `ADS_API_KEY`             | 是   | -                                           | NASA ADS API Token               |
| `LLM_API_KEY`             | 是   | -                                           | LLM API Key                      |
| `LLM_API_BASE`            | 否   | `https://api.openai.com/v1`               | LLM API 地址                     |
| `LLM_MODEL`               | 否   | `gpt-4o-mini`                             | 对话模型                         |
| `EMBEDDING_API_KEY`       | 否   | 同`LLM_API_KEY`                           | Embedding API Key                |
| `EMBEDDING_API_BASE`      | 否   | 同`LLM_API_BASE`                          | Embedding API 地址               |
| `EMBEDDING_MODEL`         | 否   | `text-embedding-3-small`                  | Embedding 模型                   |
| `LIBRARY_DIR`             | 否   | `/app/library`                            | 文献馆藏根目录                   |
| `SKILLS_DIR`              | 否   | `/app/skills`                             | Agent 技能目录                   |
| `LOG_DIR`                 | 否   | `/app/logs`                               | 日志目录                         |
| `LOG_FORMAT`              | 否   | `json`                                    | 日志格式 (`plain` / `json`)  |
| `LOG_OUTPUTS`             | 否   | `stdout`                                  | 日志输出 (`stdout` / `file`) |
| `PORT`                    | 否   | `8000`                                    | 监听端口                         |
| `AGENT_MAX_STEPS`         | 否   | `8`                                       | Agent 最大步数                   |
| `AGENT_TOOL_TIMEOUT_SECS` | 否   | `120`                                     | 工具超时 (秒)                    |
| `QINIU_AK` / `QINIU_SK` | 否   | -                                           | 七牛云存储凭证                   |
| `MINERU_API_URL`          | 否   | -                                           | MinerU PDF 解析 API              |

---

## 6. 健康检查与维护

**Docker 健康检查（Mode A）：**

```bash
docker ps --filter “health=healthy” --filter “name=astroresearch”
```

Mode B (distroless) 无内置 healthcheck，可在编排层配置：

```yaml
# docker-compose 或 k8s
healthcheck:
  test: [“CMD”, “curl”, “-f”, “http://localhost:8000/”]
```

**源码部署健康检查：**

```bash
# 只读扫描
./health_check

# 自动修复
./health_check -- --fix
```

详见 [排障指南 §4.2](troubleshooting.md#42-馆藏文献健康度检查工具-health_check)。