デプロイと運用

ochakai は、お客様自身の Google Cloud プロジェクト内で独立して動作します。最小構成は Cloud Run サービス 1 つと、最小クラスの Cloud SQL インスタンス（PostgreSQL 17）1 つです。

本ガイドは ochakai v0.31.1 に対応しています。詳細は公式リポジトリの Cloud Run デプロイ手順書・Terraform モジュール・要件と設定・運用ガイドを参照してください。クライアント側の接続手順は「エージェント接続ガイド」をご覧ください。

0. 前提条件と費用見積もり

ochakai の本番環境は Google Cloud 上に構築します。サービスへのアクセス制御は Cloud Run の IAM が担当し、データベース接続は Cloud SQL IAM データベース認証を利用します。この設計により、ochakai 自体にパスワードや API キーなどの機密情報を保持させる必要がありません。外部への通信は、セマンティック検索利用時の Vertex AI Embeddings API と、任意で有効にするデータエージェントの Gemini 呼び出しだけです（§5 参照）。

ローカルで動作確認を行いたい場合は、deploy/compose.yaml（Docker Compose）を利用するのが最も手軽です。認証なしですぐに手元でテストできます。

構築作業に必要なツールは以下の通りです。

データベースには PostgreSQL 17 を使用します。初回マイグレーション時に pg_trgm（文字トライグラム検索）および vector（pgvector: セマンティック検索）拡張機能を作成するため、初回のみ管理者権限での接続が必要です。

us-central1 リージョンでの月額費用の概算見積もりは以下の通りです。

費用の大半は Cloud SQL です（asia-northeast1 など東京リージョンでは為替や地域差により若干高くなります）。評価環境以外では日次バックアップを有効にしておくことを推奨します。

1. 構築手順

構築方法は 2 通り用意されています。構成管理や差分レビュー、クリーンな破棄が容易な Terraform の利用を推奨します。CI/CD パイプラインや既存インフラに合わせて gcloud コマンドで個別に構築できます。

どちらの方法でも作成されるリソースは同一です。

推奨: Terraform による自動構築

git clone https://github.com/na0fu3y/ochakai && cd ochakai/deploy/terraform
cp terraform.tfvars.example terraform.tfvars   # project, region, invokers を設定
terraform init
terraform apply    # Cloud SQL のプロビジョニングに 10〜15 分ほどかかります

適用完了後、初回のみスキーマの初期化を手動で実行します（実行する SQL は terraform output に出力されます）。

gcloud sql users set-password postgres --instance=ochakai --prompt-for-password
cloud-sql-proxy "$(terraform output -raw sql_connection_name)" --port 55432 &
psql "host=localhost port=55432 dbname=ochakai user=postgres"
# psql 内で `terraform output -raw database_bootstrap_sql` で表示された SQL を実行

terraform output -raw use_command   # チームメンバーに案内する ochakai use コマンドを表示

export PROJECT_ID=<your-project>
export REGION=asia-northeast1
gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com sqladmin.googleapis.com \
  sql-component.googleapis.com artifactregistry.googleapis.com

# Cloud Run は ghcr.io から直接 pull できないので、プロキシするリポジトリを作る
gcloud artifacts repositories create ghcr \
  --repository-format=docker \
  --mode=remote-repository \
  --remote-docker-repo=https://ghcr.io \
  --location=$REGION
export VERSION=0.31.1
export IMAGE=$REGION-docker.pkg.dev/$PROJECT_ID/ghcr/na0fu3y/ochakai:$VERSION

# データベース(作成に 10〜15 分)
gcloud sql instances create ochakai \
  --database-version=POSTGRES_17 \
  --edition=enterprise \
  --tier=db-f1-micro \
  --region=$REGION \
  --storage-size=10 \
  --storage-type=SSD \
  --no-storage-auto-increase \
  --no-backup \
  --database-flags=cloudsql.iam_authentication=on
gcloud sql databases create ochakai --instance=ochakai
export DB_PASSWORD=$(openssl rand -hex 24)
gcloud sql users create ochakai --instance=ochakai --password=$DB_PASSWORD

# サービスアカウント。IAM データベース認証で DB に繋ぐ
gcloud iam service-accounts create ochakai-run --display-name="ochakai service"
export SERVICE_ACCOUNT=ochakai-run@$PROJECT_ID.iam.gserviceaccount.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.instanceUser
export DB_SA_USER=ochakai-run@$PROJECT_ID.iam
gcloud sql users create $DB_SA_USER --instance=ochakai --type=cloud_iam_service_account

cloud-sql-proxy $PROJECT_ID:$REGION:ochakai --port 55432 &
psql "host=localhost port=55432 dbname=ochakai user=ochakai"

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;
-- vector は §5 のセマンティック検索用。Cloud SQL の pgvector は
-- trusted extension ではないため、admin が作る

GRANT USAGE, CREATE ON SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
GRANT ALL ON ALL TABLES IN SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO "ochakai-run@<PROJECT_ID>.iam";
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "ochakai-run@<PROJECT_ID>.iam";
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO "ochakai-run@<PROJECT_ID>.iam";

# デプロイして、組織に invoke を許可する
gcloud run deploy ochakai \
  --image=$IMAGE \
  --region=$REGION \
  --service-account=$SERVICE_ACCOUNT \
  --no-allow-unauthenticated \
  --min-instances=0 --max-instances=1 \
  --cpu=1 --memory=512Mi \
  --add-cloudsql-instances=$PROJECT_ID:$REGION:ochakai \
  --set-env-vars="OCHAKAI_DB_IAM_AUTH=true" \
  --set-env-vars="OCHAKAI_DATABASE_URL=postgres:///ochakai?host=/cloudsql/$PROJECT_ID:$REGION:ochakai&user=$DB_SA_USER"
gcloud run services add-iam-policy-binding ochakai --region=$REGION \
  --member=domain:your-org.example --role=roles/run.invoker

# セマンティック検索(日本語のベースなら特に推奨。詳しくは §5)
gcloud services enable aiplatform.googleapis.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/aiplatform.user

export OCHAKAI_URL=$(gcloud run services describe ochakai --region=$REGION --format='value(status.url)')

未認証アクセス（allUsers）は許可しないでください。ochakai は Cloud Run の IAM 認証を通過したリクエストを前提として呼び出し元情報を記録します。認証を無効化してよいのは、誰でも読み取り可能な公開展示用の public モード（§4 参照）のみです。

2. 動作確認

サービスは未認証の直接アクセスを拒否するため、通常の curl では IAM エラーとなります。手元の端末から動作確認を行うには、Cloud Run のプロキシ機能を利用します。

gcloud run services proxy ochakai --region=$REGION --port=8787 &
curl http://localhost:8787/health

ヘルスチェックのエンドポイントは /health です。（/healthz ではありません。ロードバランサーが /healthz を遮断し 404 を返す挙動に起因します）。

/health はプロセスの生存（liveness）を確認します。データベース接続も含めて正常性を確認したい場合は、CLI から ochakai whoami を実行してください。データベースへのアクセス確認とともに、現在どのユーザーとして認識されているかが表示されます。

ochakai use $OCHAKAI_URL
ochakai whoami

デプロイ時によくあるトラブルと対処法は以下の通りです。

3. 環境変数の設定

ochakai の設定はすべて環境変数で行います。設定ファイルは不要です。必須となるのは OCHAKAI_DATABASE_URL のみで、その他は用途に応じて設定します。

※Cloud Run の環境変数を更新する際は --update-env-vars を使用してください（--set-env-vars は指定外の既存変数を消去してしまいます）。

4. アクセス制御と権限管理

ochakai のアクセス境界は Cloud Run の IAM 認証に基づきます。roles/run.invoker を持つユーザーが接続でき、渡された ID（例: human:user@example.com）は来歴として自動記録されます。

組織内での権限分割

チーム間や部門間でナレッジの閲覧・編集権限を分けたい場合は、以下の 2 つの方法があります。

• サービス（インスタンス）を分ける: 最も安全かつ確実な方法です。Cloud Run サービスとデータベースを分けることで、インフラレベルでアクセスを分離できます。
• ディレクトリごとのアクセスポリシーを設定する: ひとつのナレッジベース内で、プレフィックス（ディレクトリ）単位に閲覧・編集権限を割り当てます（ochakai access コマンドで設定可能）。

ディレクトリ単位のポリシーでは、各行に「どのユーザー/グループに」「どのディレクトリの」「閲覧権（既定）または編集権（may_write）」を与えるかを定義します。

ochakai access --json > policy.json
$EDITOR policy.json
ochakai access -f policy.json --if-match "$(jq -r .version policy.json)"

--if-match オプションを付けることで、複数人によるポリシー編集時のコンフリクト（意図しない上書き）を防ぐことができます。

稼働モード（OCHAKAI_MODE）

5. 外部通信とセマンティック検索（データ送信ポリシー）

ochakai が外部と通信するのは、セマンティック検索のための Vertex AI Embeddings API のみです。任意のデータエージェント（下記）は別です。テレメトリ収集や外部への問い合わせ機能は一切含まれていません。

セマンティック検索を有効化すると、登録ナレッジの本文や検索クエリが同じプロジェクトの Vertex AI へ送信され、ベクトルデータが生成されます。送信先はベースを作ったときに決まります。v0.29.0 より後に作ったベースは gemini-embedding-2 を global で使い、画像と PDF も中身で検索できます。その代わり、本文と検索クエリは global の Vertex AI で処理されます。それより前からあるベースは、アップグレード後も gemini-embedding-001 をサービスのリージョンで使い続けます。

新しいベースでもテキストをリージョン内に留めたい場合は、OCHAKAI_EMBEDDINGS に gemini-embedding-001 とリージョンを resource name で名指します。

gcloud run services update ochakai --region=$REGION \
  --update-env-vars=OCHAKAI_EMBEDDINGS=projects/$PROJECT_ID/locations/$REGION/publishers/google/models/gemini-embedding-001

字句検索（文字トライグラム検索）のみで運用したい場合は、環境変数 OCHAKAI_EMBEDDINGS=off を設定します。あるいは、サービスアカウントの roles/aiplatform.user 権限を外すことでも無効化できます。

gcloud run services update ochakai --region=$REGION \
  --update-env-vars=OCHAKAI_EMBEDDINGS=off

セマンティック検索を有効にすると、字句検索とベクトル検索を組み合わせたハイブリッド検索が機能し、同義語や表現の揺らぎに強くなります（特に日本語ナレッジで効果的です）。

画像や PDF、アテスターの .py などの添付ファイルは、v0.30.0 から設定なしで保存できます。実体は PostgreSQL に置かれ、1 ファイル 5 MiB までです。ファイル数が多い場合や大容量ファイルを扱う環境では OCHAKAI_GCS_BUCKET にバケット名を指定します。設定後に追加されたファイルは GCS へ保存され、それまでに PostgreSQL へ保存されたファイルも引き続き参照できます。

任意: データエージェント

v0.28.7 から、デプロイ自身のデータエージェントを有効にできます。Claude Code などを持たない人が、Web UI の「エージェント」タブでナレッジについて質問できるようになります。既定は off で、未設定のあいだ ochakai の動作は何も変わりません。

gcloud run services update ochakai --region=$REGION \
  --update-env-vars=OCHAKAI_AGENT=gemini-2.5-flash

モデルはこのサービスのプロジェクトとリージョンで動き、呼び出しにはサービスアカウントの roles/aiplatform.user を使います。リージョンにモデルが無ければ起動を拒否し、別のリージョンへ黙って送りません（2026 年 9 月時点では、asia-northeast1 で gemini-2.5-flash が答えます）。public と sandbox のデプロイでは使えません。

エージェントは質問した人の権限でナレッジを読みます。新しい下書きを書くことはありますが、検証・却下・書き換えはしません。数字が要る質問には SQL を提案しますが、サーバーは SQL を実行しません。よく使われるクエリを訊かれたときは、質問した本人のクエリ履歴（JOBS_BY_USER）だけを数えます（v0.30.0 から）。質問した本人が自分の権限で実行します。手元の ochakai ui では本人の gcloud の身元を使い、SELECT だと確かめたクエリだけを課金上限 10 GiB で実行します。チームの Web UI から実行させるには OAuth クライアントを Google Cloud コンソールで作り、OCHAKAI_OAUTH_CLIENT_ID に渡します。課金先を OCHAKAI_BIGQUERY_PROJECT で決めておくと、利用者はプロジェクト ID を入力せずに済みます。手順はデプロイ手順書 §4c にあり、Terraform では agent_model・agent_oauth_client_id・agent_bigquery_project が同じことをします。

質問と会話はモデルに送られます。実行したクエリの結果の行もサーバーとモデルを通りますが、どこにも保存されません。サーバーは答えた回の形（会話の最初の質問、答えた質問、読んだドキュメント、提案した SQL の本文）と質問者の判定だけを残します。これらは 180 日で消え、エクスポートにも含まれません。

6. 日常の運用とメンテナンス

2 種類のバックアップ

システム全体の保全とデータの可搬性のため、ochakai では 2 種類のバックアップ方法を使い分けます。

システムの障害対策には Cloud SQL の定期バックアップを利用し、データの独立性やチーム共有・バージョン管理には ochakai export を利用するのが適しています。

バージョンの更新（アップグレード）

データベーススキーマのマイグレーションはコンテナ起動時に自動実行されるため、アップグレードは新しいコンテナイメージタグを指定してデプロイするだけで完了します。更新前には公式の CHANGELOG をご確認ください。

gcloud run services update ochakai --region=$REGION \
  --image=$REGION-docker.pkg.dev/$PROJECT_ID/ghcr/na0fu3y/ochakai:<new-tag>

更新後は ochakai whoami の version 行で、サーバーがどのビルドで動いているかを確認できます（手元の CLI は ochakai version です）。Web UI も上部のバーにバージョンを表示し、UI と API のビルドが食い違うときは両方を表示します。

ナレッジ運用の定期確認

システムの稼働状態だけでなく、ナレッジベースが健全に運用されているかを定期的に確認します。ochakai stats を実行することで、レビュー待ちのドラフト件数や、エージェントから失敗報告があったドキュメントの件数を一目で確認できます。

ochakai stats                 # 4 つのキュー、失敗報告、語が一致しなかった検索等を表示
ochakai stats --exit-code     # 未処理のレビューが残っている場合に非ゼロで終了（CI/cron 監視用）

レビューキューの具体的な消化手順については、「ナレッジ運用サイクルガイド」を参照してください。

想定規模とサイジング

ochakai は、人間による検証を経た高品質な数千件規模のドメインナレッジベースを安定して提供できるよう最適化されています。初期構成（Cloud SQL db-f1-micro + Cloud Run 最小インスタンス 0）で、月額十ドル前後の低コスト運用が可能です。

7. データの移行とサービスの終了

ochakai の利用を終了する場合や別環境へ移行する場合でも、データがベンダーやプラットフォームに拘束されることはありません。すべてのナレッジは標準的な OKF 形式（Markdown + YAML Frontmatter）として簡単にエクスポートできます。

ochakai export ./knowledge          # ローカルディレクトリに Markdown ファイル群として展開
ochakai export - > okf.tar.gz       # tar.gz アーカイブとして受け取る
ochakai export --prefix teams/growth -   # 特定のディレクトリ配下のみを個別エクスポート

エクスポートされたファイルはそのまま Git リポジトリで管理したり、他のドキュメントツールに移行できます。各ドキュメントの verified には、いまの内容に対して有効な検証だけが載ります（v0.30.0 から）。編集で失効した検証も含む全履歴は、バンドルの log.md に残ります。

すべてのリソースを削除する場合は、以下のコマンドを実行します。

gcloud run services delete ochakai --region=$REGION --quiet
gcloud run services delete ochakai-webui --region=$REGION --quiet
gcloud sql instances delete ochakai --quiet

Terraform で構築した環境であれば、terraform destroy を実行するだけで関連リソースが一括でクリーンアップされます。