Threads Analytics 是一個搭配 PostgreSQL 資料庫的 Next.js 應用程式。在自己管理的伺服器上，用 Docker Compose 最快：一個檔案就能把應用程式和資料庫一起啟動。也可以把預先建置好的 Docker 映像檔接到既有的資料庫、從原始碼建置，或部署到 Vercel、改由 Cron Job 負責同步。這篇整理每種方式需要準備什麼、怎麼讓貼文持續自動同步，以及之後如何更新。

不想自己動手設定的話，Railway 和 Vercel 都有一鍵範本與 Agent 部署 Prompt，可以幫你全部處理好。

事前準備

  • PostgreSQL 資料庫。代管服務或架在自己伺服器上的都可以，應用程式只需要它的連線字串。用 Docker Compose 的話會一併建立。
  • 執行應用程式的地方。能跑 Docker 映像檔（amd64 或 arm64）的伺服器、Vercel，或任何裝了 Node.js 22.12+ 或 24+ 的機器。
  • Threads Access Token。部署完成後再到儀表板貼上，產生方式請看 Token 生成教學。

環境變數

不論用哪種方式執行都要設定這些變數：Docker 寫在 env 檔、Vercel 設在專案設定，從原始碼執行則寫在 .env.local。

變數必填用途
APP_PASSWORD是登入儀表板用的密碼。
DATABASE_URL是PostgreSQL 連線字串。
TOKEN_ENCRYPTION_KEY是加密存在資料庫裡的 Threads Access Token，可用 openssl rand -hex 32 產生。
SYNC_SCHEDULER_ENABLED否設為 true 會啟動內建的同步排程。Docker、VPS、Railway 請設定；Vercel 不要設。
CRON_SECRET否保護 /api/cron/sync，也就是 Cron Job 呼叫來觸發同步的端點。Vercel 必填。

Docker 或 VPS 用的完整 env 檔大概長這樣：

APP_PASSWORD=choose-a-long-password
DATABASE_URL=postgresql://user:password@your-db-host:5432/threads_analytics
TOKEN_ENCRYPTION_KEY=paste-the-output-of-openssl-rand-hex-32
SYNC_SCHEDULER_ENABLED=true

Docker Compose

Repository 裡的 docker-compose.yml 會把儀表板和它專用的 PostgreSQL 一起跑起來，不必先準備資料庫。在伺服器上找一個空資料夾，下載這個檔案，並在旁邊寫一個 .env：

curl -fsSLO https://raw.githubusercontent.com/ridemountainpig/threads-analytics/main/docker-compose.yml
cat > .env <<EOF
APP_PASSWORD=$(openssl rand -hex 12)
TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 16)
EOF
grep APP_PASSWORD .env
docker compose up -d

grep 印出來的 APP_PASSWORD 就是登入用的密碼，記得存起來。想改用你自己的密碼，就修改 .env 再執行一次 docker compose up -d。Compose 會等資料庫就緒、套用 migration，再在 3000 port 提供儀表板，同步排程也已經開好，所以 DATABASE_URL 和 SYNC_SCHEDULER_ENABLED 都不用自己設。.env 裡的其他變數，例如 CRON_SECRET，也會一併傳給應用程式。

貼文和帳號都存在 postgres-data volume 裡，重新啟動或更新都不會消失。用 docker compose logs -f app 可以持續查看伺服器 log。

Docker

如果已經有 PostgreSQL、只想跑應用程式容器，可以直接用發佈在 GitHub Container Registry 的映像檔，支援 amd64 和 arm64。把變數寫進 .env.local 後執行：

docker run -d --name threads-analytics --restart unless-stopped \
  -p 3000:3000 --env-file .env.local \
  ghcr.io/ridemountainpig/threads-analytics:latest

容器每次啟動都會先套用尚未執行的資料庫 migration，再在 3000 port 提供儀表板。需要 HTTPS 的話，在前面加一層反向代理即可。

想自己建置映像檔的話，在 clone 下來的 repository 裡執行：

docker build -t threads-analytics .
docker run -d --name threads-analytics --restart unless-stopped \
  -p 3000:3000 --env-file .env.local threads-analytics

從原始碼執行

需要 Node.js 22.12+ 或 24+，以及 pnpm。

git clone https://github.com/ridemountainpig/threads-analytics.git
cd threads-analytics
pnpm install
pnpm prisma:generate
cp .env.example .env.local  # 接著填入環境變數
pnpm build
pnpm start

pnpm start 會先套用尚未執行的 migration，再在 3000 port 啟動伺服器。可以用 systemd 或 pm2 這類程序管理工具讓它常駐。

Vercel

Vercel 無法讓程序在請求之間持續執行，所以內建的同步排程不會在上面運作，同步要改由 Vercel Cron Job 定期呼叫 /api/cron/sync。

Vercel Agent 部署教學會透過 Vercel MCP 部署預先建置的映像檔，並幫你設定好 Neon 資料庫、環境變數和這個 Cron Job。想自己加 Cron Job 的話，在專案根目錄放一個 vercel.json：

{
  "crons": [{ "path": "/api/cron/sync", "schedule": "0 0 * * *" }]
}

接著在專案的環境變數加上 CRON_SECRET。Vercel 每次執行 Cron 都會帶上 Authorization: Bearer <CRON_SECRET>，沒有帶的請求會被端點拒絕。

Hobby 方案的 Cron Job 一天最多只能跑一次，所以請維持每天一次的排程；付費方案則可以配合你在設定頁選的同步間隔，跑得更頻繁。

讓貼文持續同步

選好同步間隔之前，自動同步都是關閉的。部署完成後，到儀表板的設定 → 自動同步選擇頻率：每小時、每 6 小時、每天，或自訂分鐘數。每次同步都會處理所有已連接的帳號，不只是目前檢視的那一個。

由誰來觸發同步，取決於應用程式跑在哪裡：

  • Docker、VPS 或 Railway：設定 SYNC_SCHEDULER_ENABLED=true（Docker Compose 已經幫你設好）。排程會隨伺服器啟動，定期檢查哪些帳號該同步了。
  • Vercel：使用上面的 Cron Job。
  • 其他環境：任何排程工具都可以帶著 CRON_SECRET 呼叫這個端點。
curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://analytics.example.com/api/cron/sync

呼叫得比同步間隔更頻繁也沒關係，還沒到時間的帳號會直接略過。

更新版本

新版本會以新的 Docker 映像檔發佈，資料庫 migration 也會在啟動時自動執行，所以更新只需要取得新的映像檔或程式碼。貼文、洞察資料和帳號都會留在資料庫裡。

Docker Compose 的話，在放著 docker-compose.yml 的資料夾裡執行：

docker compose pull
docker compose up -d

只用 Docker 的話，拉取新的映像檔，再用相同參數重建容器：

docker pull ghcr.io/ridemountainpig/threads-analytics:latest
docker rm -f threads-analytics
docker run -d --name threads-analytics --restart unless-stopped \
  -p 3000:3000 --env-file .env.local \
  ghcr.io/ridemountainpig/threads-analytics:latest
  • 從原始碼執行：git pull 後依序執行 pnpm install、pnpm prisma:generate、pnpm build，再重新啟動 pnpm start。
  • Railway：在 Railway 控制台重新部署服務。
  • Vercel：重新部署專案。

部署完成後

  1. 打開應用程式，用 APP_PASSWORD 登入。
  2. 到設定 → 新增 Threads 帳號貼上 Access Token。第一次同步會立刻開始，可能需要幾分鐘。
  3. 在設定 → 自動同步選擇同步間隔。

想讓 Claude 或其他 AI Agent 查詢你的數據，可以連接內建的 MCP 伺服器，網址是 /api/mcp。