ghcr.io/autonomy-logic/openplc-runtime:v4.2.0

OpenPLC Runtime v4

OpenPLC Runtime v4 是一款无头工业可编程逻辑控制器（PLC）运行时，可在标准计算硬件上运行 IEC 61131-3 程序。它设计为由 https://github.com/Autonomy-Logic/openplc-editor 桌面应用程序通过 REST API 或 Autonomy Edge Cloud 进行控制。

OpenPLC Runtime 组件

OpenPLC Runtime v4 包含两个主要组件：

1. REST API 服务器（Python/Flask） - 端口 8443 上的 HTTPS 接口，供 OpenPLC Editor 上传程序、监控编译和控制执行
2. PLC 运行时核心（C/C++） - 具有确定性扫描周期的实时执行引擎

该运行时执行在 OpenPLC Editor 中创建的程序，支持 IEC 61131-3 编程语言（梯形图、结构化文本、功能块图等）。

快速开始

Docker（推荐）

最快的入门方式：

docker pull ghcr.io/autonomy-logic/openplc-runtime:latest

docker run -d \
--name openplc-runtime \
-p 8443:8443 \
--cap-add=SYS_NICE \
--cap-add=SYS_RESOURCE \
-v openplc-runtime-data:/var/run/runtime \
ghcr.io/autonomy-logic/openplc-runtime:latest

运行时将启动并在端口 8443 上监听来自 OpenPLC Editor 的连接。**不要在浏览器中打开 https://localhost:8443**——与 v3 运行时不同，此处没有 Web 界面。相反，请打开 OpenPLC Editor 桌面应用程序，配置运行时 IP 地址和凭据以进行连接。

预构建二进制文件： amd64、arm64、armv7

Linux 安装

安装（推荐）

curl -fsSL https://runtime.getedge.me | sudo bash

runtime.getedge.me 会原封不动地提供 scripts/install-docker.sh。在该主机发布之前，可直接使用针对 GitHub 的相同单行命令：

curl -fsSL https://raw.githubusercontent.com/Autonomy-Logic/openplc-runtime/main/scripts/install-docker.sh | sudo bash

无需检出代码，无需构建工具链，无需预先安装依赖项。该脚本会在 Docker 缺失时安装 Docker，然后启动运行时及旁边的小型引导程序。引导程序允许 OpenPLC Editor 日后无需 SSH 即可更改运行时版本。

如果设备已通过 systemd 运行 OpenPLC，安装程序会先停止并禁用它——否则两者会争夺端口 8443。其位于 /var/lib/openplc-runtime 中的数据会被重用，因此用户、凭据和存储的项目会保留。

如需卸载：

curl -fsSL https://runtime.getedge.me | sudo bash -s -- --uninstall --yes

这将删除容器和镜像，恢复被其取代的任何 systemd 运行时，并保留 /var/lib/openplc-runtime。添加 --purge 可同时删除该目录。Docker 本身会保留安装。

WebSocket 调试接口

OpenPLC Editor 使用 WebSocket 接口进行实时调试。高级集成者也可使用此接口：

import { io } from 'socket.io-client';

// 使用 JWT 认证连接
const socket = io('https://localhost:8443', {
path: '/socket.io',
transports: ['websocket'],
auth: { token: jwt_token },
rejectUnauthorized: false // 用于自签名证书
});

// 监听连接事件
socket.on('connect', () => {
console.log('已连接到运行时');
});

// 发送调试命令（十六进制编码）
socket.emit('debug_command', {
command: '44 00 03 00 00 00 01 00 02' // 获取变量 0、1、2
});

// 接收响应
socket.on('debug_response', (response) => {
console.log(response.data);
});

有关完整的调试协议文档，请参见 docs/DEBUG_PROTOCOL.md 和 webserver/DEBUG_WEBSOCKET.md。

Docker 使用方法

基本用法

# 拉取镜像
docker pull ghcr.io/autonomy-logic/openplc-runtime:latest

# 使用持久化存储运行
docker run -d \
--name openplc-runtime \
-p 8443:8443 \
-v openplc-runtime-data:/var/run/runtime \
ghcr.io/autonomy-logic/openplc-runtime:latest

# 查看日志
docker logs -f openplc-runtime

# 停止容器
docker stop openplc-runtime

Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
openplc-runtime:
image: ghcr.io/autonomy-logic/openplc-runtime:latest
container_name: openplc-runtime
ports:
- "8443:8443"
volumes:
- openplc-runtime-data:/var/run/runtime
restart: unless-stopped

volumes:
openplc-runtime-data:

启动命令：docker-compose up -d

有关完整的 Docker 文档，请参见 docs/DOCKER.md。

运行时使用基于JWT的身份验证：

• 通过 POST /api/create-user 创建首个用户（无需身份验证）
• 通过 POST /api/login 登录返回JWT访问令牌
• 所有后续请求需包含 Authorization: Bearer 头
• 密钥存储在持久数据目录下的 .env 文件中（原生Linux系统为 /var/lib/openplc-runtime，Docker中为 /var/run/runtime）
• 使用 PBKDF2-SHA256 进行密码哈希（600,000 次迭代），并使用盐（salt）和胡椒值（pepper）

完整安全文档请参见 docs/SECURITY.md。

故障排除

常见问题

无法从 OpenPLC Editor 连接：

# 检查运行时是否正在运行
ps aux | grep python3 | grep webserver

# 检查端口 8443 是否在监听
sudo netstat -tlnp | grep 8443

# 检查防火墙
sudo ufw status

编译失败：

# 检查运行时日志
sudo journalctl -u openplc-runtime -n 50

# 检查运行时目录是否存在
ls -la /run/runtime/

权限错误：

# 确保使用 sudo 运行
sudo ./start_openplc.sh

# 检查套接字目录权限
ls -la /run/runtime/

完整故障排除指南请参见 docs/TROUBLESHOOTING.md。

开发

设置开发环境

git clone https://github.com/Autonomy-Logic/openplc-runtime.git
cd openplc-runtime
git checkout development
sudo ./install.sh

运行测试

bash scripts/run-pytest.sh

提交前钩子

pip install pre-commit
pre-commit install

代码风格

• C/C++： 遵循现有风格，4空格缩进，不使用制表符
• Python： 遵循 PEP 8 规范，使用类型提示，添加文档字符串
• 代码、注释或文档中禁止使用表情符号（项目标准）

贡献指南

1. Fork 本仓库
2. 从 development 分支创建功能分支
3. 进行修改
4. 提交拉取请求

完整开发指南请参见 docs/DEVELOPMENT.md。

项目结构

openplc-runtime/
├── webserver/ # Flask Web应用（Python）
│ ├── app.py # 主应用入口
│ ├── restapi.py # REST API蓝图
│ ├── debug_websocket.py # WebSocket调试接口
│ └── ...
├── core/
│ ├── src/plc_app/ # PLC运行时源代码（C/C++）
│ │ ├── plc_main.c # 主入口点
│ │ ├── plc_state_manager.cpp/h # 状态管理
│ │ ├── unix_socket.c/h # IPC服务器
│ │ └── utils/ # 工具类（日志、看门狗、定时）
│ └── src/drivers/ # 插件驱动系统
├── scripts/ # 构建和管理脚本
│ ├── compile.sh # 编译PLC程序
│ ├── compile-clean.sh # 清理并重命名库
│ └── manage_plugin_venvs.sh # 插件虚拟环境管理
├── build/ # 编译输出
│ ├── plc_main # 编译后的运行时可执行文件
│ └── libplc_*.so # 编译后的PLC程序库
├── docs/ # 文档
├── CMakeLists.txt # CMake构建配置
├── Dockerfile # 容器定义
├── install.sh # 安装脚本
└── start_openplc.sh # 启动脚本

系统要求

最低要求

• CPU： 1 GHz 单核
• 内存： 512 MB
• 磁盘： 500 MB 可用空间
• 操作系统： Linux（Ubuntu 20.04+、Debian 11+、Fedora、CentOS、RHEL）

推荐要求

• CPU： 2 GHz 双核或更高
• 内存： 1 GB 或更大
• 磁盘： 1 GB 可用空间
• 操作系统： Ubuntu 22.04 LTS 或 Debian 12

实时性能

如需确定性实时性能：

• 建议使用专用CPU核心
• 实时内核（PREEMPT_RT）可选但推荐
• 最小化后台进程
• SCHED_FIFO调度需 root 权限

许可证

详情参见 LICENSE 文件。

支持

• 问题反馈： https://github.com/Autonomy-Logic/openplc-runtime/issues
• 文档： 参见 docs/ 目录
• OpenPLC Editor： https://github.com/Autonomy-Logic/openplc-editor

相关项目

• https://github.com/Autonomy-Logic/openplc-editor - PLC编程环境
• https://github.com/thiagoralves/OpenPLC_v3 - 历史版本

致谢

OpenPLC Runtime v4 由 Autonomy Logic 开发和维护。