常见问题：先按这些入口查，绝大多数现场问题能定位

设备连不上：Modbus TCP

Modbus TCP 默认端口 502。连得上但数值不对，多半是地址基数或字节序和设备不一致；连不上多半是 IP、端口、从站地址或网络问题。在设备连接页做连接检查，按返回的异常码定位。

• 确认设备 IP、端口（默认 502）和「从站 / 单元 ID」正确（按设备说明书，常见是 1）。
• 地址基数：寄存器从 0 还是从 1 开始，要和设备说明书一致。
• 数值明显错乱：调「字节序 / 字序」，读一个已知寄存器对照着调到对为止。
• 读不到某类点：确认寄存器类型选对（保持寄存器、输入寄存器、线圈、离散输入）。

设备连不上：OPC UA

OPC UA 设备要先在设备侧开启 OPC UA Server。Endpoint 填 opc.tcp://地址:端口（常见 4840）。在设备连接页做连接检查，重点看是网络、握手还是会话（安全 / 认证）阶段失败。

• 确认设备已启用 OPC UA Server，Endpoint 地址和端口填对。
• 安全策略、安全模式要和设备一致（开发常用 None，生产按设备要求选）。
• 需要账号登录时，认证方式选「用户名」并填账号密码；否则用匿名。
• 证书不被信任时，按设备 / 服务器的证书信任设置处理。

连上了，但部分 Tag 是 bad、stale 或 unverified

单个坏点不等于整台设备不可用。设备主状态只看连接、采集能力和归属；坏点要进 Tag 诊断或坏点复测里单独核。unverified 表示按需点还没被采集确认，既不是 good 也不是 bad。

• 先用 Tag 诊断复核关键点的值、质量和时间戳。
• bad_address：地址写错或超出设备范围，检查地址格式、DB / 寄存器号、位偏移。
• bad_type：地址对但数据类型不匹配，把 Tag 数据类型改成和设备里实际一致。
• stale：太久没读到新值，看设备是否在线、采集周期是否太慢。
• 按需点没有画面、弹窗、趋势或诊断订阅时，不会长期进入采集计划，属正常。

实时值不刷新，先查哪里

按链路查：设备连接 → 采集 → 缓存 → WebSocket → 页面订阅。系统状态页能看到 IO、缓存、WebSocket 等模块状态；反向代理场景还要确认 WebSocket 已开启。

• 设备是否在线，当前节点是否该设备的采集节点。
• 纯显示的点要设成按周期采集（有扫描周期），否则只在被订阅时才读。
• Tag 质量为 bad 时画面不显示该值，先把设备 / 地址问题解决。
• 用域名或反向代理时，确认 WebSocket 已开启（见对应条目）。

趋势没有曲线

趋势要先给点位开启归档 / 趋势参与，再看留存周期和时间范围。刚开启的点位需要积累一段时间才有曲线。

• 在趋势配置里确认该点已开启归档或趋势参与。
• 在数据留存里确认保留周期够长，查询的时间范围落在保留期内。
• 采样周期或死区设得太大时，变化小的量会很少落点。
• 整类趋势都没有：到系统状态看趋势模块是否在运行。

数据库或缓存异常

页面打开很慢、没有实时值，或系统状态里数据库 / 缓存发灰时，多半是数据库或缓存出了问题。先看日志，再按顺序重启。

• Linux 看日志：sudo hqcontrolctl logs postgres、sudo hqcontrolctl logs redis。
• Windows：在启动设置里看对应服务是否在运行，必要时重启。
• 重启顺序按数据库 → 缓存 → HQControl；Linux 直接 sudo hqcontrolctl restart。
• 用外部数据库时，确认数据库服务器可达、账号密码对、扩展可用。

用域名或反向代理后，实时数据断开

通过域名或反向代理访问时，实时数据走 WebSocket，必须在反向代理上开启 WebSocket 透传，否则页面能打开但实时值不刷新。下面是 Nginx 的示例配置。

• 反向代理目标指向 HQControl 本机网页端口（默认 http://127.0.0.1:8080）。
• 必须透传 Upgrade 和 Connection 头，WebSocket 才能建立。
• 设置页里的对外访问地址要填用户实际访问的域名。

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

覆盖升级后如何确认更新包生效

同机覆盖升级会保留配置、数据、日志、运行目录和运行时依赖。升级后先看系统状态和 /settings，再看数据库迁移记录、画面文件的发布版本、菜单入口、关键 Tag、报警趋势和脚本执行记录。

• 确认数据库迁移记录已更新到目标版本。
• 画面文件页确认当前的发布版本。
• 关键画面打开后能读 Tag、写入受权限控制。
• 报警总页、趋势查询和事件记录可用。