メインコンテンツへ移動

デプロイに関する問題

再インストールするには​

  1. 実行中のサービスを停止します。管理ツールのルートディレクトリで次のコマンドを実行してください（正常に停止すると stoped と表示されます）。

    bash ./service.sh stopall
    rm -f ./installer.stage

  2. サービスのファイルをバックアップします（バックアップ先は任意に指定できます。通常、初回デプロイ時はバックアップ不要で、rm -rf /data/mingdao/ を直接実行できます）。

    mv /data/mingdao/ /home/hapbak/

  3. クリーンアップが完了したことを再確認します。次のコマンドをそれぞれ実行し、出力がすべて空であることを確認してください（出力がある場合は、該当するプロセスを kill してください）。

    docker ps | grep mingdaoyun
    netstat -ntpl | grep 38881
    ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep

  4. 次のコマンドで管理ツールを再起動します。起動後、http://{服务器IP}:38881 にアクセスして再インストールしてください。

    bash ./service.sh start

初期化に失敗する​

初回デプロイ画面に初期化失敗と表示された場合は、サーバーで次のコマンドを実行して出力を確認してください。通常、ターミナルに例外情報が表示されるため、その内容から原因を調査します。

bash ./service.sh restartall

iptables failed を含むエラーがある場合、通常は firewalld の停止時に iptables ルールが消去されたことが原因です。Docker を再起動してデフォルトの iptables ルールを再生成してから、再インストールしてください。

初期化完了後に「アカウントからログアウトしました。再度ログインしてください」と表示される​

主な原因：サーバーのディスクの IOPS 性能が低く、サービス起動中にディスク I/O が飽和することで、ストレージコンポーネントの起動に時間がかかっています。

解決方法：

設定ファイル /data/mingdao/script/docker-compose.yaml に環境変数を追加して、マイクロサービスの起動を遅らせます。

環境変数を追加した後、インストール管理ツールのディレクトリで bash service.sh restartall を実行してサービスを再起動します。再起動が完了してから初期情報を再入力してください。

services:
  app:
    environment:
      ENV_ROLE_MODE_WAITMS: "90000"

  • 環境変数 ENV_ROLE_MODE_WAITMS の単位はミリ秒で、デフォルト値は 30 秒です。

  • この例では待機時間をデフォルトの 30 秒から 90 秒に延長し、マイクロサービスの起動を 90 秒遅らせます。これにより、マイクロサービスが起動する前にストレージコンポーネントのプロセスが起動を完了できるようにします。

  • 問題が解消しない場合は、待機時間を 180 秒などに延長し、サービスを再起動して確認してください。

  • この値を大きくすると、サービス全体の起動が遅くなります。運用中のパフォーマンス問題を避けるためにも、高性能なディスクへのデプロイを推奨します。ディスクの性能要件はサーバーの基本性能要件を参照してください。

サービス起動後に応答コードエラー（Service response code error）が発生する​

症状：サービス起動後に "Service response code error" が表示されますが、その後は正常にアクセスできる場合があります。

原因： データディスクに HDD を使用している場合など、ディスク I/O 性能が低い環境ではサービスの起動が遅くなります。サービス起動から 5 分後にヘルスチェックが行われ、応答がないままタイムアウトすると、このエラーが発生します。

確認方法：

  1. サービスのページにアクセスします。正常にアクセスして利用できる場合、主要サービスの起動は完了しています。

  2. docker logs $(docker ps | grep -E 'mingdaoyun-community|mingdaoyun-hap' | awk '{print $1}') を実行し、マイクロサービスコンテナーのログを確認します。

    • INFO レベルのログが中心であれば、通常は正常な状態です。

    • ERROR または WARN レベルのログがある場合は、内容を詳しく確認してください。 ​

推奨事項：サービスの安定稼働、性能、保存データの安全性を確保するため、高性能なディスクへのデプロイを強く推奨します。主要クラウド事業者の標準ディスクは最低限の基本性能要件を満たします。物理サーバーへのデプロイでは SSD を推奨します。

OS 起動時にサービスを自動起動するには​

インストール管理ツールのパスが /usr/local/MDPrivateDeployment/ の場合を例に、主な OS での設定方法を示します。

仕組み：OS 標準の systemd を使用します。独自のサービスユニットファイル manager.service にサービス起動コマンドを記述することで、OS 起動時にサービスを自動起動します。

  1. /etc/systemd/system/manager.service ファイルを編集し、サービス起動コマンドを追加します。

次のコマンドで manager.service ファイルを作成できます。

cat > /etc/systemd/system/manager.service <<'EOF'
[Unit]
Description=Manager
After=docker.service
Wants=docker.service
[Service]
Type=oneshot
WorkingDirectory=/usr/local/MDPrivateDeployment
ExecStart=/bin/bash service.sh restartall
RemainAfterExit=yes
StandardOutput=append:/usr/local/MDPrivateDeployment/manager.log
StandardError=append:/usr/local/MDPrivateDeployment/manager.log
[Install]
WantedBy=multi-user.target
EOF

  1. 起動時の自動起動を有効にします。

    systemctl daemon-reload
    systemctl enable manager

サーバーの再起動後にサービスが正常に起動しない​

管理ツールのルートディレクトリで次のコマンドをそれぞれ実行し、startall コマンドの完了を待ってください。OS 起動時の自動起動を設定していない場合は、自動起動の設定を参照してください。

bash ./service.sh stopall
rm -f service.pid
bash ./service.sh startall

キーが失われ、サーバー Id が表示されない​

  1. 管理ツールのルートディレクトリで bash ./service.sh stopall を実行してサービスを停止します。
  2. ps -ef | grep 'mingdaoyun\|service.sh' | grep -v grep を実行します（出力がある場合は、該当する pid のプロセスをすべて kill してください）。
  3. bash ./service.sh startall を実行し、コマンドの完了を待ちます。

考えられる原因：

  • サーバーリソースが飽和し、管理ツールのプロセスが強制終了された。
  • サーバーの時刻が正しくなく、キーの有効期限が誤って判定された。
  • サーバーを再起動したが、管理ツールの自動起動が設定されていなかった。
  • サービスの起動・停止手順が適切でなく、キーの定期的な有効性チェックに失敗した。

Kafka の起動に失敗する​

スタンドアロンモードでは、Kafka は組み込みコンポーネントとしてコンテナー内で動作します。Kafka が利用できない場合、次のような症状が発生します。

  • ワークフローが正常に実行されない。
  • ワークシートの行レコードデータの送信が遅い。
  • 集計機能が正常に動作しない、またはデータが同期されない。

Kafka は実行中、メッセージデータやオフセット情報をローカルのデータディレクトリに保存します。停電やメモリ不足によるプロセスの強制終了などでシステムが正常な手順を経ずに停止すると、Kafka と Zookeeper のメタデータファイルに次の問題が発生することがあります。

  • ログデータファイルの破損：メッセージログやオフセットファイルへの書き込みが完了せず、検証に失敗する。
  • Zookeeper の状態の不整合：トランザクションログが正しくコミットされず、Kafka の起動時にクラスターメタデータを読み込めない。
  • Kafka の起動停止：復旧処理中にインデックスやログファイルの不整合が検出され、異常な復旧ループに陥る。

スタンドアロンモードの Kafka にはクラスターのレプリカ機構がないため、この種のエラーは自動復旧できません。異常なデータを消去して Kafka サービスを再初期化する必要があります。

コンテナーログを確認して Kafka が起動できないことが分かった場合は、次の手順で復旧します。

  1. 管理ツールのルートディレクトリで bash ./service.sh stopall を実行し、サービスを停止します。

  2. 次のコマンドで Kafka と Zookeeper のデータディレクトリ名を変更し、異常な状態データを除外します。

    mv /data/mingdao/script/volume/data/kafka{,_bak_$(date +%Y%m%d%H%M)}
    mv /data/mingdao/script/volume/data/zookeeper{,_bak_$(date +%Y%m%d%H%M)}

  3. 管理ツールのルートディレクトリで bash ./service.sh startall を実行し、サービスを起動します。

添付ファイルアップロード時にインターフェースがタイムアウトする場合​

4MB超ファイルのアップロードはデフォルトでスライスアップロードとなります。ネットワークにより一部スライスのアップロード失敗が全体失敗となることがあります。以下（nginx例）を追加してください。

location ~ /file {
  proxy_set_header Host $http_host;
  proxy_read_timeout 1800s;
  client_max_body_size 20480m;
  proxy_pass http://hap; # 実際のupstream名に合わせて修正
}

サブパスでデプロイするには​

設定ファイルの app サービスに環境変数 ENV_MINGDAO_SUBPATH を追加します。例を以下に示します。

services:
  app:
    environment:
      ENV_MINGDAO_SUBPATH: "/hap"

2つのアクセスポイントを有効化する方法​

設定ファイルの app サービスに ENV_EXT_MINGDAO_PROTO、ENV_EXT_MINGDAO_HOST、ENV_EXT_MINGDAO_PORT を追加します（ENV_MINGDAO_PROTO、ENV_MINGDAO_HOST、ENV_MINGDAO_PORT に対応する設定の組み合わせ）。18880 ポートを公開し（ホスト側のポートは任意ですが、この例では 18880）、http://example1.domain.com からホストの 18880 ポートへ接続できるようにします（ホストの内部・外部 IP アドレスで直接アクセスする場合、ドメインの名前解決設定は不要です）。例：

services:
  app:
    environment:
      ENV_EXT_MINGDAO_PROTO: "http"
      ENV_EXT_MINGDAO_HOST: "example1.domain.com"
      ENV_EXT_MINGDAO_PORT: "18880"
    ports:
      - 8880:8880
      - 18880:18880

詳細は複数アドレスの設定を参照してください。

デフォルトのストレージパスを変更するには​

インストール管理ツールのディレクトリで tail -n 3 service.sh を実行すると、管理ツールのバージョンを確認できます。

新規インストール​

管理ツールを起動する前（./service.sh start を実行する前）に、service.sh の installDir パラメーターを変更します。

移行​

インストール済みの場合は、service.sh の installDir パラメーターを変更します。サービスを停止した状態で /data/mingdao 内のすべてのファイルを installDir に移動し、サービスを再起動してください。

各ストレージコンポーネントに外部からアクセスするには​

スタンドアロンデプロイでは、依存するストレージコンポーネント mysql、mongodb、redis、kafka、file がデフォルトで起動します。これらのポートはデフォルトでは外部に公開されません。外部から接続する場合は、設定ファイル（デフォルト：/data/mingdao/script/docker-compose.yaml）で該当するコンテナーの ports フィールドを変更し、ポートを公開してください。例を以下に示します。

操作前にデータセキュリティのドキュメントをよくお読みください。 ⚠️⚠️⚠️

services:
  sc:
    ports:
      - 3306:3306   # mysql
      - 27017:27017 # mongodb
      - 6379:6379   # redis
      - 9092:9092   # kafka
      - 9000:9000   # file
      - 9200:9200   # elasticsearch

スタンドアロンモードで一部の外部ストレージコンポーネントのみ有効化する方法​

スタンドアロンデプロイでは、設定ファイル（デフォルト：/data/mingdao/script/docker-compose.yaml）に環境変数 ENV_STANDALONE_DISABLE_SERVICES を追加します。mysql、mongodb、redis、kafka、file を指定でき、複数指定する場合は半角カンマで区切ります。例を以下に示します。

services:
  app:
    environment:
      ENV_STANDALONE_DISABLE_SERVICES: "redis,file"

カスタムストレージコンポーネントを有効化する場合は、対応サービスの接続先も環境変数経由で設定してください。環境変数詳細参照。

mongodbの最大メモリ容量カスタマイズ方法​

設定ファイルに環境変数 ENV_MONGODB_CACHEGB を追加します。デフォルトは (物理メモリ-18)/2（単位：G）です。例：

services:
  app:
    environment:
      ENV_MONGODB_CACHEGB: "6"

Redis の最大メモリ使用量を変更するには​

設定ファイルに環境変数 ENV_REDIS_MAXMEMORY を追加します。デフォルトでは制限されません。制限を設定すると、LRU アルゴリズムに基づいてデータが削除されます。例を以下に示します。

services:
  app:
    environment:
      ENV_REDIS_MAXMEMORY: "5gb"

他のシステムから IFrame で埋め込むには​

デフォルトでは同一ドメインの IFrame への埋め込みに対応しています。別のドメインのシステムから埋め込む場合は、設定ファイルに環境変数 ENV_FRAME_OPTIONS を追加します。ALLOWALL、SAMEORIGIN、DENY、ALLOW-FROM uri を指定できます。例を以下に示します。

services:
  app:
    environment:
      ENV_FRAME_OPTIONS: "ALLOWALL"

IPホワイトリストによるアクセス制御設定方法​

クライアント第1段のプロキシで制御する必要があります。設定例は以下の通りです。

# 例1
http {
  server {
    ......
    # 192.168.0.1のみ許可
    allow 192.168.0.1;
    # 192.168.0.1/32サブネットも許可
    allow 192.168.0.1/32;
    # その他全て拒否
    deny all;

    location / {
      ......
    }
  }
}

# 例2
http {
  server {
    ......

    location / {
      # 192.168.0.1のみ許可
      allow 192.168.0.1;
      # 192.168.0.1/32サブネットも許可
      allow 192.168.0.1/32;
      # その他全て拒否
      deny all;
    }
  }
}

アップロードファイル拡張子のブラック・ホワイトリスト設定​

設定ファイルに次の環境変数を追加し、アップロードできるファイル形式を制御します。
ENV_FILEEXT_BLOCKLIST（拒否リスト。デフォルト値：.exe,.vbs,.bat,.cmd,.com,.sh）
ENV_FILEEXT_ALLOWLIST（許可リスト）
ENV_FILEEXT_ALLOWLIST を設定すると、ENV_FILEEXT_BLOCKLIST は自動的に無効になります。例：

スタンドアロンモードの場合：

services:
  app:
    environment:
      ENV_FILEEXT_BLOCKLIST: ".exe,.sh,.html"
      ENV_FILEEXT_ALLOWLIST: ".docx,.txt,.png"

クラスターデプロイの場合は、file.yaml に対応する環境変数を追加します。

コンテナにhosts名前解決を追加する方法​

hdp サービスに extra_hosts 設定を追加します。例を以下に示します。

services:
  hdp:
    extra_hosts:
      - "a.domain.com:192.168.1.10"
      - "b.domain.com:172.17.13.42"