跳转到内容

分离工作节点

对于拥有大量关注者的高流量实例,您可以通过将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/dahlia/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/dahlia/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/dahlia/hollo:latest
restart: unless-stopped
depends_on:
- db
environment:
- NODE_TYPE=worker
# ... 其他环境变量 ...
worker-2:
image: ghcr.io/dahlia/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)
  • 监控所有节点的日志以查找错误和性能问题