コマンドリファレンス
FastAPI・Docker・Cloud Run でよく使うコマンド、エラー対処、用語集をまとめました。
🐍 Python / uv
| コマンド | 説明 |
|---|---|
uv init | 新しいPythonプロジェクトを初期化 |
uv add fastapi | パッケージを追加（pip install に相当） |
uv add --dev pytest | 開発依存パッケージを追加 |
uv run fastapi dev app/main.py | FastAPI開発サーバーを起動（ホットリロードあり） |
uv run pytest tests/ -v | テストを実行 |
uv sync | lockファイルから依存関係をインストール |
🐳 Docker
| コマンド | 説明 |
|---|---|
docker build -t <name>:<tag> . | Dockerfileからイメージをビルド |
docker run --rm -p 8080:8080 <image> | コンテナを起動（終了時に自動削除） |
docker images | ローカルのイメージ一覧を表示 |
docker ps | 実行中のコンテナを表示 |
docker logs -f <container> | コンテナのログをリアルタイムで表示 |
docker stop <container> | コンテナを停止 |
docker rm <container> | コンテナを削除 |
docker rmi <image> | イメージを削除 |
docker tag <src> <dst> | イメージにタグを付ける（Artifact Registry用のURLに変換） |
docker push <image-url> | Artifact Registryにイメージをプッシュ |
☁️ gcloud CLI
| コマンド | 説明 |
|---|---|
gcloud init | gcloudの初期設定（認証・プロジェクト設定） |
gcloud config set project <id> | デフォルトプロジェクトを設定 |
gcloud config list | 現在の設定を表示 |
gcloud services enable run.googleapis.com | Cloud Run APIを有効化 |
gcloud auth configure-docker <region>-docker.pkg.dev | Docker認証をArtifact Registry用に設定 |
gcloud artifacts repositories create <name> --repository-format=docker --location=<region> | Artifact Registryリポジトリを作成 |
🚀 Cloud Run デプロイ
| コマンド | 説明 |
|---|---|
gcloud run deploy <service> --image <url> --region <region> --allow-unauthenticated | Cloud Runにサービスをデプロイ |
gcloud run services list --region <region> | サービス一覧を表示 |
gcloud run services describe <service> --region <region> | サービスの詳細を表示 |
gcloud run services update <service> --set-env-vars KEY=VALUE | 環境変数を設定 |
gcloud run services update <service> --min-instances 1 | 最小インスタンス数を設定（コールドスタート対策） |
gcloud run revisions list --service <service> --region <region> | リビジョン一覧を表示 |
gcloud run services update-traffic <service> --to-latest | トラフィックを最新リビジョンへ切り替え |
📋 Cloud Run ログ
| コマンド | 説明 |
|---|---|
gcloud logging read 'resource.type=cloud_run_revision AND resource.labels.service_name=<service>' --limit=50 | Cloud Runのログを取得 |
gcloud logging read 'resource.type=cloud_run_revision AND severity>=ERROR' --limit=20 | エラーログだけ取得 |
🔐 Secret Manager
| コマンド | 説明 |
|---|---|
echo -n 'my-secret' | gcloud secrets create <name> --data-file=- | シークレットを作成 |
gcloud secrets versions list <name> | シークレットのバージョン一覧 |
gcloud run services update <service> --set-secrets KEY=<secret-name>:latest | Cloud RunにSecret Managerのシークレットをマウント |
⚠️ Cloud Run エラー対処
503Service Unavailable
よくある原因
- •コンテナが起動に失敗した
- •PORT環境変数を参照していない
- •--host 0.0.0.0 でリッスンしていない
- •メモリ不足でOOMKilled
対処方法
ログを確認してエラーを特定する。PORT/0.0.0.0を確認する。
404Not Found
よくある原因
- •URLパスが間違っている
- •FastAPIにルートが定義されていない
対処方法
/docs でルート一覧を確認する。
403Forbidden
よくある原因
- •--allow-unauthenticated が設定されていない
- •IAMポリシーが不足
対処方法
allUsers に roles/run.invoker を付与する。
📖 用語集
コンテナ
アプリとその依存関係をまとめた軽量な実行環境。DockerがOSから分離して実行する。
イメージ
コンテナの「型紙」。Dockerfileからビルドされ、どこでも同じ環境を再現できる。
Artifact Registry
Google Cloud のコンテナイメージ（Dockerイメージ）保管サービス。Cloud Runのデプロイ元として使う。
リビジョン
Cloud Runでサービスを更新するたびに作られる不変のスナップショット。ロールバックやトラフィック分割に使う。
コールドスタート
リクエストがないとCloud Runが0インスタンスに縮退し、次のリクエスト時にコンテナを起動する遅延のこと。
サービスアカウント
Cloud Runのような「人間でないもの」が使うGoogle Cloud のID。最小権限の原則で設定する。
Workload Identity Federation
GitHub ActionsなどからGoogle Cloudにサービスアカウントキーなしで認証する仕組み。OIDCベース。
Pydantic
Pythonの型注釈から自動的にバリデーション・シリアライゼーションを行うライブラリ。FastAPIの中核。
依存性注入 (Depends)
FastAPIで共通処理（DB接続、認証チェックなど）をDependsを使って各エンドポイントに渡す仕組み。
マルチステージビルド
Dockerfileで複数のFROM命令を使い、ビルド用と実行用でコンテナを分けることでイメージを小さくする技術。
🐳 Dockerfile チートシート
| 命令 | 説明 | 例 |
|---|---|---|
FROM | ベースイメージを指定 | FROM python:3.12-slim |
WORKDIR | 作業ディレクトリを設定 | WORKDIR /app |
COPY | ファイルをコンテナにコピー | COPY . . |
RUN | ビルド時にコマンドを実行 | RUN pip install -r requirements.txt |
ENV | 環境変数を設定 | ENV PORT=8080 |
EXPOSE | ポートを公開（ドキュメント用） | EXPOSE 8080 |
USER | 実行ユーザーを切り替え | USER appuser |
CMD | コンテナ起動時のデフォルトコマンド | CMD ["uvicorn", "app.main:app"] |