跳到內容

分離工作節點

對於擁有大量追蹤者的高流量實例,您可以透過將 Web 伺服器與後台工作器分離來 提高效能。這使您能夠根據工作負載獨立擴展每個元件。

在以下情況下,工作器分離是有益的:

  • 您有數千個追蹤者並且活動傳遞緩慢
  • 您的實例處理大量聯邦流量(大量傳入/傳出的貼文)
  • 在尖峰活動時間 Web 伺服器回應性下降
  • 您希望跨多個伺服器進行橫向擴展

Hollo 由六個主要元件組成:

  1. Web 伺服器:處理 HTTP 請求(API、Web UI)
  2. Fedify 訊息佇列:處理 ActivityPub inbox/outbox 訊息
  3. 匯入工作器:處理後台資料匯入作業
  4. 清理工作器:處理後台清理作業
  5. 遠端回覆抓取工作器:緩慢抓取遠端回覆集合
  6. 投票通知任務:到期後通知本地作者與投票者

預設情況下(NODE_TYPE=all),所有六個都在單一程序中執行。 您可以使用 NODE_TYPE 環境變數來分離它們:

NODE_TYPE Web 伺服器 Fedify 佇列 匯入工作器 清理工作器 回覆工作器 投票通知
all(預設) ✓ ✓ ✓ ✓ ✓ ✓
web ✓ ✗ ✗ ✗ ✗ ✗
worker ✗ ✓ ✓ ✓ ✓ ✓

匯入與清理透過獨立 PostgreSQL 佇列中的 Fedify 任務執行,每個工作器程序 最多同時處理四個項目。Web 節點註冊並提交任務,但不消費佇列。工作器和組合節點 每分鐘依種類檢查最多 100 個活動作業,復原遺漏的提交與中斷的處理。 復原掃描本身不執行項目。進度統計最終結果,而非已領取的項目。

升級前請停止所有舊版 Web 與工作器節點,套用資料庫遷移,再部署相同版本到 所有節點。請勿混用不同的任務定義。現有待處理及處理中項目會復原;不完整的舊版 上傳作業會標示為失敗,需要重新提交。現有聯邦佇列及其訊息保持不變。

每個工作器最多使用 24 個資料庫連線:主要連線池 20 個,項目鎖專用連線 4 個。 佇列隔離不隔離 CPU 或儲存負載。關閉時停止新嘗試,最多等待 30 秒;強制結束的 項目可在重啟後復原。暫時錯誤每隔 5 秒重試,記錄五次失敗後終止;程序退出不計入 失敗次數。中斷後外部活動可能使用已儲存的 ID 重複投遞。已提交的匯入關係仍會投遞已儲存的活動,即使在重試期間取消工作。取消可阻止新工作, 但不會撤銷已經執行的操作。

所有節點共享相同的 PostgreSQL 資料庫,該資料庫使用 LISTEN/NOTIFY 作為訊息佇列後端進行即時訊息傳遞。

遠端回覆收集與匯入和清理共用專用任務佇列。每個工作器最多同時執行四個 應用程式任務,其中收集最多兩個。佇列限制計算可立即執行的訊息,因此延遲預約 不會阻塞其他工作。PostgreSQL 作業和主機記錄繼續在工作器之間維護集合冷卻、 要求間隔和 HTTP 429 退避。正常執行與重試預約使用任務。啟動時及每分鐘的 復原掃描分別檢查最多 100 個過期作業和孤立主機租約,並提交最多 50 個可執行 收集任務;掃描本身不擷取遠端集合。交易內建立的作業在提交後由復原掃描預約。

升級前停止所有舊版節點,並為所有節點部署相容的任務定義。現有待處理作業會 復原,處理中作業在 15 分鐘心跳租約過期後回收。關閉時中斷等待,並將已結束的 嘗試恢復為待處理狀態;強制終止後等待租約過期。HTTP 429 按記錄時間重試, 其他收集錯誤仍以失敗結束。現有環境變數和本地行為者的認證擷取行為保持不變。

投票到期通知也使用專用 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_polls
FROM hollo_task_message_v1;

以下是執行單獨的 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 值執行單獨的程序。

終端機視窗
NODE_TYPE=web pnpm prod

這僅在設定的連接埠上啟動 Web 伺服器。

終端機視窗
NODE_TYPE=worker pnpm prod
# 或
pnpm worker

這將啟動 Fedify 訊息佇列和匯入工作器,但不啟動 Web 伺服器。

如果您使用 systemd,請建立單獨的服務檔案:

[Unit]
Description=Hollo Web Server
After=network.target postgresql.service
[Service]
Type=simple
User=hollo
WorkingDirectory=/opt/hollo
Environment="NODE_TYPE=web"
EnvironmentFile=/opt/hollo/.env
ExecStart=/usr/bin/pnpm prod
Restart=on-failure
[Install]
WantedBy=multi-user.target
[Unit]
Description=Hollo Worker
After=network.target postgresql.service
[Service]
Type=simple
User=hollo
WorkingDirectory=/opt/hollo
Environment="NODE_TYPE=worker"
EnvironmentFile=/opt/hollo/.env
ExecStart=/usr/bin/pnpm worker
Restart=on-failure
[Install]
WantedBy=multi-user.target

然後啟用並啟動兩個服務:

終端機視窗
sudo systemctl enable hollo-web hollo-worker
sudo systemctl start hollo-web hollo-worker

對於 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

當工作節點啟動時,您應該看到:

Worker started (Fedify activity/task queues + Job recovery)

觀察有關處理活動、匯入、清理和遠端回覆抓取的訊息,以確認工作器正常執行。

問題:您可以存取 Web UI,但傳入的活動(追蹤、按讚、貼文)未被處理。

解決方案:確保至少有一個使用 NODE_TYPE=worker 的工作節點正在執行。

問題:工作節點退出並顯示錯誤。

解決方案:檢查:

  • DATABASE_URL 是否正確且資料庫可存取
  • 資料庫是否已套用最新的資料庫遷移
  • 儲存設定(DRIVE_DISK、FS_STORAGE_PATH 等)是否正確

問題:處理聯邦活動存在延遲。

解決方案:新增更多工作節點以並行處理訊息。PostgreSQL 的訊息佇列將在所有可用工作器之間分配工作。

問題:工作節點無法存取上傳的檔案。

解決方案:確保:

  • 所有節點(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)
  • 監控所有節點的記錄以查找錯誤和效能問題