threads-dlp

一個專為 Threads.net 設計的影片下載與自動化發布工具。

English Version

---

threads-dlp 是一個強大的命令列工具，它整合了爬取、下載、資料庫管理、AI 元數據生成、自動化 YouTube 上傳以及雲端部署等完整功能。

它不依賴官方 API 或脆弱的 HTML 解析，而是透過 Cookie 認證 登入，並 智慧地攔截網路流量 來精準獲取影片。這個方法確保了在高動態、需要登入的網站環境下，依然能穩定、高效地運作。

整個專案已針對 Zeabur 平台進行了完整的容器化與自動化部署設定。

線上儀表板 (Live Dashboard)

點擊上方藍色徽章，查看此專案自動抓取並分析的熱門影片資料庫。

帳號: admin / 密碼: password!

---

✨ 功能特性

• 安全的 Cookie 認證：無需輸入帳號密碼，透過瀏覽器 Cookie 安全登入，保護您的帳號隱私。
• 智慧型網路嗅探：不同於傳統的 HTML 爬蟲，本工具直接分析網路流量，精準捕獲影片資源，成功率更高。
• 多模式爬取：支援針對特定用戶、關鍵字搜尋結果或個人首頁推薦進行爬取。
• 自動化上傳：整合 youtubeuploader，可將下載的影片自動上傳至 YouTube。
• AI 智慧標籤：使用 Google Gemini API 自動為影片生成標題、描述與標籤。
• 排程發布：支援立即發布、預約發布以及間隔發布等多種 YouTube 發布策略。
• 資料庫管理：使用 SQLite 儲存影片元數據，避免重複下載。
• 網頁儀表板：整合 Datasette，提供一個網頁介面來瀏覽與查詢儲存在 SQLite 中的資料。
• 雲端原生：提供完整的 Dockerfile 與 Procfile，可一鍵部署至 Zeabur 等支援容器的雲端平台。
• 磁碟空間管理：自動監控並清理已上傳的影片檔案，防止磁碟空間耗盡。

🚀 快速開始

先決條件:

• Python 3.10+
• Google Chrome
• (推薦) uv - 一個極速的 Python 套件安裝器。

1. 安裝工具

建議使用 uv 或 pip 直接從 PyPI 安裝，這是最簡單的方式。

# 使用 uv (推薦)
uv pip install threads-dlp-layorx

# 或者使用 pip
pip install threads-dlp-layorx

2. 建立 .env 設定檔

在您要執行此工具的資料夾中，建立一個名為 .env 的檔案，並填入以下內容：

# 必填：Threads 的 sessionid Cookie
# 如何獲取：登入 Threads 網站，打開瀏覽器開發者工具 (F12)，在 Application -> Cookies 中找到 sessionid 的值。
THREADS_SESSION_COOKIE="在這裡填入你的 sessionid"

# --- 以下為自動上傳功能所需變數 (可選) ---

# 必填：Google Gemini API 金鑰 (用於生成影片標題和描述)
# 如何獲取：前往 Google AI Studio (https://aistudio.google.com/) 取得。
GEMINI_API_KEY="在這裡填入你的 Gemini API 金鑰"

提示: 完整的 YouTube API 變數 (YT_CLIENT_SECRETS, YT_REQUEST) 主要為雲端部署設計。在本地端，您只需先依照後續教學生成 client_secrets.json 和 request.token 檔案並放置於同目錄下即可。

3. 開始使用！

現在，您可以執行 threads-dlp 命令了。

# 下載指定用戶的影片 (例如 zuck)
threads-dlp -t zuck

# 下載後自動上傳到 YouTube
# (首次執行會引導您完成 YouTube API 授權)
threads-dlp -t zuck --upload

---

🐳 本地 Docker 部署 (進階)

如果您偏好使用 Docker 來獲得與雲端一致的環境，可以依照以下步驟在本地運行。

先決條件:

• 已安裝 Docker Desktop

1. 克隆專案並準備環境

您需要先將專案克隆到本地，因為 Docker 需要讀取 Dockerfile 和您的設定檔。

git clone https://github.com/LayorX/threads-dlp.git
cd threads-dlp

2. 建立 .env 設定檔

與快速開始的步驟相同，在專案根目錄建立一個 .env 檔案，並至少填入 THREADS_SESSION_COOKIE。Docker 會將這個檔案裡的變數全部載入到容器中。

THREADS_SESSION_COOKIE="在這裡填入你的 sessionid"
GEMINI_API_KEY="在這裡填入你的 Gemini API 金鑰"
# 如果需要，也可以將 YT_CLIENT_SECRETS 和 YT_REQUEST 填入

3. 建置 Docker 映像

在專案根目錄下執行以下指令來建置 Docker 映像。

docker build -t threads-dlp .

4. 執行 Docker 容器

此指令會啟動一個背景容器，並將本地的 db 和 downloads 資料夾掛載進去，以確保資料永久保存。

# 確保本地存在 db 和 downloads 資料夾
mkdir -p db downloads

docker run -d \
  --name threads-dlp-container \
  --env-file ./.env \
  -v "$(pwd)/db:/home/appuser/db" \
  -v "$(pwd)/downloads:/home/appuser/downloads" \
  -p 8081:8080 \
  threads-dlp

Windows 用戶注意: 在 CMD 中，請將 $(pwd) 替換為 %cd%。

5. 驗證與管理

• 查看日誌:

  docker logs -f threads-dlp-container

• 訪問儀表板: 打開瀏覽器，訪問 http://localhost:8081。

• 停止並移除容器:

  docker stop threads-dlp-container
  docker rm threads-dlp-container

📖 使用方法

threads-dlp (主程式/下載器)

短格式	長格式	功能說明	預設值
-t	--target	指定要爬取的 Threads 用戶名稱。	None (爬取首頁)
-s	--search	根據關鍵字進行搜尋並爬取結果。	None
-r	--scroll	模擬頁面向下滾動的次數，數字越大爬取越深。	3
-o	--output	指定儲存下載影片的資料夾路徑。	downloads
-l	--language	設定日誌輸出的語言。	zh-TW
-u	--upload	下載完成後，自動執行上傳任務。	False
-du	--deleteupload	(需與 -u 並用) 設定清理閾值 (GB)。當 downloads 資料夾大小超過此值，將自動刪除已上傳的影片。	0.8
-n	--num_videos	(需與 -u 並用) 指定上傳影片的數量上限。	無限制
-d	--debug	啟用詳細日誌輸出模式，方便偵錯。	False

使用範例

# 下載指定用戶的影片，並指定儲存位置與爬取深度
threads-dlp -t zuck -r 10 -o zuck_videos

# 根據關鍵字搜尋並下載
threads-dlp -s "funny cats"

# 下載首頁推薦的影片 (不帶 -t 或 -s 參數)
threads-dlp

# 下載後自動觸發上傳，並設定磁碟清理閾值為 0.5 GB
threads-dlp -t zuck -u -du 0.5

uploader (獨立上傳器)

此命令負責檢查資料庫中尚未上傳的影片，並將它們發布到 YouTube。

短格式	長格式	功能說明	預設值
-du	--deleteupload	設定清理閾值 (GB)。	0.8
-n	--num_videos	指定本次上傳影片的數量上限。	無限制

使用範例

# 獨立執行上傳任務
threads-dlp uploader

# 上傳時自訂清理閾值為 1.5 GB
threads-dlp uploader -du 1.5

view_db (資料庫查看器)

一個在命令列中快速查看資料庫內容的工具。

threads-dlp view_db

🔑 YouTube API 設定 (自動上傳功能)

重要提醒： 如果您的 Google Cloud 專案的 OAuth 同意畫面處於「測試」狀態，則生成的 request.token 只有 7 天 的有效期。若要獲得長期有效的 token，請務必在 Google Cloud Console 中將您的應用程式「發布」為正式版。發布後，您需要重新生成一次 request.token。

若要使用自動上傳至 YouTube 的功能 (--upload)，您必須先完成 Google API 的授權設定。此過程遵循 youtubeuploader 的官方指南，分為兩大步：獲取 client_secrets.json 和生成 request.token。

步驟 1：獲取 client_secrets.json

此檔案相當於您的應用程式的「鑰匙」，讓 Google 知道是您的程式在請求上傳。

1. 前往 Google Cloud Console:

   • 登入您的 Google 帳號，然後進入 Google Cloud Console。

2. 建立新專案:

   • 在頁面頂部，點擊專案選單，然後選擇「新增專案」。
   • 為專案命名（例如 Threads Uploader），然後點擊「建立」。

3. 啟用 YouTube Data API v3:

   • 在左側導覽列中，找到「API 和服務」 > 「已啟用的 API 和服務」。
   • 點擊頂部的「+ 啟用 API 和服務」。
   • 搜尋「YouTube Data API v3」並點擊進入，然後點擊「啟用」。

4. 設定 OAuth 同意畫面:

   • 在左側導覽列中，點擊「OAuth 同意畫面」。
   • 選擇「外部」，然後點擊「建立」。
   • 填寫應用程式名稱（例如 My Uploader），並選擇您的電子郵件。其他欄位暫時可以留空。
   • 在「測試使用者」步驟中，點擊「+ ADD USERS」，然後輸入您要用來上傳影片的那個 Google 帳號的 Email。這是非常重要的一步，否則後續授權會失敗。
   • 儲存並繼續，直到完成設定。

5. 建立憑證 (OAuth 用戶端 ID):

   • 在左側導覽列中，點擊「憑證」。
   • 點擊頂部的「+ 建立憑證」，然後選擇「OAuth 用戶端 ID」。
   • 在「應用程式類型」中，選擇「Web 應用程式」(Web application)。
   • 為其命名（例如 youtubeuploader-creds）。
   • 在「已授權的重新導向 URI」部分，點擊「+ 新增 URI」，然後輸入 http://localhost:8080/oauth2callback。
   • 點擊「建立」。

6. 下載憑證檔案:

   • 建立成功後，您會在憑證列表中看到剛剛建立的用戶端。
   • 點擊最右側的「下載 JSON」圖示。
   • 將下載的檔案重新命名為 client_secrets.json，並將它放置在您執行 threads-dlp 的目錄下。

步驟 2：生成 request.token

此檔案是您個人帳號授權給此應用程式的「通行證」。

1. 執行一次上傳指令:
   • 確保 client_secrets.json 已經放在當前目錄。
   • 在命令列中執行一次需要上傳的指令，例如：

     threads-dlp -t zuck --upload

2. 完成瀏覽器授權:
   • 程式會自動在您的瀏覽器中打開一個 Google 授權頁面，並在命令列中顯示一個 localhost 開頭的網址。
   • 複製該網址，並在瀏覽器中打開。
   • 登入您在「測試使用者」步驟中設定的那個 Google 帳號。
   • 同意授權請求。
   • 授權成功後，頁面會重新導向到一個無法顯示的 localhost 頁面，這是正常的。請將這個重新導向後的網址完整複製下來。
3. 貼上授權碼:
   • 回到您的命令列，程式會提示您貼上剛剛複製的網址。
   • 貼上網址並按下 Enter。
4. 生成 Token:
   • 驗證成功後，程式會自動在當前目錄下生成一個名為 request.token 的檔案。

完成以上步驟後，您的專案就擁有了完整的自動上傳權限。client_secrets.json 和 request.token 都應被視為機密檔案，切勿將它們分享或提交到 Git 倉庫中。

---

☁️ Zeabur 雲端部署指南

本專案已完全針對 Zeabur 進行優化，可實現一鍵部署與自動化運行。

步驟 1：Fork 專案

點擊本 GitHub 倉庫右上角的 Fork 按鈕，將此專案複製到你自己的 GitHub 帳號下。

步驟 2：在 Zeabur 上建立專案

1. 登入 Zeabur 控制台。
2. 建立一個新專案，並授權 Zeabur 讀取你的 GitHub 倉庫。
3. 選擇你剛剛 Fork 的 threads-dlp 倉庫進行部署。

步驟 3：設定服務與啟動指令

Zeabur 會自動偵測到 Dockerfile，並根據 Procfile 來啟動不同的進程：

• web: 運行 Datasette 服務，提供公開的網頁儀表板。
• worker: 運行主要的爬蟲排程器 (scheduler.py)，在背景定時執行任務。

步驟 4：設定永久性磁碟 (非常重要)

為了確保你的資料庫和影片不會因為服務重啟而遺失，也為了避免因使用暫存檔案系統而被收取不必要的記憶體費用，你必須為儲存路徑掛載一個永久性磁碟。

1. 在 Zeabur 專案頁面，點擊 Volumes 分頁。
2. 點擊 Create Volume。
3. 建立兩個磁碟區，並將它們分別掛載到以下路徑：
   • Mount Path 1: /home/appuser/db (用於儲存資料庫檔案)
   • Mount Path 2: /home/appuser/downloads (用於儲存下載的影片)

警告: 如果你跳過這一步，所有下載的影片和資料庫紀錄都會在每次服務重啟或重新部署後全部遺失。

步驟 5：設定環境變數

在 Zeabur 專案的 Variables 分頁中，新增以下所有環境變數：

變數名稱	說明
THREADS_SESSION_COOKIE	(必填) 用於登入 Threads 的 sessionid Cookie。
GEMINI_API_KEY	(必填) Google Gemini API 金鑰。

| YT_CLIENT_SECRETS | (必填) client_secrets.json 的單行內容。 | | YT_REQUEST | (必填) request.token 的單行內容。 | | ADMIN_PASSWORD_HASH | (可選) Datasette 儀表板的密碼雜湊值。预设值为 password!。| | UPLOAD_THRESHOLD | (可選) 觸發上傳的待處理影片數量。預設為 5。 | | UPLOAD_TIME_UTC | (可選) 每日固定執行上傳的時間（UTC）。例如 10:00。 | | THREADS_SCROLL_COUNT | (可選) 每次爬取時的滾動次數。預設為 5。 | | PUBLISH_NOW | (可選) 是否立即發布第一部影片。true 或 false，預設為 true。 | | PUBLISH_START_FROM_HOURS| (可選) 首部影片的預約發布延遲（小時）。預設為 0。 | | PUBLISH_INTERVAL_HOURS | (可選) 影片之間的發布時間間隔（小時）。預設為 4。 |

步驟 6：完成部署

儲存所有環境變數後，Zeabur 會自動重新部署你的服務。部署成功後，你就可以透過 Zeabur 提供的網址訪問儀表板，worker 服務也會在背景自動運行。

📖 使用方法

YouTube Uploader

本專案的自動上傳功能，是透過呼叫由 porjo 開發的強大開源工具 youtubeuploader 來實現的。為了兼顧本地開發與雲端部署，專案內建了跨平台策略：

• Windows (本地開發): 專案中直接包含了 youtubeuploader.exe。
• Linux (雲端部署): Dockerfile 會在建置映像時，自動下載其最新的 Linux 版本。

從原始碼安裝 (開發者)

如果你想對本專案進行二次開發，請依照以下步驟：

1. 克隆專案

   git clone https://github.com/LayorX/threads-dlp.git
   cd threads-dlp

2. 安裝 uv

   # Windows (PowerShell)
   irm https://astral.sh/uv/install.ps1 | iex
   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

3. 建立虛擬環境並同步依賴

   uv sync

4. 執行程式

   uv run python main.py --help

⚠️ 免責聲明

本工具僅供技術研究與學習之用。下載的影片版權歸原作者所有。請尊重版權，並遵守 Threads 的服務條款。任何因使用本工具而導致的版權糾紛或法律問題，開發者概不負責。