AstroResearch/docs/deployment.md

AstroResearch Deployment Guide / 部署指南

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

---

1. Docker 部署（推荐）

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

快速开始

# 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 注入，可独立更新。

构建：

docker build -t astroresearch:latest .

运行：

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（已内置）：

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) 编译在二进制内，单容器零外部二进制依赖。适合对外交付的一键部署包。

前置条件：

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

构建：

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

运行：

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 构建，无 Shell/包管理器，安全性更高但无法 docker exec 进入调试。

---

国内网络加速

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

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：构建前端

cd dashboard
npm install
npm run build

产物位于 dashboard/dist/。

步骤 2：编译后端

cd ..
cargo build --release

产物位于 target/release/astroresearch。

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

cargo build --release --bin health_check

启动

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/，赋予执行权限后启动

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

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 源码 到 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%

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

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

限制 Tokio 线程数：

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）：

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

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

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

源码部署健康检查：

# 只读扫描
./health_check

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

详见 排障指南 §4.2。