Field Bootstrap 작업 가이드

이 문서는 작업자/LLM이 field bootstrap 테스트를 이어갈 때 읽는 재개 가이드다. 사용자에게 그대로 전달하는 문서는 docs/field-bootstrap-user-test.md를 사용하고, 상세 runbook은 docs/deploy-dev.md를 확인한다.

핵심 규칙

Edge-Node 런타임 연결에 외부 공개가 필요한 포트는 19090 하나다.
18080은 bootstrap shell script, iop-node binary, checksum을 내려받는 artifact HTTP 포트다. Edge-Node 런타임 포트가 아니다.
현재 field 기준 bootstrap/artifact 외부 주소는 http://toki-labs.com:18080이다.
bootstrap이 사용하는 Edge runtime 주소는 toki-labs.com:19090으로 맞춘다.
Cline/OpenAI-compatible 외부 주소는 http://toki-labs.com:18081/v1이다.
사용자에게 보이는 bootstrap 명령은 완성된 URL과 token positional value 하나만 포함한다. IOP_*= named parameter를 사용자 기본 경로에 두지 않는다.
사용자에게 node.yaml 생성, 확인, 편집, iop-node serve --config ... 실행을 요구하지 않는다. bootstrap 내부 상태 파일은 구현 세부로만 취급한다.

완료 테스트 스냅샷

live version: field-live-20260527-19ddd9bd38b7
node id: node-silicon-ollama
model: gemma4:26b
edge config 후보: /tmp/iop-edge-field-bootstrap.yaml

위 값은 완료된 field 테스트의 임시 값이다. token은 테스트마다 새로 발급하고 문서값을 재사용하지 않는다.

재개 전 확인

stale process가 남아 있는지 먼저 본다.

ps -ef | rg 'python3 -m http.server 18080|go run ./apps/edge/cmd/edge|/tmp/go-build.*/edge serve|iop-edge serve'
netstat -ltnp 2>/dev/null | rg ':(18080|8080|9090)\b|Proto' || true

이전 테스트 프로세스가 남아 있으면 정리한 뒤 새 설정으로 띄운다.

권장 테스트 흐름

Apple Silicon bootstrap artifact를 만들 때 artifact URL과 edge runtime 주소를 분리한다.

VERSION=field-live-20260527-19ddd9bd38b7 \
APPS=node \
TARGETS="darwin/arm64" \
ARTIFACT_BASE_URL="http://toki-labs.com:18080" \
BOOTSTRAP_EDGE_ADDR="toki-labs.com:19090" \
DIST_DIR=dist/field \
./bin/build/field-binaries.sh

artifact HTTP가 필요하면 18080으로 연다.

python3 -m http.server 18080 --bind 0.0.0.0 -d dist/field/field-live-20260527-19ddd9bd38b7

Edge는 field config로 실행한다.

go run ./apps/edge/cmd/edge serve --config /tmp/iop-edge-field-bootstrap.yaml

기본 확인:

curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/v1/models
nc -vz toki-labs.com 19090

사용자에게 전달하는 bootstrap 명령의 URL은 artifact 전달 채널에 맞춰 작업자가 완성한다. 사용자 명령은 token 값 하나만 인자로 받는다. 사용자에게 <artifact-base-url> 같은 placeholder를 채우게 하지 않는다. bootstrap script 안의 기본 Edge runtime 주소는 19090으로 들어가야 한다.

curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s <token>

성공 기준

Node host에서 toki-labs.com:19090에 연결할 수 있다.
Edge 로그에 node registered가 나온다.
/v1/models가 gemma4:26b를 반환한다.
OpenAI-compatible 호출에서 비어 있지 않은 응답 또는 SSE delta가 나온다.

주의

field 기본 경로에서는 curl http://toki-labs.com:18080/... | bash -s <token> 형태를 사용한다.
18080을 사용할 수 없는 별도 환경에서만 내부망, front/control-plane, CI artifact, 임시 로컬 HTTP 같은 artifact 전달 채널로 바꾼다.
Cline 전용 감지나 provider별 분기는 만들지 않는다. OpenAI-compatible protocol 차원에서 안정화한다.
기본 configs/*.yaml에 field token이나 임시 host 값을 넣지 않는다.
테스트 후에는 임시 edge와 artifact server를 내려둔다.

3.9 KiB Raw Blame History