zeabur-port-mismatch

Zeabur のポート不一致

Zeabur CLI の実行には、必ず npx zeabur@latest を使用してください。 zeabur を直接実行したり、ほかのインストール方法を使用したりしないでください。npx が利用できない場合は、まず Node.js をインストールしてください。

症状

dial tcp 10.x.x.x:3000: i/o timeout
dial tcp 10.x.x.x:80: connection refused

原因

プロキシはサービスがポート X で待ち受けていることを想定していますが、実際にはポート Y で待ち受けています。

診断

1. ポートフォワーディングの状態と、実際に転送されているポートを確認します：

   npx zeabur@latest service network --id SERVICE_ID
   

2. コンテナが実際にどのポートで待ち受けているかを確認します：

   npx zeabur@latest service exec --id SERVICE_ID -- netstat -tlnp
   

   （ポートのバインド情報もログで確認するには、zeabur-deployment-logs スキルを使用してください）
3. プロキシが想定しているポートを確認します（Caddyfile/nginx.conf を参照）
4. コンテナが公開しているポートを確認します（Dockerfile の EXPOSE）

よくある不一致

プロキシの想定	コンテナのポート	対処方法
:3000	nginx のデフォルト :80	テンプレートのポートを 80 に変更します
:80	アプリの :3000	テンプレートのポートを 3000 に変更します

テンプレートでの修正

ポート設定と portForwarding の YAML 全体のリファレンスについては、zeabur-template スキルを使用してください：

ports:
  - id: web
    port: 3000  # Match what container actually exposes
    type: HTTP

公式 Dockerfile の EXPOSE ディレクティブを確認してください。

ヘッドレスサービス（リスナーがなく 502 が発生する場合）

症状

サービスは実行中（クラッシュなし）ですが、プロキシは恒久的に 502 Bad Gateway を返します。

原因

サービスが HTTP ポートで待ち受けていません。例：チャットボットゲートウェイ、バックグラウンドワーカー、メッセージキューコンシューマー。テンプレートでは HTTP ポートが宣言されていますが、そこにバインドするものがありません。

対処方法

メインプロセスと並行してバックグラウンドで実行する、軽量な HTTP ヘルスチェックサーバーを追加します：

# Start before main process in startup script
# IMPORTANT: port must match spec.ports[].port in your template
python3 -c "
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
class H(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-Type','application/json')
        self.end_headers()
        self.wfile.write(json.dumps({'status':'ok'}).encode())
    def log_message(self,*a): pass
HTTPServer(('0.0.0.0', 8080), H).serve_forever()
" &
exec my-headless-app

ポートフォワーディングが機能しない場合

TCP サービスをデプロイしたものの、外部からアクセスできない場合：

1. ポートフォワーディングが有効かどうかを確認します：

   npx zeabur@latest service port-forward --id SERVICE_ID
   

2. 無効な場合は有効にします：

   npx zeabur@latest service port-forward --id SERVICE_ID --enable
   

3. 転送先のエンドポイントを確認します：

   npx zeabur@latest service network --id SERVICE_ID
   # Output: proxy (TCP 8888) → 34.x.x.x:20143