インストール時のトラブルシューティング
インストール (ワンラインインストール / 量産ラインインストール / 閉域網インストール) 中または直後に発生しやすい症状を、頻度が高い順にまとめます。 インストールはコンテナモードが標準です。 インストール後の運用中エラーは コンテナモード運用 または 診断・点検 を参照してください。
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 遮断環境の場合は /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
原因: 社内ファイアウォールがアウトバウンド 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 の 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分以内に復旧しない場合は
コンテナモード運用 のエスカレーション手順に従って 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秒 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
# 플로우 도구 로그
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 インストールで固定 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 ネットワーク (NIC 2番) からインターネットに漏れている可能性
原因: 両 NIC がデフォルトルートを持っている。
対処:
# 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 モード — 一部パス拒否。
対処:
# 임시로 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 ネットワーク 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.3 再起動後に自動起動しない
sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.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 |
| 統合 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. 関連情報
- 標準手順: ワンラインインストール
- 閉域網: 閉域網インストール
- インストール後チェックリスト: インストール直後点検
- 運用中の診断: 診断・点検