Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

バックグラウンドプロセスを実行する

最終更新 Markdown で表示Agent セットアップ

このガイドでは、Sandbox で長時間実行するバックグラウンドプロセスの起動、監視、管理方法を説明します。

バックグラウンドプロセスを使う場面

次の場合は exec() ではなく startProcess() を使います。

  • Web サーバーを動かす — HTTP サーバー、API、WebSocket サーバー
  • 長時間実行するサービス — データベースサーバー、キャッシュ、メッセージキュー
  • 開発サーバー — ホットリロードする開発サーバー、ウォッチモード
  • 継続的な監視 — ログウォッチャー、ヘルスチェッカー
  • 並列実行 — 複数のサービスを同時に動かす

バックグラウンドプロセスを起動する

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Start a web server
const server = await sandbox.startProcess("python -m http.server 8000");

console.log("Server started");
console.log("Process ID:", server.id);
console.log("PID:", server.pid);
console.log("Status:", server.status); // 'running'

// Process runs in background - your code continues
import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(env.Sandbox, 'my-sandbox');

// Start a web server
const server = await sandbox.startProcess('python -m http.server 8000');

console.log('Server started');
console.log('Process ID:', server.id);
console.log('PID:', server.pid);
console.log('Status:', server.status); // 'running'

// Process runs in background - your code continues

プロセスの環境を設定する

作業ディレクトリと環境変数を設定します。

const process = await sandbox.startProcess("node server.js", {
	cwd: "/workspace/api",
	env: {
		NODE_ENV: "production",
		PORT: "8080",
		API_KEY: env.API_KEY,
		DATABASE_URL: env.DATABASE_URL,
	},
});

console.log("API server started");
const process = await sandbox.startProcess('node server.js', {
  cwd: '/workspace/api',
  env: {
    NODE_ENV: 'production',
    PORT: '8080',
    API_KEY: env.API_KEY,
    DATABASE_URL: env.DATABASE_URL
  }
});

console.log('API server started');

プロセスの状態を監視する

実行中のプロセスを一覧し、確認します。

const processes = await sandbox.listProcesses();

console.log(`Running ${processes.length} processes:`);

for (const proc of processes) {
	console.log(`${proc.id}: ${proc.command} (${proc.status})`);
}

// Check if specific process is running
const isRunning = processes.some(
	(p) => p.id === processId && p.status === "running",
);
const processes = await sandbox.listProcesses();

console.log(`Running ${processes.length} processes:`);

for (const proc of processes) {
  console.log(`${proc.id}: ${proc.command} (${proc.status})`);
}

// Check if specific process is running
const isRunning = processes.some(p => p.id === processId && p.status === 'running');

プロセスの準備完了を待つ

先に進む前に、プロセスの準備完了を待ちます。

const server = await sandbox.startProcess("node server.js");

// Wait for server to respond on port 3000
await server.waitForPort(3000);

console.log("Server is ready");
const server = await sandbox.startProcess('node server.js');

// Wait for server to respond on port 3000
await server.waitForPort(3000);

console.log('Server is ready');

または、特定のログパターンを待ちます。

const server = await sandbox.startProcess("node server.js");

// Wait for log message
const result = await server.waitForLog("Server listening");
console.log("Server is ready:", result.line);
const server = await sandbox.startProcess('node server.js');

// Wait for log message
const result = await server.waitForLog('Server listening');
console.log('Server is ready:', result.line);

プロセスのログを監視する

ログをリアルタイムでストリーミングします。

import { parseSSEStream } from "@cloudflare/sandbox";

const server = await sandbox.startProcess("node server.js");

// Stream logs
const logStream = await sandbox.streamProcessLogs(server.id);

for await (const log of parseSSEStream(logStream)) {
	console.log(log.data);
}
import { parseSSEStream, type LogEvent } from '@cloudflare/sandbox';

const server = await sandbox.startProcess('node server.js');

// Stream logs
const logStream = await sandbox.streamProcessLogs(server.id);

for await (const log of parseSSEStream<LogEvent>(logStream)) {
  console.log(log.data);
}

または、蓄積されたログを取得します。

const logs = await sandbox.getProcessLogs(server.id);
console.log("Logs:", logs);
const logs = await sandbox.getProcessLogs(server.id);
console.log('Logs:', logs);

プロセスを停止する

バックグラウンドプロセスとその子プロセスを停止します。

// Stop specific process (terminates entire process tree)
await sandbox.killProcess(server.id);

// Force kill if needed
await sandbox.killProcess(server.id, "SIGKILL");

// Stop all processes
await sandbox.killAllProcesses();
// Stop specific process (terminates entire process tree)
await sandbox.killProcess(server.id);

// Force kill if needed
await sandbox.killProcess(server.id, 'SIGKILL');

// Stop all processes
await sandbox.killAllProcesses();

killProcess() は、指定したプロセスと、それが起動した子プロセスをすべて終了します。バックグラウンドで動いているプロセスを止めたときに、孤立した子プロセスが残らないようにします。

たとえば、プロセスが複数のワーカープロセスやバックグラウンドタスクを起動する場合、killProcess() はプロセスツリー全体を片付けます。

// This script spawns multiple child processes
const batch = await sandbox.startProcess(
	'bash -c "process1 & process2 & process3 & wait"',
);

// killProcess() terminates the bash process AND all three child processes
await sandbox.killProcess(batch.id);
// This script spawns multiple child processes
const batch = await sandbox.startProcess(
  'bash -c "process1 & process2 & process3 & wait"'
);

// killProcess() terminates the bash process AND all three child processes
await sandbox.killProcess(batch.id);

複数のプロセスを実行する

依存関係の準備完了を待ちながら、サービスを順番に起動します。

// Start database first
const db = await sandbox.startProcess("redis-server");

// Wait for database to be ready
await db.waitForPort(6379, { mode: "tcp" });

// Now start API server (depends on database)
const api = await sandbox.startProcess("node api-server.js", {
	env: { DATABASE_URL: "redis://localhost:6379" },
});

// Wait for API to be ready
await api.waitForPort(8080, { path: "/health" });

console.log("All services running");
// Start database first
const db = await sandbox.startProcess('redis-server');

// Wait for database to be ready
await db.waitForPort(6379, { mode: 'tcp' });

// Now start API server (depends on database)
const api = await sandbox.startProcess('node api-server.js', {
  env: { DATABASE_URL: 'redis://localhost:6379' }
});

// Wait for API to be ready
await api.waitForPort(8080, { path: '/health' });

console.log('All services running');

長時間実行するプロセス向けにコンテナを維持する

デフォルトでは、コンテナは 10 分間操作がないと自動でシャットダウンします。アイドル期間がある長時間処理（CI/CD パイプライン、バッチジョブ、監視タスクなど）では、keepAlive オプション を使います。

import { getSandbox, parseSSEStream } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

export default {
	async fetch(request, env) {
		// Enable keepAlive for long-running processes
		const sandbox = getSandbox(env.Sandbox, "build-job-123", {
			keepAlive: true,
		});

		try {
			// Start a long-running build process
			const build = await sandbox.startProcess("npm run build:production");

			// Monitor progress
			const logs = await sandbox.streamProcessLogs(build.id);

			// Process can run indefinitely without container shutdown
			for await (const log of parseSSEStream(logs)) {
				console.log(log.data);
				if (log.data.includes("Build complete")) {
					break;
				}
			}

			return new Response("Build completed");
		} finally {
			// Important: Must explicitly destroy when done
			await sandbox.destroy();
		}
	},
};
import { getSandbox, parseSSEStream, type LogEvent } from '@cloudflare/sandbox';

export { Sandbox } from '@cloudflare/sandbox';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Enable keepAlive for long-running processes
    const sandbox = getSandbox(env.Sandbox, 'build-job-123', {
      keepAlive: true
    });

    try {
      // Start a long-running build process
      const build = await sandbox.startProcess('npm run build:production');

      // Monitor progress
      const logs = await sandbox.streamProcessLogs(build.id);

      // Process can run indefinitely without container shutdown
      for await (const log of parseSSEStream<LogEvent>(logs)) {
        console.log(log.data);
        if (log.data.includes('Build complete')) {
          break;
        }
      }

      return new Response('Build completed');
    } finally {
      // Important: Must explicitly destroy when done
      await sandbox.destroy();
    }
  }
};

ベストプラクティス

  • 準備完了を待つ — サービスの準備完了を検出するには waitForPort() または waitForLog() を使います
  • 後始末をする — 使い終わったら必ずプロセスを停止します
  • 失敗に対応する — ログでエラーを監視し、必要なら再起動します
  • try/finally を使う — エラー時でも後始末が走るようにします
  • 長時間タスクには keepAlive を使う — アイドル期間がある処理中にコンテナがシャットダウンしないようにします

トラブルシューティング

プロセスがすぐに終了する

ログを確認して原因を調べます。

const process = await sandbox.startProcess("node server.js");
await new Promise((resolve) => setTimeout(resolve, 1000));

const processes = await sandbox.listProcesses();
if (!processes.find((p) => p.id === process.id)) {
	const logs = await sandbox.getProcessLogs(process.id);
	console.error("Process exited:", logs);
}
const process = await sandbox.startProcess('node server.js');
await new Promise(resolve => setTimeout(resolve, 1000));

const processes = await sandbox.listProcesses();
if (!processes.find(p => p.id === process.id)) {
  const logs = await sandbox.getProcessLogs(process.id);
  console.error('Process exited:', logs);
}

ポートがすでに使われている

起動する前に既存のプロセスを終了します。

await sandbox.killAllProcesses();
const server = await sandbox.startProcess("node server.js");
await sandbox.killAllProcesses();
const server = await sandbox.startProcess('node server.js');

関連リソース

役に立ちましたか？