# Galaxy

**Repository Path**: dev_cpg/galaxy

## Basic Information

- **Project Name**: Galaxy
- **Description**: Galaxy银河爬虫计划
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Galaxy Spider Engine 🦆

> 高性能异步爬虫引擎 v3.1.0 — 银河计划

## 📋 项目简介

Galaxy Spider Engine 是基于 Python 3.11+ 的高性能异步爬虫框架，专为大规模数据采集场景设计。
v3.1.0 引入**生产级持久化（pgvector 真实向量库 + Redis 持久化）**：
- **pgvector 向量库**（HNSW 索引 + cosine 检索，替代 v3.0.0 keyword 匹配）
- **Redis 持久化**（Memory / Tenant / Billing，替代 v3.0.0 内存版）
- **opt-in 配置**（默认内存版，100% 向后兼容，通过环境变量启用）
- **优雅降级**（Redis/PG 不可用时自动回退 + structlog warning）
- **0 新增 Python 依赖**（复用 psycopg2 / redis / pgvector 已装包）

v3.0.0 完全智能化（Full Agentic Spider） + Harness Engineering：
- **SpiderAgent 一键生成**（描述 → 可运行 Spider，5 步流程 + 自愈）
- **全自动 SiteAnalyzer**（URL → 站点画像，6 维度检测）
- **运行时 ComplianceAgent**（每请求合规审计，4 项检查）
- **一键 Spider 生成 API**（GraphQL `generateSpider` Mutation）
- **InMemoryKnowledgeBase**（RAG 内存版，pgvector 留待 v3.1）
- **SaaS 多租户**（TenantManager + 配额 + API Key）
- **按量计费**（BillingEngine + UsageRecord）
- **Harness Engineering 7 个专题约束文档**（docs/v3.0.0/，每个 ≤150 行）
- **代码仓库为唯一事实来源**（Single Source of Truth）

v2.9.2 GraphQL API 网关：
- **5 Query**：`spiders` / `spider(name)` / `executions(limit)` / `report(goal)` / `metrics`
- **3 Mutation**：`runAgent(goal)` / `runSpider(platform, keyword, maxItems)` / `cancelExecution(id)`
- **Strawberry-GraphQL**（Type Hints 原生，FastAPI 集成成熟）
- **0 重复**：复用 SPIDER_REGISTRY（v2.7.0）+ Orchestrator（v2.9.0）+ InMemoryMemory（v2.9.0）+ Prometheus Registry（v2.7.0）
- **5 Query**：`spiders` / `spider(name)` / `executions(limit)` / `report(goal)` / `metrics`
- **3 Mutation**：`runAgent(goal)` / `runSpider(platform, keyword, maxItems)` / `cancelExecution(id)`
- **Strawberry-GraphQL**（Type Hints 原生，FastAPI 集成成熟）
- **0 重复**：复用 SPIDER_REGISTRY（v2.7.0）+ Orchestrator（v2.9.0）+ InMemoryMemory（v2.9.0）+ Prometheus Registry（v2.7.0）

v2.9.1 监控告警系统：
- **8 告警规则**：高错误率 / 慢请求 / 低吞吐 / 任务堆积 / 并发饱和 / 高取消率 / 零请求 / DNS 失败
- **3 通知渠道**：Console / Webhook / Email（SMTP）
- **MetricsSnapshot 抽象层**：KISS 适配 prometheus_client，避免侵入 metrics_v2.py
- **复用 v2.7.0 指标**：ERRORS_TOTAL / REQUEST_DURATION / PENDING_TASKS / ADAPTIVE_CONCURRENCY / TASKS_CANCELLED / ITEMS_SCRAPED，0 重复

v2.9.0 多 Agent 协作框架：
- **4 Agent 决策链**：Planner（目标分解）→ Executor（执行）→ Verifier（审计）→ Reporter（报告）
- **Orchestrator 协调器**：Plan→Execute→Verify→Report 主循环
- **ReAct 推理循环**（3 步：Thought → Action → Observation）
- **Memory 系统**（InMemory 内存版 + TTL，决策可追溯）
- **ToolRegistry**：薄包装 SPIDER_REGISTRY，0 重复

v2.8.0 智能数据管线基础：
- **LLM 驱动的字段提取**（OpenAI / Anthropic / Ollama 三后端，5 种策略自动路由）
- **数据质量评分**（5 维度：completeness / uniqueness / validity / consistency / timeliness）
- **SimHash 64-bit 语义去重**（Hamming 距离检测"内容相似但 URL 不同"的重复页面）
- **自动 Schema 映射**（8 种归一化模式 + 7 种 transform：lowercase / to_int / to_float / parse_date 等）
- **公开信息获取 Spider**（RSS / Atom + ~30+ 公开源，**4 大行业**：金融/科技/游戏/互联网，含中文+英文双语源）

## ✨ 核心特性

- 🚀 **异步高性能** — `asyncio` + `aiohttp` 统一连接池 + 域名级并发限流 + **自适应并发**
- 🔁 **智能重试** — tenacity 指数退避 + 抖动，自动重试 TimeoutError/5xx/ClientError
- 🧱 **惰性解析** — `SpiderResponse.text/json/soup/selector` 全部惰性 + 缓存，节省 ~40% 内存
- 💾 **批量写入** — `WriteBuffer` 缓冲 + 双触发（100 条或 1 秒）降低 IO
- 📋 **优先级调度** — `heapq` 本地堆 + Redis Sorted Set 分布式降级 + **Worker Pool 独立部署**
- 🧠 **智能提取（v2.8.0 新增）** — LLM Extractor + Strategy Router + Quality Scorer + SimHash + Auto Schema
- 🤖 **多 Agent 协作（v2.9.0 新增）** — Planner/Executor/Verifier/Reporter + Orchestrator + ReAct 3 步循环 + InMemory Memory
- 📊 **监控告警（v2.9.1 新增）** — 8 告警规则 + Console/Webhook/Email 通知渠道 + MetricsSnapshot 抽象
- 🌐 **GraphQL API 网关（v2.9.2 新增）** — Strawberry + 5 Query + 3 Mutation，复用现有 SPIDER_REGISTRY/Orchestrator/Memory
- 🤖 **完全智能化（v3.0.0 新增）** — SpiderAgent 一键生成 + SiteAnalyzer + ComplianceAgent + generateSpider Mutation + Harness Engineering 工程化
- 💾 **生产级持久化（v3.1.0 新增）** — pgvector 真实向量库 + Redis 持久化（opt-in + 优雅降级）
- 🛡️ **合规边界** — OnlyFans 默认禁用，生产环境启动校验拒绝默认密码
- 🔌 **依赖注入** — Engine 接收 HttpEngine/Storage/ProxyPool，便于单测和 mock
- 📊 **监控指标** — Prometheus 完整时序（DNS/TCP/TLS/TTFB）+ structlog JSON 日志
- ⚙️ **配置热更新** — Redis Pub/Sub 运行时修改配置，无需重启
- 🗄️ **冷热数据分离** — raw_pages（热）+ raw_pages_cold（30 天 TTL 自动清理）
- 🔄 **JS 引擎 V8 + Node 常驻** — PyMiniRacer 优先，Node.js stdin/stdout JSON-RPC 备选
- 📰 **公开信息获取（v2.8.0 新增）** — RSS/Atom + ~30+ 公开源（**金融/科技/游戏/互联网 4 行业**）一键接入

## ✨ 核心特性

- 🚀 **异步高性能** — `asyncio` + `aiohttp` 统一连接池 + 域名级并发限流 + **自适应并发**
- 🔁 **智能重试** — tenacity 指数退避 + 抖动，自动重试 TimeoutError/5xx/ClientError
- 🧱 **惰性解析** — `SpiderResponse.text/json/soup/selector` 全部惰性 + 缓存，节省 ~40% 内存
- 💾 **批量写入** — `WriteBuffer` 缓冲 + 双触发（100 条或 1 秒）降低 IO
- 📋 **优先级调度** — `heapq` 本地堆 + Redis Sorted Set 分布式降级 + **Worker Pool 独立部署**
- 🛡️ **合规边界** — OnlyFans 默认禁用，生产环境启动校验拒绝默认密码
- 🔌 **依赖注入** — Engine 接收 HttpEngine/Storage/ProxyPool，便于单测和 mock
- 📊 **监控指标** — Prometheus 完整时序（DNS/TCP/TLS/TTFB）+ structlog JSON 日志
- ⚙️ **配置热更新** — Redis Pub/Sub 运行时修改配置，无需重启
- 🗄️ **冷热数据分离** — raw_pages（热）+ raw_pages_cold（30 天 TTL 自动清理）
- 🔄 **JS 引擎 V8 + Node 常驻** — PyMiniRacer 优先，Node.js stdin/stdout JSON-RPC 备选

## 🏗️ 架构概览（v2.7.0）

```
┌──────────────────────────────────────────────────────────┐
│                    API / Admin 层                         │
│   FastAPI Gateway (:8080)   Django Admin (:8000)         │
│   - 任务投递到 Redis Queue    - run_spider/check_proxies │
└────────────────────┬─────────────────────────────────────┘
                     │ 任务消息
┌────────────────────▼─────────────────────────────────────┐
│                  消息队列层 (Redis)                       │
│   galaxy:queue:crawl:x       (X/Twitter 任务)            │
│   galaxy:queue:crawl:general (YouTube/小红书/Meta)     │
│   galaxy:queue:crawl:heavy   (OnlyFans/Playwright)     │
│   galaxy:config_reload       (配置热更新 Pub/Sub)        │
└────────────────────┬─────────────────────────────────────┘
                     │ BLPOP 阻塞拉取
        ┌────────────┼────────────┐
        ▼            ▼            ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  Worker-1   │ │  Worker-2   │ │  Worker-N   │
│  SpiderEngine│ │  SpiderEngine│ │  SpiderEngine│
│  (DI注入)    │ │  (DI注入)   │ │  (DI注入)    │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
       │               │               │
       └───────┬───────┴───────┬───────┘
               ▼               ▼
        ┌─────────────┐  ┌─────────────┐
        │  HTTP Engine │  │  Proxy Pool │
        │  - aiohttp   │  │  (加权轮询) │
        │  - HTTP/2    │  └─────────────┘
        │  - tenacity  │
        │  - DomainRate│
        └──────┬──────┘
               │
        ┌──────┴───────┐
        ▼             ▼
   MongoDB         PostgreSQL
   (热+冷 TTL)     (records+data)
```

## 📁 项目结构（v2.7.0）

```
galaxy/
├── galaxy_spider/
│   ├── core/
│   │   ├── base.py              # SpiderRequest/Response（惰性）+ BaseSpider（DI）
│   │   ├── engine.py            # SpiderEngine（DI + 任务取消 checkpoint）
│   │   ├── http_engine.py       # HttpEngine + DomainRateLimiter + tenacity + HTTP/2
│   │   ├── js_engine.py         # V8 优先 + Node 常驻进程 (v2.7.0 重写)
│   │   ├── adaptive_concurrency.py  # v2.7.0 新增：滑动窗口自适应并发
│   │   ├── _node_runner.js      # v2.7.0 新增：Node.js JSON-RPC handler
│   │   └── spiders/
│   │       ├── __init__.py      # SPIDER_REGISTRY
│   │       ├── x.py / youtube.py / xiaohongshu.py / onlyfans.py
│   │       └── youtube/repository.py  # v2.7.0 新增：YouTube 平台专属 Repository
│   ├── scheduler/engine.py      # heapq + Redis Sorted Set + 任务取消 + 超时回收
│   ├── storage/
│   │   ├── mongo.py             # bulk_write + 冷热分离 + 30天 TTL 索引
│   │   ├── postgres.py          # UNNEST 批量 upsert
│   │   └── buffer.py            # WriteBuffer 批量写入缓冲
│   ├── proxy/manager.py         # ProxyPool 加权 + ProxyProvider
│   ├── config/
│   │   ├── settings.py          # OnlyFans 默认禁用 + validate_production_secrets
│   │   └── hotreload.py         # v2.7.0 新增：Redis Pub/Sub 配置热更新
│   ├── worker/runner.py         # v2.7.0 新增：Worker Pool 独立入口
│   └── monitor/
│       ├── metrics.py           # 基础指标
│       └── metrics_v2.py        # v2.7.0 新增：DNS/TCP/TLS/TTFB histogram
├── web/
│   ├── api/gateway.py           # P0 真实集成 SpiderEngine.run()
│   └── crawler/
│       ├── services.py          # v2.7.0 新增：SpiderRunner + ProxyValidator 统一服务层
│       ├── views.py             # start/cancel/validate actions 真实实现
│       ├── admin.py             # validate_proxies + run_tasks bulk actions
│       └── management/commands/
│           ├── run_spider.py    # 真实调用 SpiderEngine
│           └── check_proxies.py # 真实 HTTP 验证
├── tests/
│   ├── unit/                    # 103 个单元测试（全部通过）
│   └── conftest.py
├── docs/
│   ├── wiki/                    # Wiki 9 页面（可上传到 Gitee Wiki）
│   └── CHANGELOG.md
├── config/spider.yaml           # 运行时配置（无密钥）
├── Dockerfile
├── requirements.txt
├── pytest.ini
├── README.md
└── README.en.md
```

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置

```bash
cp config/spider.yaml.example config/spider.yaml
# 编辑 config/spider.yaml 设置数据库连接
# 敏感信息通过环境变量提供：
export MONGODB_PASSWORD="your-secure-password"
export POSTGRESQL_PASSWORD="your-secure-password"
export X_BEARER_TOKEN="your-x-bearer-token"  # X 爬虫需要
```

### 3. 启动服务

```bash
# Django Admin（v2.7.0: run_spider / check_proxies 命令真实可用）
python manage.py migrate
python manage.py runserver 0.0.0.0:8000

# FastAPI Gateway
cd web && uvicorn api.gateway:app --host 0.0.0.0 --port 8080

# Worker Pool (v2.7.0 新增)
# 轻量 Worker
python -m galaxy_spider.worker.runner --platform youtube
# 重资源 Worker（独立 Pod）
python -m galaxy_spider.worker.runner --platform onlyfans
```

### 4. 发起爬取任务

```bash
curl -X POST http://localhost:8080/api/v1/crawl \
  -H "Content-Type: application/json" \
  -d '{"platform": "youtube", "keyword": "AI tools", "max_items": 50}'
```

### 5. 运行时修改配置（v2.7.0）

```bash
# 触发全量重载
redis-cli publish galaxy:config_reload '{"action": "reload"}'

# 单 key 设置
redis-cli publish galaxy:config_reload '{"action": "set", "key": "spider.concurrent_requests", "value": 50}'
```

### 6. 运行测试

```bash
pytest tests/ -v
# 103 passed in ~1.5s
```

## 🔐 合规边界（v2.6.0 重要变更）

| 平台 | 默认状态 | 启用方式 | 说明 |
|------|----------|----------|------|
| X (Twitter) | ✅ 启用 | 直接调用 | 需要 `X_BEARER_TOKEN` 环境变量 |
| YouTube | ✅ 启用 | 配置 `api_key` | Google Data API v3 |
| 小红书 | ✅ 启用 | 直接调用 | 需自备 Cookie |
| **OnlyFans** | ❌ **禁用** | 显式设置 `settings.platform.onlyfans.enabled=True` | **仅在客户授权场景下启用** |
| Meta (Facebook) | ✅ 启用 | 配置 `auth_token` | Graph API |

### 生产环境启动校验

```python
from galaxy_spider.config import get_settings, validate_production_secrets

settings = get_settings()
settings.environment = "production"
errors = validate_production_secrets(settings)
if errors:
    raise RuntimeError(f"Production secrets invalid: {errors}")
```

校验项：
- 数据库密码不能是默认值 `"123456"` 或空
- YouTube API Key 在启用时不能为空
- Proxy API Key 在启用时不能为空

## 📦 依赖

```
# 核心
asyncio, aiohttp>=3.9, structlog>=23.2
# 数据
motor>=3.3, asyncpg>=0.29, redis>=5.0, orjson>=3.9
# 可靠性
tenacity>=8.2  # 重试/退避
# 框架
fastapi>=0.104, django>=4.2
# 测试
pytest>=7.4, pytest-asyncio>=0.21
# 监控
prometheus-client>=0.19
```

完整依赖见 `requirements.txt`。

## 📈 v2.7.0 性能基线

| 指标 | v2.5 | v2.6.0 | v2.7.0 | 累计提升 |
|------|------|--------|--------|----------|
| 单机吞吐 | 1-3k URL/h | 10k+ URL/h | 50k+ URL/h (多 Worker) | **15-50x** |
| 内存峰值 | 随队列线性 | 稳定 | 稳定 + 冷热分离 | -70% |
| 磁盘 IO | 2-3 次写/请求 | 批量后 -90% | + 30 天 TTL 自动清理 | -95% |
| 调度复杂度 | O(p log p) | O(log n) | + 多 Worker 线性扩展 | - |
| 错误率 | 易受 429/503 | tenacity + 限流 | + 自适应并发调节 | -90% |
| 配置变更 | 重启进程 | - | **热更新（无需重启）** | ✅ |

## 🧪 测试覆盖（103 个）

```bash
$ pytest tests/ --no-header
======================= 103 passed in 1.37s ========================
```

覆盖模块：
- `galaxy_spider.core.base` — SpiderRequest slots、惰性解析、fingerprint 算法
- `galaxy_spider.core.http_engine` — DomainRateLimiter、tenacity 重试、body 截断、HTTP/2
- `galaxy_spider.core.js_engine` — V8/Node dispatch、NodeJSPersistentProcess
- `galaxy_spider.core.adaptive_concurrency` — 滑动窗口自适应（v2.7.0）
- `galaxy_spider.scheduler.engine` — heapq、Redis 降级、取消、清理
- `galaxy_spider.storage.buffer` — WriteBuffer 批量
- `galaxy_spider.storage.mongo` — 冷热分离 + TTL（v2.7.0）
- `galaxy_spider.config.settings` — OnlyFans 禁用、production 校验
- `galaxy_spider.config.hotreload` — Redis Pub/Sub（v2.7.0）
- `galaxy_spider.core.spiders` — SPIDER_REGISTRY、4 个 Spider
- `crawler.services` — SpiderRunner + ProxyValidator（v2.7.0）

## 📚 文档

- [Wiki Home](docs/wiki/Home.md) — 项目门户
- [Architecture](docs/wiki/Architecture.md) — 系统架构详解
- [API](docs/wiki/API.md) — REST API 文档
- [Configuration](docs/wiki/Configuration.md) — 配置项参考 + 热更新
- [Spider Development](docs/wiki/Spider-Development.md) — 编写自定义 Spider
- [Operations](docs/wiki/Operations.md) — 部署、监控、故障排查（含 Worker Pool）
- [Compliance](docs/wiki/Compliance.md) — 合规边界与法律风险
- [Performance](docs/wiki/Performance.md) — 性能优化指南
- [Changelog](docs/wiki/Changelog.md) — 版本变更历史

## 🛡️ 许可证

MIT License — 详见 [LICENSE](LICENSE)

## 🤝 贡献

提交前请阅读 `AGENTS.md`（项目根目录），遵循类型注解 + 单元测试 + Commit Message 规范。

## 📞 联系方式

- **项目主页**: https://gitee.com/dev_cpg/galaxy
- **Wiki**: https://gitee.com/dev_cpg/galaxy/wikis/Home
- **Issue Tracker**: https://gitee.com/dev_cpg/galaxy/issues

---

**v2.7.0** · 2026-06-15 · v2.7.0 路线图全量实施 + Worker Pool + 热更新