Merge c1ad988461 into 96096ea0ff

2026-05-28 17:37:34 -04:00 · 2026-05-28 17:37:34 -04:00 · 203dd78b31
parent 96096ea0ff c1ad988461
commit 203dd78b31
3 changed files with 930 additions and 0 deletions
--- a/docs/deploy-commands.sh
+++ b/docs/deploy-commands.sh
@ -0,0 +1,169 @@
+#!/bin/bash
+#=============================================================================
+# MiroFish + BettaFish 完整部署指令
+# 伺服器: 139.180.189.56 (Vultr Singapore, 12vCPU / 24GB RAM)
+#
+# 使用方式:
+#   ssh root@139.180.189.56
+#   然後複製下面的指令分段執行
+#=============================================================================
+
+#-----------------------------------------------------------------------------
+# Part 1: 系統準備 (複製整段執行)
+#-----------------------------------------------------------------------------
+apt-get update -qq && \
+apt-get install -y -qq git curl wget unzip > /dev/null 2>&1 && \
+echo "✓ 系統更新完成"
+
+# 安裝 Docker
+if ! command -v docker &> /dev/null; then
+    curl -fsSL https://get.docker.com | sh > /dev/null 2>&1
+    systemctl enable docker && systemctl start docker
+fi
+echo "✓ Docker: $(docker --version)"
+
+#-----------------------------------------------------------------------------
+# Part 2: Clone 專案 (複製整段執行)
+#-----------------------------------------------------------------------------
+git clone https://github.com/666ghj/MiroFish.git /opt/mirofish
+git clone https://github.com/virus11456/BettaFish.git /opt/bettafish
+echo "✓ 兩個專案已 clone"
+
+#-----------------------------------------------------------------------------
+# Part 3: 建立 MiroFish .env (複製整段執行)
+#-----------------------------------------------------------------------------
+cat > /opt/mirofish/.env << 'EOF'
+LLM_API_KEY=sk-ebc1d137772040cabc536dd17d2bf7b6
+LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+LLM_MODEL_NAME=qwen-plus
+ZEP_API_KEY=z_1dWlkIjoiNmYxYjRlY2UtNTA4Yy00YmU5LThmMDktNDRjNGQxYjAyN2FkIn0.FVCYTUmdtwvZK4bLAR0Q_oN488JjeAVxL-GuK0F_fwv2eCDQwpoHAL_DHLHiDROxI5oVqJ90Hnwo9sXHlaXgMQ
+EOF
+echo "✓ MiroFish .env 已建立"
+
+#-----------------------------------------------------------------------------
+# Part 4: 建立 BettaFish .env (複製整段執行)
+#-----------------------------------------------------------------------------
+if [ -f /opt/bettafish/.env.example ]; then
+    cp /opt/bettafish/.env.example /opt/bettafish/.env
+fi
+# 追加/覆寫關鍵配置
+cat >> /opt/bettafish/.env << 'EOF'
+
+# === 手動追加的配置 ===
+QUERY_API_KEY=sk-6fdfebecdea74a4a8d8fa6aeb0a94d2e
+QUERY_BASE_URL=https://api.deepseek.com
+QUERY_MODEL_NAME=deepseek-chat
+
+INSIGHT_API_KEY=sk-6fdfebecdea74a4a8d8fa6aeb0a94d2e
+INSIGHT_BASE_URL=https://api.deepseek.com
+INSIGHT_MODEL_NAME=deepseek-chat
+
+REPORT_API_KEY=sk-ebc1d137772040cabc536dd17d2bf7b6
+REPORT_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+REPORT_MODEL_NAME=qwen-plus
+
+TAVILY_API_KEY=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
+EOF
+echo "✓ BettaFish .env 已建立"
+
+#-----------------------------------------------------------------------------
+# Part 5: 建立統一 docker-compose.yml (複製整段執行)
+#-----------------------------------------------------------------------------
+cat > /opt/docker-compose.yml << 'DCEOF'
+services:
+  # MiroFish — AI 預測引擎
+  # 前端: http://139.180.189.56:3000
+  # 後端 API: http://139.180.189.56:5001
+  mirofish:
+    image: ghcr.io/666ghj/mirofish:latest
+    container_name: mirofish
+    env_file:
+      - /opt/mirofish/.env
+    ports:
+      - "3000:3000"
+      - "5001:5001"
+    restart: unless-stopped
+    volumes:
+      - /opt/mirofish/backend/uploads:/app/backend/uploads
+
+  # BettaFish — 輿情監控系統
+  # 前端: http://139.180.189.56:5000
+  bettafish-db:
+    image: postgres:15-alpine
+    container_name: bettafish-db
+    environment:
+      POSTGRES_USER: bettafish
+      POSTGRES_PASSWORD: bettafish
+      POSTGRES_DB: bettafish
+    volumes:
+      - bettafish_pgdata:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  bettafish:
+    build:
+      context: /opt/bettafish
+      dockerfile: Dockerfile
+    container_name: bettafish
+    env_file:
+      - /opt/bettafish/.env
+    ports:
+      - "5000:5000"
+    depends_on:
+      - bettafish-db
+    restart: unless-stopped
+    volumes:
+      - /opt/bettafish/final_reports:/app/final_reports
+      - /opt/bettafish/logs:/app/logs
+
+volumes:
+  bettafish_pgdata:
+DCEOF
+echo "✓ docker-compose.yml 已建立"
+
+#-----------------------------------------------------------------------------
+# Part 6: 啟動服務 (複製整段執行)
+#-----------------------------------------------------------------------------
+cd /opt
+
+# 先啟動 MiroFish（直接拉映像，最快）
+docker compose up -d mirofish
+echo "✓ MiroFish 啟動中..."
+
+# 再啟動 BettaFish（需要 build，較慢）
+docker compose up -d --build bettafish-db bettafish
+echo "✓ BettaFish 啟動中..."
+
+# 查看狀態
+docker compose ps
+
+#-----------------------------------------------------------------------------
+# Part 7: 防火牆 (複製整段執行)
+#-----------------------------------------------------------------------------
+if command -v ufw &> /dev/null; then
+    ufw allow 22/tcp > /dev/null 2>&1
+    ufw allow 3000/tcp > /dev/null 2>&1
+    ufw allow 5000/tcp > /dev/null 2>&1
+    ufw allow 5001/tcp > /dev/null 2>&1
+    ufw --force enable > /dev/null 2>&1
+    echo "✓ 防火牆已開放端口"
+fi
+
+#-----------------------------------------------------------------------------
+# 完成！
+#-----------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  部署完成！"
+echo "============================================"
+echo ""
+echo "  MiroFish:  http://139.180.189.56:3000"
+echo "  BettaFish: http://139.180.189.56:5000"
+echo ""
+echo "  常用命令："
+echo "    查看日誌: cd /opt && docker compose logs -f"
+echo "    查看狀態: cd /opt && docker compose ps"
+echo "    重啟:     cd /opt && docker compose restart"
+echo "    停止:     cd /opt && docker compose down"
+echo ""
+echo "  ⚠ 請立即更改 root 密碼: passwd"
+echo "============================================"
--- a/docs/deploy-vultr.sh
+++ b/docs/deploy-vultr.sh
@ -0,0 +1,276 @@
+#!/bin/bash
+#=============================================================================
+# MiroFish + BettaFish 一鍵部署腳本 (Vultr VPS)
+#
+# 使用方式：
+#   1. SSH 連上你的伺服器: ssh root@139.180.189.56
+#   2. 複製貼上這整個腳本執行，或：
+#      curl -sSL <raw_url> | bash
+#   3. 部署完成後編輯 .env 填入你的 API Key
+#
+# 部署內容：
+#   - MiroFish (port 3000 前端 + port 5001 後端)
+#   - BettaFish (port 5000)
+#   - 2GB Swap (防止記憶體不足)
+#=============================================================================
+
+set -e
+
+echo "============================================"
+echo "  MiroFish + BettaFish 一鍵部署腳本"
+echo "  目標伺服器: $(hostname) ($(curl -s ifconfig.me 2>/dev/null || echo 'unknown'))"
+echo "============================================"
+echo ""
+
+#-----------------------------------------------------------------------------
+# Step 0: 系統更新 & 基礎工具
+#-----------------------------------------------------------------------------
+echo "[0/7] 系統更新 & 安裝基礎工具..."
+apt-get update -qq
+apt-get install -y -qq git curl wget unzip software-properties-common > /dev/null 2>&1
+echo "  ✓ 基礎工具安裝完成"
+
+#-----------------------------------------------------------------------------
+# Step 1: 加 Swap (僅記憶體 < 8G 時需要)
+#-----------------------------------------------------------------------------
+TOTAL_MEM_MB=$(free -m | awk '/^Mem:/{print $2}')
+echo "[1/7] 檢查記憶體 (${TOTAL_MEM_MB}MB)..."
+if [ "$TOTAL_MEM_MB" -lt 8192 ] && [ ! -f /swapfile ]; then
+    echo "  記憶體 < 8GB，建立 2GB Swap..."
+    fallocate -l 2G /swapfile
+    chmod 600 /swapfile
+    mkswap /swapfile > /dev/null
+    swapon /swapfile
+    echo '/swapfile none swap sw 0 0' >> /etc/fstab
+    echo "  ✓ 2GB Swap 已建立並啟用"
+else
+    echo "  ✓ 記憶體充足 (${TOTAL_MEM_MB}MB)，無需 Swap"
+fi
+
+#-----------------------------------------------------------------------------
+# Step 2: 安裝 Docker & Docker Compose
+#-----------------------------------------------------------------------------
+echo "[2/7] 安裝 Docker..."
+if ! command -v docker &> /dev/null; then
+    curl -fsSL https://get.docker.com | sh > /dev/null 2>&1
+    systemctl enable docker
+    systemctl start docker
+    echo "  ✓ Docker 安裝完成 ($(docker --version))"
+else
+    echo "  ✓ Docker 已安裝 ($(docker --version))"
+fi
+
+#-----------------------------------------------------------------------------
+# Step 3: Clone MiroFish
+#-----------------------------------------------------------------------------
+echo "[3/7] 部署 MiroFish..."
+MIROFISH_DIR="/opt/mirofish"
+if [ ! -d "$MIROFISH_DIR" ]; then
+    git clone https://github.com/666ghj/MiroFish.git "$MIROFISH_DIR"
+    echo "  ✓ MiroFish clone 完成"
+else
+    cd "$MIROFISH_DIR" && git pull origin main
+    echo "  ✓ MiroFish 已存在，已更新"
+fi
+
+# 建立 .env（佔位符）
+cat > "$MIROFISH_DIR/.env" << 'ENVEOF'
+# ===== MiroFish 環境變數 =====
+# 部署完成後請填入你的 API Key！
+
+# LLM API 配置（支援 OpenAI SDK 格式的任意 LLM API）
+# 推薦選項：
+#   阿里雲百煉 (qwen-plus): https://bailian.console.aliyun.com/
+#   OpenAI (gpt-4o-mini):    https://platform.openai.com/api-keys
+#   DeepSeek (deepseek-chat): https://platform.deepseek.com/
+LLM_API_KEY=your_llm_api_key_here
+LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+LLM_MODEL_NAME=qwen-plus
+
+# Zep 記憶圖譜配置
+# 免費註冊：https://app.getzep.com/
+ZEP_API_KEY=your_zep_api_key_here
+
+# 加速 LLM（可選，不需要就刪掉下面三行）
+# LLM_BOOST_API_KEY=
+# LLM_BOOST_BASE_URL=
+# LLM_BOOST_MODEL_NAME=
+ENVEOF
+echo "  ✓ MiroFish .env 已建立（需填入 API Key）"
+
+#-----------------------------------------------------------------------------
+# Step 4: Clone BettaFish
+#-----------------------------------------------------------------------------
+echo "[4/7] 部署 BettaFish..."
+BETTAFISH_DIR="/opt/bettafish"
+if [ ! -d "$BETTAFISH_DIR" ]; then
+    git clone https://github.com/virus11456/BettaFish.git "$BETTAFISH_DIR"
+    echo "  ✓ BettaFish clone 完成"
+else
+    cd "$BETTAFISH_DIR" && git pull origin main 2>/dev/null || git pull
+    echo "  ✓ BettaFish 已存在，已更新"
+fi
+
+# 建立 BettaFish .env（佔位符）
+if [ -f "$BETTAFISH_DIR/.env.example" ]; then
+    cp "$BETTAFISH_DIR/.env.example" "$BETTAFISH_DIR/.env"
+    echo "  ✓ BettaFish .env 已從 .env.example 建立（需填入配置）"
+else
+    cat > "$BETTAFISH_DIR/.env" << 'ENVEOF'
+# ===== BettaFish 環境變數 =====
+# 請參考 BettaFish README 填入配置
+
+# 資料庫配置
+DB_HOST=db
+DB_PORT=5432
+DB_USER=bettafish
+DB_PASSWORD=bettafish
+DB_NAME=bettafish
+
+# LLM 配置（各 Engine 可獨立配置）
+# InsightEngine - 推薦 Moonshot/Kimi
+INSIGHT_API_KEY=your_key_here
+# QueryEngine - 推薦 DeepSeek
+QUERY_API_KEY=your_key_here
+# ReportEngine - 推薦 Gemini
+REPORT_API_KEY=your_key_here
+
+# 搜索 API（擇一即可）
+TAVILY_API_KEY=your_tavily_key_here
+ENVEOF
+    echo "  ✓ BettaFish .env 已建立（需填入配置）"
+fi
+
+#-----------------------------------------------------------------------------
+# Step 5: 建立統一 docker-compose（同時跑兩個服務）
+#-----------------------------------------------------------------------------
+echo "[5/7] 建立統一 Docker Compose..."
+cat > /opt/docker-compose.yml << 'DCEOF'
+#=============================================================================
+# MiroFish + BettaFish 統一 Docker Compose
+#=============================================================================
+services:
+
+  #---------------------------------------------------------------------------
+  # MiroFish — AI 預測引擎
+  #   前端: http://<your-ip>:3000
+  #   後端: http://<your-ip>:5001
+  #---------------------------------------------------------------------------
+  mirofish:
+    image: ghcr.io/666ghj/mirofish:latest
+    container_name: mirofish
+    env_file:
+      - /opt/mirofish/.env
+    ports:
+      - "3000:3000"
+      - "5001:5001"
+    restart: unless-stopped
+    volumes:
+      - /opt/mirofish/backend/uploads:/app/backend/uploads
+
+  #---------------------------------------------------------------------------
+  # BettaFish — 輿情監控系統
+  #   前端: http://<your-ip>:5000
+  #---------------------------------------------------------------------------
+  bettafish-db:
+    image: postgres:15-alpine
+    container_name: bettafish-db
+    environment:
+      POSTGRES_USER: bettafish
+      POSTGRES_PASSWORD: bettafish
+      POSTGRES_DB: bettafish
+    volumes:
+      - bettafish_pgdata:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  bettafish:
+    build:
+      context: /opt/bettafish
+      dockerfile: Dockerfile
+    container_name: bettafish
+    env_file:
+      - /opt/bettafish/.env
+    ports:
+      - "5000:5000"
+    depends_on:
+      - bettafish-db
+    restart: unless-stopped
+    volumes:
+      - /opt/bettafish/final_reports:/app/final_reports
+      - /opt/bettafish/logs:/app/logs
+
+volumes:
+  bettafish_pgdata:
+DCEOF
+echo "  ✓ 統一 docker-compose.yml 已建立"
+
+#-----------------------------------------------------------------------------
+# Step 6: 啟動 MiroFish（先啟動，BettaFish 等填完配置再啟動）
+#-----------------------------------------------------------------------------
+echo "[6/7] 拉取 MiroFish Docker 映像..."
+cd /opt
+docker compose pull mirofish 2>&1 | tail -3
+echo "  ✓ MiroFish 映像拉取完成"
+
+# 先只啟動 MiroFish（不需要額外 build）
+# BettaFish 需要 build 且需要填配置，先不啟動
+echo "  ⚠ 暫不啟動服務 — 需先填入 API Key"
+
+#-----------------------------------------------------------------------------
+# Step 7: 設定防火牆
+#-----------------------------------------------------------------------------
+echo "[7/7] 設定防火牆..."
+if command -v ufw &> /dev/null; then
+    ufw allow 22/tcp   > /dev/null 2>&1
+    ufw allow 3000/tcp > /dev/null 2>&1  # MiroFish 前端
+    ufw allow 5001/tcp > /dev/null 2>&1  # MiroFish 後端
+    ufw allow 5000/tcp > /dev/null 2>&1  # BettaFish
+    ufw --force enable > /dev/null 2>&1
+    echo "  ✓ 防火牆已開放 22, 3000, 5000, 5001 端口"
+else
+    echo "  ✓ 未安裝 ufw，跳過（Vultr 請在控制台設定安全組）"
+fi
+
+#=============================================================================
+# 完成！
+#=============================================================================
+echo ""
+echo "============================================"
+echo "  部署準備完成！"
+echo "============================================"
+echo ""
+echo "  檔案位置："
+echo "    MiroFish:  /opt/mirofish/"
+echo "    BettaFish: /opt/bettafish/"
+echo "    Compose:   /opt/docker-compose.yml"
+echo ""
+echo "  ⚡ 接下來你需要做的："
+echo ""
+echo "  1. 編輯 MiroFish 配置（必須）："
+echo "     nano /opt/mirofish/.env"
+echo "     → 填入 LLM_API_KEY 和 ZEP_API_KEY"
+echo ""
+echo "  2. 編輯 BettaFish 配置（必須）："
+echo "     nano /opt/bettafish/.env"
+echo "     → 填入各 Engine 的 API Key"
+echo ""
+echo "  3. 啟動所有服務："
+echo "     cd /opt && docker compose up -d"
+echo ""
+echo "  4. 或只啟動 MiroFish："
+echo "     cd /opt && docker compose up -d mirofish"
+echo ""
+echo "  5. 訪問："
+echo "     MiroFish:  http://139.180.189.56:3000"
+echo "     BettaFish: http://139.180.189.56:5000"
+echo ""
+echo "  📋 常用命令："
+echo "     查看日誌:  cd /opt && docker compose logs -f"
+echo "     停止服務:  cd /opt && docker compose down"
+echo "     重啟服務:  cd /opt && docker compose restart"
+echo "     查看狀態:  cd /opt && docker compose ps"
+echo ""
+echo "  ⚠ 安全提醒："
+echo "     部署完成後請立即更改 root 密碼: passwd"
+echo ""
+echo "============================================"
--- a/docs/research-international-platform-extension.md
+++ b/docs/research-international-platform-extension.md
@ -0,0 +1,485 @@
+# BettaFish 國際平台擴充研究報告
+
+> 研究日期：2026-04-02
+> 目標：調研如何將 BettaFish (微輿) 的 MindSpider 爬蟲系統擴充至國際社群平台
+
+---
+
+## 目錄
+
+1. [現有架構分析](#1-現有架構分析)
+2. [各國際平台推薦工具](#2-各國際平台推薦工具)
+3. [統一整合方案](#3-統一整合方案)
+4. [擴充實作步驟](#4-擴充實作步驟)
+5. [優先順序建議](#5-優先順序建議)
+6. [費用與風險](#6-費用與風險)
+7. [MiroFish 協同使用](#7-mirofish-協同使用)
+
+---
+
+## 1. 現有架構分析
+
+### 1.1 MindSpider 兩階段流水線
+
+```
+Stage 1: BroadTopicExtraction（熱門話題抓取）
+  → 從 13+ 新聞源抓取熱門新聞
+  → LLM (DeepSeek) 提取關鍵詞和話題摘要
+  → 存入 daily_news / daily_topics 表
+
+Stage 2: DeepSentimentCrawling（深度爬取）
+  → KeywordManager 從 DB 讀取關鍵詞
+  → PlatformCrawler 派發到 MediaCrawler 子模組（子進程方式）
+  → 爬取結果存入各平台專屬表（xhs_note, weibo_note 等）
+  → InsightEngine 讀取做情感分析（已支援 22 種語言）
+```
+
+### 1.2 目前支援的平台（僅中國）
+
+| 平台代碼 | 平台名稱 | 資料表 |
+|---------|---------|--------|
+| `xhs` | 小紅書 | `xhs_note` |
+| `dy` | 抖音 | `douyin_aweme` |
+| `ks` | 快手 | `kuaishou_video` |
+| `bili` | Bilibili | `bilibili_video` |
+| `wb` | 微博 | `weibo_note` |
+| `tieba` | 百度貼吧 | `tieba_note` |
+| `zhihu` | 知乎 | `zhihu_content` |
+
+### 1.3 平台派發機制
+
+`MindSpider/main.py` 中的平台別名映射：
+
+```python
+PLATFORM_CHOICES = ['xhs', 'dy', 'ks', 'bili', 'wb', 'tieba', 'zhihu']
+
+PLATFORM_ALIASES = {
+    'weibo': 'wb', '微博': 'wb',
+    'douyin': 'dy', '抖音': 'dy',
+    'kuaishou': 'ks', '快手': 'ks',
+    'bilibili': 'bili', 'b站': 'bili',
+    'xiaohongshu': 'xhs', '小红书': 'xhs',
+    'zhihu': 'zhihu', '知乎': 'zhihu',
+    'tieba': 'tieba', '贴吧': 'tieba',
+}
+```
+
+### 1.4 擴充切入點
+
+新增國際平台需要修改的位置：
+
+1. **`MindSpider/main.py`** — 加入新平台代碼和別名
+2. **`MindSpider/DeepSentimentCrawling/platform_crawler.py`** — 加入新平台爬蟲調用邏輯
+3. **`MindSpider/schema/mindspider_tables.sql`** — 建立平台專屬資料表
+4. **情感分析 — 不需修改**（`tabularisai/multilingual-sentiment-analysis` 已支援 22 種語言）
+
+---
+
+## 2. 各國際平台推薦工具
+
+### 2.1 Twitter / X
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[twikit](https://github.com/d60/twikit)** | ~4,220 | Python | **推薦首選**。使用 Twitter 內部 API，積極維護中（2026 持續更新）。支援搜尋推文、用戶資料、趨勢話題、媒體下載 | 帳號密碼（不需 API Key） |
+| [twscrape](https://github.com/vladkens/twscrape) | ~2,320 | Python | Async，支援多帳號輪換池，適合大量爬取 | 帳號密碼 |
+| [Scweet](https://github.com/Altimis/Scweet) | ~1,291 | Python | 基於 GraphQL，多帳號池 + 代理支援 | 帳號密碼 |
+| [tweety](https://github.com/mahrtayyab/tweety) | ~646 | Python | 輕量級，持續更新 | 帳號密碼 |
+| [snscrape](https://github.com/JustAnotherArchivist/snscrape) | ~5,322 | Python | 多平台（Twitter/FB/IG/Reddit），但維護停滯，Twitter 模組已不可靠 | 無 |
+
+**官方 API 狀態**：X API v2 極貴（Basic $100/月，Pro $5,000/月），免費版只能發文不能讀取，不實用。
+
+### 2.2 Reddit
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[PRAW](https://github.com/praw-dev/praw)** | ~4,075 | Python | **推薦首選**。官方 Python 包裝，最穩定可靠。`pip install praw` | API Key（免費申請） |
+| [asyncpraw](https://github.com/praw-dev/asyncpraw) | ~145 | Python | PRAW 的 async 版本 | API Key（免費申請） |
+| [URS](https://github.com/JosephLai241/URS) | ~981 | Python | CLI 工具，底層用 PRAW，輸出 JSON/CSV | API Key（免費申請） |
+| Reddit `.json` 端點 | - | HTTP | 任何 Reddit URL 加 `.json` 即可取得數據 | 無（但有速率限制） |
+
+**官方 API 狀態**：**所有平台中最友好**，免費額度足夠中等規模使用（100 requests/min）。
+
+### 2.3 Instagram
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[Instaloader](https://github.com/instaloader/instaloader)** | ~12,053 | Python | **推薦首選**。最成熟穩定，`pip install instaloader`。下載照片、影片、Stories、留言、metadata | 公開頁面免登入 |
+| [Instagrapi](https://github.com/subzeroid/instagrapi) | ~6,050 | Python | 功能最全（私訊、Stories、Reels 都支援），使用 Instagram 私有 API | 帳號密碼 |
+
+**官方 API 狀態**：Instagram Graph API 僅限商業/創作者帳號查詢自己的內容，無法抓取第三方數據。
+
+**警告**：Instagram 在 2026 年反爬非常激進（強制登入牆、IP 封鎖），需搭配住宅代理 IP 使用。
+
+### 2.4 Facebook
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[facebook-scraper](https://github.com/kevinzg/facebook-scraper)** | ~3,100 | Python | **推薦首選**。抓公開粉專貼文/留言/按讚，`pip install facebook-scraper` | 無 |
+| [fbcrawl](https://github.com/rugantio/fbcrawl) | ~685 | Python | 基於 Scrapy，輸出 CSV/JSON | 無 |
+| [facebook_page_scraper](https://github.com/shaikhsajid1111/facebook_page_scraper) | ~262 | Python | 使用 Selenium，輸出 JSON/CSV | 無 |
+
+**官方 API 狀態**：劍橋分析事件後嚴格限制，需要商業驗證，第三方幾乎不可用。
+
+### 2.5 YouTube
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[YouTube Data API v3](https://developers.google.com/youtube/v3)** | 官方 | REST | **推薦首選**。免費 10,000 單位/天，穩定可靠 | API Key（免費） |
+| [youtube-comment-downloader](https://github.com/egbertbouman/youtube-comment-downloader) | ~1,206 | Python | 輕量級，不需 API Key，輸出 JSON | 無 |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | 100k+ | Python | 加 `--write-comments` 可抓留言，加影片 metadata | 無 |
+
+**官方 API 狀態**：**所有平台中官方 API 最實用**，建議直接用官方。
+
+### 2.6 TikTok（國際版）
+
+| 專案 | Stars | 語言 | 說明 | 認證需求 |
+|------|-------|------|------|---------|
+| **[TikTok-Api](https://github.com/davidteather/TikTok-Api)** | ~6,100 | Python | **推薦首選**。最受歡迎的 TikTok 爬蟲，`pip install TikTokApi` | 無（用 Playwright） |
+| [Douyin_TikTok_Download_API](https://github.com/Evil0ctal/Douyin_TikTok_Download_API) | ~16,919 | Python | 同時支援抖音 + 國際版 TikTok，有 FastAPI 介面 | 無 |
+| [TikTokLive](https://github.com/isaackogan/TikTokLive) | ~1,380 | Python | 專門抓 TikTok 直播的即時留言/禮物/事件 | 無 |
+
+**官方 API 狀態**：TikTok Research API 需學術機構身份申請，一般用戶難以取得。
+
+### 2.7 多平台統一工具（參考）
+
+| 專案 | Stars | 支援平台 | 說明 |
+|------|-------|---------|------|
+| [snscrape](https://github.com/JustAnotherArchivist/snscrape) | ~5,322 | Twitter/FB/IG/Reddit/Telegram/VK | 維護停滯，Twitter 模組已壞 |
+| [socialreaper](https://github.com/ScriptSmith/socialreaper) | ~641 | FB/Twitter/Reddit/YouTube/Pinterest | 使用官方 API，架構值得參考 |
+| [social-media-scraper](https://github.com/julian-chan/social-media-scraper) | - | FB/IG/Weibo/Twitter/LinkedIn | 含 NLP 情感分析，與 BettaFish 最相關 |
+
+---
+
+## 3. 統一整合方案
+
+### 3.1 架構設計
+
+```
+BettaFish MindSpider 擴充架構
+│
+├── 現有 MediaCrawler（中國平台）
+│   ├── xhs, dy, ks, bili, wb, tieba, zhihu
+│
+├── 新增 InternationalCrawler/（國際平台）
+│   ├── __init__.py
+│   ├── base_crawler.py        # 統一抽象基類
+│   ├── twitter_crawler.py     # → twikit
+│   ├── reddit_crawler.py      # → PRAW
+│   ├── instagram_crawler.py   # → instaloader
+│   ├── facebook_crawler.py    # → facebook-scraper
+│   ├── youtube_crawler.py     # → YouTube API v3
+│   └── tiktok_crawler.py      # → TikTok-Api
+│
+├── 統一數據模型（Normalized Schema）
+│   所有平台輸出統一格式，存入對應資料表
+│
+└── 下游分析引擎（不需修改）
+    ├── InsightEngine（情感分析已支援 22 語言）
+    ├── QueryEngine
+    ├── ReportEngine
+    └── ForumEngine
+```
+
+### 3.2 統一數據模型
+
+所有國際平台的爬取結果應統一為以下格式，再存入各自的資料表：
+
+```python
+{
+    "platform": str,          # "twitter", "reddit", "instagram", etc.
+    "post_id": str,           # 平台原始貼文 ID
+    "author": str,            # 作者名稱
+    "author_id": str,         # 作者 ID
+    "content": str,           # 文本內容（情感分析主要讀取此欄位）
+    "title": str,             # 標題（Reddit/YouTube 有，Twitter/IG 無）
+    "timestamp": datetime,    # 發布時間
+    "url": str,               # 原始連結
+    "engagement": {
+        "likes": int,
+        "shares": int,        # 轉推/轉發
+        "comments_count": int,
+        "views": int
+    },
+    "media_urls": list,       # 圖片/影片連結
+    "comments": [             # 留言列表
+        {
+            "comment_id": str,
+            "author": str,
+            "content": str,
+            "timestamp": datetime,
+            "likes": int
+        }
+    ],
+    "topic_id": int,          # 關聯 MindSpider 話題
+    "crawling_task_id": int   # 關聯爬取任務
+}
+```
+
+### 3.3 資料表設計範例（以 Twitter 為例）
+
+```sql
+CREATE TABLE twitter_post (
+    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+    post_id         VARCHAR(64) NOT NULL UNIQUE,
+    author          VARCHAR(255),
+    author_id       VARCHAR(64),
+    content         TEXT,
+    timestamp       DATETIME,
+    url             VARCHAR(512),
+    likes           INT DEFAULT 0,
+    retweets        INT DEFAULT 0,
+    replies         INT DEFAULT 0,
+    views           INT DEFAULT 0,
+    media_urls      JSON,
+    topic_id        INT,
+    crawling_task_id INT,
+    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
+    INDEX idx_topic (topic_id),
+    INDEX idx_timestamp (timestamp)
+);
+
+-- 留言表
+CREATE TABLE twitter_comment (
+    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+    comment_id      VARCHAR(64) NOT NULL UNIQUE,
+    post_id         VARCHAR(64),
+    author          VARCHAR(255),
+    content         TEXT,
+    timestamp       DATETIME,
+    likes           INT DEFAULT 0,
+    topic_id        INT,
+    FOREIGN KEY (post_id) REFERENCES twitter_post(post_id)
+);
+```
+
+其他平台（reddit_post, instagram_post, youtube_comment 等）類比設計。
+
+---
+
+## 4. 擴充實作步驟
+
+### Step 1：安裝依賴
+
+```bash
+pip install twikit praw instaloader facebook-scraper TikTokApi
+pip install google-api-python-client  # YouTube API
+pip install playwright && playwright install chromium  # TikTok 需要
+```
+
+### Step 2：建立抽象基類
+
+```python
+# MindSpider/InternationalCrawler/base_crawler.py
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any
+
+class BaseInternationalCrawler(ABC):
+    """國際平台爬蟲統一介面"""
+
+    @abstractmethod
+    def search_by_keywords(self, keywords: List[str], limit: int = 50) -> List[Dict[str, Any]]:
+        """根據關鍵詞搜尋貼文"""
+        pass
+
+    @abstractmethod
+    def get_comments(self, post_id: str, limit: int = 100) -> List[Dict[str, Any]]:
+        """取得某貼文的留言"""
+        pass
+
+    @abstractmethod
+    def normalize(self, raw_data: Any) -> Dict[str, Any]:
+        """將平台原始數據轉換為統一格式"""
+        pass
+```
+
+### Step 3：實作各平台爬蟲（範例：Twitter）
+
+```python
+# MindSpider/InternationalCrawler/twitter_crawler.py
+import twikit
+from .base_crawler import BaseInternationalCrawler
+
+class TwitterCrawler(BaseInternationalCrawler):
+    def __init__(self, username, password):
+        self.client = twikit.Client()
+        self.client.login(auth_info_1=username, password=password)
+
+    def search_by_keywords(self, keywords, limit=50):
+        query = " OR ".join(keywords)
+        tweets = self.client.search_tweet(query, product='Latest', count=limit)
+        return [self.normalize(t) for t in tweets]
+
+    def get_comments(self, post_id, limit=100):
+        # twikit 支援取得回覆
+        ...
+
+    def normalize(self, tweet):
+        return {
+            "platform": "twitter",
+            "post_id": tweet.id,
+            "author": tweet.user.name,
+            "content": tweet.text,
+            "timestamp": tweet.created_at,
+            "engagement": {
+                "likes": tweet.favorite_count,
+                "shares": tweet.retweet_count,
+                "comments_count": tweet.reply_count,
+                "views": tweet.view_count
+            }
+        }
+```
+
+### Step 4：註冊新平台到 MindSpider
+
+在 `MindSpider/main.py` 中新增：
+
+```python
+# 擴充平台列表
+PLATFORM_CHOICES = ['xhs', 'dy', 'ks', 'bili', 'wb', 'tieba', 'zhihu',
+                    'tw', 'reddit', 'ig', 'fb', 'yt', 'tiktok']
+
+# 擴充別名映射
+PLATFORM_ALIASES.update({
+    'twitter': 'tw', 'x': 'tw', 'x.com': 'tw',
+    'reddit': 'reddit',
+    'instagram': 'ig',
+    'facebook': 'fb',
+    'youtube': 'yt',
+    'tiktok': 'tiktok',
+})
+```
+
+### Step 5：修改 PlatformCrawler 派發邏輯
+
+在 `platform_crawler.py` 中區分中國/國際平台：
+
+```python
+CHINESE_PLATFORMS = {'xhs', 'dy', 'ks', 'bili', 'wb', 'tieba', 'zhihu'}
+INTERNATIONAL_PLATFORMS = {'tw', 'reddit', 'ig', 'fb', 'yt', 'tiktok'}
+
+def run_crawler(self, platform, keywords):
+    if platform in CHINESE_PLATFORMS:
+        # 現有 MediaCrawler 子進程邏輯
+        self._run_mediacrawler(platform, keywords)
+    elif platform in INTERNATIONAL_PLATFORMS:
+        # 新增國際爬蟲邏輯
+        crawler = self._get_international_crawler(platform)
+        results = crawler.search_by_keywords(keywords)
+        self._save_to_db(platform, results)
+```
+
+---
+
+## 5. 優先順序建議
+
+根據穩定性、實用性和實作難度排序：
+
+| 優先級 | 平台 | 理由 | 預估工時 |
+|--------|------|------|---------|
+| 1 | **Reddit** | 官方 API 免費好用，數據品質高，討論型內容最適合輿情分析 | 1-2 天 |
+| 2 | **YouTube** | 官方 API 免費穩定，留言量大，覆蓋面廣 | 1-2 天 |
+| 3 | **Twitter/X** | 輿情核心平台，twikit 積極維護，但需帳號且有封號風險 | 2-3 天 |
+| 4 | **TikTok** | 年輕群體輿情重要來源，需 Playwright 環境 | 2-3 天 |
+| 5 | **Instagram** | 反爬最嚴格，需代理 IP，維護成本高 | 3-5 天 |
+| 6 | **Facebook** | API 限制最多，用戶流失中，ROI 最低 | 3-5 天 |
+
+---
+
+## 6. 費用與風險
+
+### 6.1 費用
+
+| 項目 | 費用 |
+|------|------|
+| Reddit API | 免費（中等規模） |
+| YouTube Data API v3 | 免費（10,000 單位/天） |
+| Twitter/X 官方 API | $100~$5,000/月（不建議，用 twikit 替代） |
+| 所有非官方爬蟲工具 | 免費開源 |
+| 住宅代理 IP（IG/FB 需要） | ~$5-15/GB |
+
+### 6.2 風險矩陣
+
+| 風險 | 嚴重程度 | 受影響平台 | 緩解措施 |
+|------|---------|-----------|---------|
+| 爬蟲工具失效（平台更新反爬） | 高 | IG > FB > Twitter > TikTok | 每個平台準備備選工具 |
+| 帳號被封禁 | 中 | Twitter, Instagram | 使用一次性帳號，多帳號輪換 |
+| IP 被封鎖 | 中 | Instagram, Facebook | 使用住宅代理 IP 池 |
+| 違反平台 ToS | 低 | 所有平台 | 僅用於研究/個人用途 |
+| API 收費策略變動 | 低 | Reddit, YouTube | 控制使用量，關注官方公告 |
+
+### 6.3 各平台失效頻率預估
+
+```
+穩定 ←────────────────────────────→ 不穩定
+YouTube API  >  Reddit API  >  TikTok  >  Twitter  >  Facebook  >  Instagram
+（官方 API）    （官方 API）   （Playwright）（內部 API）  （HTML 解析）  （反爬最強）
+```
+
+---
+
+## 7. MiroFish 協同使用
+
+### 7.1 BettaFish + MiroFish 工作流
+
+```
+┌──────────────────────────────────────────────────┐
+│              完整輿情工作流                         │
+│                                                    │
+│  ① BettaFish 監控（已發生的事）                     │
+│     MindSpider 爬取真實社群數據                     │
+│     → InsightEngine 情感分析                        │
+│     → ReportEngine 產出輿情報告 (PDF)               │
+│              │                                     │
+│              ▼                                     │
+│  ② MiroFish 預測（可能發生的事）                    │
+│     上傳 BettaFish 報告                            │
+│     → 建構知識圖譜                                  │
+│     → 生成模擬 Agent                                │
+│     → 多 Agent 社群模擬                             │
+│     → 產出預測報告 + 與 Agent 對話                   │
+│              │                                     │
+│              ▼                                     │
+│  ③ 驗證與迭代                                      │
+│     BettaFish 持續監控 → 驗證 MiroFish 預測          │
+└──────────────────────────────────────────────────┘
+```
+
+### 7.2 應用場景
+
+| 場景 | BettaFish | MiroFish |
+|------|-----------|----------|
+| 品牌危機公關 | 監控當前負面輿論 | 模擬不同公關策略效果 |
+| 政策發布 | 爬取民眾即時反應 | 預測後續輿論發酵方向 |
+| 產品上市 | 收集用戶真實評價 | 模擬競品反擊後的市場反應 |
+| 國際輿情 | 爬取 Twitter/Reddit 真實討論 | 模擬國際社群傳播路徑 |
+
+---
+
+## 參考連結
+
+### 爬蟲工具
+
+- twikit: https://github.com/d60/twikit
+- twscrape: https://github.com/vladkens/twscrape
+- PRAW: https://github.com/praw-dev/praw
+- Instaloader: https://github.com/instaloader/instaloader
+- Instagrapi: https://github.com/subzeroid/instagrapi
+- facebook-scraper: https://github.com/kevinzg/facebook-scraper
+- youtube-comment-downloader: https://github.com/egbertbouman/youtube-comment-downloader
+- TikTok-Api: https://github.com/davidteather/TikTok-Api
+- Douyin_TikTok_Download_API: https://github.com/Evil0ctal/Douyin_TikTok_Download_API
+- snscrape: https://github.com/JustAnotherArchivist/snscrape
+- yt-dlp: https://github.com/yt-dlp/yt-dlp
+
+### 官方 API
+
+- YouTube Data API v3: https://developers.google.com/youtube/v3
+- Reddit API: https://www.reddit.com/dev/api
+- X/Twitter API v2: https://developer.x.com/en/docs/x-api
+
+### 相關專案
+
+- BettaFish (微輿): https://github.com/virus11456/BettaFish
+- MiroFish: https://github.com/666ghj/MiroFish
+- MediaCrawler: https://github.com/NanmiCoder/MediaCrawler