Asfmq
2c8d0b8f8b
- LAMOST 新增 DR12/13/14 及子版本（v0/v1.0/v1.1/v2.0）维度，Internal 发布标记需登录认证并前端灰显，release×subtype 交叉约束下沉至 capabilities 统一声明 - ObservationFetcher trait 扩展版本/认证/交叉约束能力声明，version 参数贯穿 client→service→API→Agent tool→前端全链路 - 安全：observation cache SQL 全参数绑定 + LIKE 转义、cone_cache_hash 加长度前缀防碰撞、DESI survey/program 白名单防穿越 - 异步化：persist/cached_files_total_size/maybe_persist_tool_result迁移到 tokio::fs；cancelled_runs 与 session_permission_checkers改用 DashMap；auth 读锁优先 + 60s 节流 - Gaia 去 native-tls 改禁用连接池规避 UnexpectedEof，reqwest 移除 native-tls feature - 重构：Source/ProductType from_str 集中解析、download 模块拆分为 try_download_pdf/html、AgentRuntime::init 抽取共享逻辑 - 部署：新增 deploy.sh 一键打包推送脚本、catch-panic 启用
317 lines
11 KiB
Markdown
317 lines
11 KiB
Markdown
# 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)。
|