分離工作節點
對於擁有大量追蹤者的高流量實例,您可以透過將 Web 伺服器與後台工作器分離來 提高效能。這使您能夠根據工作負載獨立擴展每個元件。
何時考慮工作器分離
Section titled “何時考慮工作器分離”在以下情況下,工作器分離是有益的:
- 您有數千個追蹤者並且活動傳遞緩慢
- 您的實例處理大量聯邦流量(大量傳入/傳出的貼文)
- 在尖峰活動時間 Web 伺服器回應性下降
- 您希望跨多個伺服器進行橫向擴展
Hollo 由六個主要元件組成:
- Web 伺服器:處理 HTTP 請求(API、Web UI)
- Fedify 訊息佇列:處理 ActivityPub inbox/outbox 訊息
- 匯入工作器:處理後台資料匯入作業
- 清理工作器:處理後台清理作業
- 遠端回覆抓取工作器:緩慢抓取遠端回覆集合
- 投票通知任務:到期後通知本地作者與投票者
預設情況下(NODE_TYPE=all),所有六個都在單一程序中執行。
您可以使用 NODE_TYPE 環境變數來分離它們:
NODE_TYPE |
Web 伺服器 | Fedify 佇列 | 匯入工作器 | 清理工作器 | 回覆工作器 | 投票通知 |
|---|---|---|---|---|---|---|
all(預設) |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
web |
✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
worker |
✗ | ✓ | ✓ | ✓ | ✓ | ✓ |
匯入與清理任務
Section titled “匯入與清理任務”匯入與清理透過獨立 PostgreSQL 佇列中的 Fedify 任務執行,每個工作器程序 最多同時處理四個項目。Web 節點註冊並提交任務,但不消費佇列。工作器和組合節點 每分鐘依種類檢查最多 100 個活動作業,復原遺漏的提交與中斷的處理。 復原掃描本身不執行項目。進度統計最終結果,而非已領取的項目。
升級前請停止所有舊版 Web 與工作器節點,套用資料庫遷移,再部署相同版本到 所有節點。請勿混用不同的任務定義。現有待處理及處理中項目會復原;不完整的舊版 上傳作業會標示為失敗,需要重新提交。現有聯邦佇列及其訊息保持不變。
每個工作器最多使用 24 個資料庫連線:主要連線池 20 個,項目鎖專用連線 4 個。 佇列隔離不隔離 CPU 或儲存負載。關閉時停止新嘗試,最多等待 30 秒;強制結束的 項目可在重啟後復原。暫時錯誤每隔 5 秒重試,記錄五次失敗後終止;程序退出不計入 失敗次數。中斷後外部活動可能使用已儲存的 ID 重複投遞。已提交的匯入關係仍會投遞已儲存的活動,即使在重試期間取消工作。取消可阻止新工作, 但不會撤銷已經執行的操作。
所有節點共享相同的 PostgreSQL 資料庫,該資料庫使用 LISTEN/NOTIFY
作為訊息佇列後端進行即時訊息傳遞。
遠端回覆收集任務
Section titled “遠端回覆收集任務”遠端回覆收集與匯入和清理共用專用任務佇列。每個工作器最多同時執行四個 應用程式任務,其中收集最多兩個。佇列限制計算可立即執行的訊息,因此延遲預約 不會阻塞其他工作。PostgreSQL 作業和主機記錄繼續在工作器之間維護集合冷卻、 要求間隔和 HTTP 429 退避。正常執行與重試預約使用任務。啟動時及每分鐘的 復原掃描分別檢查最多 100 個過期作業和孤立主機租約,並提交最多 50 個可執行 收集任務;掃描本身不擷取遠端集合。交易內建立的作業在提交後由復原掃描預約。
升級前停止所有舊版節點,並為所有節點部署相容的任務定義。現有待處理作業會 復原,處理中作業在 15 分鐘心跳租約過期後回收。關閉時中斷等待,並將已結束的 嘗試恢復為待處理狀態;強制終止後等待租約過期。HTTP 429 按記錄時間重試, 其他收集錯誤仍以失敗結束。現有環境變數和本地行為者的認證擷取行為保持不變。
投票通知任務
Section titled “投票通知任務”投票到期通知也使用專用 Fedify 任務佇列。Web 節點預約任務,工作器與組合節點 重新讀取目前到期時間與本地接收者後執行。修改到期時間或重複訊息不會提前通知或 重複計數。很遠的到期時間分為最長七天的預約;實際執行可能晚於記錄的到期時間。
啟動時及每分鐘的復原掃描,每次預約最多 100 個缺少通知的已到期投票。即使前面的 任務尚未完成或失敗,掃描仍推進位置,復原現有投票、停機期間到期的投票、commit 後 預約失敗及耗盡重試的任務。掃描本身不建立通知。延遲訊息不計入就緒佇列的負載限制。 暫時錯誤以指數 backoff 最多嘗試三次,之後仍可由復原重新預約。關閉時等待執行中的 交易結束,中斷的工作可復原。升級前停止舊節點,並在所有節點使用相容的任務定義。
共享資料庫最多儲存 100 條待處理投票訊息,包括延遲喚醒與重試。新預約按每個 投票合併為一條訊息。重複投票與到期更新會合併;到期提前時,現有喚醒也提前; 到期延後時,執行時重新讀取。達到上限後,更早的喚醒取代最晚的訊息。被延後或 取代的投票在到期後復原。突發負載導致入列鎖無法在一秒內取得時也可能延後。 上限由所有節點共享,而非按工作節點計算,限制儲存的任務數而非通知或執行的處理器。
延遲喚醒使用佇列每五秒的輪詢,不為每個工作節點分配計時器。共享就緒訊息達到 200 條時,復原仍會暫停。100 條上限等於一頁復原批次,並不保證吞吐量。升級前 停止所有舊的生產節點。舊訊息也計入上限,但已超過 100 條的積壓會逐漸減少; 新預約不會增加該積壓。
hollo.poll-notifications.queue 日誌以 warning 級別報告容量延後、喚醒取代與
鎖逾時,每個原因、每個程序每分鐘最多一次。用下面的 SQL 觀察儲存壓力。入列計數
包含合併及延後的嘗試,不代表儲存訊息數。
SELECT count(*) AS queued, count(*) FILTER (WHERE created + delay <= CURRENT_TIMESTAMP) AS ready, count(*) FILTER (WHERE created + delay > CURRENT_TIMESTAMP) AS delayed, count(*) FILTER ( WHERE message->>'type' = 'task' AND message->>'taskName' = 'hollo.poll-notification.v1' ) AS pending_pollsFROM hollo_task_message_v1;Docker Compose 設定
Section titled “Docker Compose 設定”以下是執行單獨的 Web 和工作節點的 compose.yaml 範例:
services: db: image: postgres:17-alpine restart: unless-stopped environment: POSTGRES_USER: hollo POSTGRES_PASSWORD: password POSTGRES_DB: hollo volumes: - ./data/postgres:/var/lib/postgresql/data
web: image: ghcr.io/fedify-dev/hollo:latest restart: unless-stopped depends_on: - db ports: - "3000:3000" environment: - NODE_TYPE=web - DATABASE_URL=postgresql://hollo:password@db/hollo - SECRET_KEY=${SECRET_KEY} - DRIVE_DISK=fs - FS_STORAGE_PATH=/data/storage - STORAGE_URL_BASE=https://hollo.example.com/assets - BEHIND_PROXY=true volumes: - ./data/storage:/data/storage
worker: image: ghcr.io/fedify-dev/hollo:latest restart: unless-stopped depends_on: - db environment: - NODE_TYPE=worker - DATABASE_URL=postgresql://hollo:password@db/hollo - SECRET_KEY=${SECRET_KEY} - DRIVE_DISK=fs - FS_STORAGE_PATH=/data/storage - STORAGE_URL_BASE=https://hollo.example.com/assets volumes: - ./data/storage:/data/storage要執行多個工作節點,請新增更多工作服務:
services: # ... db 和 web 服務 ...
worker-1: image: ghcr.io/fedify-dev/hollo:latest restart: unless-stopped depends_on: - db environment: - NODE_TYPE=worker # ... 其他環境變數 ...
worker-2: image: ghcr.io/fedify-dev/hollo:latest restart: unless-stopped depends_on: - db environment: - NODE_TYPE=worker # ... 其他環境變數 ...PostgreSQL 的 LISTEN/NOTIFY 確保每條訊息只由一個工作器處理。
對於手動安裝,您可以使用不同的 NODE_TYPE 值執行單獨的程序。
Web 節點
Section titled “Web 節點”NODE_TYPE=web pnpm prod這僅在設定的連接埠上啟動 Web 伺服器。
NODE_TYPE=worker pnpm prod# 或pnpm worker這將啟動 Fedify 訊息佇列和匯入工作器,但不啟動 Web 伺服器。
Systemd 範例
Section titled “Systemd 範例”如果您使用 systemd,請建立單獨的服務檔案:
/etc/systemd/system/hollo-web.service
Section titled “/etc/systemd/system/hollo-web.service”[Unit]Description=Hollo Web ServerAfter=network.target postgresql.service
[Service]Type=simpleUser=holloWorkingDirectory=/opt/holloEnvironment="NODE_TYPE=web"EnvironmentFile=/opt/hollo/.envExecStart=/usr/bin/pnpm prodRestart=on-failure
[Install]WantedBy=multi-user.target/etc/systemd/system/hollo-worker.service
Section titled “/etc/systemd/system/hollo-worker.service”[Unit]Description=Hollo WorkerAfter=network.target postgresql.service
[Service]Type=simpleUser=holloWorkingDirectory=/opt/holloEnvironment="NODE_TYPE=worker"EnvironmentFile=/opt/hollo/.envExecStart=/usr/bin/pnpm workerRestart=on-failure
[Install]WantedBy=multi-user.target然後啟用並啟動兩個服務:
sudo systemctl enable hollo-web hollo-workersudo systemctl start hollo-web hollo-worker檢查工作器狀態
Section titled “檢查工作器狀態”對於 Docker Compose:
# 查看 Web 節點記錄docker compose logs -f web
# 查看工作節點記錄docker compose logs -f worker對於 systemd:
# 查看 Web 節點記錄sudo journalctl -u hollo-web -f
# 查看工作節點記錄sudo journalctl -u hollo-worker -f工作器記錄訊息
Section titled “工作器記錄訊息”當工作節點啟動時,您應該看到:
Worker started (Fedify activity/task queues + Job recovery)觀察有關處理活動、匯入、清理和遠端回覆抓取的訊息,以確認工作器正常執行。
Web 節點運作但活動未被處理
Section titled “Web 節點運作但活動未被處理”問題:您可以存取 Web UI,但傳入的活動(追蹤、按讚、貼文)未被處理。
解決方案:確保至少有一個使用 NODE_TYPE=worker 的工作節點正在執行。
工作節點無法啟動
Section titled “工作節點無法啟動”問題:工作節點退出並顯示錯誤。
解決方案:檢查:
DATABASE_URL是否正確且資料庫可存取- 資料庫是否已套用最新的資料庫遷移
- 儲存設定(
DRIVE_DISK、FS_STORAGE_PATH等)是否正確
活動處理緩慢
Section titled “活動處理緩慢”問題:處理聯邦活動存在延遲。
解決方案:新增更多工作節點以並行處理訊息。PostgreSQL 的訊息佇列將在所有可用工作器之間分配工作。
儲存存取錯誤
Section titled “儲存存取錯誤”問題:工作節點無法存取上傳的檔案。
解決方案:確保:
- 所有節點(Web 和工作器)都可以存取相同的儲存
- 對於檔案系統儲存:儲存卷已掛載到所有節點
- 對於 S3 儲存:所有節點具有相同的 S3 憑證
- Web 節點:輕量級,可以使用最少的資源執行(512MB-1GB RAM)
- 工作節點:資源密集型,特別是在高聯邦活動期間(建議 1GB-2GB RAM)
- 資料庫:由所有節點共享;確保它有足夠的資源 (對於繁忙的實例建議 2GB+ RAM)
- 並行數:每個工作器透過獨立佇列同時處理最多 10 條 ActivityPub 訊息和 4 個應用程式任務。遠端回覆收集最多占用這 4 個任務名額中的 2 個。 限制按工作器程序計算,增加工作器會提高總並行數。
- 從
NODE_TYPE=all(預設)開始,直到遇到效能問題 - 監控資源使用情況以確定何時需要分離
- 使用
NODE_TYPE=web時至少執行一個專用工作節點 - 在 Web 節點前使用反向代理(nginx、Caddy)進行負載均衡
- 保持儲存對所有節點可存取(共享卷或 S3)
- 監控所有節點的記錄以查找錯誤和效能問題