설치 트러블슈팅 — 설치 중 자주 만나는 에러

설치 (빠른 설치 / 양산 라인 / 폐쇄망 설치) 중 또는 직후에 자주 만나는 증상을 가장 빈도 높은 순서대로 정리합니다. 2026.05+ 신규 설치는 컨테이너 모드가 표준이고, tools/setup.sh 기반 H/W 전체 설치는 legacy native 유지보수용입니다. 설치 후 운영 중 에러는 컨테이너 모드 운영 가이드 또는 진단 / 점검을 참고하세요.

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. 상세 시나리오: 박스 안 /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 <사내-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` 디렉토리가 없음

원인: 별도 디스크 mount 안 됨.

해결:

# 현재 마운트
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 엣지 ID 가 비어있거나 의도와 다름

원인: app.properties 의 edge.id 미설정.

해결: 환경 설정 → edge.id=EDGE_<번호> → 저장 → 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 (웹 / 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 전체 설치
폐쇄망: 오프라인 / 폐쇄망 설치
설치 후 체크리스트: 설치 직후 체크리스트
운영 중 진단: 진단 / 점검

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 (legacy native) [4] DB START 단계에서 멈춤 (60초+)​

2.2 (legacy native) [7] SERVER START 후 Tomcat 이 안 떠 — Connection refused​

2.3 Node-RED 가 부팅 안 됨​

2.4 INSTALL COMPLETED 떴는데 웹 안 열림 (외부에서)​

3. 네트워크 / 시간 동기​

3.1 set-1.sh / set-2.sh 후 SSH 끊김​

3.2 시각이 1970년 / NTP 동기 안 됨​

3.3 PLC 망 (NIC 2번) 으로 인터넷이 새는 것 같음​

4. 권한 / SELinux​

4.1 Permission denied (binding port 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.2 (legacy native) systemd plantpulse.service 가 활성화 안 됨​

7.3 재부팅 후 자동 시작 안 됨​

7.4 firefox / GUI 도구가 깔리지 않음 (서버 모드)​

8. 로그 위치 — 어디를 봐야 하나​

9. 그래도 안 되면​

10. 더 알아보기​