安装问题排查

在安装（单线安装 / 产线安装 / 隔离网络安装）期间或之后，我们按出现频率从高到低整理常见症状。安装标准采用容器模式。安装后运行期间的错误，请参考容器模式运行或诊断与巡检。

2026.05+ 容器模式安装后快速验证

sudo bash /opt/kopens/install/bin/status.sh   # 한 줄 상태
sudo bash /opt/kopens/install/bin/health.sh   # exit 0/1
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool   # image_tag / build_date / container_mode
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool   # components UP

若 install.sh 失败，检查 /var/log/kopens-install.log。若容器 unhealthy，执行 journalctl -u plantpulse-edge.service -n 100 或 docker logs plantpulse-edge。详情：容器模式运行。

故障应对前保存证据

在计划投入运行的设备上，重新安装、clean、restore 之前，请尽可能先保存 doctor.sh 和 acceptance log。请勿共享密码原文。

sudo bash /opt/kopens/install/bin/doctor.sh || true
sudo journalctl -u plantpulse-edge.service -n 200 --no-pager \
  > /root/pp-edge-journal-$(date +%Y%m%d-%H%M%S).txt

1. 下载 / 安装阶段

1.1 `curl: (6) Could not resolve host: product.kopens.io`

原因：DNS 解析失败。

解决方法：

nslookup product.kopens.io
# Server: ... (사내 DNS) — 응답이 없으면 DNS 가 안 풀림

# /etc/resolv.conf 확인
cat /etc/resolv.conf
# nameserver 8.8.8.8 또는 사내 DNS 가 있어야 함

# 임시로 공인 DNS 추가
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

如果内网存在 DNS 拦截，则将 IP 直接添加到 /etc/hosts：

# product.kopens.io 의 실제 IP 를 운영팀에 문의 후 등록
echo "X.X.X.X product.kopens.io" | sudo tee -a /etc/hosts

如果现场只开放 product.kopens.io，请用同样方式检查 .com。

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

原因：公司防火墙拦截出站 443 端口，或需要代理。

解决方法：

# 프록시 환경이면 export HTTP_PROXY / HTTPS_PROXY
export HTTPS_PROXY=http://proxy.company.local:8080
export HTTP_PROXY=http://proxy.company.local:8080

# 그 후 install.sh 다시 실행
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)

若代理也不行，请按照隔离网络安装流程使用 USB 搬运。

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

原因：下载过程中断——磁盘空间不足或网络线路断开。

解决方法：

# 디스크 공간
df -h /opt /tmp

# 다시 다운로드 (`-C` 로 이어받기)
curl -O -C - https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# 무결성 확인 (있으면 sha256)
sha256sum KOPENS_EDGE_V2026.tar.zstd

1.4 `bash: java: command not found`

原因：未安装 Java。2026.05+ 容器安装通常会安装所需包（通常需要 install.sh），但如果因公司安全策略或仓库拦截导致包安装步骤失败，则可能需要手动安装。

解决方法：

# Fedora / RHEL
sudo dnf install -y java-17-amazon-corretto-devel

# Ubuntu / Debian
sudo apt-get install -y temurin-17-jdk

# 확인
java -version
# openjdk version "17.x" ...

如果是新容器安装，与其手动调整 Java，不如先解决 install.sh 中包安装失败的原因。

1.5 `docker: command not found`

原因：未安装 Docker，或 install.sh 中的 Docker 安装步骤失败。

解决方法：

# Fedora
sudo dnf -y install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

# Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# 확인
docker --version

2. 启动 / 开始阶段

2.0 容器模式下 health 为 503

原因：某个组件处于 DOWN 状态。首先查看 health JSON 中的组件名称。

解决方法：

curl -ks https://127.0.0.1/api/v1/system/health | python3 -m json.tool
sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/logs.sh tomcat | tail -100
sudo bash /opt/kopens/install/bin/logs.sh cassandra | tail -100
sudo bash /opt/kopens/install/bin/logs.sh mqtt | tail -100
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -100

检查各组件日志中的原因后采取措施。若 30 分钟内未恢复，请按照容器模式运行中的升级流程执行 backup.sh 和 doctor.sh。

2.1 停留在 `[4] DB START` 阶段（超过 60 秒）

原因：Cassandra 正在回收 commitlog。首次启动或异常关闭后属正常现象——仅需更多时间。

解决方法：

# 별도 ssh 세션에서 실시간 로그
tail -f /opt/kopens/plantpulse-edge/db/logs/system.log

# `Listening for thrift clients` 또는 `Startup complete` 가 보이면 OK
# 그 후 메인 화면의 [4] 단계가 자동 진행됨

若 10 分钟后仍无消息——则可能为 heap / 磁盘 / sstable 损坏。执行 bin/node-cleanup.sh 后重试。

2.2 `[7] SERVER START` 后服务器未启动——`Connection refused`

原因 A：Tomcat 启动后 1–2 秒内未开始监听——属正常现象。

原因 B：80 / 443 端口被其他进程占用。

解决方法：

# 포트 점유 확인
sudo ss -lntp | grep -E ':80 |:443 '

# 점유 중이면 그 프로세스 정리 (예: nginx)
sudo systemctl stop nginx

# tomcat 재시작
sudo /opt/kopens/plantpulse-edge/bin/restart.sh

原因 C：catalina.out 中的启动错误。

sudo tail -100 /opt/kopens/plantpulse-edge/server/logs/catalina.out | grep -E 'SEVERE|ERROR|Exception'

根据 Address already in use、Cannot find class、Failed to load app.properties 等消息进行相应处理。

2.3 Node-RED 无法启动

原因 A：1880 端口被占用。 原因 B：userDir（/opt/kopens/.../node/userDir）权限问题。 原因 C：flows.json 损坏。

解决方法：

# 1880 포트 점유?
sudo ss -lntp | grep 1880

# userDir 권한
ls -la /opt/kopens/plantpulse-edge/node/userDir/

# Node-RED 로그 (container)
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -50

# 플로우 도구 로그
tail -50 /opt/kopens/plantpulse-edge/node/log/node-red.log

# flows.json 손상 시 백업본으로 복원
cd /opt/kopens/plantpulse-edge/node/userDir
cp .flows.json.backup flows.json

# 재시작
/opt/kopens/plantpulse-edge/node/bin/stop.sh
/opt/kopens/plantpulse-edge/node/bin/start.sh

2.4 `INSTALL COMPLETED` 已启动但网页无法访问（外部）

原因：防火墙拦截 80/443 端口（外部访问）。

解决方法：

# 게이트웨이 자체에서는 되는지
curl -kI https://127.0.0.1/api/v1/system/health
# HTTP/1.1 200 이면 게이트웨이 정상, 외부 접근만 차단됨

# firewalld 확인
sudo firewall-cmd --list-all
# 80/tcp, 443/tcp 가 ports 에 없으면 추가

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

iptables 环境：

sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

3. 网络 / 时间同步

3.1 安装时设置了静态 IP 后 SSH 断开

原因：在 install.sh 中提供的 NET1_IP / NET2_IP 的 IP、网关、子网配置错误。（如果您使用的是 set-1.sh / set-2.sh 这类旧脚本，它已不再存在——现在安装会通过 nmcli 直接设置。）

解决方法（通过控制台——KVM / IPMI / VM 控制台进入）：

# 현재 NIC 상태
nmcli dev show
ip a

# IP 수정 (예: enp1s0 의 IP 변경)
sudo nmcli con modify enp1s0 ipv4.address 192.168.0.50/24 ipv4.gateway 192.168.0.1
sudo nmcli con up enp1s0

# 재부팅 권장
sudo reboot

3.2 时间显示为 1970 年 / NTP 同步失败

原因：chrony 服务未启用或无法访问 NTP 服务器。

解决方法：

# chrony 상태
sudo systemctl status chronyd
# Active: inactive (dead) 면 시작
sudo systemctl enable --now chronyd

# 동기 강제
sudo chronyc makestep
sudo chronyc tracking
# Reference ID 가 채워지면 OK

# 사내 NTP 서버 사용 시 /etc/chrony.conf 의 server 라인 수정
# server <internal-ntp-ip> iburst

3.3 感觉互联网流量通过 PLC 网络（网卡 2）泄漏

原因：两块网卡都有默认路由。

解决方法：

# default route 확인
ip route | grep default

# 두 NIC 가 default 면 NIC 2 (PLC 망) 의 never-default 설정
sudo nmcli con modify enp2s0 ipv4.never-default yes
sudo nmcli con up enp2s0

4. 权限 / SELinux

4.1 `Permission denied`（无法绑定端口 80）

原因：使用非 root 用户运行。

解决方法：使用 sudo -i 后执行所有命令。若已注册为 systemd 服务，则自动以 root 运行。

4.2 `avc: denied` 消息（SELinux）

原因：SELinux 处于 enforcing 模式——拒绝访问某些路径。

解决方法：

# 임시로 SELinux 끄기 (테스트용)
sudo setenforce 0

# 영구 (운영 환경에서 비추천)
sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

# 정식: 거부된 path 에 컨텍스트 부여 (운영팀과 함께)
sudo semanage fcontext -a -t bin_t '/opt/kopens/.*\.sh'
sudo restorecon -Rv /opt/kopens

5. 磁盘

5.1 `/data1` 目录不存在

原因：未挂载独立磁盘。

解决方法：

# 현재 마운트
df -h

# /data1 이 없으면 디스크 인식 → mkfs → mount
lsblk
# /dev/sdb 같은 디스크 확인 후
sudo mkfs.xfs /dev/sdb
sudo mkdir -p /data1
sudo mount /dev/sdb /data1
echo '/dev/sdb  /data1  xfs  defaults,noatime  0 2' | sudo tee -a /etc/fstab

5.2 `/opt` 磁盘已满——解压产物失败

解决方法：清理与维护—— clean.sh + node-cleanup.sh + 删除旧备份。

6. 首次运行——数据 / 注册

6.1 平台 API 服务器卡片 🔴 连接失败

原因：app.properties 中的 server.host / port / username 配置错误，或平台未运行，或公司防火墙拦截出站连接。

解决方法：

# 외부에서 플랫폼 도달 가능?
curl -I https://<server.host>:<server.port>/

# 사내 방화벽 outbound 정책 — 운영팀에 문의 (HTTPS / 80 / 443)

# app.properties 수정 → 저장 → restart.sh

6.2 边缘 ID 为空或与预期不符

原因：app.properties 中的 edge.id 未设置。

解决方法：Web UI 环境设置 → edge.id=EDGE_<number> → 保存 → restart.sh。

6.3 注册 PLC 后采集状态停留在未知

原因 A：使用 auto_collect=false 注册——需要手动启动。 原因 B：PLC 网络网卡 down 或无法访问 PLC IP。

解决方法：

# PLC IP ping
ping -c 3 192.168.100.20

# PLC 포트 도달 (Modbus 502 예시)
nc -vz 192.168.100.20 502

# 도달 OK 면 화면에서 ▶ 시작 누르기

7. 其他

7.1 未启用 systemd `plantpulse-edge.service`

这是容器模式的标准服务。

解决方法：

sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse-edge.service
sudo systemctl status plantpulse-edge.service --no-pager
sudo journalctl -u plantpulse-edge.service -n 100 --no-pager

若为 Unit not found，则表示 /opt/kopens/install/install.sh 在部署 systemd unit 前失败。请检查 /var/log/kopens-install.log 后重新执行 bash /opt/kopens/install/install.sh。

7.3 重启后未自动启动

sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.service

7.4 未安装 firefox / GUI 工具（服务器模式）

原因：无头服务器上未安装 GUI 包。

解决方法：忽略即可，不影响网关运行。从 setup.sh 中移除 firefox 或在 dnf install 中排除后继续。

8. 日志位置——应查看哪里

组件	日志位置
Tomcat（Web / REST API）	`/opt/kopens/plantpulse-edge/server/logs/catalina.out`
Cassandra	`/opt/kopens/plantpulse-edge/db/logs/system.log`
HiveMQ (MQTT)	`/opt/kopens/plantpulse-edge/mqtt/log/hivemq.log`
Node-RED	`/opt/kopens/plantpulse-edge/node/log/node-red.log`
timeseries-engine	`/opt/kopens/plantpulse-edge/timeseries/engine/log/*.log`
systemd（容器）	`journalctl -u plantpulse-edge.service -n 200`
集成 tail	`/opt/kopens/plantpulse-edge/bin/log-viewer.sh`

9. 若仍无法解决

容器模式下，捕获 status.sh、health.sh、journalctl -u plantpulse-edge.service -n 200 的输出
将 df -h、free -h、systemctl status ... 的结果与上述日志摘录发送给运维团队
重新执行单线安装中的 install.sh——由于是幂等的，多次运行也安全。

10. 更多信息

标准流程：单线安装
隔离网络：隔离网络安装
安装后检查清单：安装后检查
运行中诊断：诊断与巡检

1. 下载 / 安装阶段​

1.1 curl: (6) Could not resolve host: product.kopens.io​

1.2 curl: (7) Failed to connect to product.kopens.io port 443​

1.3 tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory​

1.4 bash: java: command not found​

1.5 docker: command not found​

2. 启动 / 开始阶段​

2.0 容器模式下 health 为 503​

2.1 停留在 [4] DB START 阶段（超过 60 秒）​

2.2 [7] SERVER START 后服务器未启动——Connection refused​

2.3 Node-RED 无法启动​

2.4 INSTALL COMPLETED 已启动但网页无法访问（外部）​

3. 网络 / 时间同步​

3.1 安装时设置了静态 IP 后 SSH 断开​

3.2 时间显示为 1970 年 / NTP 同步失败​

3.3 感觉互联网流量通过 PLC 网络（网卡 2）泄漏​

4. 权限 / SELinux​

4.1 Permission denied（无法绑定端口 80）​

4.2 avc: denied 消息（SELinux）​

5. 磁盘​

5.1 /data1 目录不存在​

5.2 /opt 磁盘已满——解压产物失败​

6. 首次运行——数据 / 注册​

6.1 平台 API 服务器卡片 🔴 连接失败​

6.2 边缘 ID 为空或与预期不符​

6.3 注册 PLC 后采集状态停留在未知​

7. 其他​

7.1 未启用 systemd plantpulse-edge.service​

7.3 重启后未自动启动​

7.4 未安装 firefox / GUI 工具（服务器模式）​

8. 日志位置——应查看哪里​

9. 若仍无法解决​

10. 更多信息​

1. 下载 / 安装阶段

1.1 `curl: (6) Could not resolve host: product.kopens.io`

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

1.4 `bash: java: command not found`

1.5 `docker: command not found`

2. 启动 / 开始阶段

2.0 容器模式下 health 为 503

2.1 停留在 `[4] DB START` 阶段（超过 60 秒）

2.2 `[7] SERVER START` 后服务器未启动——`Connection refused`

2.3 Node-RED 无法启动

2.4 `INSTALL COMPLETED` 已启动但网页无法访问（外部）

3. 网络 / 时间同步

3.1 安装时设置了静态 IP 后 SSH 断开

3.2 时间显示为 1970 年 / NTP 同步失败

3.3 感觉互联网流量通过 PLC 网络（网卡 2）泄漏

4. 权限 / SELinux

4.1 `Permission denied`（无法绑定端口 80）

4.2 `avc: denied` 消息（SELinux）

5. 磁盘

5.1 `/data1` 目录不存在

5.2 `/opt` 磁盘已满——解压产物失败

6. 首次运行——数据 / 注册

6.1 平台 API 服务器卡片 🔴 连接失败

6.2 边缘 ID 为空或与预期不符

6.3 注册 PLC 后采集状态停留在未知

7. 其他

7.1 未启用 systemd `plantpulse-edge.service`

7.3 重启后未自动启动

7.4 未安装 firefox / GUI 工具（服务器模式）

8. 日志位置——应查看哪里

9. 若仍无法解决

10. 更多信息