智能制造与工业软件 / 系统课时
检查容器端口和现场协议连通性
检查容器端口和现场协议连通性
容器显示正在运行,不代表工业协议客户端一定能够访问模拟设备。本课通过 Docker Compose、DNS 查询、TCP 连接测试和 Modbus TCP、OPC UA 协议读取,逐层确认通信路径,并将端口映射错误、网络不可达和协议请求错误区分开来。
学习目标
- 检查容器运行状态、端口发布关系和服务监听地址。
- 区分宿主机与容器网络中的 DNS 解析和 TCP 连通性。
- 使用 Modbus TCP、OPC UA 客户端验证协议响应,并根据错误类型定位故障。
核对容器状态和端口映射
在包含 compose.yaml 的项目目录执行检查。以下以两个示例服务为背景:simulator 提供 Modbus TCP 和 OPC UA,gateway 是需要访问模拟设备的边缘网关。实际服务名称必须以当前 Compose 文件为准。
假设模拟设备采用以下端口关系:
| 协议 | 容器监听端口 | 宿主机访问地址 | 用途 |
|---|---|---|---|
| Modbus TCP | 502 | 127.0.0.1:1502 |
读取寄存器和线圈 |
| OPC UA | 4840 | 127.0.0.1:14840 |
建立会话并读取节点 |
这些端口是演示配置,不代表项目已经发布了对应服务。先检查实际状态:
docker compose config --services
docker compose ps --all
docker compose port simulator 502
docker compose port simulator 4840预期结果:服务列表包含 simulator,容器状态为 Up;如果示例映射已经配置,最后两条命令分别返回 127.0.0.1:1502 和 127.0.0.1:14840。实际地址和端口可能不同。执行前应将 simulator 替换为真实服务名。
端口映射中的宿主机端口与容器端口不必相同。127.0.0.1:1502:502 表示宿主机本地 1502 转发到容器 502,而不是要求容器监听 1502。仅声明 expose: 502 不会自动发布宿主机端口。

还需要确认模拟服务实际监听的是容器网络接口。服务若只绑定容器内部的 127.0.0.1,即使配置了端口发布,其他容器或宿主机也可能无法正常连接。实验环境通常让服务监听 0.0.0.0,再通过端口绑定、防火墙和网络隔离限制访问范围。
区分 DNS 解析和 TCP 连通性
通信检查应区分访问位置。宿主机通过发布端口访问模拟服务;同一 Compose 网络内的容器通常通过服务名和容器端口访问,不需要绕行宿主机发布端口。
| 客户端位置 | Modbus TCP 目标 | OPC UA 目标 |
|---|---|---|
| Docker 宿主机 | 127.0.0.1:1502 |
127.0.0.1:14840 |
| 同一 Compose 网络中的 gateway | simulator:502 |
simulator:4840 |
| 其他物理主机 | 宿主机可达 IP 与已对外发布端口 | 宿主机可达 IP 与已对外发布端口 |
如果端口只发布到宿主机的 127.0.0.1,第三行的远程访问不成立。需要对外访问时,应先确定安全边界,不能为了测试直接向不可信网络开放工业控制协议。
在宿主机创建 tcp_probe.py,利用 Python 标准库分别检查名称解析和 TCP 建连:
import socket
import sys
host = sys.argv[1]
port = int(sys.argv[2])
try:
# 名称解析成功不代表目标端口可连接
socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
print(f"DNS_OK {host}")
except socket.gaierror:
print(f"DNS_FAIL {host}")
raise SystemExit(2)
try:
# 三秒连接超时用于避免排查时长期等待
with socket.create_connection((host, port), timeout=3):
print(f"TCP_OK {host}:{port}")
except OSError as exc:
print(f"TCP_FAIL {type(exc).__name__}")
raise SystemExit(3)保存后在宿主机执行:
python3 tcp_probe.py localhost 1502预期输出(服务已正确发布并监听时):
DNS_OK localhost
TCP_OK localhost:1502如果出现 DNS_FAIL,先检查主机名和 DNS;如果名称能够解析却出现 TCP_FAIL,优先检查端口、服务监听、路由和防火墙。TCP_OK 只证明 TCP 握手成功,不能证明对端使用了正确的工业协议。
在包含 Python 3 的网关容器中,还可以直接验证 Compose 内部 DNS。以下命令要求实际存在名为 gateway 和 simulator 的服务:
docker compose exec gateway python3 -c "import socket; print(socket.getaddrinfo('simulator', 502, type=socket.SOCK_STREAM)[0][4][0])"预期输出为模拟设备容器的一个网络地址,例如 <CONTAINER_IP>。实际 IP 可能随容器重建变化,因此业务配置应优先使用 Compose 服务名,而不是固定容器 IP。若解析失败,核对服务名称以及两个容器是否位于同一 Compose 网络。
使用 Modbus TCP 客户端读取寄存器
TCP 建连成功后,需要发送真正的 Modbus 请求。这里使用 Python 3.10 及以上版本和 PyModbus 3.13.1,在本地模拟设备上读取一个保持寄存器。
先安装客户端依赖:
python3 -m pip install pymodbus==3.13.1预期结果:安装成功,或在已经安装该版本时提示依赖满足。随后创建 check_modbus.py:
from pymodbus.client import ModbusTcpClient
from pymodbus.exceptions import ModbusException
client = ModbusTcpClient(
"127.0.0.1", port=1502, timeout=3, retries=0
)
try:
if not client.connect():
print("TCP_FAIL")
else:
# 功能码 03,设备号 1,读取零基地址 0 的一个保持寄存器
response = client.read_holding_registers(
address=0, count=1, device_id=1
)
if response.isError():
code = getattr(response, "exception_code", "unknown")
print(f"MODBUS_EXCEPTION code={code}")
else:
print(f"MODBUS_OK register_0={response.registers[0]}")
except (ModbusException, OSError) as exc:
print(f"MODBUS_FAIL {type(exc).__name__}")
finally:
client.close()运行 python3 check_modbus.py。当设备号为 1 且地址 0 存在可读保持寄存器时,预期输出格式为:
MODBUS_OK register_0=<VALUE><VALUE> 是模拟设备当前的实际寄存器值,不应预设固定数字。如果返回 MODBUS_EXCEPTION code=2,说明已经收到 Modbus 协议异常响应,但请求的数据地址无效,应检查测点映射,而不是立即判断网络断开。
使用 OPC UA 客户端验证会话
OPC UA 需要在 TCP 连接之上建立安全通道和会话,因此 TCP 4840 端口可达仍不足以说明节点可以读取。本节采用 asyncua 2.0.1,先读取标准的服务器当前时间节点 i=2258,避免依赖模拟设备自定义命名空间。
安装客户端:
python3 -m pip install asyncua==2.0.1预期结果:安装成功,或提示该版本已经安装。创建 check_opcua.py:
import asyncio
from asyncua import Client
async def main():
# 按模拟服务实际发布的 OPC UA Endpoint 调整地址和路径
endpoint = "opc.tcp://127.0.0.1:14840/"
async with Client(url=endpoint, timeout=3) as client:
# 标准节点 ServerStatus.CurrentTime
server_time = await client.get_node("i=2258").read_value()
print(f"OPCUA_OK server_time={server_time.isoformat()}")
if __name__ == "__main__":
asyncio.run(main())运行 python3 check_opcua.py。在允许匿名客户端建立会话、Endpoint 地址正确且标准节点可读的模拟服务上,预期输出格式为:
OPCUA_OK server_time=<TIME><TIME> 是服务端返回的动态时间。如果服务要求证书、特定安全策略或用户名密码,匿名示例可能在建立安全通道或会话时失败。此时应使用服务端声明的 Endpoint、安全策略和身份认证配置,不应通过关闭生产环境安全设置来强行通过测试。
如果标准节点读取正常,但 Machine01 等业务节点读取失败,继续检查命名空间 URI、节点标识符和访问权限。不要默认自定义节点始终属于 ns=2;命名空间索引可能因服务器配置变化而不同。
按错误层级定位并完成验收
根据失败发生的位置选择修复动作,避免看到超时就反复重启容器。
| 观察到的结果 | 优先检查 | 修复方向 |
|---|---|---|
Compose 显示 Exited |
启动日志、配置和端口冲突 | 修复服务启动失败原因 |
DNS_FAIL |
主机名、Compose 网络 | 改正服务名并确认网络成员关系 |
ConnectionRefusedError |
监听端口、进程状态、端口映射 | 启动监听服务或修正目标端口 |
TimeoutError |
路由、防火墙、目标地址 | 排查网络路径和访问限制 |
| TCP 成功但 Modbus 无响应 | 目标端口、协议类型、设备号 | 核对真正的 Modbus TCP 服务和站号 |
MODBUS_EXCEPTION code=2 |
寄存器地址、功能码 | 按点表修正数据区和偏移 |
| OPC UA 会话或安全协商失败 | Endpoint、安全策略、证书及认证 | 使用与服务端匹配的连接配置 |
OPC UA BadNodeIdUnknown |
命名空间、节点 ID | 浏览地址空间并使用实际节点标识 |
如果容器状态异常,先查看对应服务最近的日志:
docker compose logs --tail=50 simulator预期结果:显示该服务最近最多 50 行日志。日志内容取决于实际镜像,重点寻找监听失败、地址被占用、协议服务启动失败或配置读取错误,而不是期待某条固定成功消息。
可以按以下顺序进行最终验收:
docker compose ps --all显示目标服务正在运行,端口发布与配置一致。- 宿主机可以访问发布端口;同一 Compose 网络中的客户端可以通过服务名解析并连接到容器端口。
- Modbus 客户端收到有效寄存器数据,或至少收到能够解释的 Modbus 异常响应,以证明协议请求到达了服务端。
- OPC UA 客户端成功建立会话并读取标准节点,再使用真实点表核对业务节点。
- 记录测试位置、目标地址、端口、设备号或 NodeId,以及成功响应或具体异常,便于重建环境后复测。
验收时要明确区分三个结论:DNS 可解析只证明名称解析正常,TCP 可连接只证明传输层建立了连接,协议读取成功才证明客户端能够按预期与模拟设备交换业务数据。对于工业现场真实设备,优先执行只读测试,不使用随意写寄存器或更改设备状态的操作验证连通性。