简介openTCS 5.9中文版用户手册是一份面向自动导引车调度系统开发者、物流自动化工程师以及机器人控制系统集成商的完整中文指南。手册从软件目的、系统要求、许可证说明入手帮助读者建立基础认知系统概述部分深入剖析了控制台、运输任务管理器、车辆控制器三大组件并详细解析工厂模型中的点、路径、位置、位置类型、车辆、块、图层、图层组等要素。操作指南覆盖系统启动与关闭、工厂模型创建与编辑、运输订单与订单序列管理、外设作业配置、公用属性设置、系统监控、错误处理及常见故障排查目录式章节设计便于快速查阅。资源包内共一个PDF文件大小约13.31MB中文排版清晰章节完整既适合作为新手入门教程也可作为日常运维的速查手册。已有五百九十五人学习下载是中文环境下学习openTCS调度与物流自动化的实用参考资料。1. 先别急着建模openTCS 5.9 启动失败先查 Java 环境和 JRE 版本第一次接触 openTCS 5.9 的人十个里有八个这么翻车从某公司现场拷回安装包装好 Java双击启动脚本窗口一闪而过以为软件坏了。其实先查 Java 环境。openTCS 是开源的 AGV 调度系统行业里常叫 RCS它对运行时有硬性要求需要 JRE 13官方原版警告过某些商业发行版 JRE 由于依赖库Docking Frames的限制目前和它不兼容。更隐蔽的是很多人把「能运行」当成「能启动」装了 JRE 8 或系统默认 JRE内核进程根本没起来。这篇排错记录不聊泛泛的调度理论只讲现场踩过的四类问题起不来、连不上、模型路线不通、订单不派发每一步怎么定位、怎么改、怎么验证。2. 连不上内核RMI、SSL 与主机名三类报错的排查顺序先把玄学过滤掉绝大多数「连不上」不是网络玄学而是配置不一致。openTCS 是典型的客户端-服务器结构内核Kernel是服务器进程模型编辑器、操作台Operations Desk、内核控制中心KCC都是客户端。对 Java 客户端内核暴露的是 RMI 接口对外部系统则提供 Web API 用于创建、撤销运输订单和获取状态更新。所以「连不上」分两类Java 客户端连 RMI 连不上外部系统调 Web API 调不通。先分清是哪一类再动手否则后面全是白查。2.1 区分「起不来」和「连不上」先开 KCC再看日志提示内核、内核控制中心、模型编辑器、操作台四个应用各自有 log/ 子目录故障定位第一优先级永远是内核日志。内核控制中心是最好用的诊断工具我一般第一个开的就是它。如果 KCC 自己也连不上内核问题基本就锁定在内核进程或网络层而不是单个客户端的配置。这时候按顺序查三件事内核进程是否活着、内核日志尾部有没有异常、客户端配置里的主机名和端口与内核监听是否一致。下面这段脚本是现场常用动作以发行版解压后的目录结构为例# 用前台方式跑内核启动脚本把真实错误直接打到终端而不是双击后一闪而过 ./startKernel.sh # 确认内核进程还在发行版里内核进程名通常包含 Kernel 字样 ps -ef | grep -i kernel # 内核自己的日志先看最后 100 行 tail -100 kernel/log/kernel.log脚本的作用是把「双击启动脚本一闪而过」的隐藏错误暴露出来脚本找不到 JRE、类加载失败、端口被占都会直接打印到终端。ps 确认进程是否真的活着tail 看日志尾部判断是启动期错误还是运行期错误三个命令组合能筛掉一半问题。2.2 RMI 连不上优先怀疑主机名解析而不是端口RMI 连接类报错文本通常是 ConnectException、RemoteException 或者 NoSuchObjectException指向某个 host:port。现场出问题最多的不是端口不通而是主机名解析到了 127.0.0.1。内核部署在服务器 A客户端在服务器 B配置里写 localhost或者 hosts 文件里没有服务器 A 的条目结果就是 RMI 注册表能找到对象调用找不到。还有一种常见情况是「在不同的系统上运行内核和客户端」手册第六章有专门一节两边网络环境不一致IP 直连和主机名混用最容易踩这个。常见做法是让内核和所有客户端使用同一个主机名条目别混用 IP 和主机名。我会在配置目录里搜一遍相关项确认两边完全一致# 在发行版配置目录下搜含 rmi、host、port 的配置项逐条对比内核侧和客户端侧 grep -rin --include*.cfg --include*.properties -E rmi|host|port . # 确认 hosts 里主机名到 IP 的映射存在且和内核实际监听地址一致 cat /etc/hosts这里不放具体键名因为每个项目的配置文件组织方式不同但搜索关键词是通用的。搜完你会发现多数连不上都是「配置里写的地址和实际监听地址不一致」这种低级坑改完 hosts 或配置项重启内核和客户端就恢复了。2.3 SSL 开启后连不上两边配置不对称手册配置章节分别列了内核侧 SSL 服务器端加密配置项以及内核控制中心、模型编辑器、操作台各自的 SSL 配置项。这个布局说明一件事SSL 是成对配置的。服务器端配了 keystore 和口令客户端要么信任对应证书要么按对应项配置。现场最常见的报错是 SSLHandshakeException原因往往不是密码错而是测试环境开过 SSL 后来又关了客户端配置里还残留加密开关两边不对称握手直接失败。我一般会做一道校验把服务器端和客户端的 SSL 相关配置项打印出来逐行对重点看开关项是否一致、证书路径是否指向同一个文件、口令是否相同。测试环境可以临时统一指向同一份证书生产环境则按正式加密方案来做。另外Web API 通道有管理 Web API 和服务 Web API 两组独立配置项外部系统调接口调不通时先确认对应服务是否启用、端口是否冲突再查鉴权配置。外部系统报连接拒绝先 netstat 看端口有没有进程监听能监听但鉴权失败才去看 Web API 配置项这一组问题和 RMI 的排查路径完全不同别混在一起查。3. 模型与路线建好却不通点类型、双坐标系、锁定标志三类建模坑openTCS 的行驶路线由点和路径构成点是车辆在逻辑上被命令移动到的位置路径连接两个点。建模期最隐蔽的问题不是画图而是要素类型选错导致路线看起来存在、实际不能路由。这一章把建模期三个高频问题拆开讲点类型、双坐标系、锁定标志。3.1 点类型选错报告位置太多路线必然无解点有三种类型停靠位置halt默认、报告位置report、停车位置park。三者的行为约束完全不同点类型能否停靠能否作为路线终点典型场景停靠位置 halt可临时停靠是装载、卸载、执行操作报告位置 report禁止停靠否路径上的过程确认点停车位置 park可长期停靠是空闲车辆存放、待命手册把限制说得很直接只由报告位置组成的路线将无法路由因为车辆无法在任何位置停靠。我见过有项目把所有点都画成报告位置认为车辆路过报个到就行订单创建后路由器直接给不出路线。根因是把「报告」理解成「停靠点」和调度策略的假设冲突。建模时先问三个问题任务终点要执行装载或充电放停靠位置。只是路线上的过程确认点放报告位置。所有任务完成后去待命放停车位置。一个完整的路网至少要保证每个任务终点是停靠或停车类型否则调度程序无解。3.2 布局坐标和模型坐标错乱车按「图上位置」跑到错误点位这是 openTCS 独有的双坐标系设计也是新人最容易忽略的坑。每个点有两套坐标布局坐标系只用于在模型编辑器和操作台里显示地图模型坐标系才是车辆驱动实际使用的导航坐标。两者可以不相关这样设计是为了允许把很长的路径在图上压缩展示或者用扭曲视图让密集区域更便于观察。问题在于拖动点改变的是布局坐标模型坐标不会跟着变。如果现场按图上位置去标定车辆方向、外设位置实际发给车辆的坐标和显示坐标不一致车就会走到错误地点外设操作永远对不上号。解决办法手册给了两条路全局同步用菜单 Actions › Copy model values to layout 或 Copy layout values to model只想同步单个要素右键该要素在上下文菜单里选同名命令。提示注意点的车辆方向角体系——0 度在 3 点钟位置正值表示顺时针旋转。方向角错了车辆占用点时的朝向就不对AGV 原地打转的现象有一半是这么来的。我一般保存模型前强制做一次「布局→模型」同步顺便检查方向角。这一条在手册 2.2.1 里写得很细值得建模前通读一遍。3.3 外设操作建模触发器与完成要求标志的四象限路径上可以挂一系列外设操作描述车辆沿路径行驶时外设设备按顺序执行的动作。外设操作有三个属性要执行操作的外设设备引用、实际要执行的操作、执行触发器。触发器有两个值再加上完成要求标志组合出来四种行为很多现场故障出在这个矩阵里触发器完成要求false完成要求trueBEFORE_MOVEMENT车辆穿过路径前触发不等结果直接走车辆必须等在路径起点直到操作完成AFTER_MOVEMENT车辆穿过路径后触发不等结果车辆必须等在路径终点直到操作完成用错最多的是 AFTER_MOVEMENT 加完成要求true外设设备只执行了动作但不回报完成车辆就永远等在目的地。建模时要把「完成要求」理解成「等确认」而不是「等动作」。如果现场出现车辆到了位置不动的故障先看这一步再去查调度。3.4 锁定标志的两种语义路径和位置都有锁定标志但语义不同特别容易混。路径锁定路由器计算路线时完全不使用该路径表现是「订单找不到路线」。位置锁定调度程序不分派那些需要在该位置执行操作的订单表现是「订单在池子里排队但不派发」。排查时先看锁定标志因为它的优先级高于其它属性。然后看位置类型的操作集合。位置类型定义了两组操作允许的车载操作、允许的外设设备操作。订单要求的操作不在集合里位置对订单就是不可用的。这两个锁定标志和操作集合是模型加载后「看着正常却跑不动」的三大根源里最容易被忽略的两个。4. 运输订单不派发集成级别、电量阈值和资源调度的三层定位订单建了、车也有但就是不动这是 AGV 调度系统现场最折腾人的问题。这一章按排查顺序写先看车辆集成级别再看电量阈值最后看路由和调度。按这个顺序查通常能在一刻钟内定位到具体环节。4.1 车辆驱动没接、级别不对车显示着但不参与任务第一层检查是车辆本身。车辆驱动的角色是把内核的抽象接口翻译成车辆听得懂的通信协议没有驱动车辆对内核来说不存在。所以在内核控制中心里把驱动配给车辆、确认通信正常这是前置条件。驱动配好之后还要看车辆的集成级别这个属性只能通过操作台调整模型编辑器改不了。三个级别的差异ignored车辆及其报告的位置被完全忽略操作台不显示不可用于订单noticed操作台显示位置但系统不分配资源不可用于订单respected正式参与调度可分配订单现场最气的是车在操作台能看到物流人员以为正常订单就是不派。打开车辆详情才发现集成级别停在 noticed。根因是配车时只完成了驱动关联没把级别切到 respected。解决就一步操作台上把车辆设为 respected。我见过多次「排查半天最后改一个下拉框」的情况所以现在调试第一步就是看这个级别。还有一个低级陷阱暂停和恢复车辆、将车辆从运行系统中移除这些操作在手册里有专门章节。运营中要临时让某辆车下线正确路径是操作台的「将车辆从运行系统中移除」或「暂停和恢复车辆运行」功能。如果直接关掉车辆通信再回来时调度上下文已经发生变化订单进度和实际位置对不上反而增加排查成本。4.2 电量阈值配反充电逻辑自相矛盾第二层看电量。车辆有四个电量级别属性临界电量、良好电量、完全充电电量、充分充电电量。手册原话的语义是电量低于临界就要决定充电高于良好就不用充电充到充分充电电量就可以停止充电充到完全充电电量视为充满。四个值必须满足严格递增临界 良好 充分 完全。如果配反比如完全充电阈值低于充分充电阈值车辆会永远充不满或者刚充满立刻又要充电形成循环。充电和停车是联动的默认策略里有停车位置选择、停车位置优先级、默认充电位置选择。模型里如果没有合法停车位置或者停车位置被锁定车辆完成订单后进入不了空闲驻留状态表现就是任务完了车停在原地后续订单不接。建模阶段就应该把充电位置和停车位置按优先级规划好而不是到现场再补这部分内容手册第四章 4.1 节说得很透。4.3 成本函数、路由组与调度公平性线路不是越短越好第三层看路由与调度。默认路由器有两个核心概念成本函数和路由组。路径的长度、最大行进速度、最大倒车速度都可能进入成本计算路径最大行进速度慢但长度短未必比长而快的路线便宜。路由组把某些路径和点绑定限制车辆只能穿过指定区域。排查时按现象分类订单找不到路线先查路径锁定再查起终点是否同属一个路由组路线莫名绕远看成本函数权重速度权重是否压过了长度权重车辆原地等待查是否有另一辆车占用了同一块区域块是地理区域用于限制 AGV 活动范围也是交通管理中资源分配的单位。默认调度程序负责分配资源、释放资源并且在文档里明确强调调度公平性——这意味着订单不是严格按创建顺序先到先得而是按车辆可用性动态分配。有的现场把「订单晚创建但先执行」当成 bug 来报其实这是默认调度策略的公平性设计。真要严格按顺序需要替换或调整调度策略实现而不是调几个参数就能解决。批量发单的场景还涉及订单序列操作台支持连续创建运输订单订单序列是批量作业的容器。现场大批量导入订单时优先用订单序列而不是逐条创建既能统一跟踪状态撤销时也方便整体处理避免一条条误操作。5. 避坑排查五条高发踩坑记录现象、原因、解决这章是现场问题清单每条按现象、原因、解决排列可以直接对照。这些都是实际存在的坑不是理论推演。5.1 订单池一直涨订单就是不派发现象创建了上百个运输订单操作台里每单的状态一直停在待处理旁边的车却闲着。原因最常见两个。一是车辆集成级别不是 respected车辆根本不被调度程序考虑二是订单要求的操作与位置类型允许的操作集合不匹配车辆被调度程序视为不可用。解决先看车辆集成级别再看订单操作。我会把所有位置类型允许的操作整理成一张对照表和订单创建时填的外设操作字段逐项比对多数不匹配在建模阶段就能发现不用等到现场。验证方法是改完级别或操作后看操作台里订单状态是否在下一个调度周期变化——默认调度是按车辆可用性动态分配的别盯着创建顺序看。5.2 车辆完成订单后停不下来现象车到了目的地装完卸完然后就卡住不进停车场不接新单。原因目的地是报告位置而不是停靠或停车位置或者路径上的外设操作设置成 BEFORE_MOVEMENT 且完成要求标志为 true车辆在路径起点等外设完成外设那边却一直没回报完成。解决改终点类型再查外设。先把车辆当前位置类型改成停靠或停车再核对路径外设操作的触发器和完成要求组合。还有一条经常被忽略外设设备必须先映射到位置上操作命令才发得出去。默认外设作业调度程序会用预留令牌机制协调多车对外设的访问外设忙时令牌不可得车辆排队是预期行为但如果令牌一直不被释放就要查外设作业状态而不是干等。5.3 电量永远充不满或刚充满又立刻要充现象车停在充电位置电量卡在某个值一整天不动或者充满后刚跑一个订单又回充电位循环不断。原因四档电量阈值顺序出错常见就是「完全充电」设得比「充分充电」低充电逻辑自相矛盾另一类是充电位置对应的位置类型不允许充电操作充电作业本身不合法。解决核对车辆四个电量级别的数值关系严格保证临界 良好 充分 完全再核对位置类型允许的外设操作集合。这个问题单纯改参数就能好区别只在于你有没有意识到阈值是四项联动——很多人改完一项发现更糟就是因为没通盘看。每次改完电量参数我都会让车辆实际跑一遍「低电量→充电→充满→返回任务」的闭环确认真的稳了再收工。5.4 虚拟车跑得好好的真车一上就各种停现象用系统自带的虚拟车辆流程测试一切正常真实车辆接入后订单不执行、位置对不上。原因虚拟车辆的特征参数和真实车辆不一致。调度规划基于模型里的车辆参数计算速度、加速度、电量阈值全是虚拟车的真车自然对不上。手册第六章专门有一节「配置虚拟车辆的特征」但大多数人调试时直接用了默认值。解决按手册那节内容把虚拟车的参数改成和真车一致或者直接用真车模型。调试阶段虚拟车很有用但它代替不了真车验证。正式验收前至少用一辆真车跑完整订单流程我就吃过「虚拟车全绿、真车一启动就报错」的亏从那以后虚拟车只用来测流程连通性不拿来验调度逻辑。5.5 两台客户端同时改模型保存后模型对不上现象模型编辑器 A 改了布局另一台模型编辑器或操作台加载后布局错乱或内核启动时模型校验报名称冲突。原因模型数据多端同时编辑且没有统一基线。openTCS 的要素名称要求全局唯一手册里有「唯一名称」专门一节命名前缀混乱时会触发加载失败。模型文件没有自动合并能力谁后保存谁覆盖这是文件型模型的天然限制。解决指定唯一一台机器作为模型编辑入口改完保存后统一分发要素命名按模型编辑器要素命名方案配置项的规则加前缀配合唯一名称校验。我现在的习惯是谁改模型谁负责重新加载内核验证。模型文件别走多人协同那套宁可排队改不要同时改。6. 快速定位 openTCS 故障十分钟内锁定内核、模型还是车辆配置最后给一套立足「日志加定位顺序」的快速排查法。openTCS 把日志分在四个子目录内核、内核控制中心、模型编辑器、操作台各自有 log/ 子目录工厂模型数据则在内核和模型编辑器的 data/ 子目录。定位最快的永远先看内核日志因为调度、路由、资源分配的判断都发生在内核侧。排查顺序我固定走四步不乱跳。第一内核日志尾部两百行看有没有异常堆栈或调度器提示第二内核控制中心里看车辆状态集成级别、当前位置、分配到的资源第三操作台里看订单状态和车辆绑定关系第四按现象反查模型参数例如路线不通查路径锁定订单不派发查位置类型与集成级别。日志是黑匣子车辆状态是现场模型参数是根源用这个先后顺序不会漏。症状与首查参数对照现象最先查的地方第二顺位内核起不来JRE 版本与启动脚本输出内核日志尾部客户端连不上RMI 配置与 hostsSSL 配置一致性订单不派发车辆集成级别位置类型操作集合车辆不动路径锁定标志块占用与调度外设不执行外设触发器与完成要求标志外设设备映射关系电量异常四档电量阈值顺序位置类型充电操作这套流程是血泪经验换来的。有一次现场几十台车全停在通道里报表以为是调度死锁查到最后是模型里报告位置比例过高车辆完成订单后没有合法停靠点。从那以后我每次到现场调试都强制先把内核日志和车辆状态页看一遍再动模型再谈算法配置——这个次序能挡掉八成伪故障。完整的中文版用户手册里第五章把内核、订单池、默认调度程序、默认路由器、外设作业调度程序、Web API、RMI、SSL 的配置项逐条列了出来遇到具体配置项就拿手册对应小节逐行核对比瞎试快得多。希望帮到你。本文还有配套的精品资源点击获取