安装故障排查 — 安装过程中的常见错误
本文按出现频率由高到低整理了安装（快速安装 / 量产线 / 隔离网络安装）过程中或安装完成后常见的现象。
2026.05+ 的新装以容器模式为标准，基于 tools/setup.sh 的 H/W 完整安装仅用于 legacy native 的维护。
安装完成后运行期间的错误，请参考容器模式运维指南或诊断 / 巡检。
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。
详细场景：设备内的 /opt/kopens/install/RUNBOOK.md（A~E 矩阵）。
在计划投入运行的设备上执行重装、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，请在 /etc/hosts 中直接添加 IP：
# 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
原因：内部防火墙阻断 outbound 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 安装所需软件包，但若因内部安全策略或 repo 被阻断导致软件包安装步骤失败，则可能需要手动安装。
解决：
# 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 软件包安装失败的原因。
仅旧版 native 设备参考 (legacy) H/W 完整安装。
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 中的 component 名称。
解决：
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
在对应 component 的日志中确认原因后再处理。若 30 分钟内仍未恢复，
请按容器模式运维指南中的 escalation 流程执行 backup.sh 和 doctor.sh。
2.1 （legacy native）卡在 [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 （legacy native）[7] SERVER START 之后 Tomcat 未启动 — Connection refused
原因 A：Tomcat 启动后 1–2 秒内未开始 listen — 属正常。
原因 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 中的 startup error。
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
# Node-RED 로그 (legacy native)
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 set-1.sh / set-2.sh 之后 SSH 断开
原因：NIC IP / 网关 / 子网输入错误。
解决（控制台 — 通过 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 网络（NIC 2）泄漏到互联网
原因：两个 NIC 都拥有 default route。
解决：
# 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（binding port 80）
原因：以非 root 用户运行。
解决：所有命令请在 sudo -i 之后执行。若已注册为 systemd 服务，则自动以 root 运行。
4.2 avc: denied 消息（SELinux）
原因：SELinux 处于 enforcing 模式 — 部分 path 被拒绝。
解决：
# 임시로 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 配置错误，或平台未运行，或内部防火墙阻断 outbound。
解决：
# 외부에서 플랫폼 도달 가능?
curl -I https://<server.host>:<server.port>/
# 사내 방화벽 outbound 정책 — 운영팀에 문의 (HTTPS / 80 / 443)
# app.properties 수정 → 저장 → restart.sh
6.2 Edge ID 为空或与预期不符
原因：app.properties 中的 edge.id 未设置。
解决：环境配置 → edge.id=EDGE_<number> → 保存 → restart.sh。
6.3 注册 PLC 后采集状态停留在未知
原因 A：以 auto_collect=false 注册 — 需要手动启动。
原因 B：PLC 网络 NIC 处于 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.2 （legacy native）systemd plantpulse.service 未启用
解决：
# 서비스 파일 위치
ls -la /etc/systemd/system/plantpulse.service
# 없으면 등록
sudo cp /opt/kopens/tools/service/plantpulse.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse
# 상태
sudo systemctl status plantpulse
sudo journalctl -u plantpulse -n 100
7.3 重启后未自动启动
sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.service
legacy native 使用 plantpulse.service 执行相同流程。
7.4 firefox / GUI 工具无法安装（服务器模式）
原因：Headless 服务器上没有 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 (container) | journalctl -u plantpulse-edge.service -n 200 |
| systemd (legacy native) | journalctl -u plantpulse -n 200 |
| 汇总 tail | /opt/kopens/plantpulse-edge/bin/log-viewer.sh |
9. 若仍未解决
- 容器模式下，捕获
status.sh、health.sh、journalctl -u plantpulse-edge.service -n 200的输出 - legacy native 下，用
bin/log-viewer.sh监控 30 秒 → 捕获 SEVERE / ERROR 消息 - 将
df -h、free -h、systemctl status ...的结果与上述日志摘录提交给运维团队 - 若是新设备，请重新执行快速安装中的
install.sh。仅旧版 native 设备可考虑重试 H/W 完整安装 的tools/setup.sh。
10. 了解更多
- 标准流程：快速安装
- legacy native：(legacy) H/W 完整安装
- 隔离网络：离线 / 隔离网络安装
- 安装后检查清单：安装完成检查清单
- 运行期诊断：诊断 / 巡检