iop/agent-test/dev-corp/node-smoke.md

---
test_env: dev-corp
test_profile: node-smoke
domain: node
verification_type: smoke
last_rule_updated_at: 2026-07-02
---

# node-smoke dev-corp 테스트

## 읽기 조건

- `apps/node/**` 변경 또는 dev-corp node 실행, adapter, transport, router, store 검증 판단이 필요한 경우

## 적용 범위

- `apps/node/cmd/node/**`
- `apps/node/internal/bootstrap/**`
- `apps/node/internal/node/**`
- `apps/node/internal/runtime/**`
- `apps/node/internal/router/**`
- `apps/node/internal/transport/**`
- `apps/node/internal/adapters/**`
- `apps/node/internal/store/**`
- dev-corp Linux ARM64/macOS Node bootstrap과 provider endpoint 연결

## 분류

- domain: node
- verification_type: smoke
- scope: dev-corp node 실행 파이프라인과 Edge 연결 baseline

## 환경

- host: local checkout. dev-corp host, provider, shared Edge runtime evidence가 필요하면 mac-mini `ssh fe@172.24.63.178`을 사용한다.
- port: compose Edge-Node TCP transport `19006`, native provider-pool Edge-Node TCP 후보 `18087`
- runtime: Go `1.24`
- package manager: Go modules / Makefile
- docker: unit/smoke quick check는 Docker를 요구하지 않는다. compose dev-corp 검증은 mac-mini에서 수행한다.
- external service: dev-corp Edge runtime 후보 `172.24.63.178:18087`
- model endpoint: dev-corp OpenAI-compatible base URL 후보 `http://172.24.63.178:18086/v1`
- credential: token/secret/API key 원문은 문서에 기록하지 않는다.

## dev-corp Node 접속 기준

dev-corp의 실제 3-node 연결을 점검할 때는 mac-mini `ssh fe@172.24.63.178`의 `/Users/fe/agent-work/iop-dev-corp` checkout과 `build/dev-corp-runtime/edge.yaml`을 기준으로 한다. Node는 provider pool 기준에서 Edge-Node TCP `172.24.63.178:18087` 또는 host별 reverse SSH tunnel로 붙는다.
2026-07-02 현재 DGX Spark 01/02는 `127.0.0.1:28087 -> mac-mini 127.0.0.1:18087` reverse SSH tunnel로 붙고, Mac Studio는 직접 Edge TCP 후보를 사용한다. tunnel pid file은 mac-mini runtime의 `build/dev-corp-runtime/node01-tunnel.pid`, `build/dev-corp-runtime/node02-tunnel.pid`다.

- DGX Spark 01 vLLM node: `corp-dgx-spark-01-vllm-node` / `corp-dgx-spark-01-vllm`
  - SSH/user: mac-mini에서 `ssh digitalcommerce_dgx_spark_01@192.168.2.2`
  - provider endpoint: `http://192.168.2.2:8002/v1`
  - Edge adapter endpoint: node-local `http://127.0.0.1:8002/v1`
  - Edge addr: `127.0.0.1:28087` via mac-mini reverse SSH tunnel in the current native runtime
  - served model: `gemma-4-26B-A4B-it-NVFP4`
  - capacity baseline 후보: `4`
  - runtime capacity/context/KV: `--max-num-seqs 4`, `--max-model-len 262144`, `--gpu-memory-utilization 0.40`; 2026-07-02 startup log 기준 GPU KV cache `834,507` tokens, `262144` full-context concurrency `3.18x`; FP4 MoE env `VLLM_MAX_TOKENS_PER_EXPERT_FP4_MOE=4194304`
  - start script: `/home/digitalcommerce_dgx_spark_01/start_vllm_8002.sh`
  - 주의: FlashInfer FP4 JIT가 first compile 중 `ninja`를 호출하므로 start script에서 `/home/digitalcommerce_dgx_spark_01/vllm_env/bin`을 `PATH` 앞에 둔다.
  - workspace: `/home/digitalcommerce_dgx_spark_01`
- DGX Spark 02 vLLM node: `corp-dgx-spark-02-vllm-node` / `corp-dgx-spark-02-vllm`
  - SSH/user: mac-mini에서 `ssh dplab@192.168.2.4`
  - provider endpoint: `http://192.168.2.4:8004/v1`
  - Edge adapter endpoint: node-local `http://127.0.0.1:8004/v1`
  - Edge addr: `127.0.0.1:28087` via mac-mini reverse SSH tunnel
  - served model: `gemma-4-26B-A4B-it-NVFP4`
  - capacity baseline 후보: `4`
  - runtime capacity/context/KV: `--max-num-seqs 4`, `--max-model-len 262144`, `--gpu-memory-utilization 0.40`; 2026-06-25 startup log 기준 GPU KV cache `860,222` tokens, `262144` full-context concurrency `3.28x`; FP4 MoE env `VLLM_MAX_TOKENS_PER_EXPERT_FP4_MOE=4194304`
  - start script: `/home/dplab/start_vllm_gemma4_8004.sh`
  - workspace: `/home/dplab`
  - 주의: Docker publish 때문에 host endpoint와 container endpoint 모두 `8004`이다. `8000`, `8001`, `8002`를 기본 endpoint로 쓰지 않는다.
- Mac Studio vLLM-MLX node: `corp-mac-studio-mlx-vllm-node` / `corp-mac-studio-mlx-vllm`
  - SSH/user: mac-mini에서 `ssh dc_dev@192.168.2.3`
  - provider endpoint: `http://192.168.2.3:8004/v1`
  - Edge adapter endpoint: node-local `http://127.0.0.1:8004/v1`
  - Edge provider catalog type: `openai_compat`; provider runtime type remains `vllm-mlx`.
  - served model: `mlx-community/gemma-4-26b-a4b-it-nvfp4`
  - capacity baseline 후보: `5` (`--max-num-seqs 5` 기준)
  - runtime capacity/context/KV: `--max-num-seqs 5`, `--max-request-tokens 262144`, requested KV `262144x3` mapped to `--max-kv-size 786432`
  - start script: `/Users/dc_dev/iop-dev-corp-field/start_vllm_mlx_8004.sh`
  - workspace: `/Users/dc_dev`
  - process manager: 2026-06-25 기준 detached `screen` session `vllm_mlx_8004`; 이 host는 Python `pyexpat` 로딩에 `DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib`가 필요하다.

DGX Spark nodes는 Linux/ARM64 bootstrap을 기본으로 한다. Mac Studio node는 macOS bootstrap을 기본으로 한다. Windows native bootstrap은 dev-corp provider pool 기본 대상이 아니다.

Mac Studio의 secondary `http://192.168.2.3:8005/v1` endpoint는 기본 Node/provider pool 검증 대상이 아니다. 별도 alias/capacity 정책이 확정된 후 추가한다.

## 런타임 설정/검증 상태

- DGX Spark 01에는 capacity `4`, context window `262144`, requested KV `262144x2` 이상의 기준을 반영했다. vLLM에는 vLLM-MLX식 `--max-kv-size`가 없으므로 DGX01은 `--max-num-seqs 4`, `--max-model-len 262144`, `--gpu-memory-utilization 0.40`로 운용하고, 실제 KV cache는 startup log의 `GPU KV cache size`로 검증한다.
- DGX Spark 01은 2026-07-02 재기동 후 mac-mini 내부 endpoint `http://192.168.2.2:8002` 기준 `/health` 200, `/v1/models` smoke를 통과했다. 같은 로그에서 GPU KV cache `834,507` tokens, `262144` tokens/request concurrency `3.18x`가 확인됐다.
- DGX Spark 02에는 capacity `4`, context window `262144`, requested KV `262144x2` 이상의 기준을 반영했다. Docker `vllm-gemma4`는 host/container `8004` 기준으로 동작하며, node-local과 mac-mini 경유 `/health`, `/v1/models`, 직접 동시성 `1..4` chat completion benchmark를 통과했다.
- DGX Spark에서 explicit `--max-num-batched-tokens 524288`를 사용하는 경우 first profile 중 FP4 MoE 커널 한계에 걸릴 수 있어 `VLLM_MAX_TOKENS_PER_EXPERT_FP4_MOE=4194304` 보정이 필요하다.
- DGX Spark 01은 FlashInfer FP4 JIT가 first compile 중 `ninja`를 PATH에서 찾으므로 `/home/digitalcommerce_dgx_spark_01/vllm_env/bin` PATH prefix가 필요하다.
- Mac Studio에는 capacity `5`, context window `262144`, requested KV `262144x3` 기준을 `--max-num-seqs 5`, `--max-request-tokens 262144`, `--max-kv-size 786432`로 반영했고 `/health`, `/v1/models`, 직접 동시성 `1..5` chat completion benchmark 통과를 확인했다.
- Gemma provider-pool은 `default_thinking_token_budget: 1024` 기준으로 thinking을 기본 활성화한다. vLLM과 vLLM-MLX provider 모두 Edge/Node adapter 요청에서 `chat_template_kwargs.enable_thinking=true`가 적용되는 방향으로 검증한다.
- Gemma provider-pool의 provider queue timeout은 두지 않는다. config 값은 `queue_timeout_ms=0`이며, backend request timeout은 30분 기준인 `request_timeout_ms=1800000`으로 맞춘다.
- 2026-07-02 재확인 기준 DGX Spark 02는 mac-mini에서 SSH, provider `/health`, `/v1/models`가 회복됐고 직접 provider benchmark를 통과했다. Edge OpenAI-compatible capacity smoke는 Control Plane status snapshot 기준으로 재검증 완료됐다.

## 2026-07-02 연결/용량 검증 상태

- dev-corp Control Plane native runtime이 활성화되어 `http://127.0.0.1:18002/edges/dev-corp-edge/status`에서 3개 provider node가 connected로 관측된다.
- DGX Spark 01, DGX Spark 02, Mac Studio Node binary는 source ref `5b1255a` 기준으로 재배포되었고 각 host의 `iop-dev-corp-field/iop-node`로 실행된다.
- Control Plane `provider_snapshots` 기준 provider 상태는 DGX01 capacity `4`, DGX02 capacity `4`, Mac Studio capacity `5`, 모두 `health=healthy`, `status=available`이다.
- `/v1/responses`와 `/v1/chat/completions` 각각 14개 동시 요청에서 peak total `in_flight=13`, `queued=3`을 관측했고, 완료 후 모든 provider가 `in_flight=0`, `queued=0`으로 회복했다.

## 명령

- setup:
- lint:
- unit: `go test ./apps/node/...`
- smoke: `./scripts/e2e-smoke.sh`는 기본 포트 임시 설정을 쓰는 보조 smoke이므로 dev-corp 포트 override 필요 여부를 먼저 확인한다.
- e2e: `make test-e2e`
- provider-health: mac-mini에서 `curl -fsS http://192.168.2.2:8002/health`, `curl -fsS http://192.168.2.4:8004/health`, `curl -fsS http://192.168.2.3:8004/health`
- full-cycle: repo 내부 edge-node 진단과 사용자 실행 cycle 수동 검증

## 필수 검증

- 변경한 node 패키지 또는 `go test ./apps/node/...`를 실행한다.
- 실행 요청, stream, cancel, status, session, adapter registry 경로를 바꾼 경우 repo 내부 edge-node 진단과 full-cycle 실제 구동 기준을 함께 적용한다.
- vLLM/OpenAI-compatible adapter 설정을 바꾼 경우 mac-mini에서 provider `/health`와 `/v1/models`를 먼저 확인하고, 이후 Edge OpenAI-compatible 경로에서 model alias 후보 `gemma4:26b` 또는 작업에서 확정한 alias가 노출되는지 확인한다.
- dev-corp Edge runtime으로 연결하는 경우 Node가 `18087` native provider-pool TCP를 사용하고 local/test/dev baseline으로 붙지 않는지 확인한다.
- Node bootstrap UX는 Edge가 출력한 완성 명령을 사용하고, 사용자에게 수동 `node.yaml` 편집이나 named env parameter를 기본 경로로 요구하지 않는다.

## 보조 검증

- `./scripts/e2e-smoke.sh`는 mock adapter 기반 보조 smoke로 사용한다.
- `make test-e2e`는 보조 smoke이며 full-cycle 실제 구동을 대체하지 않는다.

## 판정 기준

- node 등록 후 edge console에서 node가 조회된다.
- 같은 session에서 메시지 2회가 start, 기대 payload를 포함한 `[node-*-message]`, 같은 run의 complete 순서로 edge 화면에 도착한다.
- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다.
- edge complete는 같은 run의 마지막 `[node-*-message]` 이후에만 정상이다.
- command 결과가 `[node-*-<command>]` 또는 명확한 성공/unsupported/error 출력으로 edge 화면에 표시된다.
- provider nodes는 mac-mini에서 내부 endpoint로 `/health`와 `/v1/models`가 성공해야 한다.

## 기준 출력 예시

```text
curl -fsS http://192.168.2.2:8002/health
curl -fsS http://192.168.2.4:8004/health
curl -fsS http://192.168.2.3:8004/health
```

## 차단 기준

- mac-mini 또는 내부 provider node SSH 접근이 불가능하다.
- dev-corp Edge-Node TCP 후보 port 접근이 불가능하다.
- 필수 provider endpoint가 닫혀 있거나 `/v1/models`가 기대 모델을 노출하지 않는다.
- DGX Spark 02가 provider port down과 SSH banner exchange timeout을 동시에 보인다.
- Mac Studio vLLM-MLX node를 재시작해야 하는데 `8004` runtime의 `screen` session 또는 `DYLD_LIBRARY_PATH=/opt/homebrew/opt/expat/lib` 적용 여부를 확인할 수 없다.
- 외부 CLI profile 검증에 필요한 CLI 설치, 계정, provider 상태가 없다.

## 보고 항목

- 실행한 명령:
- 성공한 검증:
- 실패/차단된 검증:
- 생략 사유:
- 남은 위험:

## 금지 사항

- 사용자 실행 파이프라인 변경을 unit test만으로 완료 처리하지 않는다.
- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다.
- secret, token, API key 원문은 tracked 파일에 기록하지 않는다.