Twitter Bookmark Hub

複数の Twitter アカウントのブックマークを収集・閲覧するアプリケーション。

概要

• crawler: 全アカウントのブックマークを定期取得し SQLite に保存
• viewer: 収集したブックマークを Twitter 風 UI で一覧表示
• analyzer (任意): 形態素解析によるタグ抽出とカテゴリ自動分類

前提条件

• Docker / Docker Compose
• data/config.json (アカウント設定ファイル)

セットアップ

1. アカウント設定

data/config.json を作成してください:

{
  "twitter": {
    "accounts": [
      {
        "email": "your-email@example.com",
        "username": "your_username",
        "password": "your_password",
        "otp_secret": null
      }
    ],
    "clientLanguage": "ja"
  }
}

otp_secret は 2 段階認証 (TOTP) を使用している場合に設定します。

clientLanguage は Twitter API クライアントの言語コード (BCP47) です。x-twitter-client-language ヘッダーとして送信され、Grok 翻訳先言語など API レスポンスの言語に影響します。省略時は ja (日本語) になります。

2. 環境変数の設定 (任意)

cp .env.example .env
# .env を編集して設定をカスタマイズ

3. 起動

docker compose up -d

4. Analyzer の有効化 (任意)

analyzer は形態素解析によるタグ抽出とカテゴリ自動分類を行うオプション機能です。 analyzer プロファイルを指定して起動します （ポート 3002、ホストには公開されません）。

# .env に ANALYZER_URL を設定する
echo "ANALYZER_URL=http://analyzer:3002" >> .env

# analyzer プロファイルを有効にして起動
docker compose --profile analyzer up -d

アクセス

サービス	URL
Web UI	http://localhost:3000
Crawler API	http://localhost:3001

環境変数

crawler

変数名	デフォルト	説明
CRAWL_SCHEDULE	0 * * * *	クロールスケジュール (cron 式、デフォルト: 1 時間毎)
CRAWL_ON_STARTUP	true	起動時に即クロール実行
PROXY_SERVER	-	プロキシサーバー
PROXY_USERNAME	-	プロキシ認証ユーザー名
PROXY_PASSWORD	-	プロキシ認証パスワード
TWITTER_COOKIE_ISSUER_URL	-	Cookie issuer の URL。パスワード・OTP を送信しセッション Cookie を受け取るため、信頼できる内部/プライベートネットワークのエンドポイントだけを指定し、公開してはならない
ANALYZER_URL	-	analyzer サービスの URL（設定時にクロール後に自動分析を実行する）

viewer

変数名	デフォルト	説明
CRAWLER_URL	http://crawler:3001	crawler サービスの URL
ANALYZER_URL	-	analyzer サービスの URL（設定時に analyzer 機能が有効になる）

Crawler API

エンドポイント	メソッド	説明
/health	GET	ヘルスチェック
/crawl	POST	クロール手動実行
/crawl/status	GET	最新クロールジョブの状態
/bookmarks	POST	ブックマーク追加（ボディ: {"account": "<username>", "tweetId": "<id>"} ）
/bookmarks/:tweetId	DELETE	ブックマーク削除（クエリ: ?account=<username>）。DB からも即時削除

データ

data/ ディレクトリに以下が保存されます:

ファイル	説明
config.json	アカウント設定
db.sqlite	ブックマーク DB
cookies-{username}.json	Cookie キャッシュ (7 日間有効)