# x-crawler

**Repository Path**: deepeye/x-crawler

## Basic Information

- **Project Name**: x-crawler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Crawler

基于 Scrapling + FastAPI 的 X.com 采集代理服务。

## 功能特性

- 搜索采集：按关键词搜索推文
- 账号采集：获取指定用户的推文
- 列表采集：获取 Twitter 列表中的推文
- 自动重试：Cookie/代理失效时自动切换重试
- 速率控制：防止触发限制

## 快速开始

### 安装依赖

```bash
uv sync --extra dev
```

### 配置环境变量

```bash
# Cookie 池（多个用逗号分隔）
export X_COOKIES="auth_token=xxx; ct0=xxx,auth_token=yyy; ct0=yyy"

# 代理池（可选，多个用逗号分隔）
export X_PROXIES="http://user:pass@host:port"

# 速率控制（每分钟请求数，默认 10）
export X_RPM=10
```

### 启动服务

```bash
uv run uvicorn main:app --host 0.0.0.0 --port 8000
```

## API 接口

### 健康检查

```
GET /health
```

### 搜索采集

```
POST /search
Content-Type: application/json

{
  "keyword": "AI agents",
  "limit": 50,
  "sort": "latest"
}
```

### 账号采集

```
POST /user/{username}
Content-Type: application/json

{
  "limit": 50,
  "include_replies": false,
  "include_retweets": true
}
```

### 列表采集

```
POST /list/{list_id}
Content-Type: application/json

{
  "limit": 50
}
```

## 获取 Cookie

1. 登录 https://x.com
2. 打开浏览器开发者工具 (F12)
3. 进入 Application > Cookies > https://x.com
4. 复制 `auth_token` 和 `ct0` 的值
5. 格式：`auth_token=xxx; ct0=xxx`

## 运行测试

```bash
uv run pytest tests/ -v
```

## 技术栈

- Python 3.11+
- FastAPI
- Scrapling 0.4.2
- Pydantic