1. 为什么值得折腾集群：从单机瓶颈说起

如果你用过 OpenDroneMap（下称 ODM）跑过上百张照片的正射或三维重建，大概率经历过那种“进度条卡在某个阶段一动不动、风扇狂转、机器烫得能煎蛋”的绝望。单机跑 ODM 的痛点非常明确：特征点提取和稠密匹配是典型的 CPU 密集型任务，而内存占用会随着影像数量呈近似平方级增长。一个 500 张 2000 万像素照片的项目，单机 32GB 内存经常在稠密重建阶段直接 OOM，即便侥幸跑完，耗时也常常以“天”为单位。

集群搭建的核心目的，就是把这些可以并行的计算任务拆散到多台机器上，让多台机器的 CPU 和内存同时干活。ODM 本身提供了--split和--split-overlap参数来做分块处理，配合ClusterODM这个调度中间件，就能把一个大项目切成若干子任务，分发给多台计算节点并行执行，最后再合并结果。这套方案解决的是“单机资源天花板”问题，适合手里有几台闲置工作站、或者想用多台中等配置机器替代一台顶配机器的团队。哪怕你只有两台机器，搭起来也能明显缩短处理时间。

我先把结论摆在这里：集群不是万能加速药，它的收益取决于任务类型、网络带宽和节点均衡性。下面我会把整套思路、参数计算、踩坑记录全部摊开讲，你照着做基本能复现一个可用的 ODM 集群。

2. 整体架构设计与方案选型

2.1 集群的三种角色划分

ODM 集群在逻辑上分三个角色，理解清楚这个划分，后面所有配置都不会迷路：

• 调度节点（ClusterODM）：只负责接收任务、切分任务、把子任务分发给计算节点、收集结果并合并。它本身不跑重建计算，配置要求很低，一台 2 核 4GB 的小机器甚至树莓派都能胜任。
• 计算节点（NodeODM）：真正干活的机器，每台跑一个 NodeODM 服务，暴露 HTTP 接口。CPU 核数、内存大小决定了单节点能处理多大的子任务。
• 存储/入口节点：通常和调度节点合并部署，负责存放原始影像、中间文件和最终成果。如果影像数据量大，建议单独挂一块大容量 SSD。

这种“调度与计算分离”的设计，好处是扩容极其简单——加一台机器，装好 NodeODM，在 ClusterODM 里注册一下就行，不用动已有节点。坏处是调度节点会成为单点，一旦它挂了整个集群不可用，所以生产环境建议给调度节点做个定时快照。

2.2 为什么选 ClusterODM 而不是自己写调度脚本

有人会想：不就是把照片分堆、分别调用 ODM、最后合并吗，我自己写个 shell 脚本循环调用不就行了？我早期确实这么干过，结论是自己写脚本的维护成本远高于收益。原因有三：

第一，ODM 的--split分块不是简单按数量切，它要考虑影像之间的重叠关系（--split-overlap），切出来的子块之间必须有足够重叠才能保证拼接无缝。这套逻辑 ODM 内部已经实现好了，自己复刻容易出错。

第二，子任务之间的依赖关系、失败重试、节点负载均衡，这些 ClusterODM 都内置了。它维护一个节点池，根据每个节点当前的任务队列长度自动分配，节点挂了会自动把任务转给其他节点。

第三，结果合并阶段（--merge）需要把所有子模型的点云、纹理对齐拼接，这一步对参数一致性要求很高，用官方工具链能避免大量玄学问题。

所以我的建议很明确：调度层直接用 ClusterODM，不要重复造轮子。你要定制的部分，主要是节点规格、切块参数和网络配置。

2.3 硬件与网络的最低要求

下面这张表是我实测下来比较靠谱的配置参考，注意这是“能跑起来”的底线，不是“跑得快”的推荐值：

网络这块要特别强调：节点之间的数据传输量很大。切块后的子任务影像、中间的点云文件都要在调度节点和计算节点之间来回传。千兆网络下传几十 GB 数据会明显拖慢整体效率，如果条件允许，计算节点和调度节点之间上万兆或者至少做链路聚合。我踩过的坑是：用无线网络连节点，结果传输阶段比计算阶段还慢，整体耗时反而比单机长。

3. 核心组件部署与关键参数解析

3.1 用容器方式部署 NodeODM 的完整步骤

计算节点我强烈建议用 Docker 部署，原因是 ODM 依赖的库版本很挑剔，裸机安装经常在 OpenCV、GDAL 这些库上翻车。容器镜像把这些依赖都封好了，省心。

在每台计算节点上执行：

docker run -d --restart unless-stopped \ --name node-odm \ -p 3000:3000 \ -v /data/odm/images:/code/images \ -v /data/odm/odm_texturing:/code/odm_texturing \ opendronemap/nodeodm

这里几个点值得展开说。-p 3000:3000把 NodeODM 的 API 端口映射出来，ClusterODM 就是通过这个端口和节点通信的。两个-v挂载是必须的，否则容器一重启中间成果全丢，重跑一次又是几个小时。--restart unless-stopped保证机器意外重启后节点自动恢复，集群里节点掉线是很常见的故障，自动拉起能省很多事。

启动后验证节点是否正常：

curl http://<节点IP>:3000/info

返回一段 JSON，里面有version、taskQueueCount、maxImages等字段，说明节点活了。如果返回连接拒绝，先查防火墙有没有放行 3000 端口。

3.2 ClusterODM 的安装与节点注册

调度节点上同样用容器跑 ClusterODM：

docker run -d --restart unless-stopped \ --name cluster-odm \ -p 3001:3000 \ -p 8080:8080 \ -v /data/cluster:/var/www/data \ opendronemap/clusterodm

3001是 ClusterODM 对外提供 API 的端口（容器内还是 3000，映射到宿主机 3001 避免和本机其他服务冲突），8080是它的 Web 管理界面。挂载/data/cluster用来持久化节点配置和任务记录。

容器起来后，进入容器内部用命令行注册节点：

docker exec -it cluster-odm clusterodm

进入交互式命令行后，依次执行：

node add <计算节点1的IP> 3000 node add <计算节点2的IP> 3000 node list

node list会列出所有已注册节点及其状态。看到每个节点后面显示online就说明注册成功。如果显示offline，九成是网络不通或者节点端口没开。

注意：ClusterODM 的节点配置默认存在容器内的文件里，如果你没做-v挂载，容器重建后节点列表会清空，得重新注册。这个坑我踩过一次，半夜容器被自动更新重启，第二天发现集群空了。

3.3 切块参数的计算逻辑

这是整个集群调优里最需要动脑子的部分。ODM 的分块由两个参数控制：

• --split N：把项目切成 N 块，N 通常设为“计算节点数 × 每节点并行任务数”。
• --split-overlap 米数：相邻子块之间的重叠距离，单位是米。

--split的取值不是越大越好。切得太碎，每块影像太少，特征点匹配的冗余度下降，拼接处容易出现接缝错位；切得太粗，单块还是超出节点内存，等于没切。我的经验公式是：

单块影像数 ≈ 节点可用内存(GB) × 8

比如节点是 64GB 内存，单块控制在 500 张左右比较稳妥。假设总共有 2000 张照片、4 个计算节点，那么--split设为 4 到 8 之间，让每个节点分到 1 到 2 块。

--split-overlap的取值和飞行高度、地面分辨率有关。粗略估算：重叠距离取 20 到 50 米，航高越高、地物越平坦，取值可以小一些；城市密集区、地形起伏大的区域，建议取 50 米以上。重叠不足的典型症状是拼接处出现明显的错位或模糊带，看到这个现象就回头把 overlap 调大重跑。

4. 完整实操流程与现场记录

4.1 从上传影像到提交集群任务

假设调度节点 IP 是192.168.1.10，端口 3001。整个提交流程如下：

第一步，把影像打包上传到调度节点。ClusterODM 支持通过 API 上传 zip 包，也可以用它的 Web 界面拖拽。影像数量多的时候建议先在本地压成 zip，减少传输时的小文件开销。

第二步，构造任务参数。用 curl 提交一个任务：

curl -X POST "http://192.168.1.10:3001/task/new" \ -F "images=@/data/project.zip" \ -F "options=[{\"name\":\"dsm\",\"value\":true},{\"name\":\"orthophoto\",\"value\":true},{\"name\":\"split\",\"value\":8},{\"name\":\"split-overlap\",\"value\":30},{\"name\":\"pc-quality\",\"value\":\"medium\"}]"

返回的 JSON 里有个uuid字段，记下它，后续查进度全靠这个 ID。

第三步，轮询任务状态：

curl "http://192.168.1.10:3001/task/<uuid>/info"

返回里的status字段会经历queued、running、completed等状态，processingTime是已耗时。集群跑起来后，你可以同时在 ClusterODM 的 Web 界面看到每个节点的任务分配情况，哪个节点在跑、跑的是哪一块，一目了然。

4.2 一次真实项目的耗时对比记录

我拿一个 800 张照片、单张 2000 万像素的测绘项目做过对比，硬件是 3 台 16 核 64GB 的机器：

加速比大约 2.5 倍，没有达到理论上的 3 倍，损耗主要来自切块后的合并阶段和节点间数据传输。这个结果符合预期——集群加速比永远小于节点数，因为合并是串行的，传输也有开销。如果你的项目影像数量少（比如 100 张以内），切块带来的合并开销可能抵消并行收益，这种小项目老老实实单机跑反而更快。

4.3 结果合并与成果校验

所有子任务完成后，ClusterODM 会自动触发合并。合并阶段最容易被忽视的是坐标系统一。如果原始影像的 GPS 信息坐标系不一致，合并后的正射影像会出现整体偏移。提交任务前务必确认所有照片的 EXIF 里坐标系一致，或者在参数里显式指定--gps-accuracy。

合并完成后，成果文件在调度节点的挂载目录下，主要看三个东西：正射影像（orthophoto.tif）、数字表面模型（dsm.tif）、三维点云（odm_georeferencing 目录）。校验方法很简单，把正射影像拖进任意 GIS 软件，叠加原始航迹点，看边缘有没有错位、接缝处纹理是否连续。我遇到过接缝处出现一条几米宽的模糊带，回头查是split-overlap设小了，从 20 米调到 40 米重跑后消失。

5. 常见故障排查与避坑清单

5.1 节点掉线与任务卡死的处理

集群跑长任务时，最常见的故障是某个节点中途掉线，导致它负责的子任务卡在running状态永远不结束。排查顺序是这样的：

先看节点本身是否存活，curl http://<节点IP>:3000/info有没有响应。没响应就登机器看容器状态，docker ps看容器是否还在，docker logs node-odm看有没有 OOM 被杀。ODM 在稠密匹配阶段内存暴涨是常态，容器被系统 OOM killer 干掉的情况很普遍。

如果节点活着但任务卡住，可以在 ClusterODM 命令行里用task list查看任务分配，必要时task cancel <uuid>取消后重新提交。这里有个经验：给计算节点的 Docker 容器设置内存上限时要留足余量，比如 64GB 的机器，容器上限设 56GB，留 8GB 给系统和文件缓存，否则容易触发系统级 OOM。

5.2 常见问题速查表

5.3 几条用血换来的实操心得

第一条，先小规模验证再上全量。拿 50 张照片跑一遍完整流程，确认节点注册、切块、合并都正常，再提交几百张的大项目。我见过有人直接上 1000 张，跑到合并阶段才发现参数错了，白等一整天。

第二条，调度节点和存储节点分开考虑。如果影像数据量超过几百 GB，把存储放在调度节点上会让它的磁盘 IO 成为瓶颈，建议单独挂 NAS 或者给调度节点配大容量 SSD。

第三条，记录每次任务的参数组合。集群调参是个反复试错的过程，split、split-overlap、pc-quality这几个参数的不同组合效果差异很大，用个简单的表格记下每次的参数和结果，比凭记忆靠谱得多。

第四条，别迷信节点数量。三台均衡的机器往往比五台参差不齐的机器效率更高，因为集群的整体速度受最慢那个节点拖累。节点规格尽量保持一致，实在不一致就把慢节点分配少一点任务。

这套集群我前后搭过三次，第一次折腾了两天才跑通，后面两次基本半天就能从零到可用。核心难点不在安装，而在切块参数和故障处理上，把上面这些细节吃透，剩下的就是熟练度问题。后续如果影像量继续增长，还可以考虑把存储层换成对象存储、给调度节点做高可用，不过那是另一个量级的工程了，普通项目用现在这套足够。