トラブルシューティング
よく発生する症状／エラーと解決策。まず簡易分類 → 詳細な解決フローへ。
status.sh— コンテナ + ポート + API + app.properties 主要キーの 1 行サマリhealth.sh— exit code ベースの総合ヘルスチェック (cron に適合)doctor.sh— 診断一括 tarball (api / docker / systemd / 7 コンポーネントの logs / config redacted / host metrics) → support escalation/api/v1/system/health— 8 コンポーネント別 status map + 503 分岐 (どのコンポーネントが DOWN かを即座に特定)- ボックス内の
/opt/kopens/install/RUNBOOK.md— 5 シナリオマトリクス (A〜E) + コマンド cheat sheet
症状別インデックス
| 症状 | 想定原因 |
|---|---|
| アプリが起動途中で停止する | Cassandra 接続失敗、DDL 適用失敗 |
/api/v1/edge の応答が started=false | Collector 初期化失敗 (ドライバ／キャッシュの問題) |
特定の OPC のみ connection_status=DISCONNECTED | PLC ネットワーク／認証／アドレス形式 |
| すべての OPC が時々一斉に切断される | OPC の追加／変更による OPCUAServerManager 全体の restart |
| MQTT publish できない | mqtt.enable=false または broker 認証失敗 |
| Sparkplug トピックが発行されない | sparkplug.enable=false または jar 欠落 |
| 画面表示が遅い | opcList() の N+1 クエリ + sleep の累積 |
| OPC の起動に 5 秒かかる | Thread.sleep の影響 (Phase A1 対象) |
起動／初期化
Cassandra 接続失敗
Caused by: com.datastax.oss.driver.core.exceptions.NoHostAvailableException
| チェック | 確認内容 |
|---|---|
| Cassandra の稼働 | nodetool status |
| ポート到達性 | telnet <app.db.host> 9042 |
| キースペースの存在 | cqlsh -u cassandra -p cassandra の後 DESCRIBE KEYSPACE pe; |
app.db.* と oltp.cassandra.* の一致 | app.properties の両方の項目を確認 |
app.sql.path が resouces の誤字
app.properties の app.sql.path = classpath:resouces/sql の resouces は誤字ですが、ディレクトリも
同じ名前で維持されているため動作します。SQL リソースが見つからないというエラーが出た場合は WEB-INF/resouces/sql/ パスの
実在有無を確認してください。
OPC／ドライバ
特定の OPC に接続できない
| プロトコル | 一次確認 |
|---|---|
| OPCUA | opc_agent_port の到達性、discovery=true の試行、ユーザー／パスワード |
| Modbus TCP | 502 ポートの到達性、holding-register:... の形式 |
| MELSEC | MC プロトコル有効、controller-type=Q_L の一致 |
| S7 | rack/slot の一致、"PUT/GET" の有効化 |
| LS | NetUtils.isReachable が失敗する場合は ICMP 遮断を疑う、ポート 2004 |
| EIP | rack/slot、port 44818 |
各ドライバページの「よくあるエラー + 解決」表を優先して参照してください。
LS-PLC Ping failed
LS ドライバは connect 前に ICMP ping で到達性を確認します。社内網で ICMP が遮断されている場合、正常な PLC も 失敗と表示されます。
解決:
- ファイアウォールで ICMP を許可
- または
LSDriver.connect()の ping 検査をオプションで無効化できるようにする後続変更 (現時点ではコード変更が必要)
32-bit / 64-bit の値が不整合
多くは format の未指定 が原因です。
| プロトコル | 誤ったパターン → 正しいパターン |
|---|---|
| LS | D00600 + Integer (16-bit として読まれる) → D00600 + Integer + format=DW |
| Modbus | holding-register:1 (16-bit) → holding-register:1:DINT |
| S7 | %DB1.DBW0 + Float → %DB1.DBD0 + format=REAL |
32-bit float の値が NaN／異常に大きい数値
byte order (endianness) の問題です。スレーブ／マスターの byte/word swap ポリシーを確認してください。
- Modbus →
:UDINT_LSWORD_FIRSTなどの PLC4j オプションを使用 - 他のプロトコルは fomula で後処理
転送 (MQTT / Sparkplug)
MQTT publish できない
# broker 도달 확인
MQTT_USER="${MQTT_USER:-edge}"
MQTT_PASSWORD="$(tr -d '\r\n' < /run/secrets/mqtt-password)"
mosquitto_pub -h <mqtt.server.host> -p 1883 -u "$MQTT_USER" -P "$MQTT_PASSWORD" -t /edge/point -m '{"test":1}'
チェックリスト:
mqtt.enable=truemqtt.server.host/port/user/passwordが正確か- broker が client からの publish を許可する ACL になっているか
- catalina.out に
MQTT connectedまたは reconnection ログがあるか
Sparkplug トピックが見えない
| チェック | 方法 |
|---|---|
sparkplug.enable=true になっているか | properties を確認 + 再起動が必要 |
| jar が lib にあるか | ls WebContent/WEB-INF/lib/tahu-core*.jar |
| 同一 broker か | mqtt.server.* と SPB が同一 |
| broker の SPB トピック ACL | spBv1.0/# の発行権限 |
NDEATH が 2 回発行されているように見える
正常な動作です。正常終了時の明示的な発行 + (will も登録されているため) broker が接続終了を will-bypass と認識できない場合、will による発行が追加されることがあります。この場合、host 側で同一 bdSeq の NDEATH は 一度だけ処理するように実装されている必要があります。
パフォーマンス／応答性
OPC の start/stop 応答が 5 秒
ConnectService の意図的な Thread.sleep が原因です (collector のウォームアップ保証)。
- 暫定回避: 画面 reload で polling 応答を確認
- 恒久対応:
REFACTORING_PLAN.mdPhase A1 (Thread.sleepの削除 /CountDownLatch) を適用する後続 PR
画面の初回ロードが遅い
opcList() の N+1 クエリ + LastValueMap lookup の分散により、1〜2 秒程度の追加遅延が発生することがあります。
- Phase B1 (IN 一括 select) と B2 (単一 facade) の適用で改善予定
1 つの OPC を変更すると他の OPC も一時停止する
OPCUAServerManager.restart() が全体再起動であるためです (Phase A2 — partial reload 対象)。
緊急回避: 運用時間外に OPC の変更を実施してください。
データ／Cassandra
tombstone 累積の警告
運用で OPC を多数削除すると、一時的に nodetool cfstats pe.app_tag の tombstone メトリクスが spike する場合が
あります。
- 本ゲートウェイの OPC/Tag 数は通常 ≤ 1000 のため深刻ではない
- 時系列 (
TM_TAG_POINT) は本ゲートウェイではなくplantpulse-timeseries-engineの責務
tag not found: <id>
PUT /api/v1/tag/{tagId} または read 時に頻発します。
原因:
tag_idの誤字APP_TAG.xmlR03のALLOW FILTERINGクエリのため partition key が未指定。tag_id が正確である必要があります。
確認:
cqlsh -u cassandra -p cassandra -k pe -e "SELECT tag_id FROM app_tag;"
値の書き込み時に tag write not supported for opc_type=...
HTTP 以外のプロトコルは現時点で write 未対応です。
HTTPDriver.bind()のみ実装済み- 他プロトコルの write は Sparkplug Phase 3 (NCMD/DCMD) と併せて SPI 拡張が必要
セキュリティ／運用
/api/* が認証なしで公開されている
設計上、社内網を前提としています (SecurityFilter check-pattern に /api/* を含まない)。外部公開する場合はリバースプロキシの
前段に mTLS / API Key / Basic auth を配置してください。
CSRF
*_.do パターンのみ CSRF を適用しています。v1 mutation エンドポイントは適用外です。外部公開時には併せて検討してください。
ログ収集ガイド
問題を報告する際は、以下を添付すると分析が早くなります。
# 환경
curl -s http://localhost:8080/api/v1/edge
# OPC 상태
curl -s http://localhost:8080/api/v1/opc
# 시스템 메트릭
curl -s http://localhost:8080/api/v1/monitoring
# 최근 로그
tail -n 500 $CATALINA_HOME/logs/catalina.out
app.properties のパスワードはマスキングしてから添付してください。