cloudrun-development

関連スキル（ローカルのみ）

関連する CloudBase スキルは、このスキルと同じ場所に配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の関連スキルファイルがこの環境にない場合は、CloudBase プラグイン一式（または不足しているスキル）をインストールするようユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP 経由で取得して、エージェントのコンテキストに読み込んではいけません。

横断的なプロトコル（HTTP ハンドラーの作成またはイメージのデプロイ前に必須）：

• 機密ランタイムデータの保護：../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md
• デプロイゲート：../cloudbase-platform/references/protocols/deployment-gate.md

CloudBase Run の開発

有効化の条件

次の場合はまずこのスキルを使用してください

• CloudBase Run サービスの初期化、実行、デプロイ、調査、デバッグを行う場合。
• 長時間稼働する HTTP サービス、SSE、WebSocket、カスタムシステム依存関係、またはコンテナ形式のデプロイが必要な場合。
• CloudBase Run で Agent サービスを作成または実行する場合。
• 従来の DATABASE_URL / TCP データベースクライアントを使用する既存の / GitHub / サードパーティ製バックエンドを移行する場合。
• 安定した独立プロセスが必要なサービス（長時間接続、カスタムランタイム、VPC データベースへのアクセス）。下記の「云托管 vs HTTP 云函数」の選択セクションを参照してください。Dockerfile があることだけでは、使用の強い判断材料にはなりません。

コードを書く前に読む必要がある場合

• Function モードと Container モードのどちらを選ぶか、まだ決まっていない場合。
• プロンプトに queryCloudRun、manageCloudRun、Dockerfile、サービスドメイン、パブリック／プライベートアクセスが含まれている場合。
• アプリが TCP 経由で MySQL、PostgreSQL、Redis、その他の VPC 内プライベートリソースに依存している場合 → まずデータベースのアクセス方法を決定してください（SDK／ゲートウェイを優先。下記の「データベースアクセス方式の決定ゲート」を参照）。TCP による直接接続が必須と確認できた場合は → references/vpc-and-database.md も読んでください。
• ステートレス HTTP サービスに CloudRun と HTTP クラウド関数のどちらを使うか選ぶ場合。
• サービスが SDK 経由で CloudBase リソース（PG app.rdb()、NoSQL、ストレージ、関数）を呼び出す場合 → まず「計算リソースから CloudBase にアクセスする際の認証情報決定ゲート」を通過してください。認証情報の発行元、注入方法、失効方法は、コードを書く前にすべて決定しておく必要があります。
• コンテナのデプロイに失敗する場合（deploy_failed、Pod が準備未完了、readiness／probe の失敗、サードパーティの imageUrl が起動状態を維持できない）→ references/image-deploy-troubleshooting.md も読み、下記のコンテナデプロイ失敗 SOPに従ってください。最初に InitialDelaySeconds を増やしてはいけません。

次にあわせて読む資料

• CloudRun ではなくクラウド関数を使用する場合 → ../cloud-functions/SKILL.md
• Agent SDK と AG-UI の詳細 → ../cloudbase-agent/SKILL.md
• ブラウザーから呼び出す場合の Web 認証 → ../auth-web-cloudbase/SKILL.md
• 既存アプリと TCP データベースのネットワーク接続 → references/vpc-and-database.md
• コンテナイメージのデプロイ失敗／probe／deploy_failed → references/image-deploy-troubleshooting.md
• サービスが SDK 経由で CloudBase リソースを呼び出す場合（認証情報の取得元／注入／失効）→ ../cloud-functions/references/http-function-credentials.md
• CloudRun の請求に関する質問（「何もデプロイしていないのに請求された理由」「無料枠が使い切られていない理由」）→ ../cloud-api-operations/references/recipes/billing-charges-explained.md（付与された無料枠は3 か月分の合計であり、コンテナはインスタンス数が 0 でない間、課金されます）

使用しない場合

• Function モデルに適したシンプルな Event Function または HTTP Function のワークフロー。
• バックエンドサービスのないフロントエンドのみのプロジェクト。
• データベーススキーマの設計タスク。

よくある間違い／注意点

• リクエストが通常のクラウド関数だけを必要としているのに、CloudRun を選択する。
• Container モードでプラットフォームが提供する PORT をリッスンし忘れること。 その逆も同様です。Function モードで app.listen() を呼び出すと、ポートはすでにフレームワークが管理しているため、2 回目のバインドは EADDRINUSE で失敗します。
• 認証情報の環境変数名を推測すること。 @cloudbase/node-sdk が読み取るのは CLOUDBASE_APIKEY です（たとえば TCB_API_KEY のような）存在しない名前は無視され、後になって実行時に「認証情報がない」として表面化します。
• ローカルのクライアントログイン状態（auth.json、.cloudbase/）からサーバー認証情報をコピーし、デプロイ済みサービスに設定すること。代わりに manageAppAuth(action="createApiKey", keyType="api_key") でキーを発行してください。そうすれば所有者が明確になり、ローテーションでき、失効可能な keyId も得られます。../cloud-functions/references/http-function-credentials.md を参照してください。
• 静的コンテンツ（メディアファイル、ユーザーアップロード、または独自のペースで更新されるアセット）をイメージに含めること。 3 つのケースに共通する根本原因は 1 つです。デプロイのたびに、またスケールアップのたびにイメージが再ビルド、再プッシュ、再プルされるため、大きなファイルや独立して更新されるファイルがあると、理由もなくデプロイが遅くなります。
  • メディアファイル（*.mp4、大きな画像、フォント）を COPY . . で取り込む場合、デモ動画 1 本だけでデプロイが 30 秒から数分に延びることがあります。メディアはクラウドストレージに置き、URL から参照してください。*.mp4、*.mov、*.zip、*.psd や public/videos/ などのメディアディレクトリを対象とする .dockerignore を追加してください。
  • コンテナのファイルシステムに書き込まれるユーザーアップロード。サービスはステートレスです。ローカルディスク上のデータは、次のデプロイ、再起動、またはスケールアウトで失われます。アップロード先にはクラウドストレージを使用してください。
  • イメージから配信される、頻繁に更新される静的リソース。アセットが独自のスケジュールで変更される場合、変更のたびにサービス全体を再デプロイする必要があります。クラウドストレージから配信すれば、サービスの再デプロイはコードが変更されたときだけで済みます。
• CloudRun をステートフルなアプリのホスティングとして扱い、重要な状態をローカルディスクに保存する。
• Container モードではローカル実行が利用できると思い込む。
• シナリオで必要なのがプライベートアクセスまたはミニプログラム内のアクセスだけなのに、デフォルトでパブリックアクセスを有効にする。
• 既存のアプリを DATABASE_URL／MySQL／PostgreSQL／Redis とともにデプロイする際、serverConfig.VpcConf を省略すること。 デプロイは成功したように見えても、実行時にデータベース接続が失敗します。
• 新しいアプリのデプロイでは、デフォルトで TCP によるデータベースへの直接接続を選ぶこと。 SDK／ゲートウェイ経由でアクセスできるデータ（PG の app.rdb()、NoSQL、storage）には VpcConf もデータベースのアカウントとパスワードも必要ありません。TCP による直接接続と VpcConf を使うのは、移行を目的としたアプリ（従来のドライバー／ORM を置き換えられないもの）に限ります。「データベースアクセス方式の判断ゲート」を参照してください。
• OpenAccessTypes（ユーザーがサービスにアクセスする方法）と VpcConf（サービスが VPC データベースにアクセスする方法）を混同する。
• CloudRun が初期化されていない環境にデプロイすること。 大租户レコードがない環境で CreateCloudRunServer を実行すると、従来の小租户パスに黙って進み、誤った小租户サービス／バージョンが作成されます。初回デプロイの前に、必ず環境を初期化してください（tcbr の manageCloudRun(action="initEnv")）。manageCloudRun(action="deploy") は、未初期化の環境での新規サービス作成をブロックし、案内を表示するようになりました。
• 従来の tcb CloudRun API（CreateCloudBaseRunResource／DescribeCloudBaseRunResource／DeleteCloudBaseRunResource）を使用すること。これらは非推奨の小租户向け公開 API であり、callCloudApi ではブロックされます。CloudRun では常に tcbr（CreateCloudRunEnv／CreateCloudRunServer）を使用します。単一環境の基本情報／CloudRun が有効かどうかを確認するには DescribeEnvBaseInfo（EnvId 必須）を使用してください。環境を開くには manageCloudRun(action="initEnv") を、状態をポーリングするには queryCloudRun(action="envStatus") を使用します。環境一覧／リソース情報の取得には DescribeCloudRunEnvs（EnvId の絞り込みは任意）を使用してください。
• httpbin／リクエストをエコーするイメージをデプロイする、または req.headers／process.env を返すこと。 CloudBase が一時的な認証情報を含む x-cloudbase-context（base64）を挿入する場合があります。これをエコーすると、アカウントのクラウドアクセス情報が漏えいします。../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md に従ってください。
• Readiness probe failed／deploy_failed が発生して、すぐに InitialDelaySeconds を引き上げること。 プローブの猶予時間はすでに約 N+150 秒です。クラッシュループやループバックへのバインドは、起動に時間がかかっているわけではありません。Container デプロイ失敗の SOP に従ってください。
• 実行ドキュメントを読まずにサードパーティーのイメージをデプロイすること。 Cmd、バインドアドレスの環境変数、または VolumesConf の設定漏れは、プローブ失敗と同じように見えます。
• imageUrl を使ったデプロイで getDeployLog を呼び出すこと。これは CODING のビルドログです。getProcessLog を使用してください。
• 起動時のバナーをサービスが正常である証拠として扱うこと。 getProcessLog を 2 回取得して比較してください。起動シーケンスが繰り返されている場合は、再起動ループです。

最小限のチェックリスト

• Function モードか Container モードを明示的に選択します。
• 初回デプロイの前に、環境で CloudRun が初期化されていることを確認します — 新しい環境では、まず CreateCloudRunEnv（tcbr）を呼び出す必要があります。初期化されていない環境で CreateCloudRunServer を呼び出してはいけません（旧来の小租户パスにフォールバックします）。manageCloudRun(action="deploy") はこれを自動で検証し、初期化されていない環境での新しいサービス作成をブロックします。ブロックされた場合は、まず manageCloudRun(action="initEnv", envId=...)（非同期で開通）を呼び出し、queryCloudRun(action="envStatus") を Status=normal になるまでポーリングします。または、CloudRun を完全に回避できる HTTP クラウド関数を改めて検討します。
• サービスをパブリック、VPC 限定、ミニプログラム内部向けのどれにするかを確認します（ingress）。
• アプリが TCP データベース／キャッシュを使用する場合は、デプロイ前に VpcConf を解決して設定します（egress／プライベートネットワーク）。references/vpc-and-database.md を参照してください。
• サービスをステートレスに保ち、永続データは外部に保存します。
• 静的なコンテンツと動的なコンテンツを分離します：メディアファイル、ユーザーのアップロード、頻繁に更新されるアセットはイメージではなく、クラウドストレージに保存します。Dockerfile が何をコピーしているか確認してください。
• コードを書く前に、すべての CloudBase SDK 呼び出しで使う認証情報の経路を確定します — manageAppAuth(action="createApiKey") で発行したサーバー API Key を EnvParams 経由で注入し、ローカルクライアントのログイン状態からコピーしたキーは絶対に使いません。
• ローカルプロジェクトのパスには、すべて絶対パスを使用します。
• ハンドラーが x-cloudbase-context、ヘッダー全体、認証情報の環境変数を絶対に返さないことを確認します。httpbin のようなリフレクターはデプロイしないでください。
• サードパーティ製イメージでは、デプロイ前にドキュメントの5項目チェックリスト（Cmd／ポート／bind env／volume／health）を完了します。

概要

短時間で終了するサーバーレス関数ではなく、デプロイ済みのバックエンドサービスが必要な場合は CloudBase Run を使用します。

CloudBase Run と HTTP クラウド関数の比較（ファイルではなく要件で選択）

基本原則：まず HTTP クラウド関数を検討してください。要件が本当に CloudBase Run を必要とする場合にのみ CloudBase Run を使用します。Dockerfile があるからといって、必ず CloudBase Run を使う必要はありません。

HTTP クラウド関数が適している場合（優先）：

• ステートレスな HTTP サービスで、PORT／9000 をリッスンし、「リクエストを受信 → 処理 → 応答」するリアクティブなロジックのみを実行する
• 短時間のリクエストで、長時間接続を必要としない（SSE／WebSocket 以外の一般的な API、CRUD、転送）
• 標準のランタイムで十分（カスタムシステム依存関係や非標準言語が不要）— 必要な場合も、イメージ関数（Custom Image HTTP Function）で実行でき、関数の選択肢のままです
• デプロイが速く、費用が低い（リクエスト単位の課金で、0 までスケールダウン可能）。CloudBase Run 環境の初期化は不要
• Dockerfile があっても、サービスの本質がステートレスな HTTP サービスなら、HTTP クラウド関数（HTTP Function／Custom Image HTTP Function）を優先します。CloudBase Run を使う必要はありません

CloudBase Run が必要な場合（次のいずれかに該当する場合のみ選択）：

• 長時間接続：WebSocket、長時間の SSE 接続、サーバープッシュ
• 常時稼働する独立プロセスが必要：バックグラウンドタスクのループ、常駐キャッシュ／接続プール、独自のポートを管理するサービス
• VPC 内のデータベース／Redis へのアクセス（VpcConf によるプライベートネットワーク接続）
• エージェントサービス（Function モードの CloudRun）
• 既存アプリ／GitHub／サードパーティ製アプリの移行

言語は CloudBase Run を選ぶ条件ではありません：非標準言語（Java／Rust／C++／PHP／.NET など）やカスタムシステム依存関係が必要な場合でも、サービスが「リクエストを受信 → 応答」する形式で、長時間接続がなければ、イメージ化して Custom Image HTTP Function で実行すれば、引き続き関数として扱えます。常時稼働／長時間接続／VPC のいずれかも必要な場合にのみ、CloudBase Run を選択します。

判断例： Dockerfile を含む Go／Python の HTTP API で、長時間接続がなく、カスタムシステム依存関係もなく、VPC データベースにも接続しない場合は、CloudBase Run ではなく HTTP クラウド関数を選びます。同じコードでも、WebSocket の長時間接続がある場合は CloudBase Run を選択します。

データベースアクセス方法の判断ポイント（デプロイ前に必ず確認：SDK 優先、TCP 直接接続は代替手段）

基本原則：CloudBase SDK／ゲートウェイでアクセスできるデータは、すべて SDK 経由を優先します。 TCP 直接接続では VPC、セキュリティグループ、データベースのアカウントとパスワードの3点セットが必要になり、いずれもデプロイ後に初めて問題として現れます（ETIMEDOUT、セキュリティグループによるブロック、パスワードの注入）。可能な限り避けてください。

優先：SDK／ゲートウェイ経由（VpcConf 不要、データベースのアカウントとパスワードも不要）

• CloudBase PG → app.rdb()（js-sdk v3／node-sdk、PG HTTP ゲートウェイ経由。詳しくは ../postgresql-development-cloudbase/SKILL.md を参照）
• NoSQL → app.database()、オブジェクトストレージ → app.storage
• 新しいアプリ／CloudBase ネイティブデータ → データ層は SDK 経由を前提に設計します。デプロイ時に VPC 設定はまったく不要です。これらのデータ面のみを使う場合は、前のセクションにある「HTTP クラウド関数を優先」も組み合わせることで、CloudBase Run も不要にできます

次の場合にのみ TCP 直接接続を使用します（references/vpc-and-database.md の手順をすべて完了してください）：

• 既存アプリ／GitHub／サードパーティ製アプリの移行で、データ層が従来のドライバーや ORM（mysql2、pg、Prisma、SQLAlchemy、WordPress／Ghost など）を使っており、SDK に変更するコストが高い、またはユーザーから現状維持を明示的に求められている
• SDK が対応していない機能（特定の SQL 方言、ストアドプロシージャ、Redis ネイティブプロトコルなど）が必要

判断時のアクション： DATABASE_URL／DB 依存関係の兆候を検出したら、まず作業を止め、「このデータアクセスを SDK／ゲートウェイに置き換えられるか」を確認してから、VPC チェックリストに進むかを判断します。TCP 直接接続の案を前提に進めないでください。

コンピューティングリソースから CloudBase にアクセスするための認証情報の決定ゲート（デプロイ前に必ず回答）

基本原則：SDK の経路で省略できるのはデータベースのアカウントとパスワードであり、CloudBase リソースへのアクセス認証情報ではありません。 サービスコードから CloudBase リソース（PG app.rdb()／NoSQL／storage／functions）を呼び出す場合は、まず認証情報の取得元を決めてからコードを書き、デプロイしてください。

必ず事前に答えるべきことは3つです。

1. 誰が発行するか — CloudBase サーバーサイド API Key：manageAppAuth(action="createApiKey", keyType="api_key", keyName="<service>-<env>")、または CLI tcb env apikey create my-key -e env-xxx。ローカルクライアントのログイン状態（auth.json／.cloudbase/）からキーを取得して使うのは避けてください。
2. どう注入するか — serverConfig.EnvParams を通じて CLOUDBASE_APIKEY を注入します（@cloudbase/node-sdk はこの変数を自動的に読み取ります。明示的に指定するフィールドは accessKey です）。変数名は公式のものを使い、独自に作らないでください。環境変数を変更する際は、既存のキーと値を保持し、全体を上書きしないでください。
3. どう失効させるか — サービスごとに専用キーを1つ用意し、keyName とローテーション担当者を記録します。サービスの停止時またはローテーション時には、manageAppAuth(action="deleteApiKey", keyId=...) を実行して再デプロイしてください。ローテーション後、古いインスタンスに残った複製はエラーにならず、静かに無効になります。

CloudRun コンテナには使用可能な CloudBase 認証情報が自動的に設定されていると想定しないでください。デプロイ後に実際の SDK 読み取りを行い、検証してください（2回以上検証し、プロセスが起動したかどうかだけで判断しないでください）。手順の全容、Manager SDK で Tencent Cloud のアクセスキーを使う方法、環境変数を安全にマージする方法については、../cloud-functions/references/http-function-credentials.md を参照してください。

api_key は環境単位の認証情報です。RLS を回避でき、1つの環境で発行できる数には限りがあります。すべてのサービスに同じキーを使い回さないでください。いずれかのインスタンスが侵害されると、環境全体が侵害されます。

CloudRun がより適している場合

• WebSocket、SSE、サーバープッシュなどの長時間接続
• 長時間実行されるリクエスト処理、または常時稼働するサービスプロセス
• カスタムランタイム環境やシステムライブラリ
• 任意の言語やフレームワーク
• スケーリングに柔軟に対応する、安定した外部サービスエンドポイント
• Function モードの CloudRun への AI エージェントのデプロイ
• データベースへの VPC アクセスが必要な、既存のコンテナ化アプリや複数言語対応アプリの移行

モードの選択

項目	Function モード	Container モード
最適な用途	迅速な開始、Node.js サービスのパターン、組み込みフレームワーク、エージェントのフロー	既存のコンテナ、任意のランタイム、カスタムシステム依存関係
ポートのモデル	関数フレームワークがプラットフォームのポートを自動的にバインドします — コードから app.listen() を呼び出さないでください	アプリは注入された PORT をリッスンする必要があります
Dockerfile	不要	必須 — ただし、Dockerfile があるだけで CloudRun が適しているとは限りません。まず、長時間接続やカスタムランタイムが必要か確認してください。Dockerfile を使うステートレスな HTTP サービスには、HTTP クラウド関数のほうが適している場合があります。
ツール経由でのローカル実行	対応	非対応
典型的な用途	ストリーミング API、低レイテンシのバックエンド、エージェントサービス	カスタム言語スタック、移行したコンテナアプリ

このスキルの使い方（コーディングエージェント向け）

1. 最初にモードを選択します

   • Function モード -> HTTP／SSE／WebSocket またはエージェントのシナリオに最適です
   • Container モード -> Docker／カスタムランタイムが実際に必要な場合に使用します

2. 必須のランタイムルールに従います

   • Container モード：注入された PORT でリッスンします。Function モード：フレームワークがポートをバインドするため、app.listen() は絶対に呼び出さないでください
   • CloudBase SDK の呼び出しを記述する前に、認証情報のゲート（誰が発行するか、どのように注入するか、どのように取り消すか）を確定します
   • サービスはステートレスに保ちます
   • 永続データは DB／ストレージ／キャッシュに保存します
   • 依存関係とイメージサイズは小さく保ちます。イメージにはコードと依存関係のみを含め、メディア、ユーザーのアップロード、頻繁に更新されるアセットはクラウドストレージに保存します（よくある間違いを参照）
   • リソース比率のガイダンスに従います：Mem = 2 × CPU

3. 適切なツールを使用します

   • 読み取り操作 -> queryCloudRun
   • 書き込み操作 -> manageCloudRun
   • 削除には明示的な確認と force: true が必要です
   • 常に絶対パスの targetPath を使用します

4. デプロイの順序に従います

   • コードを初期化するか、ダウンロードします
   • 新しい環境の場合、最初のデプロイ前に CloudRun が初期化されていることを確認します。manageCloudRun(action="initEnv", envId=...)（非同期、冪等）を呼び出してください。未初期化の環境では manageCloudRun(action="deploy") が新しいサービスをブロックし、initEnv の呼び出しを指示します
   • Container モードの場合は、Dockerfile を確認します
   • DB／キャッシュ依存の兆候をスキャンします（DATABASE_URL、docker-compose の DB サービス、ORM 設定）
   • TCP による DB アクセスが必要な場合は、デプロイ前に references/vpc-and-database.md の VPC チェックリストを完了します
   • 利用可能な場合はローカルで実行します
   • 必要に応じて、イングレスのアクセスモデルとエグレスの VpcConf を設定します
   • imageUrl／サードパーティ製イメージの場合は、デプロイ前に Container デプロイ失敗時の SOP にある5 項目のドキュメントチェックリストを完了します
   • デプロイし、詳細出力と DB 接続を確認します
   • デプロイに失敗した場合は、Container デプロイ失敗時の SOP（references/image-deploy-troubleshooting.md）に従います。ドキュメント → getProcessLog → 設定の順に確認し、InitialDelaySeconds から調査を始めないでください

ツールの振り分け

読み取り操作

• queryCloudRun(action="list") -> サービスの一覧を表示します
• queryCloudRun(action="detail") -> 1 つのサービスと、利用可能な場合は最新のデプロイ状態を確認します
• queryCloudRun(action="templates") -> 利用可能なスターターを確認します
• queryCloudRun(action="getDeployLog") -> ビルドログ（CODING／DescribeCloudRunBuildLog）。クラウド上でのソースビルドにのみ有効です。既存イメージのデプロイ（imageUrl）ではビルドプロセスがないため、イメージのデプロイ失敗の診断には使用しないでください。CODING にログインしていないアカウントではエラーが発生します（例：User not created or may not qcloud user）
• queryCloudRun(action="getProcessLog") -> 実行ログ（tcbr/DescribeCloudRunProcessLog）。デプロイ段階のステップ（例：create_version_check_vpc／create_eks_virtual_service／check_eks_virtual_service）に加え、コンテナの起動／実行ログ（s6-overlay、アプリケーションプロセス、readiness probe の失敗理由）を返します。イメージのデプロイとソースビルドのどちらでも使用でき、CODING には依存しません。パラメーター：detailServerName／serverName + 任意の runId（指定しない場合は最新のデプロイの RunId を取得します。RunId は detail／getDeployRecords の latestDeploy.RunId からも取得できます）
• queryCloudRun(action="getDeployRecords") -> デプロイ記録の一覧を新しい順に表示します（BuildId／RunId／FlowRatio／Status を含みます）。トラフィック操作の前に、リリース履歴とロールバックの状況を確認するために使用します
• queryCloudRun(action="envStatus") -> 環境の CloudRun が開通しているかと、そのプロビジョニング状態（Status=creating は開通処理中、normal は開通済み）を確認します。initEnv の後に進行状況を確認するため、または deploy の前に準備状況を確認するために使用します
• queryCloudRun(action="getManageTask") -> リリースタスクの状態（tcbr/DescribeServerManageTask）。taskId／taskStatus と最新デプロイ記録の状態 latestDeployStatus を返します。次の 2 つの用途で使用します。「既存のデプロイリリースタスクが実行中です」という状況になった場合は、まずタスクが実際に進行しているかを確認します。また、デプロイが長時間進展しない場合は、「タスクがまだ進行中」なのか「タスクが停止している」のかを判別します。タスクの状態がわからないまま deploy を繰り返し再試行しないでください

ログ照会 SOP（ビルドログと実行ログ）

デプロイ失敗のトラブルシューティングでは、必ず次の2種類のログを区別してください。getDeployLog だけを使わないでください。

1. クラウド上でのソースコードビルド（targetPath を渡し、CODING ビルドを実行）
   • まず queryCloudRun(action="getDeployLog", detailServerName=..., buildId=...) でビルドログ（コンパイル／パッケージ化の失敗）を確認します
   • 次に queryCloudRun(action="getProcessLog", detailServerName=..., runId=...) で実行ログ（デプロイ手順とコンテナの起動／ヘルスチェック）を確認します
2. 既存イメージのデプロイ（imageUrl を渡し、DeployType=image）
   • getDeployLog はスキップします（ビルド工程がなく、CODING に依存するため、未ログインの場合はそのまま失敗します）
   • queryCloudRun(action="detail") または getDeployRecords から latestDeploy.RunId を取得し、getProcessLog で実行ログを確認します

{
  "action": "getProcessLog",
  "detailServerName": "my-svc",
  "runId": "<from latestDeploy.RunId>"
}

デプロイタスク SOP（「既存のデプロイ公開タスクが実行中」に遭遇した場合）

manageCloudRun(action="deploy") が「既存のデプロイ公開タスクが実行中」／ already has a deploy task running と報告した場合、むやみに再試行したり、Dockerfile や serverConfig を何度も変更したりしないでください。まずタスクの実際の状態を確認します。

1. queryCloudRun(action="getManageTask", detailServerName=...) → taskId／taskStatus／latestDeployStatus を確認します
2. queryCloudRun(action="getProcessLog") → 20～40 秒間隔で2回取得して比較し、デプロイ段階の手順がまだ進行しているか確認します
3. 結果に応じて対応します。

状況	対応
taskStatus がまだ実行中で、デプロイ手順が進行している	そのまま待ちます。deploy を再送信しないでください
タスクが終了している（実行中ではない）のに、deploy が引き続き拒否される	その場合に限り、再試行を検討します
タスクが長時間、終了状態にならず、バージョンも creating のまま進まない	taskId／latestDeployStatus／時間帯を証拠として記録し、無意味な再試行をしないでください

force=true ではこの問題は解決しません。これは本ツールの確認プロンプトをスキップするだけで、サーバー側の既存の公開タスクをキャンセルしたり上書きしたりすることはありません。「強制上書き」として使っても、無駄な失敗が一度増えるだけです。

ログ側のトラブルシューティングの順序（ビルドログと実行ログの区別、設定より先にログを確認）については、上記の ログ照会 SOP と コンテナデプロイ失敗 SOP を参照してください。

書き込み操作

• manageCloudRun(action="initEnv") -> 環境の CloudRun を開く（初期化する） — 非同期、べき等（Status=normal → すでに開いているため、再作成しません）。新しい環境で最初のデプロイを行う前、または「クラウドホスティングが未初期化」というメッセージで deploy がブロックされた場合に使用します。パラメーター：envId（設定済みの環境がデフォルト）、packageType（デフォルトは Trial）。Status=normal になるまで queryCloudRun(action="envStatus") をポーリングします。
• manageCloudRun(action="init") -> ローカルプロジェクトを作成
• manageCloudRun(action="download") -> リモートコードを取得
• manageCloudRun(action="run") -> Function モードでローカル実行
• manageCloudRun(action="deploy") -> デプロイを開始し、登録完了まで軽量に待機します（ビルド全体の完了を待つことはありません。buildId が不要で、その待機もスキップする場合は waitRegistration=false を渡します）。buildId／runId／taskId と、DeployType に対応した next_step を返します。source → getDeployLog の後に getProcessLog、image（imageUrl、BuildId は多くの場合 0）→ getDeployLog をスキップし、getDeployRecords／detail で RunId を取得してから getProcessLog を使用します。返された next_step に従ってください。常にビルドログをポーリングしないでください。既存サービスの場合：RMW はリモートの VpcConf／EnvParams キー／OpenAccessTypes を保持します。新規サービスの場合は、環境の CloudRun が初期化済みかどうかを自動で検証します。未初期化の場合、initEnv を先に呼び出すよう案内してデプロイをブロックします
• manageCloudRun(action="updateConfig") -> 設定のみを更新（コードのアップロードなし。VPC／EnvParams／スケーリング／アクセスタイプ）
• manageCloudRun(action="traffic") -> トラフィック管理／カナリアリリース（tcb cloudrun traffic に準拠）：trafficOp="set" は安定版／カナリアのトラフィック比率を調整します（stablePercent + canaryPercent は合計が 100 である必要があります。例：90/10）。trafficOp="promote" はカナリア版を正式リリース（100％）に昇格させます（グレーリリースを終了します。元に戻せません）。trafficOp="rollback" は直前の安定版にロールバックします（リリース中のカナリアを停止します）。現在のバージョンとトラフィックを確認するため、まず queryCloudRun(action="getDeployRecords") を実行してください
• manageCloudRun(action="delete") -> サービスを削除
• manageCloudRun(action="createAgent") -> Agent サービスを作成

既存イメージのデプロイ（imageUrl）

既存のイメージ（ローカルでビルド済み、またはサードパーティが公開済み）がある場合、ローカルのソースコードディレクトリは不要です。manageCloudRun(action="deploy") に imageUrl を渡すだけで、DeployType="image"（コンテナ型）としてデプロイできます。targetPath は省略可能です。ユーザーが特定のイメージの使用、またはコードの再ビルドが不要であることを明確に指定している場合は、必ず imageUrl を渡してください。ローカルにソースコードディレクトリがあるという理由だけで、ソースコードからのビルドに切り替えてはいけません。

判断手順（直接指定するか、ローカル経由にするか）：

1. パブリックから認証なしで取得可能（ccr.ccs.tencentyun.com/...、公開 Docker Hub イメージなど）→ imageUrl に直接指定：manageCloudRun(action="deploy", serverName=..., imageUrl="ccr.ccs.tencentyun.com/ns/img:v1", serverConfig={...})。CloudBase がその registry アドレスから直接取得してデプロイ用にビルドします。ノードで docker.io / Docker Hub からの取得が繰り返し失敗する場合は、無意味に再試行しないでください。Dockerfile に FROM <public-image> を記述し、targetPath を使ったソースコードビルドに切り替えます（CODING がパブリックからイメージを取得し、生成物を CCR に格納して、内部ネットワーク経由で取得します）。以下の SOP の手順 4 を参照してください。
2. プライベート、またはログインが必要な registry（ghcr.io、プライベート ECR／Harbor など）→ ローカル経由で CCR に転送：

   docker pull ghcr.io/example/app:latest
   docker tag ghcr.io/example/app:latest ccr.ccs.tencentyun.com/<ns>/app:latest
   docker login ccr.ccs.tencentyun.com
   docker push ccr.ccs.tencentyun.com/<ns>/app:latest
   

   次に、ccr.ccs.tencentyun.com/<ns>/app:latest を imageUrl として渡します。転送で解決するのはイメージの取得だけです。イメージのドキュメントに記載された起動コマンド／環境変数／データディレクトリの代わりにはなりません。

initEnv との連携： イメージのデプロイでも、環境で CloudRun が有効になっている必要があります。新しい環境で初回デプロイする前に manageCloudRun(action="initEnv", envId=...) を実行し、queryCloudRun(action="envStatus") で Status=normal になるまでポーリングしてください。有効化されていない場合、deploy はブロックされ、先に initEnv を実行するよう案内されます。

例：

{
  "action": "deploy",
  "serverName": "my-image-svc",
  "imageUrl": "ccr.ccs.tencentyun.com/ns/app:latest",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 3,
    "Port": 8080,
    "Cmd": ["node", "server.js"],
    "EnvParams": "{\"PORT\":\"8080\",\"BIND_HOST\":\"0.0.0.0\"}"
  }
}

Port／Cmd／EnvParams は、イメージの公式ドキュメントにある必須 5 項目の一覧に基づいて設定してください。3000 を流用したり、起動コマンドを省略したりしないでください。サードパーティ製イメージとの詳しい対応表は、references/image-deploy-troubleshooting.md の付録を参照してください。

デプロイ後：イメージに対して manageCloudRun(deploy) が返す next_step は、デフォルトで getProcessLog を指します（または、先に getDeployRecords で RunId を取得してください）。getDeployLog に切り替えてはいけません。 queryCloudRun(action="detail") で imageInfo（イメージアドレスとデプロイの種類）を確認することもできます。イメージのデプロイ失敗時は、以下の SOP に沿ってトラブルシューティングしてください。

コンテナデプロイ失敗時の SOP

順序：まずイメージの公式ドキュメントを確認し、次に実行ログを確認して、最後に設定を変更します。probe failed / deploy_failed を見ただけで InitialDelaySeconds を変更することは禁止です。

詳しい説明と事例：references/image-deploy-troubleshooting.md。

1. デプロイ前：イメージの公式ドキュメントで必須 5 項目を確認

Docker Hub のタグや「よくあるデフォルト値」をもとに推測してはいけません。デプロイ前に、必ず以下を確認してください。

1. 起動コマンド EntryPoint / Cmd（プロセスをどのようにフォアグラウンドで常駐させるか）→ serverConfig.EntryPoint / Cmd
2. サービスポート（プロセスが実際に bind するポート。80／3000 と決めつけたり、イメージが PORT を尊重すると想定したりしないでください）→ serverConfig.Port
3. 外部接続用の環境変数（127.0.0.1 ではなく 0.0.0.0 を指定すること、機能フラグがデフォルトで無効になっていることなど）→ EnvParams
4. データディレクトリのマウント → serverConfig.VolumesConf
5. ヘルスチェックエンドポイント（CloudRun readiness が確認するのはサービスポートであり、任意の HTTP パスではありません）

いずれか 1 つでも確認せずにデプロイすると、失敗の原因が「ヘルスチェック失敗」のように見えることがあります。

2. デプロイ失敗時：getProcessLog で原因を特定

イメージのデプロイ（imageUrl）では、getDeployLog をスキップしてください（これはクラウド側でソースコードをビルドする際のビルドログです）。detail / getDeployRecords から RunId を取得し、queryCloudRun(action="getProcessLog") を実行してください。

起動ログがあること ≠ サービスが正常に稼働していること。 banner、s6／tini の行、sidecar の「listening」は、いずれもプローブ対象が起動した証拠にはなりません。

ログを 2 回比較して稼働状態を判断： 20～40 秒待ってから、再度 getProcessLog を取得してください。

観察内容	判定
スケジューリング／作成手順（create_eks_*）のみで、コンテナの stdout がない	Pod のスケジューリング中／イメージの取得中
同じ起動 banner／PID 1 の行が繰り返し表示される（タイムスタンプは進んでいるが、内容はほぼ同じ）	コンテナの起動直後の終了／再起動ループ
プロセスはまだ動いているが、127.0.0.1 で listen している、またはポートが serverConfig.Port と異なる	ポート／バインドアドレスの問題
2 回目の取得で、同一の起動プロセスのログが先に進んでおり、banner が繰り返されていない	起動に時間がかかっている可能性があります

3. Readiness probe の実際の仕組み（遅延時間を先に変更しない）

デプロイ手順の完了後、まず N 秒（InitialDelaySeconds）待ち、その後、約 5 秒ごとにサービスポートをプローブします。約 30 回連続ですべて失敗した場合に限り、そのデプロイは失敗と判定されます。判定までの時間は約 N+150s です。「N 秒後に即座に失敗」するわけではありません。

• 禁止： probe failed を見て N を 120 に変更すること。クラッシュループや loopback バインドは、N を大きくしても解決しません。
• N を大きくしてよいのは、 2 回のログから、同じプロセスが一度限りの初期化（JVM のウォームアップ、マイグレーションなど）をまだ実行中で、listen を開始していないと確認できる場合に限ります。

4. パブリックイメージ（docker.io）からの取得が繰り返し失敗する場合 → Dockerfile を使ったソースコードビルド

ノードから Docker Hub への直接接続が繰り返し失敗する場合、imageUrl を無意味に再試行しないでください。以下を記述します。

FROM docker.io/example/app:latest

targetPath を使用してクラウド側でソースコードをビルドします。CODING のビルドマシンがパブリックからイメージを取得し、生成物を CCR に格納して、CloudRun ノードが内部ネットワーク経由で取得します。これで解決するのは取得経路だけです。手順 1 の Cmd／環境変数／ボリュームの代わりにはなりません。

5. Supervisor イメージ（s6／tini／supervisord）が起動直後に終了する場合

PID 1 は、多くの場合 HTTP アプリではなく監視プロセスです。2 回分のログを使って、子プロセスの再起動が連続していないか確認してください。イメージの issue に PID 1／pgrep -f の誤マッチが記録されている場合は、ドキュメントの回避策（絶対パスの Cmd、supervise の無効化）に従ってください。プローブの遅延を変更してはいけません。例は reference の付録を参照してください。

アクセスに関するガイダンス

• Web／パブリックなシナリオ → PUBLIC ingress を意図的に有効にし、適切な認証フローと組み合わせてください。
• ミニプログラム → 内部の直接接続を優先し、不要なパブリック公開を避けてください。
• プライベート ingress のシナリオ → プロダクト要件で明確に必要とされない限り、パブリックアクセスは無効のままにしてください。
• VPC 内のデータベース／Redis → これは OpenAccessTypes では解決できません。serverConfig.VpcConf を設定し、データベースのプライベートアドレスを使用する必要があります。references/vpc-and-database.md を参照してください。

クイック例

初期化

{ "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" }

ローカル実行（Function モード）

{ "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } }

デプロイ（VPC のプライベート依存関係なし）

{
  "action": "deploy",
  "serverName": "my-svc",
  "targetPath": "/abs/ws/my-svc",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 5
  }
}

デプロイ (TCP 経由で MySQL / PostgreSQL / Redis に接続する既存アプリ)

{
  "action": "deploy",
  "serverName": "my-existing-app",
  "targetPath": "/abs/ws/my-existing-app",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 5,
    "EnvParams": "{\"DATABASE_URL\":\"postgres://user:[email protected]:5432/app\"}",
    "VpcConf": {
      "VpcId": "vpc-xxxxxxxx",
      "SubnetId": "subnet-xxxxxxxx"
    }
  }
}

有効な OpenAccessTypes の値: OA (办公网访问)、PUBLIC (公网访问)、MINIAPP (小程序访问)、VPC (VPC访问)。パブリック HTTPS アクセスが必要な Web アプリケーションには PUBLIC を使用します。

MinNum: 1 は、コールドスタートのレイテンシを削減したい場合に推奨されるデフォルト値です。ユーザーがより低コストを明確に優先し、コールドスタートの増加を受け入れる場合は、トレードオフを説明したうえで MinNum を 0 に下げてもらってください。

ベストプラクティス

1. 可能な場合は PRIVATE/VPC またはミニプログラム内部の イングレス を優先してください。
2. TCP によるデータベースアクセスでは、常にプライベート DB URL を、データベースと同じ VPC/リージョンの VpcConf と組み合わせてください。
3. シークレットと環境ごとの設定には環境変数を使用してください — サーバー側でのみ読み取り、HTTP レスポンスで返さないでください。CloudBase API キーは、ローカルのクライアントログインファイルではなく manageAppAuth(action="createApiKey") から取得します。
4. デプロイの前後に queryCloudRun(action="detail") で設定を検証してください。
5. コールドスタートの影響を減らすため、起動時の処理は小さく保ってください。
6. エージェントのシナリオでは、プロトコルとアダプターの詳細をここで重複して説明するのではなく、Agent SDK スキルを使用してください。
7. スモークテストでは、固定の { "ok": true } / ヘルスペイロードを返してください — httpbin や、リクエストヘッダーをそのまま返すようなサービスは決してデプロイしないでください。

トラブルシューティングのヒント

• アクセス失敗 -> イングレスのアクセスタイプ、ドメイン設定、およびインスタンスがゼロにスケールされたかどうかを確認してください。
• 「尚未初始化云托管 / not initialized」でデプロイがブロックされる -> その環境で先に CloudRun を有効化する必要があります: manageCloudRun(action="initEnv", envId=...) を呼び出し (异步开通)、queryCloudRun(action="envStatus") を Status=normal になるまでポーリングします。またはコンソールで 环境 → 云托管 → 开通 を開きます。ステートレスな HTTP サービスでは、CloudRun ではなく HTTP クラウド関数の使用を検討してください。
• デプロイ失敗 -> 上記の コンテナデプロイ失敗 SOP (および references/image-deploy-troubleshooting.md) に従ってください: イメージデプロイでは getDeployLog をスキップし、getProcessLog のみを使用します。2 回のログ取得で、スケジューリング、ポート、起動時終了のいずれであるかを分類します。ログで単一の遅い初期化が証明されるまでは、InitialDelaySeconds を 引き上げないでください。また、Dockerfile (ソース) と CPU/メモリ比も確認してください。
• 「a deploy task is already running」/「已有部署发布任务运行中」でデプロイが拒否される -> まず queryCloudRun(action="getManageTask") で実際のタスク状態を確認してください。盲目的に再試行しないでください。また、force=true で上書きされると期待して設定しないでください — これはこのツールの確認プロンプトをスキップするだけです。上記の デプロイタスク SOP を参照してください。
• デプロイは受け付けられたが、バージョンが creating から進まない -> queryCloudRun(action="getManageTask") で latestDeployStatus と taskStatus を確認し、次に getProcessLog でデプロイ段階のステップを確認してください。ログが実際にコードや設定を指し示した場合にのみ、Dockerfile / serverConfig を変更してください。
• ローカル実行の失敗 -> ローカル実行ツールでサポートされるのは Function モードのみであることを覚えておいてください。
• パフォーマンスの問題 -> 依存関係を減らし、初期化を最適化し、最小インスタンス数を調整してください。
• デプロイ成功後の DB / Redis 接続失敗 -> ほとんどの場合、VpcConf の欠落または誤り、プライベートホストの誤り、あるいはセキュリティグループが原因です。アプリケーションコードを書き換える前に references/vpc-and-database.md に従ってください。
• サービス内部で CloudBase SDK 呼び出しが認証情報の欠落 / 無効で失敗する -> 上記の認証情報ゲートがスキップされたか、変数名が公式のものではありません。manageAppAuth(action="createApiKey") でキーを発行し、EnvParams を介して CLOUDBASE_APIKEY として注入し、再デプロイしてから、実際の読み取りを検証してください。../cloud-functions/references/http-function-credentials.md を参照してください。

リファレンスインデックス

パッケージ化されたすべてのリファレンスファイル (スキルの lint 到達性に必要):

• vpc-and-database.md
• image-deploy-troubleshooting.md