使用iotedgehubdev生成的IoT Hub模块本地运行报仓库名需小写错误

算力阿峰

2026-7-4

问题分析与解决

错误根源

invalid reference format: repository name must be lowercase 是Docker的强制规则：镜像名称（包含仓库名、模块名部分）必须全部使用小写字母，任何大写字母都会触发这个错误。

MODULES变量的作用逻辑

${MODULES.ModBusModule.debug} 是iotedgehubdev的内置变量，它的取值来自模块目录下的docker-compose.yml文件：

变量格式为 ${MODULES.<模块服务名>.<构建配置>}
<模块服务名> 必须和模块目录下docker-compose.yml中定义的服务名称完全一致，且必须小写

具体修复步骤

修改模块目录下的docker-compose.yml
找到ModBusModule模块目录里的docker-compose.yml，将服务名改为全小写，同时确保镜像标签也为小写：

services:
  modbusmodule: # 原ModBusModule改为全小写
    build:
      context: .
      dockerfile: Dockerfile.amd64
      args:
        - ARCH=amd64
    image: modbusmodule:debug # 镜像名全小写

同步修改部署模板文件
打开deployment.debug.amd64.json，把所有涉及模块名的地方统一改成全小写：

"modules": {
  "modbusmodule": { // 模块名全小写
    "version": "1.0",
    "type": "docker",
    "status": "running",
    "restartPolicy": "always",
    "settings": {
      "image": "${MODULES.modbusmodule.debug}", // 变量里的模块名同步小写
      "createOptions": {}
    }
  }
},
"$edgeHub": {
  "properties.desired": {
    "routes": {
      "modbusmoduleToIoTHub": "FROM /messages/modules/modbusmodule/outputs/* INTO $upstream", // 路由里的模块名小写
      "sensorToModbusmodule": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/modbusmodule/inputs/input1\")"
    }
  }
}