diff --git a/docker/platformclaw-runtime/OPERATIONS.ko.md b/docker/platformclaw-runtime/OPERATIONS.ko.md index affd893ef5..e175305786 100644 --- a/docker/platformclaw-runtime/OPERATIONS.ko.md +++ b/docker/platformclaw-runtime/OPERATIONS.ko.md @@ -132,6 +132,27 @@ Compose config에는 숫자 설정만 표시된다. 별도 `docker compose exec launcher가 계산한 옵션을 상속하지 않으므로 실제 Gateway 프로세스의 `NODE_OPTIONS`와 유효 heap limit으로 적용 여부를 확인한다. +Gateway의 heap 페이지가 스왑으로 밀리면 GC가 해당 페이지를 다시 읽는 동안 이벤트 루프가 +수십 초 멈춰 관리 RPC가 시간 초과될 수 있다. Compose는 `mem_limit`와 `memswap_limit`에 +`deployment.env`의 `PLATFORMCLAW_GATEWAY_MEM_LIMIT`를 동일하게 적용해 스왑을 막는다. +키가 없거나 비어 있으면 `16g`를 사용한다. 기본값은 old-space 8GiB에 Node의 기타 할당, +버퍼, 컨테이너 내 `ssh`·`sshpass` 프로세스용 여유 4GiB 이상을 더한 값이다. 나머지 공간에 +들어간 파일 캐시는 메모리 압박 시 cgroup 안에서 회수된다. 한도는 +`PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE`보다 최소 4GiB 높게 설정한다. Docker는 `0`을 +한도 미설정으로 처리하며, 양의 한도가 너무 낮으면 스왑 없이 OOM kill이 발생할 수 있다. +`platformclaw-deploy up`, `image update`, `config apply`는 +같은 Compose 설정을 사용하며 컨테이너를 재생성할 때 새 한도를 적용한다. + +배포 후 cgroup v2와 systemd cgroup 드라이버를 사용하는 Docker 호스트에서 확인한다. + +```bash +cat /sys/fs/cgroup/system.slice/docker-$(docker inspect -f '{{.Id}}' platformclaw-openclaw-gateway-1).scope/memory.swap.max +docker inspect -f '{{.HostConfig.Memory}} {{.HostConfig.MemorySwap}}' platformclaw-openclaw-gateway-1 +``` + +첫 명령은 `0`을, 두 번째 명령은 같은 양의 바이트 값 두 개를 출력해야 한다. 기본값이면 +두 값 모두 `17179869184`다. + secret 경로는 `~/platformclaw/secrets`를 가리킨다. `init`은 경로만 기록하며, 첫 새 설치의 첫 `up`은 PlatformClaw이 소유하는 Gateway/Knox/execution 계열의 누락 secret을 생성한다. 외부 시스템 credential은 자동 생성하지 않는다. 예를 들어 private S3 가이드의 diff --git a/docker/platformclaw-runtime/compose.yaml b/docker/platformclaw-runtime/compose.yaml index 1bed35003c..5f939e19fa 100644 --- a/docker/platformclaw-runtime/compose.yaml +++ b/docker/platformclaw-runtime/compose.yaml @@ -22,6 +22,10 @@ services: openclaw-gateway: image: ${PLATFORMCLAW_IMAGE:-platformclaw:local} pull_policy: never + # 16 GiB budgets 8 GiB of old space plus at least 4 GiB for Node, buffers, + # and ssh/sshpass. The cgroup can reclaim file cache under pressure. + mem_limit: ${PLATFORMCLAW_GATEWAY_MEM_LIMIT:-16g} + memswap_limit: ${PLATFORMCLAW_GATEWAY_MEM_LIMIT:-16g} # Match mem_limit to disable swap. user: "${PLATFORMCLAW_RUNTIME_UID:?run platformclaw-compose with a service user}:${PLATFORMCLAW_RUNTIME_GID:?run platformclaw-compose with a service user}" depends_on: platformclaw-state-init: diff --git a/docker/platformclaw-runtime/deployment.env.example b/docker/platformclaw-runtime/deployment.env.example index 9ca7f05bbe..f1caa57721 100644 --- a/docker/platformclaw-runtime/deployment.env.example +++ b/docker/platformclaw-runtime/deployment.env.example @@ -3,6 +3,9 @@ PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox: # Gateway V8 old-space ceiling in MiB. This is not an RSS/container memory limit. # The launcher appends this heap option to existing NODE_OPTIONS. PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE=8192 +# Keep the Gateway container limit at least 4 GiB above the old-space ceiling. +# Swap is disabled. A limit set too low can cause an OOM kill. +PLATFORMCLAW_GATEWAY_MEM_LIMIT=16g # Composer Predictions model must name a configured provider/model. PLATFORMCLAW_COMPOSER_PREDICTIONS_MODEL=codemate/codellm-fast PLATFORMCLAW_SKILL_HUB_ENABLED=true diff --git a/docker/platformclaw-runtime/platformclaw-compose b/docker/platformclaw-runtime/platformclaw-compose index 8b615380bf..de905a7769 100755 --- a/docker/platformclaw-runtime/platformclaw-compose +++ b/docker/platformclaw-runtime/platformclaw-compose @@ -70,7 +70,7 @@ skillhub_enabled="$(sed -n 's/^PLATFORMCLAW_SKILL_HUB_ENABLED=//p' "$PLATFORMCLA # Stable deployment values come only from deployment.env. Ambient shell values # must not silently override an image update, rollback, origin, or secret path. unset PLATFORMCLAW_IMAGE PLATFORMCLAW_SANDBOX_IMAGE \ - PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE \ + PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE PLATFORMCLAW_GATEWAY_MEM_LIMIT \ PLATFORMCLAW_COMPOSER_PREDICTIONS_MODEL \ PLATFORMCLAW_PUBLIC_ORIGIN PLATFORMCLAW_PUBLIC_PORT PLATFORMCLAW_GUIDE_VIDEO_URL \ PLATFORMCLAW_GUIDE_VIDEO_S3_ENDPOINT PLATFORMCLAW_GUIDE_VIDEO_S3_REGION \ diff --git a/scripts/generate-npm-package-lock.mjs b/scripts/generate-npm-package-lock.mjs index 639ce14024..3c83e9a9b8 100644 --- a/scripts/generate-npm-package-lock.mjs +++ b/scripts/generate-npm-package-lock.mjs @@ -315,15 +315,17 @@ function resolvePnpmLockOverridePlan(lockfile) { ) { continue; } - // Hosted-source snapshots use a URL key, while npm matches the package's - // published semantic version when applying a scoped child policy. - const parentVersion = exactVersionFromOverrideSpec( - lockfile.packages?.[`${parent.name}@${parent.version}`]?.version ?? parent.version, - ); + const parentPackage = lockfile.packages?.[`${parent.name}@${parent.version}`]; + const parentVersion = exactVersionFromOverrideSpec(parentPackage?.version ?? parent.version); if (!parentVersion) { continue; } - const parentSelector = `${parent.name}@${parentVersion}`; + // npm cannot match a versioned override to a Git commit edge. A name-only + // selector preserves the child pins when the parent has one locked source. + const parentSelector = + parentPackage?.resolution?.gitHosted === true && versionsByName.get(parent.name)?.size === 1 + ? parent.name + : `${parent.name}@${parentVersion}`; for (const [dependencyName, dependencySpec] of Object.entries(dependencies)) { if (!multiVersionPackageNames.has(dependencyName)) { continue; diff --git a/test/scripts/generate-npm-package-lock.test.ts b/test/scripts/generate-npm-package-lock.test.ts index f929856963..ba361ed303 100644 --- a/test/scripts/generate-npm-package-lock.test.ts +++ b/test/scripts/generate-npm-package-lock.test.ts @@ -254,11 +254,11 @@ describe("generate-npm-package-lock", () => { }); }); - it("preserves decorated snapshot children under the hosted parent's actual package version", () => { + it("preserves decorated snapshot children for an unambiguous Git commit parent", () => { const source = "https://codeload.github.com/example/acpx/tar.gz/reviewed"; - const plan = resolvePnpmLockOverridePlan({ + const lockfile = { packages: { - [`acpx@${source}`]: { version: "0.13.2" }, + [`acpx@${source}`]: { version: "0.13.2", resolution: { gitHosted: true } }, "@agentclientprotocol/sdk@1.3.0": {}, "@agentclientprotocol/sdk@1.4.0": {}, "zod@3.25.76": {}, @@ -278,16 +278,26 @@ describe("generate-npm-package-lock", () => { dependencies: { zod: "3.25.76(patch_hash=other)" }, }, }, - }); + }; + const plan = resolvePnpmLockOverridePlan(lockfile); expect(plan.scopedVersionOverrides).toEqual({ "@agentclientprotocol/sdk@1.3.0": { zod: "3.25.76" }, "@agentclientprotocol/sdk@1.4.0": { zod: "4.6.6" }, - "acpx@0.13.2": { + acpx: { "@agentclientprotocol/sdk": { ".": "1.4.0", zod: "4.6.6" }, zod: "4.6.6", }, }); expect(plan.versionOverrides).not.toHaveProperty("zod"); + + const ambiguous = resolvePnpmLockOverridePlan({ + ...lockfile, + packages: { ...lockfile.packages, "acpx@0.13.2": {} }, + }); + expect(ambiguous.scopedVersionOverrides).not.toHaveProperty("acpx"); + expect(ambiguous.scopedVersionOverrides["acpx@0.13.2"]).toEqual( + plan.scopedVersionOverrides.acpx, + ); }); it("does not invent a semantic parent version for an unversioned hosted package", () => { diff --git a/test/scripts/platformclaw-gateway-heap.test.ts b/test/scripts/platformclaw-gateway-heap.test.ts index 35c420adfd..9418f259d5 100644 --- a/test/scripts/platformclaw-gateway-heap.test.ts +++ b/test/scripts/platformclaw-gateway-heap.test.ts @@ -9,6 +9,7 @@ const runtimeRoot = path.resolve("docker/platformclaw-runtime"); const bash = process.platform === "win32" ? "C:/Program Files/Git/bin/bash.exe" : "bash"; const hasCompose = spawnSync("docker", ["compose", "version"], { stdio: "ignore" }).status === 0; const heapKey = "PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE"; +const memLimitKey = "PLATFORMCLAW_GATEWAY_MEM_LIMIT"; function shellPath(value: string): string { return process.platform === "win32" @@ -233,7 +234,7 @@ compose=(record_compose) } }, 30_000); - it("preserves a custom setting through the updater's image-pair update and rollback", () => { + it("preserves custom gateway limits through image-pair update and rollback", () => { const root = tempDirs.make("platformclaw-heap-update-"); const functions = extractDeployFunctions("read_env_value", "set_image_pair"); const result = runShell( @@ -241,10 +242,11 @@ compose=(record_compose) deploy_root="$PLATFORMCLAW_TEST_ROOT" env_file="$deploy_root/deployment.env" for heap in 4096 8192 12288; do - printf '%s\\n' 'PLATFORMCLAW_IMAGE=platformclaw:old' 'PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox:old' "${heapKey}=$heap" >"$env_file" + printf '%s\\n' 'PLATFORMCLAW_IMAGE=platformclaw:old' 'PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox:old' "${heapKey}=$heap" '${memLimitKey}=20g' >"$env_file" cp "$env_file" "$env_file.previous" set_image_pair platformclaw:new platformclaw-sandbox:new [[ "$(read_env_value ${heapKey})" == "$heap" ]] + [[ "$(read_env_value ${memLimitKey})" == 20g ]] [[ "$(read_env_value PLATFORMCLAW_IMAGE)" == platformclaw:new ]] set_image_pair "$(read_env_value PLATFORMCLAW_IMAGE "$env_file.previous")" "$(read_env_value PLATFORMCLAW_SANDBOX_IMAGE "$env_file.previous")" cmp "$env_file" "$env_file.previous" @@ -254,9 +256,15 @@ done`, expect(result.status, result.stderr || result.error?.message).toBe(0); }); - it.skipIf(!hasCompose).each([undefined, "", "4096", "8192", "12288"])( - "uses the deployment env value %j only for the gateway through Compose", - (heap) => { + it.skipIf(!hasCompose).each([ + { heap: undefined, memLimit: undefined, limitGiB: 16 }, + { heap: "", memLimit: "", limitGiB: 16 }, + { heap: "4096", memLimit: "12g", limitGiB: 12 }, + { heap: "8192", memLimit: "16g", limitGiB: 16 }, + { heap: "12288", memLimit: "20g", limitGiB: 20 }, + ])( + "renders gateway-only limits with heap $heap and memory $memLimit", + ({ heap, memLimit, limitGiB }) => { const root = tempDirs.make("platformclaw-heap-compose-"); const envFile = path.join(root, "deployment.env"); const secret = path.join(root, "synthetic-secret"); @@ -279,6 +287,7 @@ done`, "SSH_CREDENTIAL_MASTER_KEY_SECRET_FILE", ].map((key) => `PLATFORMCLAW_${key}=${secret.replaceAll("\\", "/")}`), ...(heap === undefined ? [] : [`${heapKey}=${heap}`]), + ...(memLimit === undefined ? [] : [`${memLimitKey}=${memLimit}`]), ]; writeFileSync(envFile, `${values.join("\n")}\n`); const result = runShell( @@ -293,6 +302,7 @@ exec bash "$PLATFORMCLAW_TEST_COMPOSE" config --format json PLATFORMCLAW_DEPLOY_ROOT: shellPath(root), PLATFORMCLAW_ENV_FILE: shellPath(envFile), [heapKey]: "16384", + [memLimitKey]: "24g", PLATFORMCLAW_GUIDE_VIDEO_URL: "", PLATFORMCLAW_GUIDE_VIDEO_S3_ENDPOINT: "", PLATFORMCLAW_GUIDE_VIDEO_S3_BUCKET: "", @@ -306,16 +316,23 @@ exec bash "$PLATFORMCLAW_TEST_COMPOSE" config --format json ); expect(result.status, result.stderr || result.error?.message).toBe(0); const config = JSON.parse(result.stdout) as { - services: Record }>; + services: Record< + string, + { environment?: Record; mem_limit?: number; memswap_limit?: number } + >; }; - const gateway = config.services["openclaw-gateway"]!.environment!; - expect(gateway[heapKey]).toBe(heap || "8192"); + const gateway = config.services["openclaw-gateway"]!; + expect(gateway.environment?.[heapKey]).toBe(heap || "8192"); + expect(Number(gateway.mem_limit)).toBe(limitGiB * 1024 ** 3); + expect(gateway.memswap_limit).toBe(gateway.mem_limit); for (const [name, service] of Object.entries(config.services)) { if (name !== "openclaw-gateway") { expect(service.environment?.[heapKey], name).toBeUndefined(); + expect(service.mem_limit, name).toBeUndefined(); + expect(service.memswap_limit, name).toBeUndefined(); } } - const launched = runLauncher(gateway[heapKey]); + const launched = runLauncher(gateway.environment?.[heapKey]); expect(launched.status, launched.stderr).toBe(0); const probe = JSON.parse(launched.stdout) as GatewayProbe; expect(probe.options).toBe(`--max-old-space-size=${heap || "8192"}`);