Nginxの背後にあるONLYOFFICEドキュメントサーバーの502 Bad Gatewayエラーを修正する方法

ONLYOFFICE DocsのURLを開いた際にブラウザに「502 Bad Gateway」エラーが表示される場合、またはNextcloud/ownCloudコネクタがドキュメントサーバーに接続できない場合は、通常、Nginxがリクエストを受信して​​いるものの、アップストリームから有効な応答を取得できていないことが原因です。アップストリームとは、ONLYOFFICEの内部ドキュメントサービス、Dockerコンテナ、または別のリバースプロキシである可能性があります。まず、どのNginxが502エラーを返したかを特定し、設定を変更する前に、ネクストホップを直接テストしてください。

ONLYOFFICEの最新のLinuxトラブルシューティングガイドではds-docservice、ds-converterサービスとドキュメントサーバーのログを確認することを推奨しています。また、リバースプロキシガイドでは、転送されたホストおよびプロトコルヘッダーについても言及しています。以下の手順では、まずサービスの健全性を確認し、次にNginxルーティングとDockerネットワークを確認します。

1. どのNginxが502エラーを返しているか調べます。

ONLYOFFICEのパッケージインストールには独自のNginx設定が含まれており、デプロイメントによっては外部のNginxリバースプロキシが使用される場合もあります。Dockerはネットワークホップをさらに追加する可能性があります。502ページの表示だけではレイヤーを特定できない場合があるため、公開URLをローカルのヘルスチェックとNginxのエラーログと比較してください。

パッケージベースのLinuxインストール環境で、ローカルのドキュメントサーバーのエンドポイントをテストします。

curl -i http://127.0.0.1/healthcheck

サーバーがデフォルト以外のローカルポートで ONLYOFFICE を提供するように構成されている場合は、そのポートを使用してください。正常なインストールでは、通常、HTTP 成功応答が返されますtrue。このローカル要求が失敗した場合は、外部プロキシを編集する前に、ドキュメントサーバーサービスを修正してください。ローカルでは成功するが、パブリックホスト名が 502 を返す場合は、外部の Nginx アップストリーム、プロトコル、ヘッダー、およびファイアウォールパスに注目してください。

どのプロセスが想定されるポートを所有しているかを確認します。

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

ポートはトポロジーによって異なります。一般的なDockerマッピングでは、ホストポート（例：8080）をコンテナポート80に公開します。パッケージのインストールでは、ホスト上で独自のNginxを使用することもできます。127.0.0.1:80両方のサービスが同じマシン上にあるからといって、それが正しいアップストリームであると決めつけないでください。

2. ONLYOFFICEのサービスとログを確認する

Linuxパッケージのインストール時に、ドキュメントサービスとコンバーターを検査します。

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

ONLYOFFICEのトラブルシューティングガイドでは、これらのサービスがリストアップされており、Docsサービスが起動しない場合に確認すべき事項として、メモリ不足、ポート80の競合、サービスログが挙げられています。サービスが停止している場合は、まずそのエラーを調べてから、影響を受けているサービスのみを再起動してください。

sudo systemctl restart ds-docservice

Linux のメインログディレクトリは です/var/log/onlyoffice/documentserver/。Nginx エラーログと docservice ログで、「接続拒否」、「アップストリームタイムアウト」、またはファイルが見つからないなどのメッセージを確認してください。これらはそれぞれ異なる原因を示しています。接続拒否は通常、アップストリームのプロセスまたはポートが利用できないことを意味し、タイムアウトはサービスが過負荷または停止していることを意味する可能性があります。

サービスが繰り返し終了する場合は、利用可能なディスクとメモリも確認してください。

df -h
free -h

ログを確認せずに、障害が発生したサービスを再起動し続けないでください。再起動によって一時的に症状が隠蔽されるだけで、ポートの競合、依存関係の失敗、リソースの問題などが解決されない場合があります。

3. Nginxが到達可能なアップストリームを指していることを確認します。

アクティブな仮想ホストを読み取り、正確なアドレスとポートを確認しますproxy_pass。Nginx が実行されているマシンまたはコンテナから、アップストリームに直接リクエストを送信します。たとえば、コンテナがホストポート 8080 としてポート 80 を公開している場合:

curl -i http://127.0.0.1:8080/healthcheck

例示されているアドレスを、プロキシから実際にアクセス可能なエンドポイントに置き換えてください。Nginxが別のDockerコンテナで実行されている場合は、127.0.0.1DockerホストやONLYOFFICEコンテナではなく、そのNginxコンテナ自体を参照してください。共有Dockerネットワーク上でアクセス可能なサービス名、または正しいホストアドレスと公開ポートを使用してください。

アップストリームのスキームがバックエンドと一致していることを確認してください。http://バックエンドリスナーがプレーンなHTTPで通信する場合、https://かつTLS用に設定されている場合にのみ使用してください。TLSポートにHTTPを送信したり、プレーンなHTTPポートにTLSを送信したりすると、正常なサービスがNginxから利用不可と認識される可能性があります。

4. 転送されたヘッダーと WebSocket プロキシを確認する

ONLYOFFICEのリバースプロキシガイドでは、アプリケーションが元のプロトコルとホスト名を認識できるようにX-Forwarded-Proto、それらを保持するように指示していますX-Forwarded-Host。公式のNginxのサンプルでも、アップグレードヘッダーが渡されます。ONLYOFFICEの前に外部プロキシがある場合は、その設定を、お使いのトポロジーに一致する公式のシナリオと比較してください。

ホストポート8080にマッピングされたDockerコンテナの簡略化された例を以下に示します。このmapディレクティブをNginxのhttpコンテキスト内に配置して、ホスト名、TLS構成、およびアップストリームポートをご使用の環境に合わせて変更してください。

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

これは参考パターンであり、あらゆるインストール環境に適用できるものではありません。特に、パッケージ化された ONLYOFFICE の Nginx 設定に、ポート 80 と 443 をどのサーバー ブロックが所有しているかを理解せずに、このパターンを貼り付けないでください。Nginx がパッケージインストールされた ONLYOFFICE と同じホストを使用している場合は、まずポートの競合がないことを確認し、外部プロキシをデプロイメント用に構成された内部リスナーにルーティングしてください。

編集後、Nginxをリロードする前に設定をテストしてください。

sudo nginx -t
sudo systemctl reload nginx

構成テストが失敗した場合は、再読み込みする前に報告されたファイルと行を修正してください。構文エラーとアップストリームの502エラーは別々の問題です。テストが成功したとしてnginx -tも、構文が正しいことを示しているだけで、アップストリームが応答していることを意味するものではありません。

5. ONLYOFFICEがDockerで実行されている場合は、その健全性とポートマッピングを検査する。

コンテナが実行されているかどうか、またどのホストポートが公開されているかを確認してください。

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

公式の Docker インストール ガイドでは、ホスト ポートをコンテナ ポート 80 にマッピングしており、ウェルカム ページが読み込まれない場合はコンテナ ログを確認する例を示しています。docker portホスト側のアップストリームとして、表示されているポートを使用してください。Nginx と ONLYOFFICE の両方がコンテナである場合は、それらを共有ネットワークに配置し、ホストのループバック アドレスではなく、ONLYOFFICE サービス名とコンテナ ポートにルーティングしてください。

Compose ファイルでヘルスチェックが定義されている場合は、コンテナのヘルス状態を確認してください。現在のアップストリームの Compose の例では、http://localhost:8000/info/info.jsonコンテナ内部をチェックしています。「実行中」のコンテナでも、ドキュメント サービスに異常がある場合があります。コンテナが再起動中または異常な状態の場合は、外部プロキシを変更する前に、ログを使用してデータベースの起動、メモリ、および構成を調査してください。

ONLYOFFICEは、ログ、証明書、ファイルキャッシュ用の永続的なDockerパスを文書化します。トラブルシューティング中はボリュームを削除しないでください。サービス復旧に必要な証明書やその他のデータが含まれている可能性があります。

6. リロードして、ヘルスエンドポイントをテストし、統合を再テストします。

確認済みの問題を修正した後、公開ホスト名をテストし、ローカルエンドポイントと比較してください。

curl -i https://docs.example.com/healthcheck

実際のドキュメントサーバーのURLを使用してください。ローカルのアップストリームとパブリックホスト名の両方で正常な応答が得られれば、Nginxがバックエンドに到達し、正常性を示す応答を返すことができることがわかります。その後、ドキュメントサーバーのウェルカムページを開き、Nextcloud、ownCloud、またはその他のコネクタで最初に失敗した操作を再試行してください。

ヘルスチェックが成功してもコネクタがエラーを報告する場合は、残りの問題はNginxの502エラー以外の原因（例えば、コネクタのURL、TLS信頼度、JWT設定など）にある可能性があります。プロキシのタイムアウト値を闇雲に変更し続けるのではなく、これらの値をコネクタとONLYOFFICEの設定と比較してください。

迅速な診断

公式資料

• ONLYOFFICEのLinux向けトラブルシューティングドキュメント
• ONLYOFFICE ドキュメント（プロキシ経由）
• ONLYOFFICE公式Nginx HTTPS-to-HTTPプロキシの例
• ONLYOFFICEドキュメント：Dockerのインストールとポートマッピング
• ONLYOFFICEドキュメントサーバー作成例