存在多个源仓库时Antora playbook执行崩溃问题咨询

问题成因 #

• 并行克隆触发系统文件描述符上限：Linux默认普通进程的最大打开文件数上限通常为1024，单个Git克隆操作会占用多个文件句柄，50-60个仓库并行拉取时很容易触达上限，内核会直接强制结束进程。
• 老版本依赖存在内存回收缺陷：Antora 2.3内置的isomorphic-git客户端在并行拉取场景下存在明显的临时缓存内存泄漏问题，即便给Node进程分配了大内存，累计的未回收内存仍然会触发系统OOM Killer终止进程，该缺陷在Antora 3.x版本才得到官方修复。
• 内核终止进程无错误输出：当进程被内核发送SIGKILL信号强制终止时，Node进程来不及输出任何堆栈日志，所以即便加了--stacktrace参数也看不到任何报错提示。
• 自定义生成器未做并发限流：如果你的custom-generate-site生成器没有调整内容源拉取的并发配置，Antora 2.3默认会同时启动所有配置的仓库克隆任务，没有队列缓冲，直接打满系统资源。

解决方案 #

快速验证方案 #

先执行以下命令调高当前Shell的文件句柄上限，再重新运行原命令验证问题是否解决：

ulimit -n 65535

如果调整后仍然崩溃，可执行以下优化方案：

调整并发配置（无代码改动，优先级最高） #

在playbook.yaml根级别添加运行时并发限制配置，降低并行拉取的任务数：

runtime:
  fetch:
    concurrency: 5 # 可根据机器配置调整为5-10的低值，避免并行任务过多

降低资源占用优化 #

• 给每个content.sources条目添加edit_url: false配置，关闭元数据拉取逻辑，减少额外资源消耗。
• 替换内置Git客户端：安装原生Git连接器替代默认的JS实现Git客户端，稳定性和资源占用表现更好：
  1. 执行安装命令：npm i @antora/git-connector-legacy
  2. 运行Antora命令时添加参数：--git-connector legacy

彻底修复方案 #

• 条件允许的情况下升级到Antora 3.x版本，该版本官方修复了并行拉取的内存泄漏和并发控制缺陷，相同配置下可支持200+仓库的拉取需求。
• 预克隆所有仓库到本地服务器，将playbook.yaml的content.sources地址改为本地路径，完全跳过远程克隆阶段，稳定性最高。

内容的提问来源于stack exchange，提问作者Kal_331