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 でエージェントサービスを作成または実行する場合。
• 従来の 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

使用しない場合

• 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を参照してください。
• CloudRunをステートフルなアプリのホスティングと見なし、重要な状態をローカルディスクに保存する。
• Containerモードではローカル実行を利用できないことを想定していない。
• シナリオでプライベートアクセスやミニプログラム内部からのアクセスだけが必要なのに、デフォルトでパブリックアクセスを開放する。
• DATABASE_URL／MySQL／PostgreSQL／Redisを使用する既存アプリを、serverConfig.VpcConfを指定せずにデプロイすること — デプロイは成功したように見えても、実行時にDB接続が失敗します。
• 新しいアプリのデプロイでは、デフォルトでTCPによるDBへの直接接続を選ぶこと — SDK／ゲートウェイでアクセスできるデータ（PGのapp.rdb()、NoSQL、storage）には、VpcConfもDBのアカウントとパスワードも不要です。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に従ってください。
• 準備状態プローブの失敗／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 を参照してください。
• サービスをステートレスに保ち、永続データは外部化します。
• コードを書く前に、すべての CloudBase SDK 呼び出しで使用する認証情報の経路を確定します — manageAppAuth(action="createApiKey") で発行したサーバー API Key を EnvParams 経由で注入し、ローカルクライアントのログイン状態からキーをコピーして使うことは決してありません。
• すべてのローカルプロジェクトパスに絶対パスを使用します。
• ハンドラーが x-cloudbase-context、ヘッダー全体、または認証情報の環境変数をエコーバックしないことを確認します。httpbin 形式のリフレクターはデプロイしないでください。
• サードパーティ製イメージでは、デプロイ前にドキュメント用の 5 項目チェックリスト（Cmd／ポート／バインド環境変数／ボリューム／ヘルスチェック）を完了します。

概要

短期間だけ実行するサーバーレス関数ではなく、デプロイ済みのバックエンドサービスが必要なタスクでは CloudBase Run を使用します。

クラウドホスティングと HTTP クラウド関数（ファイルではなく要件で選択）

基本原則：HTTP クラウド関数を優先します。本当にクラウドホスティングが必要な場合に限り、クラウドホスティングを使用してください。Dockerfile があるからといって、クラウドホスティングが必須になるわけではありません。

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

• ステートレスな HTTP サービスで、PORT／9000 をリッスンし、「リクエスト受信 → 処理 → 応答」のリクエスト／レスポンス型ロジックのみを実行する
• 長時間接続が不要な、短時間のリクエスト（SSE／WebSocket 以外の通常の API、CRUD、転送）
• カスタムシステム依存関係や複数言語のランタイムが不要で、標準ランタイムで十分
• デプロイが速く、コストが低い（リクエスト単位の課金で、スケールを 0 まで縮小可能）。クラウドホスティング環境の初期化も不要
• Dockerfile があっても、サービスの本質がステートレスな HTTP である → HTTP クラウド関数（HTTP Function／Custom Image HTTP Function）を優先します。クラウドホスティングは不要です

クラウドホスティングが必要な場合（以下のいずれかに該当するときのみ選択）：

• 長時間接続：WebSocket、SSE の長時間接続、サーバープッシュ
• カスタムシステム依存関係／任意の言語ランタイム／安定した独立プロセスが必要
• VPC 内のデータベース／Redis へのアクセス（VpcConf によるプライベートネットワーク接続）
• エージェントサービス（Function mode CloudRun）
• 既存／GitHub／サードパーティ製アプリの移行、または常駐プロセスが必要

判断例： Dockerfile を含む Go／Python の HTTP API で、長時間接続もカスタムランタイムもなく、VPC データベースにもアクセスしない場合 → クラウドホスティングではなく HTTP クラウド関数を選択します。同じコードでも WebSocket の長時間接続が必要なら → クラウドホスティングを選択します。

データベースアクセス方式の判断ゲート（デプロイ前に必ず回答：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 クラウド関数を優先」と組み合わせることで、クラウドホスティングも不要にできます

次の場合に限り 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