简介：openTCS 5.9中文版用户手册是一份面向AGV调度系统工程师、物流自动化集成人员及RCS系统维护者的操作型指南，系统讲解开源运输管理系统openTCS的核心机制与使用方法，帮助读者掌握工厂建模、运输订单管理、车辆调度控制等关键技能，适用于物流仓储、智能制造等需要AGV调度的场景。压缩包内为单个PDF文件，大小13.31MB，已有595人学习，便于离线查阅和反复参考。手册从系统介绍、系统要求、许可说明入手，逐步展开系统组件与结构、工厂模型要素（点、路径、位置、位置类型、车辆、块、图层）及运行要素（运输订单、订单序列、外设作业），并覆盖系统操作、重要属性配置、维护与故障排查等章节。对于正在部署AGV调度系统或需要理解RCS调度逻辑的用户，这份手册配有清晰的章节组织和截图辅助，能帮助读者从概念到实践快速建立完整知识链路，降低上手门槛。
1. 装 openTCS 5.9 前先泼盆冷水：它是一套调度框架，不是开箱即用的软件
第一次接触 openTCS 5.9，多半是带着“AGV 调度系统”和“RCS 系统”这类词来的。它是目前少见的开源车队调度框架，制造与仓储场景里的多车导航、订单分派和交通管理都能靠它兜底。但别指望解压就能跑：它默认不带你车辆的通信协议，JRE 版本还卡在 13，版本不符时启动脚本会一句话不说直接退出。装不好，轻则几天耗在环境上，重则模型建完一辆车都不动。这篇笔记写给正在搭 AGV 调度环境、要对接 RCS 系统的开发者，从 JRE 准备到四进程启动，再到车辆真的跑起来，每一步都按我踩过的路径来。
2. 拆解系统架构：内核、三个客户端和工厂模型要素
2.1 四个独立进程：内核、模型编辑器、操作台和内核控制中心
openTCS 5.9 安装完，你会在 bin 目录里看到一列启动脚本，它们对应四个独立进程：内核（Kernel）、模型编辑器（Model Editor）、操作台（Operations Desk）和内核控制中心（Kernel Control Center）。其中内核是唯一的服务器进程，负责维护工厂的抽象行驶模型、管理运输订单、为车辆规划路线；其余三个都是客户端。模型编辑器用来建立和编辑工厂模型；操作台用于工厂运行期间可视化模型、交互式创建运输订单；内核控制中心则负责控制和监视内核，比如查看车辆驱动状态、给车辆关联驱动。
为什么拆成四个进程而不是一个？把与车辆无关的调度逻辑全部收敛进内核之后，上层客户端可以任意替换和扩展，比如再接一个负责与仓库管理系统通信的自定义客户端。这也意味着安装动作不是“启动一个软件”，而是“把四个进程都按顺序跑起来”。实际部署时，内核所在的机器是唯一的服务器，三个客户端可以都跑在同一台机器上，也可以分别部署到不同机器，只要网络能通。
在内核内部，订单的处理由三个策略模块完成。手册里它们的中文翻译容易混在一起，因为 dispatcher 和 scheduler 都被译成“调度程序”，我建议直接记英文职责：
- Dispatcher：决定哪台车辆执行哪个运输订单，也决定车辆空闲时去哪个停车位、电量低时去哪个充电位。
- Router：为车辆计算到达目的地的最佳路线，默认策略按路径成本函数选路。
- Scheduler：管理交通资源分配，避免车辆相撞，也就是交通管理里的“资源锁”。
这三个模块在日志里对应三条记录线，后面第 6 章验证跑通时，就是靠它们各自留下的调度日志来确认安装成功。
2.2 工厂模型的三类点、两类位置和路径属性
在 openTCS 里，工厂模型由点（Point）、路径（Path）、位置（Location）、位置类型（Location Type）、车辆（Vehicle）、块（Block）、图层（Layer）这些要素组成。建模时最先接触、也最容易搞混的是点和位置。
点（Point）是行驶路线中车辆的逻辑映射，分三种类型：
- 停靠位置（Halt Position）：默认类型，车辆处理订单时可以停靠，到达需要报告，但不得超过必要时间。
- 报告位置（Report Position）：车辆只需要经过并报告，不被命令在此停靠，也不允许停车。
- 停车位置（Park Position）：车辆不处理订单时可以长期停靠的位置。
这里有一个新手必踩的坑：只由报告位置组成的路线无法路由，因为车辆没有任何可以停靠的终点。后面第 5 章的排查记录会单独展开。
位置（Location）则标记车辆可以执行特殊操作的点，比如装卸货、充电。位置本身要链接到至少一个点，车辆才能到得了；位置的类型（Location Type）定义了该位置支持哪些车辆操作和哪些外设设备操作。路径（Path）连接两个可导航点，主要属性包括长度、最大前进速度、最大倒车速度、锁定标志，以及一组外设操作。锁定标志一旦设置，路由器计算路线时就不能使用这条路径，这点在做检修区隔离时非常有用。
车辆（Vehicle）映射物理 AGV，属性里有四档电量阈值（临界、良好、完全充电、充分充电），以及最大前进/倒车速度。集成级别（Integration Level）只能通过操作台调整，分为忽略（ignored）、关注（noticed）、尊重（respected），含义分别是不显示不派单、显示但不派单、完全参与调度。
| 点类型 | 能否被命令前往 | 能否停靠/停车 | 典型用途 |
|---|---|---|---|
| 停靠位置 | 能 | 能临时停靠 | 订单处理、装卸货过程中的停靠点 |
| 报告位置 | 不能 | 不能 | 途经点、需要上报位置的通路 |
| 停车位置 | 能 | 能长期停靠 | 车队空闲时的停放点 |
2.3 布局坐标与模型坐标：新手最容易忽略的设定
手册里专门用了一小节讲“布局坐标系与模型坐标系”，这一节在中文资料里很少被提到，但实际部署时几乎必踩。每个点有两套坐标：布局坐标（Layout Coordinates）只用于模型编辑器和操作台里的图形化显示；模型坐标（Model Coordinates）才是车辆驱动使用、甚至发给车辆的真实导航数据。两套坐标本身不关联，可以不同。
这意味着你在编辑器里把点拖到一条直线排好，只改变了图形展示位置，AGV 收到的目标坐标可能还是老样子。如果你的 AGV 需要精确坐标导航，就会出现“图上看着路线整齐，真车跑过去偏得离谱”的情况。要同步两套坐标，可以在菜单里选“操作 > 将模型值复制到布局”或“操作 > 将布局值复制到模型”做全局同步；也可以右键单个要素，在上下文菜单里只同步这一个。这一点在模型保存进内核之前一定要确认，否则后面排错会非常痛苦。
工厂运行要素方面，还需要理解三个概念：运输订单（Transport Order）是让车辆执行一项运输任务的最小单元；订单序列（Order Sequence）是按顺序处理的一批运输订单；外设作业（Peripheral Job）是外设设备需要执行的操作，例如车辆经过某条路径时打开防火门。外设作业由默认外设作业调度程序管理，它用预留令牌机制避免多个车辆作业同时请求同一个外设，这部分配置会在第 4 章讲到。
3. 安装 openTCS 5.9：JRE 13、发行版解压和四进程启动
3.1 JRE 版本为什么卡在 13
openTCS 5.9 手册的“系统要求”写得非常明确：需要 Java 运行环境（JRE）版本 13，并且要求 JRE 的 bin 目录已经加入 PATH 环境变量，否则自带启动脚本没法用。网上不少转载的摘要会把系统要求写成“Java 8 或更高版本”，我对比了手册正文，5.9 的要求是 13，就以手册为准。版本不对的典型后果是：启动脚本执行后没有任何报错窗口，进程一闪就没了。
原因在于 openTCS 使用的界面库 Docking Frames 对 JRE 实现有兼容限制。手册明确警告，部分厂商打包的 JRE 与 openTCS 不兼容。我实践下来的经验是：直接装社区维护的 OpenJDK 13 发行版，具体构建版本选择带 hotspot 的标准版即可，避免那些深度定制过的商业版 JRE。
安装步骤：
# 解压 JRE 到 /opt 目录 tar -xzf OpenJDK13-jre-x64_linux.tar.gz -C /opt # 将 JRE 的 bin 目录追加到 PATH，并设置 JAVA_HOME export JAVA_HOME=/opt/jdk-13.0.2 export PATH=$JAVA_HOME/bin:$PATH # 验证版本，输出应为 openjdk version "13.0.2" 左右 java -version这段配置里最关键的不是 JAVA_HOME，而是 PATH。openTCS 自带的启动脚本在启动时会直接调 java 命令，它并不像某些软件那样自动扫描 JAVA_HOME，脚本里写死的就是 PATH 查找。所以 PATH 配好了，启动脚本就能找到运行时；PATH 没配上，脚本会因找不到 java 而退出。Windows 上道理一样，在系统环境变量里新建 JAVA_HOME，再把%JAVA_HOME%\bin追加到 Path 变量，保存后重开一个终端窗口再验证。
3.2 解压发行版：bin、config、data、log 各管什么
拿到 openTCS 5.9 发行版压缩包后，解压到一个不带中文和空格的路径下，得到如下目录结构：
opentcs-5.9/ ├── bin/ # 各组件启动脚本 ├── config/ # 内核与客户端的配置文件 ├── data/ # 工厂模型、车辆驱动相关数据 ├── log/ # 运行日志 ├── lib/ # 依赖库与第三方驱动 └── LICENSE.txt # 许可证文件这个目录结构值得先记熟，因为排查问题时几乎所有关键信息都在这几个目录里。config 目录存放内核、模型编辑器、操作台各自的配置文件；data 目录存放工厂模型文件，内核和模型编辑器都会在这里读写模型；log 目录对应每个应用都有独立的日志子目录。手册在“支持”一节专门提到，提交问题报告时要把 log 子目录下的日志文件和你正在使用的工厂模型一并附上，缺了这两样，社区基本没法帮你定位。
我一般会顺手确认一下 LICENSE.txt 是否存在，顺便看一眼许可证类型。手册正文写明 openTCS 在 MIT 许可协议下分发，网上有些转载渠道写成 Apache License 2.0，以发行版自带的 LICENSE.txt 为准，别被二手信息带偏。
3.3 启动顺序与启动脚本：先内核，再客户端
四个进程的启动顺序有讲究：必须先启动内核，再启动客户端。客户端启动时会尝试连接内核，内核没起来的话，客户端通常只会记录一条连接失败日志，然后继续等。Linux 下启动内核：
cd opentcs-5.9 ./bin/opentcs-kernel.shWindows 环境则运行同目录下的opentcs-kernel.bat。启动脚本的逻辑很简单：在 PATH 里找 java，读取 config 目录下的内核配置，拉起内核进程，把日志写到 log 目录。内核起来后，再分别启动三个客户端：
# 启动模型编辑器，用于建模型 ./bin/opentcs-modeleditor.sh # 启动操作台，用于运行期可视化和发订单 ./bin/opentcs-operationsdesk.sh # 启动内核控制中心，用于挂车辆驱动和监视内核 ./bin/opentcs-kernelcontrolcenter.sh三个客户端没有强制先后关系，但建议先开内核控制中心，因为它能看到内核的详细状态，方便确认驱动加载情况。内核与客户端之间通过 Java RMI 通信，同时内核还提供 Web API 用于创建和撤销运输订单、查询订单状态，外部系统对接走 Web API 更干净。
3.4 启动后先看三样东西：日志、模型文件和进程状态
启动完成不算装完，我每次都会做三件事确认环境真实可用：
第一，看 log 目录下内核的子目录，确认日志文件已经生成，并且里面有内核启动完成、网络接口注册成功的记录。第二，看 data 目录，确认至少存在一个工厂模型文件。首次启动没有自己的模型时，可以打开模型编辑器加载发行版自带的示例模型，保存后 data 目录里就会出现对应的模型文件。第三，确认四个进程都还活着。启动脚本闪退是最常见的问题，如果启动后几秒内只剩两个进程，大概率是 JRE 版本问题，直接回到 3.1 节排查。
这套检查流程走完，环境才算是真的立住了，接下来才能进入配置阶段。
4. 配置内核与客户端：订单池、车辆驱动和连接参数
4.1 内核配置项：订单池、调度器、路由器和外设作业调度
openTCS 5.9 的内核配置集中在 config 目录下，手册第 5.2 节从订单池、默认调度程序、默认路由器、默认外设作业调度程序、Web API、RMI 接口、SSL 加密、虚拟车辆等维度列了一批配置项。配置文件是文本格式，修改后用启动脚本重启内核生效。挑选几个最影响行为的配置组说明：
| 配置组 | 关键作用 | 应用场景 |
|---|---|---|
| 订单池配置项 | 运输订单的过期清理策略 | 生产计划变更频繁时，避免死订单占着车队资源 |
| 默认调度程序（Dispatcher）配置项 | 停车位置选择、停车优先级、充电位置选择 | 车辆空闲时的行为策略 |
| 默认路由器配置项 | 成本函数、路由组 | 决定车辆选哪条路的计算依据 |
| 默认外设作业调度程序配置项 | 预留令牌机制 | 多车争用同一外设时避免冲突 |
| 虚拟车辆配置项 | 启动时是否启用虚拟车辆 | 没有真实 AGV 时的联调验证 |
以示意性的配置片段说明写法，实际文件里的键名以发行版自带的 cfg 文件为准：
# 订单池：启用自动清理，避免无效订单堆积 # 具体键名以 config 目录下实际文件为准 orderpool.cleanup.enabled=true orderpool.cleanup.interval=600 # 调度：车辆空闲时优先选择停车位 dispatcher.vehicle.idle=true我一般不会一次性改动所有配置，而是先跑通默认配置，确认车队行为符合预期后，再逐项调整。比如默认路由器按路径成本选路，路径长度、最大行驶速度都会进入成本函数计算；如果你想引导车辆走某条固定路线而不是最短路线，可以通过设置路由组或者调整路径属性来实现，而不是盲目改成本公式。
4.2 车辆驱动与集成级别：AGV 从“存在”到“可调度”
openTCS 本身不直接控制某款具体 AGV，它把车辆通信协议隔离在“车辆驱动”（OpenTCS 中叫通信适配器）这一层。安装驱动的做法是把驱动 jar 包放到 lib 目录或指定加载目录，然后在内核控制中心里把驱动关联到对应的车辆。这一步不做，内核面对的只是一堆没有通信能力的抽象车辆对象，订单派下去也没人执行。
驱动关联好之后，还需要在操作台里调整车辆的集成级别。前面说过三个级别：ignored 是完全忽略，车辆不显示也不参与任何订单；noticed 是车辆会显示位置，但系统不会在它所在位置分配任何资源；respected 才允许车辆参与运输订单。实际部署时常犯的错是车辆驱动挂好了、位置也上报了，但订单一直分不出去，打开操作台一看集成级别还在 noticed，这就是典型的“能看见但没被纳入调度”。
4.3 客户端连接配置：RMI 地址、SSL 和跨主机部署
三个客户端默认都往本机内核连，只要内核和客户端在同一台机器上，默认配置就能跑通。真正要改配置的场景是跨主机部署：内核跑在服务器上，操作台放在中控室电脑上，模型编辑器在工程机里。这种情况下，三个客户端各自的应用程序配置里要指明内核主机地址和 RMI 接口配置。
手册第 6.4 节专门给了“在不同的系统上运行内核和客户端”的示例，核心思路是：内核所在机器固定 IP，客户端配置里的连接地址从默认的本机地址改成内核 IP。如果跨公网或跨安全域部署，还需要启用 SSL 加密，手册 5.2.9、5.3.2、5.4.2、5.5.2 分别对应内核、内核控制中心、模型编辑器、操作台四个应用的 SSL 服务端加密配置项。我的建议是：局域网内部署可以先不开 SSL，本地跑通再开；一旦涉及跨网络，SSL 必须开，否则车辆控制指令在网络上裸奔，风险太大。
# 跨主机场景下，假设内核在 192.168.1.10 # 客户端机器的配置文件中修改内核连接地址指向该 IP # 具体键名以发行版配置文件为准 kernel.registry.host=192.168.1.104.4 应用语言与模型命名方案
openTCS 5.9 的应用语言配置在手册 5.1 节，模型编辑器、操作台、内核控制中心各自有语言设置项，默认界面以英文为主。中文用户可以把模型编辑器和操作台的语言切到中文，减少现场操作人员的理解成本。
模型编辑器还有一个容易被忽略的配置：要素命名方案（5.4.3 节）。它决定你在画布上新增点、路径、位置时，系统自动生成的名字规则。项目前期我习惯把命名方案配置成“前缀 + 序号”的格式，例如 Point-001、Path-001、Loc-001，这样内核日志里出现 Point-042 时，能直接对应到图纸编号。如果不配置，默认命名很快会让日志变得没法读，尤其车辆多、路径多的时候，日志里全是无名代码。
5. 常见问题排查：五个安装与调试阶段的典型踩坑记录
5.1 启动即闪退：JRE 与界面库的兼容性问题
现象：执行opentcs-kernel.sh或客户端启动脚本后，终端里没有任何输出，进程几秒内消失，log 目录下要么没有日志，要么只有一条不完整的初始化记录。
原因：openTCS 使用的 Docking Frames 界面库对 JRE 实现有兼容限制，部分厂商深度打包的 JRE 会触发不兼容问题，导致界面框架初始化失败。手册里已经把这个问题写得很直白，属于已知坑。
解决：卸载当前 JRE，换装社区维护的 OpenJDK 13 发行版，重新配置 PATH 后再次执行java -version，确认当前生效的确实是新装的版本。这里有个细节：Windows 上改完系统环境变量后，一定要重开终端窗口再启动，旧窗口里 PATH 还是老值，很容易误判问题没有解决。
5.2 模型能建但路由失败：报告位置不能作为终点
现象：模型画好了，点、路径、位置都齐全，但 dispatcher 一直派不出订单，日志提示找不到可行路线或目的地不可达。
原因：把路线上的点全部建成了报告位置。报告位置不允许车辆停靠，车辆也不会被命令前往报告位置，只由报告位置组成的地图从根本上就无法路由，因为车辆永远没有可停靠的终点。
解决：把需要车辆停靠处理订单的点改成停靠位置，长期停放的改成停车位置，报告位置仅保留给纯途经点。修改后保存模型，并在模型编辑器里重新加载到内核。
5.3 车辆坐标不对：动的是布局坐标，发出去的是模型坐标
现象：操作台视图上路径整齐、位置精确，但真实车辆收到的目标坐标和预期不符，甚至出现车辆朝着错误方向行驶的情况。
原因：建模时拖动的是布局坐标，只改了图形显示；模型坐标没有同步变化，而车辆驱动最终使用的是模型坐标。
解决：在模型编辑器里执行“将模型值复制到布局”或反方向的全局同步，再单独检查可能需要微调的要素。完成同步后保存工厂模型，重新加载到内核。从那以后，我建完模型必定检查两套坐标的一致性，不再只盯着画面看。
5.4 车辆不接单：集成级别停留在 noticed
现象：车辆出现在操作台界面上，位置也在实时上报，但创建运输订单后，订单状态一直停在等待分配，没有车辆响应。
原因：车辆集成级别还处于“关注（noticed）”状态。该状态下系统接收车辆位置报告，但不会在车辆所在位置分配任何资源，车辆也不参与订单分配。
解决：在操作台客户端找到车辆详情，把集成级别调整为“尊重（respected）”。调整后观察内核日志，应能看到该车辆开始参与资源分配和订单评估的记录。
5.5 反馈支持没人理：日志和模型文件没带全
现象：在讨论区发布了问题帖，很久没人回复，或者回复第一句就是“请提供日志文件和工厂模型”。
原因：openTCS 是开源社区的免费支持模式，维护团队没有无限免费支持义务，问题定位必须靠数据。手册明确要求提供两类材料：各应用 log 子目录下的日志文件，以及 data 子目录下的工厂模型文件。
解决：提问前把内核、内核控制中心、模型编辑器、操作台四个应用的日志子目录打包，连同当前使用的工厂模型文件一起上传。日志里带上时间点、操作步骤描述和预期结果，问题被定位的概率会高很多。
6. 验证跑通：用虚拟车辆走一张完整运输订单
6.1 三要素核对清单
配置完成先别急着接真实 AGV，我用虚拟车辆做端到端验证。第一步是在模型编辑器里建一个最小模型：两个停靠位置点 A 和 B，用一条路径连接，B 点旁边放一个位置并链接到 B 点。对照三个要素检查模型是否可运行：点必须是停靠位置或停车位置，不能是报告位置；路径不能带有锁定标志；位置至少链接一个点。三样确认无误后保存模型。
6.2 跑一张虚拟车辆运输订单看三段日志
打开内核配置里的虚拟车辆开关，重启内核，然后在操作台里能看到一台虚拟车辆上线。给它创建一张从 A 到 B 的运输订单，观察这个过程：
操作台视图里，虚拟车辆会从起点出发，沿路径移动到达终点；这个过程中，位置上报、停靠、行驶状态变化都会显示出来。更重要的是内核日志里会出现三段关键记录：dispatcher 完成订单与车辆的匹配、router 计算并输出路径、scheduler 依次分配和释放沿途资源。三段记录齐全，说明内核核心链路是活的。
如果订单发出后没有任何日志反应，先检查虚拟车辆是否处于 respected 状态；如果只有 dispatcher 记录而 router 没有输出，优先怀疑模型里存在不可路由的点类型问题，回到 5.2 节排查。
从那以后我每次装完 openTCS，都强制自己用虚拟车辆走一遍完整订单流程再往下推进，确认 dispatcher、router、scheduler 三个模块都在日志里留下记录，才开始接真实 AGV。这套方法帮我避开了很多“环境看着没问题、一上真车就翻车”的尴尬场面。希望帮到你。
本文还有配套的精品资源，点击获取
