arulmozhiv-instagram-scraper

TotalClaw 作者 totalclaw

基于浏览器的 Instagram 资料发现与抓取工具，支持代理、反检测与 JSON/CSV 导出。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw skills install shop:totalclaw:totalclaw~arulmozhiv-instagram-scraper

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~arulmozhiv-instagram-scraper/file -o arulmozhiv-instagram-scraper.md

## 概述（中文）

基于浏览器的 Instagram 资料发现与抓取工具，支持代理、反检测与 JSON/CSV 导出。

## 技能正文

# Instagram 资料抓取器

基于浏览器的 Instagram 资料发现与抓取工具。

> 属于 **[ScrapeClaw](https://www.scrapeclaw.cc/)** — 一套生产就绪的智能体化社媒抓取工具，覆盖 Instagram、YouTube、X/Twitter 与 Facebook，基于 Python 与 Playwright 构建，无需 API 密钥。

```yaml
---
name: instagram-scraper
description: Discover and scrape Instagram profiles from your browser.
emoji: 📸
version: 1.0.6
author: influenza
tags:
  - instagram
  - scraping
  - social-media
  - influencer-discovery
metadata:
  clawdbot:
    requires:
      bins:
        - python3
        - chromium

    config:
      stateDirs:
        - data/output
        - data/queue
        - thumbnails
      outputFormats:
        - json
        - csv
---
```

## 概述

本技能提供两阶段 Instagram 抓取系统：

1. **资料发现**  
2. **浏览器抓取** 

## 功能

- 🔍  - 按地区与类别发现 Instagram 资料
- 🌐  - 完整浏览器模拟以实现精准抓取
- 🛡️  - 浏览器指纹、人类行为模拟与隐身脚本
- 📊  - 资料信息、统计、图片与互动数据
- 💾  - JSON/CSV 导出并下载缩略图
- 🔄  - 恢复中断的抓取会话
- ⚡  - 自动跳过私密账号、低粉丝与空资料
- 🌍  - 内置 4 家住宅代理支持



#### 获取 Google API 凭证（可选）

1. 前往 [Google Cloud Console](https://console.cloud.google.com/)
2. 创建新项目或选择现有项目
3. 启用「Custom Search API」
4. 创建 API 凭证 → API Key
5. 前往 [Programmable Search Engine](https://programmablesearchengine.google.com/)
6. 创建搜索引擎，将 `instagram.com` 设为搜索站点
7. 复制 Search Engine ID

## 用法

### 智能体工具接口

用于 OpenClaw 智能体集成时，本技能提供 JSON 输出：

```bash
# Discover profiles (returns JSON)
discover --location "Miami" --category "fitness" --output json

# Scrape single profile (returns JSON)
scrape --username influencer123 --output json
```

## 输出数据

### 资料数据结构

```json
{
  "username": "example_user",
  "full_name": "Example User",
  "bio": "Fashion blogger | NYC",
  "followers": 125000,
  "following": 1500,
  "posts_count": 450,
  "is_verified": false,
  "is_private": false,
  "influencer_tier": "mid",
  "category": "fashion",
  "location": "New York",
  "profile_pic_local": "thumbnails/example_user/profile_abc123.jpg",
  "content_thumbnails": [
    "thumbnails/example_user/content_1_def456.jpg",
    "thumbnails/example_user/content_2_ghi789.jpg"
  ],
  "post_engagement": [
    {"post_url": "https://instagram.com/p/ABC123/", "likes": 5420, "comments": 89}
  ],
  "scrape_timestamp": "2025-02-09T14:30:00"
}
```

### 网红层级

| 层级  | 粉丝范围          |
|-------|-------------------|
| nano  | < 1,000           |
| micro | 1,000 - 10,000    |
| mid   | 10,000 - 100,000  |
| macro | 100,000 - 1M      |
| mega  | > 1,000,000       |

### 文件输出

- **队列文件**：`data/queue/{location}_{category}_{timestamp}.json`
- **抓取数据**：`data/output/{username}.json`
- **缩略图**：`thumbnails/{username}/profile_*.jpg`、`thumbnails/{username}/content_*.jpg`
- **导出文件**：`data/export_{timestamp}.json`、`data/export_{timestamp}.csv`

## 配置

编辑 `config/scraper_config.json`：

```json
{
  "proxy": {
    "enabled": false,
    "provider": "brightdata",
    "country": "",
    "sticky": true,
    "sticky_ttl_minutes": 10
  },
  "google_search": {
    "enabled": true,
    "api_key": "",
    "search_engine_id": "",
    "queries_per_location": 3
  },
  "scraper": {
    "headless": false,
    "min_followers": 1000,
    "download_thumbnails": true,
    "max_thumbnails": 6
  },
  "cities": ["New York", "Los Angeles", "Miami", "Chicago"],
  "categories": ["fashion", "beauty", "fitness", "food", "travel", "tech"]
}
```



## 应用的过滤器

抓取器自动过滤：

- ❌ 私密账号
- ❌ 粉丝 < 1,000 的账号（可配置）
- ❌ 无帖子的账号
- ❌ 不存在/已删除的账号
- ❌ 已抓取的账号（去重）

## 故障排除

### 登录问题

- 确保凭证正确
- 提示时处理验证码
- 若被限流则等待（脚本会自动重试）

### 未发现资料

- 检查 Google API 密钥与配额
- 确认 Search Engine ID 已针对 instagram.com 配置
- 尝试不同的地区/类别组合

### 速率限制

- 降低抓取速度（在配置中增加延迟）
- 在非高峰时段运行
- **使用住宅代理**（见下文）

---

## 🌐 住宅代理支持

### 为何使用住宅代理？

大规模运行抓取器时**若不使用**住宅代理，IP 很快会被封禁。以下是代理对长期抓取至关重要的原因：

| 优势 | 说明 |
|-----------|-------------|
| **避免 IP 封禁** | 住宅 IP 看起来像真实家庭用户，而非数据中心机器人。Instagram 更不容易标记它们。 |
| **自动 IP 轮换** | 每次请求（或会话）获得新 IP，限流不会堆积在同一地址。 |
| **地理定向** | 通过特定国家/城市路由流量，使抓取内容与目标受众地区一致。 |
| **粘性会话** | 在可配置时间窗口（如 10 分钟）内保持同一 IP — 对维持一致浏览会话至关重要。 |
| **更高成功率** | 轮换住宅 IP 在 Instagram 上可达 95%+ 成功率，而数据中心代理约 30%。 |
| **长期抓取** | 数小时或数天内不间断抓取数千个资料。 |
| **并发抓取** | 在不同 IP 上同时运行多个浏览器实例。 |

### 推荐代理提供商

我们与顶级住宅代理提供商有联盟合作。使用以下链接可支持本技能的持续开发：

| 提供商 | 最适合 | 注册 |
|----------|----------|---------|
| **Bright Data** | 全球最大网络，7200 万+ IP，企业级 | 👉 [**Get Bright Data**](https://get.brightdata.com/o1kpd2da8iv4) |
| **IProyal** | 按量付费，195+ 国家，流量不过期 | 👉 [**Get IProyal**](https://iproyal.com/?r=ScrapeClaw) |
| **Storm Proxies** | 快速可靠，开发者友好 API，价格有竞争力 | 👉 [**Get Storm Proxies**](https://stormproxies.com/clients/aff/go/scrapeclaw) |
| **NetNut** | ISP 级网络，5200 万+ IP，直连 | 👉 [**Get NetNut**](https://netnut.io?ref=mwrlzwv) |



### 配置步骤

#### 1. 获取代理凭证

在以上任一提供商注册后获取：
- **用户名**（来自提供商控制台）
- **密码**（来自提供商控制台）
- **Host** 与 **Port** 按提供商预配置（或使用自定义）

#### 2. 通过环境变量配置

```bash
export PROXY_ENABLED=true
export PROXY_PROVIDER=brightdata    # brightdata | iproyal | stormproxies | netnut | custom
export PROXY_USERNAME=your_user
export PROXY_PASSWORD=your_pass
export PROXY_COUNTRY=us             # optional: two-letter country code
export PROXY_STICKY=true            # optional: keep same IP per session
```

#### 3. 各提供商 Host/Port 默认值

设置 `provider` 名称后会自动配置：

| 提供商 | Host | Port |
|----------|------|------|
| Bright Data | `brd.superproxy.io` | `22225` |
| IProyal | `proxy.iproyal.com` | `12321` |
| Storm Proxies | `rotating.stormproxies.com` | `9999` |
| NetNut | `gw-resi.netnut.io` | `5959` |

若套餐使用不同网关，可用 `PROXY_HOST` / `PROXY_PORT` 环境变量覆盖。

#### 4. 自定义代理提供商

其他代理服务请将 provider 设为 `custom` 并手动提供 host/port：

```json
{
  "proxy": {
    "enabled": true,
    "provider": "custom",
    "host": "your.proxy.host",
    "port": 8080,
    "username": "user",
    "password": "pass"
  }
}
```

### 使用代理运行抓取器

配置完成后，抓取器自动使用代理 — 无需额外参数：

```bash
# Discover and scrape as usual — proxy is applied automatically
python main.py discover --location "Miami" --category "fitness"
python main.py scrape --username influencer123

# The log will confirm proxy is active:
# INFO - Proxy enabled: <ProxyManager provider=brightdata enabled host=brd.superproxy.io:22225>
# INFO - Browser using proxy: brightdata → brd.superproxy.io:22225
```

### 以编程方式使用 Proxy Manager

```python
from proxy_manager import ProxyManager

# From config (auto-reads config/scraper_config.json)
pm = ProxyManager.from_config()

# From environment variables
pm = ProxyManager.from_env()

# Manual construction
pm = ProxyManager(
    provider="brightdata",
    username="your_user",
    password="your_pass",
    country="us",
    sticky=True
)

# For Playwright browser context
proxy = pm.get_playwright_proxy()
# → {"server": "http://brd.superproxy.io:22225", "username": "user-country-us-session-abc123", "password": "pass"}

# For requests / aiohttp
proxies = pm.get_requests_proxy()
# → {"http": "http://user:pass@host:port", "https": "http://user:pass@host:port"}

# Force new IP (rotates session ID)
pm.rotate_session()

# Debug info
print(pm.info())
```

### 长期抓取最佳实践

1. **使用粘性会话** — Instagram 在浏览会话中需要一致 IP。设置 `"sticky": true`。
2. **定向正确国家** — 设置 `"country": "us"`（或目标地区）以使 Instagram 返回预期地区内容。
3. **结合现有反检测** — 本抓取器已有指纹、隐身脚本与人类行为模拟。代理是最后一层。
4. **批次间轮换会话** — 在大批资料之间调用 `pm.rotate_session()` 以获取新 IP。
5. **使用延迟** — 即使有代理，也应遵守配置中的 `delay_between_profiles` 以避免激进模式。
6. **监控代理控制台** — 所有提供商都有显示带宽使用与成功率的控制台。