openplc runtimev4 Python插件虚拟环境指南

Python插件虚拟环境指南

本文档描述了如何在OpenPLC运行时中为Python插件使用单独的虚拟环境（venv），允许每个插件拥有自己的依赖项而不会产生冲突。

概述

分离的虚拟环境系统允许您：

• 让每个Python插件使用特定的库版本
• 避免不同插件的依赖项之间的冲突
• 简化插件开发与维护
• 保持与现有插件的兼容性

文件结构

openplc-runtime/
├── venvs/                          # 虚拟环境目录
│   ├── modbus_slave/               # Modbus插件的venv
│   └── mqtt_client/                # MQTT插件的venv
├── core/src/drivers/plugins/python/
│   ├── modbus_slave_plugin/
│   │   ├── simple_modbus.py
│   │   ├── modbus_slave_config.json
│   │   └── requirements.txt        # 插件特定依赖项
│   └── mqtt_plugin/
│       ├── plugin.py
│       ├── config.json
│       └── requirements.txt
└── scripts/
    └── manage_plugin_venvs.sh      # 管理脚本

使用方法

1. 创建带虚拟环境的插件

1. 创建插件目录：

   mkdir core/src/drivers/plugins/python/my_plugin

2. 创建requirements.txt文件：

   echo "pymodbus==3.6.4" > core/src/drivers/plugins/python/my_plugin/requirements.txt
   echo "paho-mqtt==2.1.0" >> core/src/drivers/plugins/python/my_plugin/requirements.txt

3. 创建虚拟环境：

   ./scripts/manage_plugin_venvs.sh create my_plugin

4. 配置plugins.conf：

   my_plugin,./core/src/drivers/plugins/python/my_plugin/plugin.py,1,0,./config.json,./venvs/my_plugin

2. 管理虚拟环境

为插件创建虚拟环境：

./scripts/manage_plugin_venvs.sh create PLUGIN_NAME

列出所有虚拟环境：

./scripts/manage_plugin_venvs.sh list

安装依赖项：

./scripts/manage_plugin_venvs.sh install PLUGIN_NAME

移除虚拟环境：

./scripts/manage_plugin_venvs.sh remove PLUGIN_NAME

虚拟环境信息：

./scripts/manage_plugin_venvs.sh info PLUGIN_NAME

plugins.conf格式

新格式（带虚拟环境）：

# 名称,路径,启用状态,类型,配置文件路径,虚拟环境路径
modbus_slave,./core/src/drivers/plugins/python/modbus_slave_plugin/simple_modbus.py,1,0,./config.json,./venvs/modbus_slave

旧格式（无虚拟环境 - 仍然兼容）：

# 名称,路径,启用状态,类型,配置文件路径
example_plugin,./core/src/drivers/examples/example_python_plugin.py,1,0,./example_config.ini

实际示例

带有特定虚拟环境的Modbus插件：

1. 创建requirements.txt：

   cat > core/src/drivers/plugins/python/modbus_slave_plugin/requirements.txt << EOF
   pymodbus==3.6.4
   asyncio-mqtt==0.16.2
   EOF

2. 创建虚拟环境：

   ./scripts/manage_plugin_venvs.sh create modbus_slave

3. 配置plugins.conf：

   modbus_slave,./core/src/drivers/plugins/python/modbus_slave_plugin/simple_modbus.py,1,0,./core/src/drivers/plugins/python/modbus_slave_plugin/modbus_slave_config.json,./venvs/modbus_slave

4. 验证安装：

   ./scripts/manage_plugin_venvs.sh info modbus_slave

兼容性

• 现有插件： 无需更改即可正常工作
• 传统系统： 如果venv_path为空或缺失，则使用系统Python
• Python版本： 适用于Python 3.6+

故障排除

插件找不到模块：

• 检查虚拟环境是否创建：./scripts/manage_plugin_venvs.sh list
• 检查依赖项是否已安装：./scripts/manage_plugin_venvs.sh info PLUGIN_NAME
• 检查plugins.conf中的路径

依赖项冲突：

• 每个插件都有自己的隔离虚拟环境
• 在requirements.txt中使用特定版本
• 如果需要，重新创建虚拟环境：./scripts/manage_plugin_venvs.sh remove PLUGIN_NAME && ./scripts/manage_plugin_venvs.sh create PLUGIN_NAME

构建错误：

• 更改后重新编译：./scripts/compile.sh
• 验证Python头文件是否已安装：sudo apt install python3-dev

限制

• 每个虚拟环境会占用额外的磁盘空间
• 启动时间稍长
• 需要Python 3.3+以使用原生venv

技术架构

实现：

1. plugin_config.h： 在结构中添加了venv_path字段
2. plugin_config.c： 更新解析器以读取可选的第六个字段
3. plugin_driver.c： 在导入插件之前设置sys.path的逻辑
4. manage_plugin_venvs.sh： 完整的管理脚本

加载流程：

1. 系统读取plugins.conf
2. 如果指定了venv_path，则设置sys.path以包含虚拟环境的site-packages
3. 导入插件的Python模块
4. 照常执行init/start/stop/cleanup函数

该系统在需要时保持与现有插件的完全兼容性，同时实现依赖项隔离。