よくある質問
クラスターデプロイでは対応する kubectl コマンドに置き換えてください。コンテナ／ワークロード名には ops- 接頭辞が付きます（例：kubectl -n hap-ops logs deploy/ops-gateway）。アクセス用ポートは 48881 ではなく 30881 です。
起動とアクセス
コンテナが繰り返し再起動する場合：まず docker compose -f ops.yaml logs サービス名 でログを確認します。よくある原因は以下のとおりです：
- 接続情報が誤っている → 「データソース」ページで確認してください（収集設定は UI が基準です）。
- ポートの競合（48881/59100/4317/4318 が使用中）→ ホスト側のポートマッピングを変更するか、使用中のプロセスを停止します。
- メモリ不足 →
docker statsで使用状況を確認し、ホストに 8G 以上を確保することを推奨します。
:48881 のページが読み込み中のままの場合：
docker ps | grep gatewayでgatewayが Up であることを確認します。- ブラウザーのコンソールに 401 が表示される → 正しい
ENV_OPS_TOKENでログインします。 - リバースプロキシ経由でアクセスしているのにサブパスを未設定 →
ENV_OPS_SUB_PATHの設定が必要です。
ログイン後、Grafana パネルが読み込み中または 404 になる場合：
- リバースプロキシの場合：
ENV_OPS_SUB_PATHを実際のパスと一致させます（/mdisでプロキシするなら/mdis）。 - ポートへ直接接続する場合：
ENV_OPS_SUB_PATHは設定しません。
gateway が ops-mongo より先に起動すると接続失敗が続きますか？ いいえ。ops-server は ops-mongo に接続できない間、バックグラウンドで間隔を延ばしながら再試行し、mongo の準備ができると自動接続します。docker logs gatewayコンテナ | grep 告警子系统 で確認し、最終的に [alert] 告警子系统已挂载 /api/alert/ が出力されれば正常です。手動再起動は不要です。
監視データがない
「データソース」ページの「収集状態」列で、各データソースの収集状況を確認できます：
- 収集中 — 正常。
- データなし — 収集プロセスは稼働していますがデータを取得できていません。通常はユーザー名／パスワードの誤りか権限不足です。
- 停止済み — 収集プロセスが稼働していません。
- 未収集 — このデータソースの収集を開始していません（用途の「グラフ表示」が未選択の場合など）。
赤いラベルにカーソルを合わせると、失敗理由と再試行回数が表示されます。理由は中国語のトラブルシューティングメッセージ（「ポートに接続できないか、接続先サービスが未起動」「ユーザー名またはパスワードが違う：プライベートデプロイ内蔵 ES のユーザー名は elastic ではなく md」など）で表示され、exporter の英語ログや Go スタックは直接表示しません。多くの収集問題はこの列から特定できます。
ホスト（Host）パネルにデータがない場合：
nodeagentが Up であることを確認します。- 「データソース」のホスト IP に prometheus コンテナからアクセスできることを確認します：
docker exec prometheusコンテナ wget -O- http://IP:59100/metrics。
ミドルウェアのパネルにデータがない場合：「収集状態」列に応じて調査します：
| 状態 | 意味 | 対処方法 |
|---|---|---|
| データなし | 接続には成功したがメトリクスを取得できない | 通常はアカウント／パスワード／権限の問題。ES では特に多く、次項を参照 |
| 停止済み | exporter プロセスが稼働していない | カーソルを合わせて原因を確認。自動再試行されますが、停止状態のまま回数が増える場合は対象への接続失敗が継続しています（アドレス誤り／ポート遮断／ファイアウォール） |
| 未収集 | このデータソースの収集を開始していない | 用途のグラフ表示が選択され、有効状態か確認 |
| 不明 | agent が報告していない | agent コンテナが Up か確認 |
Elasticsearch の接続テストは成功するのに「データなし」となる場合：最も多い原因は認証情報の誤りです。プライベートデプロイ内蔵 ES のユーザー名は elastic ではなく md です。「データソース」でユーザー名とパスワー ドを修正してください（即時反映され、コンテナ再起動は不要です）。
内部ログを確認する場合：docker logs agentコンテナ を実行します。agent は起動後 10～50 秒で収集セルフチェック表を出力し、各項目の ✓/✗ と原因を表示します。exporter が異常終了した場合も、[supervise] xxx 退出(code=N) と末尾数行のログを出力します。
Datasource ${DS_PROMETHEUS} was not found と表示される場合：
この既知の問題は 1.4.0 の単一イメージで修正済みです。発生する場合は、イメージ tag が 1.2.5 以上か確認してください。
データソースの新規作成／編集
接続先に一時的に到達できなくても保存できますか？ 保存できます。接続失敗によって設定の保存は妨げられないため、対象が未デプロイ、またはネットワークが一時的に不通でも先に設定できます。フォーム上部に理由を示す黄色の通知が表示され、保存ボタンが「そのまま保存」に変わります。再確認すると保存されます。保存後は継続的に再試行し、接続できると自動収集を開始します。進捗は「収集状態」列で確認できます。
接続チェックはいつ実行されますか？ 接続フィールドの変更から約 0.6 秒後に自動実行されます。完了前に保存した場合も、チェック完了後に保存処理が判断され、検証がスキップされる ことはありません。**ホスト（Host）**も自動チェックの対象です。
「一時的に接続をチェックできません」とは？ チェックサービスが一時的に応答していない状態です。接続設定が誤っているという意味ではありません。設定を保存し、後から「収集状態」を確認できます。
収集設定を変更しても反映されない
UI でデータソースを変更しても収集が変わらない場合：通常は 30 秒以内に反映されます。反映されない場合は agent コンテナのログを確認します。
[sd] 拉取 xxx 失败 が続く場合、agent がサービスディスカバリー API に接続できていません。よくある原因は ENV_OPS_SD_URL がゲートウェイの 48881（nginx のポートで /api/sd ルートはありません）を指しているか、Kubernetes Service が 48881 のみを公開し、8081 を公開していないことです。この場合 exporter はすべて起動できず、すべてのミドルウェア監視が空になります。
ops.yaml のミドルウェア接続情報を変更しても反映されない場合：1.5.0 以降、ops.yaml では監視対象を設定しません。ENV_KAFKA_ENDPOINTS/ENV_ELASTICSEARCH_*/ENV_REDIS_*/ENV_MYSQL_*/ENV_MONGODB_URI は読み込まれなくなりました（起動ログに明示されます ）。接続情報はすべて UI の「データソース」で変更します。
ops.yaml に残っている廃止変数は起動ログに 1 件ずつ表示され、無視される旨が通知されます。該当する設定行を削除してください。
ログが表示されない
「サービスログ」に HAP/HDP マイクロサービスのログがない場合：次の順に確認します。
- HAP/HDP サービス側で
ENV_LOKI_URLを設定する必要があります（MDIS の Loki、例：http://MDISホスト:3100）。未設定の場合、logservice は Loki にログを書き込みません（インストーラーがStoreInLokiをfalseにするため）。その結果、運用プラットフォームからサービスログを検索できません。変更後は対象の製品サービスを再起動してください。 - 製品サービスのコンテナからそのアドレスにアクセスできるか確認します（別ホストの場合は 3100 ポートの許可を確認）。
- マイクロサービスのログは実際の業務呼び出し時に書き込まれます。ログインや確認コード送信などを実行してから更新してください。
ENV_LOKI_URL は役割が異なります- HAP/HDP サービス側：書き込みの有効化設定。未設定ならログを書き込みません。デフォルトは空です。
- MDIS 側：検索先アドレス。デフォルトは
http://ops-loki:3100で、標準構成では設定不要です。
設定するのは前者です。設定先を間違えないようにしてください。
コンテナコンソールの選択肢に特定のコンテナがない場合：Alloy は起動後に追加されたログのみを収集し、過去のログは補完しません。最近 stdout が出ていないコンテナ（メインプロセスが何も出力しない期間など）は表示されないことがあります。出力を発生させるか、コンテナを再起動して再確認してください。
オブジェクトストレージ（MinIO/COS）
スタンドアロンではログ（Loki）のみが検討対象です。スタンドアロンにはトレース機能がなく、ops-tempo のトレースデータは発生しないため、オブジェクトストレージの設定は不要で推奨もしません。トレースとオブジェクトストレージの組み合わせはクラスターデプロイ向けです。
オブジェクトストレージ設定後に ops-loki が起動しない場合：docker logs lokiコンテナ で最初のエラーログを確認します。
dial tcp: lookup xxx: no such host— endpoint にコンテナネットワーク内で名前解決できない名前を指定しています。MinIO が同じ compose ネットワークにない場合（別 stack やホスト上など）、コンテナ名ではなくホスト IP + ホスト側の公開ポートを指定します。connection refused— ポートが誤っています。ホスト側の公開ポートは 9000 とは限りません。docker psの実際の表示を確認してください。SignatureDoesNotMatch/AccessDenied— AK/SK またはバケット権限の問題です。- パス形式：MinIO は
ENV_S3_FORCE_PATH_STYLE=true、Tencent Cloud COS は必ずfalse（virtual-hosted 形式のみ対応）にします。
オブジェクトストレージへの切り替え後、過去ログが見えない場合：Loki はバックエンド変更時に既存データを移行しません。過去ログは元のローカルボリュームに残ります。新しいバックエンドに表示するには新たにログを発生させてください。
アップグレード
アップグレード後もバージョンが変わらない場合：1.4.0 以降は全コンポーネントが単一イメージ ops-allinone を共有します。ops.yaml 冒頭の x-ops-image の tag を変更し、docker compose -f ops.yaml pull、続いて docker compose -f ops.yaml up -d を実行します。強制作り直しが必要なら --force-recreate を追加します。
アップグレード後も過去データは残りますか？ Loki/Prometheus/Tempo/ops-mongo のボリュームを変更しなければ、監視履歴とアラート設定は保持されます。Grafana の未保存の手動編集は失われ、provisioned パネルは自動再読み込みされます。
新しいドキュメントに合わせてデータボリュームのパスを変更する必要はありますか？ 不要です。 新版では volume/data/mdis/ に統一していますが、この配置は新規インストール専用です。既存の ops.yaml のパスを直接変更すると空のディレクトリがマウントされ、「監視履歴、アラートルール、データソース設定がすべて失われた」ように見えます。実データは元のパスに残っているため、元の設定に戻せばアクセスを復旧できます。
1.4.x からのアップグ レードで収集設定はどうなりますか？ UI の既存データソースは変更されず、監視は中断されません。ops.yaml のミドルウェア ENV_* は 1.5.0 以降読み込まれないため削除できます（残っていても稼働には影響せず、起動ログに廃止済みと表示されます）。
デプロイ後のセルフチェック
配布パッケージにはエンドツーエンドの回帰テストスクリプトが含まれます。デプロイ後に一度実行し、主要機能（ログイン、各リソースページ、Grafana 表示、データソース追加／削除と接続テスト、PromQL プレビュー、アラート全体、通知チャンネル、ログ／トレース検索）の正常動作を確認してください：
pip install playwright && playwright install chromium
# ポートに直接接続
python3 mdis_regression.py --base http://<ホストIP>:48881 --token <ENV_OPS_TOKEN>
# リバースプロキ シのサブパス経由
python3 mdis_regression.py --base http://<ホストIP>:9080 --subpath /mdis --token <ENV_OPS_TOKEN>
終了コード 0 は全項目成功、非 0 は失敗項目があることを示します。スクリプトの末尾に失敗一覧が出力されます。