简介：基于C++与Qt框架的分布式智能AGV调度系统项目，面向毕业设计、课程设计以及物流自动化方向的开发者，覆盖多智能体协同、路径规划、任务分配、通信协议与状态监控等核心环节，是一套结构完整、可直接阅读运行的工程实例。压缩包共31个文件，主体为cpp与h源码，另包含界面布局文件、工程配置、通信协议说明文档、仓库布局图纸以及统一建模语言模型，整体大小约2.64MB，方便对照文档和代码理解整体架构。源码中定义了多类AGV子类，模块划分清晰，通信协议文档详细说明了调度系统与底层设备的交互方式，适合快速上手。目前已有189人学习参考。该资源的价值在于将C++的高效算法与Qt的可视化界面有机结合，既能通过源码掌握分布式任务分配和路径搜索的实现思路，又可借助通信协议与布局图开展二次开发，是完成毕业设计或课程设计时难得的完整参照。
1. 这套系统在解决调度现场的什么问题
仓库里二十台AGV同时跑起来，调度屏上的车有时会原地打转，任务下发了却没人接，两辆车同时挤向同一个货架位。这些问题大多数情况下不是算法不够好，而是调度系统本身没有把任务分发、状态回传和车辆控制拆成可以水平扩展的模块。基于C++与Qt框架做分布式智能AGV调度系统，核心是用C++扛住调度算法的性能需求，用Qt把地图、车辆状态、任务进度可视化出来，再用分布式协议把多个调度节点连接成一个集群，解决单点崩溃和任务积压。本文将按一套可复现的工程方法，走通从架构设计到仿真验证的完整闭环，适合正在评估AGV调度自研方案的团队，也给已经跑通单机版、想升级成分布式的开发者一个可落地的对照路径。
2. 调度系统怎么拆成分布式模块，才能不互相拖累
AGV调度系统不能一开始就写成一个巨大的进程。常见做法是拆成三个独立进程：agv_master负责全局任务分配与地图管理，agv_agent每台车一个，负责执行指令并回报位姿，agv_console是基于Qt的监控端，只做状态展示和人工干预。这三个进程可以部署在同一台机器上，也可以拆到三台机器，进程间全部走网络通信。这样做的好处是，车端agent出现异常时不会拖垮主调度器，监控端重启也不影响正在执行的任务。
2.1 中央调度与车端代理的职责边界
agv_master和agv_agent的边界必须清晰，否则会出现逻辑放错位置导致循环调用。主调度器只做三件事：维护全局任务队列、执行路径规划、决定哪台车去执行哪个任务。车端代理只做三件事：接收指令、执行运动控制、定时上报状态。路径规划结果下发为一系列路点坐标，agent不参与全局决策，只负责按路点走，遇到障碍物时把异常状态上报，等主调度重新规划。
这种拆分能直接解决AGV调度最常见的“死等”问题。如果agent被设计成可以自己重新规划路径，那一旦多台车同时避障，很容易陷入各自为战的死锁。把决策权收归master，agent就变成无状态执行器，重启后可以直接从master同步当前任务，不需要本地维护复杂状态机。
2.2 进程间通信:心跳包与任务指令的协议设计
分布式调度系统里，进程间的通信协议比功能实现更重要。我一般用JSON做任务指令格式，因为调试方便，热更新逻辑时不用重新编译。心跳包则用固定长度的二进制结构，减少高频通信的序列化开销。下面是一个心跳包和任务指令的最小定义:
#pragma pack(push, 1) struct HeartbeatPacket { uint8_t type; // 0x01 表示心跳 uint32_t agent_id; // 车编号，小端字节序 uint32_t timestamp; // 毫秒时间戳 float x, y, theta; // 当前位置与航向角 uint8_t battery; // 电量百分比 }; #pragma pack(pop)心跳包走UDP，每200ms发一次。任务指令走TCP，保证不丢包。这个设计能保证状态数据即使偶尔丢一两帧也没关系，但任务指令绝不能丢。uint32_t agent_id用在小规模车队足够，如果超过4亿台车再换64位。timestamp要统一用主调度器的时间，避免各台车本地时钟漂移导致任务排序错乱。
2.3 分布式一致性:锁、事务与任务状态机
多台车协作时，AGV调度会碰两个经典问题:分布式锁和分布式事务。举一个实际场景:两个任务都需要占用同一段路径，如果两台车同时申请通过，就会出现路径冲突。单机版用mutex就能解决，分布式环境下要改用Redis的SETNX命令实现分布式锁。调度器在指定某段路径给某台车前，先抢锁，抢到才能下发指令:
# 获取路径锁，10秒自动过期，防止持有锁的节点宕机导致死锁 redis-cli SET path_lock:rack_12 agent_3 NX EX 10 # 任务执行完毕后释放锁 redis-cli DEL path_lock:rack_12NX参数表示不存在时才设置，两个节点同时来抢锁时只有一个能成功。EX 10设置过期时间，如果拿锁的mater节点崩了，锁也会自动释放，不会把整条路径永久锁死。实际生产环境不会直接拼命令行，而是用C++Redis客户端在代码里调用，但命令本质就是这样。
分布式事务主要体现在多任务协调上。一个搬运任务往往包含取货、运送、放货三个子任务，某个子任务失败时，前面已完成的子任务要回滚。AGV场景下做不了回滚，只能做补偿的SAGA模式:任务状态流转记录在数据库中，失败时把状态改为CANCELLED，并给相关车辆下发一条补偿指令。我维护的任务状态表一般长这个样子:
| 状态 | 含义 | 可转入状态 |
|---|---|---|
| PENDING | 已入队，等待分配 | ASSIGNED, CANCELLED |
| ASSIGNED | 已分配给某台车 | RUNNING, CANCELLED |
| RUNNING | 车正在执行 | COMPLETED, FAILED |
| FAILED | 执行失败 | RETRYING, CANCELLED |
| COMPLETED | 完成 | 终态 |
| CANCELLED | 取消 | 终态 |
这个状态机是调度系统的主干，数据库里每行任务都记录当前状态和时间戳。分布式环境下不追求强一致，只要保证最终状态是COMPLETED或CANCELLED即可。用SAGA模式调度任务时，如果发现某台车长时间没有推进任务状态，master会主动查询agent的实时状态，超时30秒就把任务转给另一台空闲车，同时把原车标记为异常。
3. 调度算法层:任务分配、路径规划与避碰时间窗
架构搭好后，核心工作集中在调度算法。AGV调度算法可以从三个层次穿起来:任务怎么分配给车、路线怎么走、多车相遇时怎么让。三层是依次调用的关系，任务分配决定目标点，路径规划算出路点序列，避碰时间窗给每个路点加上占用时间段。下面分别给出可落地的C++实现思路。
3.1 任务分配:贪心策略加负载均衡
任务分配不需要一上来就上遗传算法。对中小型车队，贪心策略加负载均衡已经能拿到不错的效果，实现代价却低一个量级。算法逻辑是:当一个新任务到达时，遍历所有空闲车辆，选择离起点最近的那台，终点不是选择依据，因为车辆在执行完任务后往往会滞留在目标点附近。
int assignTask(const Task& task) { int bestAgent = -1; float minDist = std::numeric_limits<float>::max(); for (const auto& agent : agents) { if (agent.status != AgentStatus::IDLE) { continue; } float dist = distance(agent.position, task.pickupPoint); if (dist < minDist) { minDist = dist; bestAgent = agent.id; } } if (bestAgent == -1) { return -1; // 返回-1表示等待，不进入失败状态 } // 负载因子：每台车最多分配3个任务，超过则跳过 return bestAgent; }这段代码里判断是否跳过重载车辆的负载因子，我建议放在距离比较之前判断，否则会出现某台车因为离得近被反复分配任务，最后积压一堆任务变成热点。返回-1而非直接抛异常，是为了让任务留在PENDING状态等待下一轮调度，不是变成FAILED。AgentStatus这个枚举建议把IDLE、BUSY、CHARGING、ERROR四种状态都定义齐，避免使用魔法数字。
3.2 路径规划:A*算法在栅格地图上的C++实现
AGV地图通常预先离散成栅格，每个栅格可通行或不可通行。路径规划我推荐用A*，比起Dijkstra，A*在全局寻路时的搜索规模明显小。实现的关键点不在算法本身，而在堆处理逻辑，优先队列用错了会退化成BFS。下面给出核心代码:
struct Node { int x, y; float g, h; int parentIndex; }; float heuristic(const Node& a, const Node& b) { return std::abs(a.x - b.x) + std::abs(a.y - b.y); // 曼哈顿距离，栅格地图上比欧氏距离稳 } std::vector<Node> aStar(const GridMap& map, const Point& start, const Point& goal) { auto cmp = [](const Node* a, const Node* b) { return (a->g + a->h) > (b->g + b->h); // 小顶堆:按 f = g + h 排序 }; std::priority_queue<Node*, std::vector<Node*>, decltype(cmp)> openSet(cmp); std::unordered_map<long long, Node> allNodes; // 初始节点入堆并记录 Node startNode{start.x, start.y, 0.0f, heuristic({start.x, start.y}, {goal.x, goal.y}), -1}; allNodes[startNode.x * map.width + startNode.y] = startNode; openSet.push(&allNodes[startNode.x * map.width + startNode.y]); int dx[4] = {1, -1, 0, 0}; int dy[4] = {0, 0, 1, -1}; while (!openSet.empty()) { Node* current = openSet.top(); openSet.pop(); if (current->x == goal.x && current->y == goal.y) { // 回溯路径并返回 } for (int i = 0; i < 4; i++) { int nx = current->x + dx[i]; int ny = current->y + dy[i]; if (!map.isWalkable(nx, ny)) { continue; } float tentativeG = current->g + 1.0f; // 计算邻居节点，更新g值 } } }这段代码里有几个工程上的坑。unordered_map的key用x * width + y拼成long long，可以避免开整张二维数组，地图特别大时节省内存。障碍物判断用isWalkable，A*寻路过程中不能修改地图，否则迭代器会失效。四向移动还是八向移动取决于AGV的转弯半径，差分驱动AGV一般用四向，因为斜向移动的边长不统一，路径平滑度反而下降。
启发函数选曼哈顿距离而不是欧氏距离，是因为栅格地图上四方向移动的实际代价就是曼哈顿距离，这样A*扩展节点数最少，路径也最符合AGV的走行方向。如果AGV支持斜走，则改成对角距离。
3.3 多车避碰:时间窗预留的5个关键参数
多车避碰最实用的方案是时间窗预留。每台车沿着路径走时，会占用经过的每一个栅格，占用时段记录在栅格的时间窗列表里。当某台车规划路径时，依次检查路径上的栅格，看规划的到达时间和已有的时间窗是否有重叠。只要每一个栅格都能插入一段不与现有时间窗重叠的时间段，这条路就是可行的。
时间窗策略的落地，需要调对这几个参数:
| 参数 | 推荐初始值 | 说明 |
|---|---|---|
| 栅格大小 | 0.5m | 必须大于AGV长宽的一半 |
| 车身后方安全距离 | 1.0m | 防止后车追尾前车 |
| 通过一个栅格的时间 | 8s | 由AGV直行速度除以栅格大小得到 |
| 时间窗重叠判断阈值 | 5.0s | 两车通过同一栅格的时间差小于此值时视为冲突 |
| 等待最大时长 | 30s | 超过后主调度器重新规划路径 |
时间窗的实现在C++里核心是维护每个栅格的占用区间列表，插入新区间时做区间合并与碰撞检测。当发现某条路径时间排不开时，最常见的处理是让后车在路径起点等待。等待时间可以直接加进时间窗里，然后重新检测整条路径。这个方案的优点是计算量可控，因为只在路径规划阶段做检查，不像人工势场法那样每个周期都在算力场。
4. Qt框架下实现调度监控界面
Qt在AGV调度系统里的角色是监控与交互层，不是逻辑层。很多开发者把大量业务逻辑写进Qt窗口类，结果界面卡顿、算法延迟，这就是架构没分开。让我强调一个原则:Qt线程里只允许发生UI相关操作，调度计算全部放在工作线程，通过信号槽与界面通信。这样界面即使刷新频率高，也不会阻塞调度核心。
4.1 用QGraphicsView绘制地图图层
AGV地图可视化的标准做法是用QGraphicsView+QGraphicsScene，把地图元素分成三个图层:静态障碍图层、动态路径图层、车辆图层。静态障碍层栅格化渲染，动态路径层绘制规划路径，车辆层每100ms更新一次位置。下面是最小示例:
// 地图初始化:把障碍物栅格画成灰色矩形 void MapWidget::initScene(GridMap* map) { scene_ = new QGraphicsScene(this); for (int x = 0; x < map->width; ++x) { for (int y = 0; y < map->height; ++y) { if (!map->isWalkable(x, y)) { QGraphicsRectItem* item = scene_->addRect( x * gridSize_, y * gridSize_, gridSize_, gridSize_); item->setBrush(QBrush(QColor(120, 120, 120))); item->setZValue(0); // 障碍物在最下层 } } } view_->setScene(scene_); }这里用setZValue控制图层层次，车辆图层的Z值设为10，路径图层设在5，这样车辆永远显示在最上面。只刷新车辆图层而不是刷新整个Scene，避免了QGraphicsView大范围重绘的性能问题。如果地图超过100x100栅格，建议把障碍物绘到一张QPixmap上再贴到Scene里，单独添加几百个小item会很慢。
4.2 车辆状态呈现:自定义进度条与信号槽传值
Qt里的AGV状态展示有个细节很实用:正在执行任务的车辆，可以用自定义进度条显示任务完成度。AGV把当前位置到目标的距离换算成百分比，通过信号槽发给Qt更新进度条。注意QProgressBar默认样式比较简陋，实际项目中需要继承后重绘。自定义进度条的paintEvent里绘制背景、进度条和文字，效果比改样式表更可控。
// 车辆状态线程发来的信号 void MainWindow::onPositionUpdated(quint32 agentId, float x, float y, float progress) { if (progressBars_.contains(agentId)) { progressBars_[agentId]->setValue(static_cast<int>(progress * 100)); } // 同时更新车辆在QGraphicsScene中的坐标 agents_[agentId]->setPos(x / gridSize_, y / gridSize_); }注意这段代码里progress是0到1的浮点数，传值到槽函数后立即转成整数。如果直接把浮点进度传给界面层，会导致setValue被频繁调用，刷新帧率过高时CPU占用虚高。槽函数默认在接收线程执行，MainWindow的信号应该由工作线程通过QueuedConnection关联到UI线程，避免在非GUI线程操作控件。信号槽之间不要传自定义结构体指针，传基本类型或值类型最安全。
4.3 Qt构建清单:依赖项与跨平台发布的坑
用Qt做AGV调度系统，最头疼的往往不是写界面，而是发布阶段的环境依赖。先看CMake配置，这套配置能同时满足开发和部署:
cmake_minimum_required(VERSION 3.16) project(AgvScheduler) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) find_package(Qt6 COMPONENTS Widgets Network REQUIRED) add_executable(agv_console main.cpp map_widget.cpp vehicle_item.cpp ) target_link_libraries(agv_console PRIVATE Qt6::Widgets Qt6::Network )发布时两个高频环境变量问题值得在这里写出来。第一，运行时提示could not find the Qt platform plugin "windows"，这是因为程序在非安装目录下找不到Qt平台的dll。解决方案是把编译输出的exe放在发布目录，运行windeployqt自动拷贝依赖;如果手动拷贝，需要确保qt.conf文件里[Paths] Platforms=/plugins的路径指向正确。第二，Windows上运行时提示缺少vcruntime140.dll或msvcp140.dll，这是没装对应版本的Microsoft Visual C++ Redistributable，Qt如果用的是MSVC编译器编译，目标机器必须装匹配的VC运行库，MinGW编译的版本则不需要。建议在发布包里捆绑对应的redistributable安装包，而不是假设每台操作员电脑都已安装。
5. 用日志重放和参数微调把系统调稳
分布式系统上线后，最耗时的环节是复现问题。AGV调度系统里的bug往往不是稳定出现的，跟车的位置、时间点都有关系。所以系统的最后一步，是要在架构设计阶段就埋好日志和回放机制，让现场出问题后能用几分钟离线还原问题。
5.1 统一日志字段与按车分文件
日志要统一字段顺序，不要每个模块各打各的。我的做法是定义一条日志格式:时间戳 | 模块名 | 车辆ID | 任务ID | 事件类型 | 详情，每台车一个独立日志文件，再加上一个全局调度日志。这样排查时先看全局日志定位冲突时间段，再打开对应车辆的日志看细节。事件类型用英文单词加数字的形式，比如MOVE_REJECTED、TASK_TIMEOUT，日志里不要用中文枚举，脚本解析时中英文混排会让处理变得很麻烦。
grep "MOVE_REJECTED" scheduler.log | tail -20如果日志里频繁出现MOVE_REJECTED，说明时间窗参数过紧，后车等待时间过多。如果出现TASK_TIMEOUT，则要检查agent执行速度是不是不达预期，或地图路径有死胡同。
5.2 压测脚本快速判断系统容量
调度系统做压测比功能测试重要。用最简单的方式产生并发任务，看任务在PENDING状态停留的时间有没有持续增长。增长意味着调度能力跟不上任务注入速度，瓶颈可能在路径规划或任务分配。一个可快速执行的压测思路是写一个脚本批量下发任务。
for i in $(seq 1 100); do curl -X POST http://localhost:8080/api/task \ -H "Content-Type: application/json" \ -d "{\"pickup\":\"A_$i\",\"dropoff\":\"B_$i\"}" sleep 0.5 done关注两个指标:每分钟完成的任务数和任务平均等待时间。每多压50个任务，如果完成数没有线性上涨，就要开始查瓶颈了。常见瓶颈是单线程路径规划，处理办法是改成线程池，规划任务与地图版本隔离，否则多线程同时读地图会出数据竞争。
5.3 三个参数的微调方向
chassis.conf配置文件里有三个参数对系统的稳定性影响最大，建议调试时优先调整。第一个是心跳超时阈值，默认500ms内没收到agent心跳就认为掉线，仓库里Wi-Fi不稳定时误判率会上升，可放宽到800ms。第二个是路径锁过期时间，默认10秒，如果某个路径段较长，AGV可能还没走出锁定区域锁就过期了，另一台车就可能进入同一区域，要根据最长路径段的通行时间乘以1.5倍来设定。第三个是任务分配时的负载因子，默认每台车最多3个任务，重载AGV多次往返的运输场景可以提高到5，但超过后要警惕任务堆积在那台车后面。参数调整时只改一个，压测观察10分钟后看数据对比，不要同时改多个，否则出了问题分不清是哪次调整引起的。
本文还有配套的精品资源，点击获取
