OpenShipでAIエージェントをデプロイする手順

OpenShipでAIエージェントをデプロイするなら、最初に最小構成の常駐サービスを公開し、正常性確認と再起動を済ませてからデータベースやツール呼び出しを追加する方法が安全です。長時間稼働するAPIやWorkerを、特定のServerless実行方式を前提にしたまま移行しないことが条件です。

今週の推奨アクション： まずヘルスチェックと単一モデル呼び出しだけを含むブランチを用意し、OpenShipの構築ログ、公開URL、再起動後の応答、旧版へのロールバックを順番に記録してください。

この記事は、ローカルのAIエージェントを外部公開したい独立開発者、Git pushから公開までを整えたい小規模チーム向けです。クラウド構築環境や、常時利用できるMacの開発端末を選んでいるAI SaaS開発者にも適しています。

※最終更新：2026年8月1日。OpenShipの公式サイト、インストール文書、クイックスタート、公式リポジトリを再確認しています。(openship.io)

失敗しやすいのは、コードではなくデプロイ順序です

AIエージェントの試作では、ローカルのメモリ、ファイル、開発用データベースに状態を保存していても動作します。しかし公開後にコンテナが再作成されると、会話履歴、ジョブの状態、アップロードファイルが消えることがあります。

また、モデルAPIの応答待ちをWebリクエストの中で処理すると、上流モデルの遅延で接続が切れたり、同時実行時にWorkerが詰まったりします。管理者画面、API、Worker、定期処理を一度に追加すると、どのサービスが原因で失敗したのかログから追いにくくなります。

OpenShipは、コードの構築、環境変数、コンテナの公開、ログ、指標、ドメイン、ロールバックを扱う導線を提供しています。一方で、アプリケーション側の状態保存、ジョブの冪等性、モデルAPIのタイムアウト設計まで自動的に正しくなるわけではありません。(openship.io)

最初に実行形態を4種類へ分けます

AIエージェントをOpenShipへ載せる前に、サービスを次のように分解します。ここを曖昧にすると、Web APIとして起動したプロセスにバックグラウンド処理まで詰め込む構成になり、再起動やスケール時に重複実行が起こりやすくなります。

実行形態	主な役割	先に確認する項目
Web API	画面や外部クライアントから要求を受ける	待ち受けポート、ヘルスチェック、タイムアウト
常駐Worker	ツール実行、長い推論、キュー処理	再試行、重複実行、停止時の扱い
定期ジョブ	同期、集計、通知、データ整理	実行間隔、失敗時の再実行、ログ保存
複数サービス	API、管理画面、Worker、DBなど	内部通信、起動順、データの永続化

OpenShipでバックエンド付きのAIエージェントを公開するには、何を用意すべきですか。
アプリケーションのソースコード、依存関係を記したファイル、起動コマンド、待ち受けポート、ヘルスチェック用エンドポイント、環境変数の一覧を準備します。Dockerfileを使う場合は、ローカルで同じイメージを構築して起動できることも確認します。

特定のServerless実行時だけ提供される短時間処理、独自のイベント方式、リクエスト間で保持される一時状態に依存している場合は、常駐コンテナへ移行する設計変更が必要です。OpenShipが標準コンテナとして扱える形か、対象の構成を公式文書で確認してから進めてください。

構築元と実行先を先に固定します

OpenShipの入口は、手元のフォルダーから公開する方法と、Gitリポジトリを連携する方法に分けられます。実行先はローカル環境、クラウド環境、自前サーバーから選べますが、構築する場所と本番で稼働する場所を混同しないことが重要です。公式説明では、ビルドを開発端末またはクラウド側で行い、本番サーバー上で直接構築しない流れが示されています。(openship.io)

選択肢	向いている状況	注意点
ローカルフォルダー	まず動作を確認したい、非公開リポジトリを使う	Git履歴や自動公開の運用は別途整える
Gitリポジトリ	チーム開発、継続的な公開、変更履歴の管理	秘密情報をリポジトリへ保存しない
クラウド実行先	サーバー管理を減らしたい	利用できるサービスと費用、データ責任を確認する
自前サーバー	ネットワークや保存先を細かく管理したい	OS更新、ファイアウォール、バックアップを担当する

自前サーバーへOpenShipを導入する場合、公式インストール文書ではLinuxを前提にし、最小要件として2コア、2GB RAM、20GBディスク、Ubuntu 22.04以降を示しています。これはAIエージェント本体の推奨値ではなく、OpenShipの制御環境に関する目安です。(openship.io)

# 例：OpenShipの導入
curl -fsSL https://get.openship.io | sh

# 初回設定
openship

# 対象プロジェクトへ移動
cd /path/to/<PROJECT_DIRECTORY>

# フォルダーをプロジェクトとして初期化し、公開
openship init
openship deploy

実際のパス、リポジトリ名、ドメイン、IPアドレスは環境に合わせて置き換えてください。構築環境のCPUアーキテクチャ、Node.jsやPythonなどの実行バージョン、依存パッケージの取得先、SSH資格情報を本番サーバー上で急に用意する運用は避けます。

最初の公開はヘルスチェックだけに絞ります

初回デプロイでいきなり全機能を載せるのではなく、次のような最小構成を用意します。

<PROJECT_DIRECTORY>/
├── src/
├── package.json または pyproject.toml
├── .env.example
├── Dockerfile
└── README.md

.env.exampleには変数名だけを記載し、実際の値は含めません。APIはGET /healthのような軽量なエンドポイントを持たせ、モデルAPIを呼び出すPOST /agent/runとは分離します。

# ローカルでの確認例
curl http://localhost:<PORT>/health

# 公開後の確認例
curl https://<YOUR_DOMAIN>/health

確認するのは、単にビルドが完了したかどうかではありません。構築ログに依存関係の失敗がないこと、サービス状態が稼働中であること、公開端点からヘルスチェックが返ること、モデルAPIの認証失敗が適切なエラーとして記録されることを確認します。

モデル呼び出しが成功した後も、上流APIのタイムアウト、空の応答、レート制限、再試行による重複処理を確認します。外部APIの秘密情報を含むリクエストヘッダーや、完全なプロンプトを構築ログへ出力しない設計にしてください。

データベースとバックグラウンド処理を追加します

最小サービスが安定したら、永続化が必要な機能から追加します。推奨順序は、データベース、キャッシュ、ジョブキュー、Worker、外部ツール連携です。データベースの接続確認前にWorkerを起動すると、初期化前のテーブルを読みに行く失敗が発生しやすくなります。

OpenShipの公式サイトでは、PostgreSQL、Redis、MongoDB、MySQL、オブジェクトストレージ、Workerなどのサービスが案内されています。ただし、複数サービスのネットワーク構成や、利用するフレームワークとの組み合わせが本番で安定するかは、対象構成ごとに公式文書と実環境で確認する必要があります。(openship.io)

OpenShipでデータベースとバックグラウンド処理を一緒に扱えますか。
公式機能としてデータベースやWorkerは示されていますが、初回公開ではAPIと同じタイミングに追加しない方が安全です。DBの接続先、内部ホスト名、認証情報、マイグレーションの実行主体を決めてから、Workerが再起動しても同じジョブを二重処理しない仕組みを確認します。

最低限、次の確認を行います。

データベースへ接続できること
コンテナ再起動後も必要なデータが残ること
マイグレーションが複数回実行されても壊れないこと
Worker停止中に投入されたジョブを復旧できること
バックアップの取得者、保存先、復元担当者が決まっていること

初回起動に成功しただけでは、データサービスの導入完了とはいえません。再起動後のデータ保持と、バックアップからの復元手順まで確認して初めて、AI SaaSの基礎的な公開条件を満たします。

ドメイン、HTTPS、APIキーの境界を整理します

ドメインを接続する前に、アプリケーションが内部ポートで応答しているか、外部公開ポートと混同していないかを確認します。OpenShipの公式案内では、ドメインのルーティングとTLS証明書を構成する機能が説明されていますが、DNSの反映状況や既存レコードの競合は利用者側で確認する必要があります。(openship.io)

APIキーは、次のように環境変数または秘密情報の管理機能へ登録します。

# 値はシェル履歴やリポジトリへ残さない
export MODEL_API_KEY="<MODEL_API_KEY>"

# アプリケーションは環境変数から読み込む
# Authorizationヘッダーやキー本体をログへ出力しない

モデルAPIキーはOpenShipでどのように設定しますか。
プロジェクトまたは実行環境ごとの環境変数として登録し、ソースコード、.envファイル、Dockerfile、READMEには実値を書きません。開発用、検証用、本番用でキーを分け、ログ、エラー追跡、監査記録に完全なキーや認証ヘッダーが残らないことを確認します。

キーを変更した場合は、再デプロイが必要なのか、秘密情報の更新だけで反映されるのかを対象環境で確認します。更新後は正常なモデル呼び出しだけでなく、旧キーが使われていないこと、失敗時のエラーメッセージに秘密情報が含まれていないことも検証します。

ログとロールバックを本番条件で検証します

公開前には、正常系だけでなく失敗系を意図的に作ります。最低限、モデルAPIのタイムアウト、アプリケーションの起動失敗、新版でのレスポンス形式エラーを再現し、ログから原因を特定できるか確認します。

# 現在の状態とログを確認する例
openship status
openship logs

# 失敗した公開の後、管理画面またはCLIから旧版へ戻す
openship rollback

コマンド名やオプションは導入時点の公式CLIリファレンスを優先してください。公式サイトでは、デプロイごとの不変スナップショット、ログ、指標、以前の版へのロールバックが案内されていますが、データベースのスキーマ変更まで自動的に元へ戻るとは限りません。(openship.io)

公開前の受け入れチェック

[ ] /healthが公開URLから応答する
[ ] モデルAPIの正常系とタイムアウトを確認した
[ ] APIキーがログやリポジトリに出ていない
[ ] コンテナ再起動後も必要なデータが残る
[ ] Worker停止後に未処理ジョブを回復できる
[ ] DNSとHTTPS証明書を確認した
[ ] 構築ログから依存関係の失敗を特定できる
[ ] 新版の失敗から旧版へ戻せる
[ ] ロールバック後にDBスキーマとアプリの互換性を確認した
[ ] デプロイ版、復旧手順、バックアップ担当を文書化した

OpenShipでデプロイに失敗した場合、どのように戻しますか。
まず新しい版のログとサービス状態を保存し、アプリケーションだけの問題か、データベースの変更を伴う問題かを分けます。アプリケーションの版だけを戻しても新しいスキーマが残る場合は、互換性のあるマイグレーションを用意し、必要ならバックアップからの復元を担当者が判断します。

チームへの引き渡しでは、デプロイ日時、対象コミット、利用した環境変数名、公開ドメイン、データ復元責任者、ロールバック実行者を一枚にまとめます。OpenShipの公式インストールや公開手順が更新された場合は、導入コマンド、ネットワークモデル、ロールバック動作を新しい環境で再確認してください。

OpenShipは、標準的なコンテナ化AIエージェントの構築、公開、ログ確認、版管理、ロールバックを一つの流れへまとめやすい選択肢です。ただし、短時間実行を前提にした設計、状態をローカルファイルだけへ保存する設計、複雑なサービス間通信を未検証のまま移す構成は、長期運用の障害要因になります。

本番用のビルド端末を毎回用意したり、自前サーバーへ開発環境まで詰め込んだりすると、構築環境の差分、SSH権限、依存パッケージのキャッシュ、チーム内の再現性が問題になります。継続稼働するmacOSの構築端末、遠隔協業用の作業環境、隔離した検証機が必要なら、プロジェクト期間に合わせてVuncloudのMacレンタル環境を検討する方が、手元の端末だけで運用するより切り分けしやすい場合があります。

ただし、長期にわたる安定した高負荷運用、物理ポートへの常時アクセス、専用ネットワークや固定された保存装置が必要な場合は、自前環境の方が適しています。導入前にヘルプセンターで利用条件を確認し、この記事のチェック項目で健康確認、再起動、データ保持、ロールバックまで検証できる案件だけをレンタル環境へ切り出すのが現実的です。