技術的なトラブルシューティング
よくある症状 / エラーとその解決策。クイック分類 → 詳細な解決フロー。
status.sh— コンテナ + ポート + API + app.properties の主要キーを1行で要約health.sh— exit code ベースの総合ヘルスチェック（cron に適しています）doctor.sh— 診断用一括 tarball（api / docker / systemd / 7コンポーネントのログ / config の機密情報をマスク / host metrics）→ support escalation/api/v1/system/health— 8コンポーネント別 status map + 503 分岐（どのコンポーネントが DOWN かを即座に特定）- コンテナモード運用 — 障害対応 + コマンド cheat sheet
症状別インデックス
| 症状 | 原因候補 |
|---|---|
| アプリが起動時に停止 | Cassandra 接続失敗、DDL 適用失敗 |
/api/v1/edge の応答が started=false | Collector 初期化失敗（ドライバ / キャッシュの問題） |
特定の OPC のみ connection_status=DISCONNECTED | PLC ネットワーク / 認証 / アドレス形式 |
| すべての OPC が時々一斉に切断 | OPC の追加/変更による OPCUAServerManager 全体の再起動 |
| 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 に接続できない
| プロトコル | 1次確認 |
|---|---|
| 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（エンディアン）の問題。スレーブ / マスターの byte/word swap ポリシーを確認:
- Modbus →
:UDINT_LSWORD_FIRSTなど PLC4j オプションを使用 - その他のプロトコルは formula で後処理
転送 (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 も追加発行される可能性があります。この場合、ホスト側で同じ 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 のパスワードはマスキング後に添付してください。