インストールのトラブルシューティング — インストール中によく遭遇するエラー
インストール（クイックインストール / 量産ライン / 閉域網インストール）中または直後によく遭遇する症状を 発生頻度の高い順に まとめます。
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 は表示されるのに Web が開かない（外部から）
原因: ファイアウォールが 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 ディレクトリが存在しない
原因: 別ディスクが 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_<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 フルインストール
- 閉域網: オフライン / 閉域網インストール
- インストール後のチェックリスト: インストール直後のチェックリスト
- 運用中の診断: 診断 / 点検