openTCS 5.9中文手册：从零搭建AGV调度系统与首张运输订单

简介：openTCS 5.9中文版用户手册面向AGV调度系统与RCS系统的开发者、集成工程师及运维人员，将开源运输管理平台的核心概念与操作方法译成中文，可降低英文文档的阅读门槛，帮助用户理清模块关系。手册从软件目的、系统要求与许可说明讲起，依次介绍控制台、运输任务管理器、车辆控制器等组件结构，并详细解释点、路径、位置、位置类型、车辆、块、图层与图层组等工厂模型要素，以及运输订单、订单序列和外设作业等运行要素，后续章节覆盖系统操作、常见问题与解决思路。资源包内含1个PDF文件，大小约13.31MB，目录层级清晰，便于按章节检索与对照查阅。已有598人学习，适合作为搭建与调试AGV调度系统时随时查阅的参考手册。

1. 先弄明白一件事：openTCS 到底是个什么软件

你在工厂车间里大概见过那种自己跑、自己拐弯、到工位前停下等装卸的小车，那就是 AGV。一台车好办，十台车凑到一起立刻就乱：这单派给谁、走哪条路、岔路口谁先过，全靠一套 AGV 调度系统在背后指挥。openTCS 干的就是这件事，全称 Transportation Control System，一套免费开源的调度软件，专门协调自动导航车辆和移动机器人组成的车队，而且不管你用的是哪种导航方式、哪种负载设备，它都能接。手上这份 openTCS 5.9 中文版用户手册，就是把装环境、画地图、配车辆、下第一张运输订单这一整套流程，用中文一条条写明白的操作说明。它适合刚接触 AGV 调度、想自己动手把一套系统跑起来的新手；如果你只是想买套现成软件开箱就用，那它不适合你。

2. 为什么值得学：一套开源调度系统能替你决定什么

2.1 一台车靠人盯，十台车靠三个算法

先想一个特别具体的场景。车间里有八台 AGV，此刻压着五张运输订单：三张要把原料从仓库送到产线，两张要把成品从产线送回出货区。你站在操作台前面，脑子里要瞬间回答三个问题——这五张单分别派给哪台车？每台车走哪条路最省时间？两条路线在同一个岔路口交叉时谁先过？

这三个问题，正好对应 openTCS 内核里的三个策略模块。手册第 2.1 节写得很清楚：调度程序（dispatcher）决定哪台车处理哪张订单，还负责在没订单或者车跑得太远时决定车该干什么；路由程序（router）负责给车找去目的地的最佳路线；调度器（scheduler）负责交通管理的资源分配，说白了就是避免两台车撞上。三件事拆成三个模块，各自可以单独替换，这就是这套系统最值钱的地方——它不是一堆揉在一起的代码，而是三个有名字、有边界、可以拔下来换掉的决策单元。

这也是为什么值得花时间学它。很多人对 AGV 调度的第一印象是「某个厂家的封闭软件，界面点点点」，出了问题上论坛都搜不到答案。openTCS 把「派单、找路、避让」这三件事摊开给你看，默认实现还带了一套，你可以先跑通，再按自己车间的情况去改。手册第 4 章整章都在讲默认策略：默认停车位置怎么选、停车位置优先级怎么排、充电位置怎么定、成本函数怎么算、路由组怎么划、资源怎么分配和释放、调度公平性怎么保证、外设作业怎么预留令牌。这些名词第一次看确实发怵，但你只要记住一句话就够了：这一章讲的是「车没事干的时候停哪、车干活的时候怎么排队」。

还有一个新手容易忽略的好处：openTCS 对车辆本身几乎是中立的。手册开篇就强调，它对车辆的控制和车辆的具体特性无关，导航原理、轨道引导方式、负载处理设备都不在它的关心范围内，它可以同时管理执行不同任务的多种车型。真正做到这一点靠的是「车辆驱动」这个适配层，后面第 4 章我们会专门讲它。这意味着你在这儿学会的调度思路，换一家车厂、换一种导航方式，基本不用重学。

2.2 内核加客户端：先认清谁在指挥谁

刚打开这套系统的人最容易犯的迷糊，是把四五个程序图标一起双击开，然后对着满屏窗口不知道先动哪个。先把结构理清楚，后面所有操作都会顺。

openTCS 采用客户端-服务器架构，每个组件都是独立进程。服务端只有一个：Kernel，也就是内核，它跑着与车辆无关的策略和驱动，是整个系统的大脑。客户端有好几个：模型编辑器负责建工厂模型；操作台负责在工厂运行期间把模型可视化出来、并交互式地创建运输订单；内核控制中心负责控制和监视内核，比如把车辆驱动分配给车辆、查看车辆状态、手动给车发报文。除此之外，你还可以自己写客户端接进来，Java 客户端走 RMI 接口，其它语言的系统走 Web API，用来创建和撤销运输订单、拿订单状态更新。

打个饭馆的比方：内核是后厨，模型编辑器是给厨房画平面图的设计师，操作台是前台点单和看进度的大屏，内核控制中心是挂在后厨墙上的监控屏，能看到每个灶眼的状态。前台不能直接炒菜，设计师画完图也得把图纸交给后厨才算数——所有客户端都要和内核通信，内核不在，客户端基本就是个空壳。

理清这一点，你就明白为什么手册第 3 章要分成「构建新的工厂模型」和「运作工厂」两半：前半段是画图纸，后半段是开火做饭。

2.3 第一次翻手册，别从第一页读起

手册有六章，硬着头皮从头读到尾，大概读到第 4 章「默认策略」就会放弃。第一次用，建议按这个顺序翻：

1. 先看第 1.2 节「系统要求」，确认 Java 环境这件事，这是唯一一个不解决就什么都做不了的前置条件。
2. 跳到第 2.2 节「工厂模型要素」，把点、路径、位置、位置类型、车辆、块、图层、图层组这八个名词过一遍，只求眼熟，不求记住。
3. 回到第 3.1 节，跟着「构建新的工厂模型」一步步做，边做边回头查第 2.2 节。
4. 模型建完，看第 3.2 节「运作工厂」，把车跑起来。
5. 剩下第 4 章策略、第 5 章配置、第 6 章高级示例，全部当字典，遇到问题再查。

这里有个血泪经验：手册第 5 章是配置项大全，从内核、订单池、调度程序、路由器、外设作业调度程序，一直到 Web API、RMI 接口、SSL 加密、虚拟车辆、虚拟外设，逐条列了每个配置项是什么意思。新手最常见的翻车方式，是一上来就打开配置文件逐行读，读到最后连自己要改哪个都不知道。正确姿势是先用默认配置把系统跑起来，等你真的遇到「我想让车自动回充电位」这种具体需求，再去第 6 章「高级使用示例」里找对应的那一节，它会告诉你该动哪几个配置项。

还有个小提醒：手册里「默认调度程序」这个词出现了两次，4.1 和 4.3 都叫这个名字，但对应的英文其实是两个不同的角色，一个管派单，一个管资源分配。第一次读容易看串，建议对照英文原文区分，别被中文译名绕进去。

3. 第一个工厂模型：从零画出一条能跑通的路

3.1 环境先过关：Java 13 和 PATH 这两件事

整套系统跑不跑得起来，八成卡在这一步。手册第 1.2 节写得很明确：运行 openTCS 需要 Java 运行环境版本 13，而且 JRE 的 bin 目录必须加进系统环境变量 PATH，否则自带的启动脚本找不到 Java。同一节还有一条警告，说因为系统用到的某个界面库存在限制，某些 JRE 和 openTCS 不兼容，比如 Oracle 提供的 JRE 就是如此，建议使用 Adoptium 项目提供的 JRE。

先验证一下现在机器上是什么情况：

# 查看当前默认的 Java 版本 # 输出第一行应该能看到 13 这个版本号 java -version

如果输出的是别的版本，或者干脆提示找不到命令，就说明 PATH 没配好。Linux 或 macOS 上可以临时这样设：

# 指向 JRE 13 的安装目录，再把 bin 目录放到 PATH 最前面 export JAVA_HOME=/opt/jdk-13.0.2.8-hotspot export PATH="$JAVA_HOME/bin:$PATH" # 再验证一次 java -version

Windows 上如果用 PowerShell 临时试，可以写成$env:Path = "C:\Program Files\AdoptOpenJDK\jdk-13.0.2.8-hotspot\bin;" + $env:Path，但这只在当前窗口有效。想长期生效，老老实实打开「系统属性 → 环境变量」，在 Path 里加一条指向 bin 目录的路径，然后重开一个命令行窗口再验证。

注意：装好 Java 之后一定要开一个新的命令行窗口再试。已经开着的窗口读的是旧环境变量，改完不生效，很多人会误以为装错了。

这一步过了，后面基本就没有环境问题了。手册里也提到，openTCS 本身没有任何特殊的硬件要求，CPU 和内存取决于你路线的复杂程度和管理的车辆数量，另外需要一块普通的网卡用于和车辆通信。也就是说，你先在自己笔记本上把流程跑通，是完全可行的。

3.2 三个客户端别一起开：模型编辑器的第一次启动

环境好了，第一个要开的不是内核，是模型编辑器。因为内核要加载工厂模型才能干活，你手上还没有模型。

打开模型编辑器之后，你的目标只有一个：画出一张最小可用的地图。所谓最小可用，就是能让一辆车从 A 点开到 B 点、并且在中途不撞墙不迷路。别想着一次把整个车间画完，第一张图越简单越好。

界面里你会看到几个部分：一块绘图区，用来摆放点和路径；一个要素列表或者树状结构，列出当前模型里的所有东西；还有属性面板，选中某个要素之后在这里改它的名字、坐标、速度这些参数。手册第 3.1.2 节讲的就是怎么往里加要素，第 3.1.3 节讲图层和图层组，第 3.1.4 节讲保存。建议第一次建模型时先不碰图层，等地图超过二三十个点、画面上开始糊成一片了再说。

新手在这里最容易犯的错，是给要素随便起名。手册第 2.4.1 节专门讲了「唯一名称」这个公用属性，模型里每个要素的名字必须是唯一的。你今天随手起个「点1」「点2」，明天车间里有八十个点，自己都认不出哪个是哪个。养成习惯：名字里带上位置信息，比如「原料库-入口」「产线A-工位3」，后面排查问题的时候你会感谢自己。

3.3 五个要素搭出最小地图：点、路径、位置、位置类型、车辆

现在动手搭。一个能跑通的最小模型，需要五种要素，我按添加顺序说。

第一步，加点。点是行驶路线中车辆的逻辑映射，运行时车辆被命令从一个点移动到另一个点。点有三种类型，这是新手第一个必须记牢的知识点：

先加两个「停靠位置」类型的点，命名成「起点站」和「终点站」，给它们填好坐标。手册还提到点有一个「车辆方向角」属性，表示车辆占据该点时的预期朝向，注意 openTCS 里 0 度在 3 点钟位置，正值是顺时针旋转——这个和很多人习惯的数学坐标系不一样，画的时候别搞反。

第二步，加路径。路径连接两个可导航的点，属性里有长度、最大行进速度、最大倒车速度、锁定标志，还有一串外设操作。把刚才那两个点连起来，长度按实际距离填，速度按车的实际能力填。

第三步，加位置。这里是新手最容易和「点」搞混的地方。点是车行驶路线上的节点；位置是车可以执行特殊操作的地方，比如装卸货、充电，而且要链接到至少一个点上才能在工厂模型里用起来。换句话说，位置是挂在点上的「功能标签」。给「起点站」挂一个位置，类型叫装载位；给「终点站」挂一个位置，类型叫卸载位。

第四步，加位置类型。位置类型是抽象层，只干两件事：定义这类位置允许车辆执行哪些操作，以及允许挂在这类位置上的外设设备执行哪些操作。先建「装载位」和「卸载位」两个类型，各勾上允许的操作。

第五步，加车辆。车辆映射的是实物车。要填的属性不少：临界电量级别、良好电量级别、完全充电电量级别、充分充电电量级别，还有最大运行速度和最大倒车速度。前四个是电量阈值，运行时用来判断什么时候必须充电、什么时候可以不充、什么时候该停止充电。第一次建模型随便填几个合理值就行，比如临界 20%、良好 80%。这里有个特别容易忽略的属性叫「集成级别」，它表示当前允许把车辆集成到系统的程度，可以是忽略、关注、尊重等等，而且手册明确说了，这个值只能在操作台里调整，模型编辑器里改不了。第一次跑不通订单，十有八九是它没设对，后面第 5 章还会专门讲。

3.4 布局坐标和模型坐标：画歪了真没关系

画图的时候你可能会发现一个问题：为了让画面好看，你把某两个点的距离拉得很近，但实际车间里这段路有五十米长。这时候长度属性填 50，图上却显示得很短，看着别扭。

手册第 2.2.1.1 节专门解释了这件事：一个点其实有两套坐标系。布局坐标系只负责在模型编辑器和操作台里把地图画出来给你看；模型坐标系才是真正可能被车辆驱动使用、或者发给车辆的数据。这两套坐标系本身并不相关，可以不一样。设计成这样就是为了让你能一边保持画面可读，一边保持数据准确。

那什么时候需要同步？当你发现图上位置和实际位置对不上、或者车报告的坐标看着很怪的时候。同步有两个办法：全局同步用菜单里的「操作 › 将模型值复制到布局」或「操作 › 将布局值复制到模型」；只改某一个要素，就右键点它，在上下文菜单里选同样的两项。记住方向别搞反：把模型值复制到布局，是用真实数据刷新画面；把布局值复制到模型，是用你拖动后的画面位置覆盖真实数据。后者慎用。

提示：拖点改变画面位置，只影响布局坐标，不影响车辆的导航数据。想改真实坐标，去属性面板里改数值。

3.5 保存并加载到内核：图纸变成活地图

模型建完，按第 3.1.4 节保存。保存下来的是一个工厂模型文件，手册在讲问题反馈时提到，内核和模型编辑器的 data/ 子目录里就放着这个文件。这个细节值得记住：以后模型出问题，第一件事就是去这个目录把文件找出来，它是你所有排查的起点。

保存之后，光有文件还不够，得让内核加载它。顺序是：先启动内核，再打开内核控制中心连上去，在里面把模型加载进内核。加载成功之后，模型就从一份静态文件变成了内核里「活的地图」——这时候操作台才能把它可视化出来，车辆才能在上面跑。

第一次加载失败很常见，通常是要素之间有断点：某个路径的起点或终点没连上，或者整条路线全是报告位置、根本没有可以停靠的点。手册里明确说了，只由报告位置组成的路线是无法路由的，因为车辆没法在任何位置停下来。所以加载失败的时候，先别怀疑软件，回到图上从头到尾捋一遍，看看有没有哪个点忘了设类型。

4. 让车动起来：第一张运输订单的完整流程

4.1 启动内核和操作台，先确认车在线

模型加载进内核之后，打开操作台。操作台的作用有两个：把工厂模型可视化出来，让你看到每台车在哪、在干什么；以及交互式地创建新的运输订单。

刚打开的时候，你多半会看到一张空地图，车没有出现。别急，这不是模型坏了。车辆要在操作台里显示出来，前提是它在模型里的集成级别不是「忽略」。手册写得很清楚：被设为忽略的车辆，连同它报告的位置会被完全忽略，根本不会在操作台里显示，也不能接运输订单；设为关注的车辆会显示位置，但系统不会在那个位置分配任何资源，同样不能接单；只有集成级别足够高的车辆，才会真正参与调度。

所以第一件事是去操作台里把这台车的集成级别调上来。这也是为什么手册强调集成级别只能在操作台调整、不能在模型编辑器调整——它是个运行时开关，不是模型属性。

4.2 车辆驱动：openTCS 和真车之间的翻译官

车显示出来了，但它还不会动。原因很简单：内核不知道怎么跟这台车说话。

手册开篇就讲清楚了，openTCS 本身并不是一个能直接拿来控制 AGV 的完整软件，它是一个框架加上基本数据结构和算法实现。要真正控制车辆，至少需要创建并插入一个车辆驱动，手册里也叫通信适配器，作用是在内核的抽象接口和你的车辆所理解的通信协议之间做转换。这个角色和操作系统里的设备驱动程序很像。

这就带来一个新手必须接受的事实：如果你手上没有真实车辆，或者车辆厂商没有提供现成的驱动，那你第一步跑通的只能到「虚拟车辆」这一层。手册第 5 章配置部分专门有「虚拟车辆配置项」和「虚拟外设配置项」，第 6 章高级示例里还有「配置虚拟车辆的特征」一节。用虚拟车辆先把整条链路跑通，是新手最稳妥的路径——你验证的是模型、订单、调度这套逻辑，不是车辆通信。

有真车的话，流程是：打开内核控制中心，把对应的车辆驱动分配给车辆，然后观察车辆状态信息。内核控制中心还提供一些低级别的功能，比如手动向相关车辆发送报文，调试通信的时候特别有用。

4.3 下第一张订单：三样东西必须对上

现在下第一张运输订单。手册第 3.2.3 节讲创建订单，第 3.2.4 节讲怎么用操作台撤销订单，第 3.2.5 节讲连续创建订单。

一张订单最核心的信息是「从哪到哪」：起点位置、终点位置。这两个位置必须是你在模型里建好的、并且链接到了点上的位置。系统拿到订单后会走三步：调度程序决定派哪台车，路由程序算出走哪条路，调度器在车辆经过的路径上分配资源防止相撞。这三步都是自动的，你不需要干预。

订单建好之后，观察操作台。你会看到被选中的车开始沿路径移动，到达起点位置后执行装载操作，然后沿路径驶向终点。如果车一直停在原地不动，按这个顺序查：车辆集成级别对不对、车辆驱动分配了没有、起点和终点位置是不是被设了锁定标志。手册提到位置有个锁定标志，设置之后调度程序会认为需要在该位置执行操作的订单可能无法分配给车辆。这个开关本来是给临时施工、设备维修这类场景用的，新手建模型时误勾了，就会出现「订单建了、车就是不来」的玄学现象。

4.4 订单序列和外设作业：让流程连成串

一张订单跑通之后，可以往深走一小步：订单序列和外设作业。

订单序列是把手头几张订单按顺序串起来执行，适合「先送原料、再取成品、最后回充电位」这种有先后关系的流程。手册第 2.3 节把它和运输订单、外设作业放在一起讲，都属于工厂运行要素。

外设作业稍微复杂一点，但理解了很有用。车间里除了车，还有别的设备要配合：防火门要开、电梯要叫、充电桩要通电。这些在 openTCS 里叫外设设备，位置可以映射外设设备，路径上可以挂一串外设操作。每个外设操作有几个关键属性：引用哪台外设设备、执行什么操作、什么时候执行、以及一个「完成要求」标志。

「什么时候执行」由运行触发器决定，只有两个取值：BEFORE_MOVEMENT 表示车辆穿过这条路径之前触发，AFTER_MOVEMENT 表示穿过之后触发。这个标志要和「完成要求」配合着看：如果触发器是 BEFORE_MOVEMENT 且完成要求为真，车辆必须在路径的源点等着，直到操作完成才能走；如果是 AFTER_MOVEMENT 且完成要求为真，车辆就在目的地等。想明白这一层，你就能设计出「车到门口 → 门开 → 门确实开了 → 车才通过」这种带安全确认的流程。

配置外设设备的驱动在第 3.2.6 节，创建外设作业在第 3.2.7 节，撤销在第 3.2.8 节。跟车辆一样，没有真实外设的时候，先用虚拟外设把流程走一遍。

5. 新手避坑：五个现象、五个原因、五个解法

现象一：双击启动脚本，窗口一闪就没了。原因：脚本内部调用了 java 命令，但系统 PATH 里找不到，或者找到的是不兼容的版本。手册明确警告过，因为界面库的限制，某些 JRE 和 openTCS 不兼容，Oracle 提供的 JRE 就是其中之一。 解决：开一个命令行窗口，手动执行java -version看版本号。不是 13 就重装，装 Adoptium 提供的版本，然后把 bin 目录加进 PATH，重开窗口再试。这一步别偷懒用「差不多能用」的版本，界面起不来的时候你根本分不清是环境问题还是模型问题。

现象二：模型建好了，加载到内核时提示路线无法路由。原因：路线上全是报告位置。手册写得很直白，报告位置只用于上报，车辆不会被命令到那儿，也不允许停靠甚至停车，所以只由报告位置组成的路线根本没法路由。 解决：从头到尾检查每个点的类型，至少要有一个停靠位置或者停车位置作为起点和终点。另外顺手看一眼路径的锁定标志有没有被勾上——勾上之后路由器计算路线时会直接跳过这条路径。

现象三：订单创建成功，车一直不动。原因：三个地方按概率从高到低排——车辆集成级别被设成忽略或关注，车辆不参与订单分配；车辆驱动没分配给车辆，内核不知道怎么跟它通信；起终点位置被设了锁定标志，调度程序直接跳过。 解决：先去操作台确认车的集成级别，再去内核控制中心确认驱动分配，最后回模型编辑器检查位置的锁定标志。这三个点按顺序过一遍，九成的问题当场解决。

现象四：地图上拖动点之后，车报告的坐标全乱了。原因：布局坐标和模型坐标是两套独立的东西，拖动只改布局坐标。如果你之前手动改过模型坐标，两套数据就对不上了。 解决：先明确你要改哪一个。只想让画面好看，随便拖；想改真实导航数据，去属性面板改数值，或者用「操作 › 将模型值复制到布局」把真实数据刷到画面上。方向搞反用「将布局值复制到模型」，会把拖出来的视觉位置当成真实坐标写回去，属于自己给自己埋雷。

现象五：改了配置文件，重启之后一点效果都没有。原因：改错了文件。这套系统有好几个独立进程，内核有内核的配置，模型编辑器有模型编辑器的配置，操作台有操作台的配置，内核控制中心的 SSL 又是单独一组。很多新手在内核的配置文件里找界面语言，找了半天找不到，因为应用程序语言是单独一项，不在内核配置里。 解决：改之前先想清楚这个行为归谁管。跟派单、找路、订单池、Web API、RMI 相关的，是内核配置；跟画图时要素怎么命名相关的，是模型编辑器的要素命名方案配置。手册第 5 章把每一组配置项都分节列出来了，按进程去找，别在错的文件里翻。

注意：报问题或者自己排查时，记得把 log/ 子目录里的日志一起看。内核、内核控制中心、模型编辑器、操作台各自都有 log/ 子目录，光看界面提示很难定位。

6. 下一步学什么：从「能跑」到「能改」的三条路

第一张订单跑通之后，接下来往哪走，取决于你想解决什么问题。我给三个方向，按难度排。

方向一：把默认策略读懂。这是性价比最高的一步。手册第 4 章讲了默认停车位置怎么选、停车位置优先级怎么排、默认充电位置怎么选、成本函数怎么算、路由组怎么划、资源怎么分配和释放、调度公平性怎么保证。读的时候不要当理论看，带着问题读：我的车干完活为什么停在那儿不停在充电桩旁边？为什么两台车总是同一台在跑？答案多半就在这一章。

方向二：学配置项的用法。手册第 5 章是配置大全，第 6 章给了八个现成的高级示例：配置自动启动、启动时自动选择特定车辆驱动、配置虚拟车辆的特征、在不同系统上运行内核和客户端、对与内核的通信进行加密、配置自动停车和充电、配置订单池清理、为项目特定数据使用模型要素属性。想实现什么功能，先去第 6 章找有没有现成示例，有就照着改，没有再回第 5 章逐项查。

方向三：动手改代码。到这一步说明你已经开始做项目了。手册第 1.4 节提到，要扩展和自定义 openTCS，得看开发者指南和 JavaDoc 文档，它们是发行版的一部分。另外记得三件事：调度程序、路由程序、调度器这三个策略模块的默认实现都可以替换；车辆驱动是可以自己写的适配层；对外集成走 Web API 或 RMI 接口，不用改内核。数组一下自己的需求落在哪一层，比闷头读源码快得多。

最后说个我自己的教训。我第一次搭环境的时候，图省事用了机器上现成的 Java，结果模型编辑器打开一片空白，我以为是显卡驱动的问题，折腾了一下午。后来老老实实按手册第 1.2 节装了指定版本的 JRE，把 bin 目录加进 PATH，重开窗口，一次就起来了。从那以后我每次碰这套系统，都强制先跑一遍java -version，版本对不上就不往下走，宁可花两分钟，也不花两小时。

希望帮到你。

本文还有配套的精品资源，点击获取