diff --git a/README.md b/README.md index 50ab915..130c771 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ Edge의 핵심 역할은 다음과 같다. - Node registry - Domain agent registry -- Node configuration +- Edge-managed Node bootstrap/configuration - Agent bootstrap/enrollment - Adapter/Profile configuration - Runtime routing diff --git a/agent-ops/rules/project/domain/testing/rules.md b/agent-ops/rules/project/domain/testing/rules.md index 894dfcb..de61181 100644 --- a/agent-ops/rules/project/domain/testing/rules.md +++ b/agent-ops/rules/project/domain/testing/rules.md @@ -8,13 +8,13 @@ last_rule_updated_at: 2026-05-27 ## 목적 / 책임 -작업 완료 후 어떤 테스트와 bin shell 사용자 흐름 검증을 거쳐야 하는지 정리한다. 테스트 파일을 바꿨는지가 아니라, 변경 작업이 어떤 사용자 실행 파이프라인에 닿았는지를 기준으로 검증 범위를 정한다. 대상 host에서 사용자가 복사해 실행하는 bootstrap/install command의 기본 UX 기준도 이 도메인에서 다룬다. +작업 완료 후 어떤 테스트와 full-cycle 실제 구동 검증을 거쳐야 하는지 정리한다. 테스트 파일을 바꿨는지가 아니라, 변경 작업이 어떤 사용자 실행 파이프라인에 닿았는지를 기준으로 검증 범위를 정한다. 대상 host에서 사용자가 복사해 실행하는 bootstrap/install command의 기본 UX 기준도 이 도메인에서 다룬다. ## 포함 경로 - `Makefile` — 공식 test target과 보조 smoke target을 선언하는 위치이다. -- `bin/edge.sh` — 사용자가 edge console/server를 실행하는 shell entrypoint이며 bin shell 사용자 흐름 검증의 기준 대상이다. -- `bin/node.sh` — 사용자가 node를 edge에 연결하는 shell entrypoint이며 bin shell 사용자 흐름 검증의 기준 대상이다. +- `bin/edge.sh` — repo 내부 edge console/server 개발 진단 helper이다. +- `bin/node.sh` — repo 내부 node 연결 개발 진단 helper이다. field 사용자 기본 경로로 안내하지 않는다. - `bin/web.sh` — 사용자가 Web Portal dev server를 실행하는 shell entrypoint이다. - `bin/build/field-binaries.sh` — field 배포용 edge/node 바이너리 build entrypoint이다. - `scripts/e2e-smoke.sh` — mock/real profile 기반 보조 edge-node smoke 검증이다. @@ -31,7 +31,7 @@ last_rule_updated_at: 2026-05-27 - 대상 패키지 테스트 — 변경한 패키지와 인접한 패키지의 빠른 회귀 검증이다. - `go test ./...` — 저장소 전체 Go 테스트 회귀 검증이다. -- bin shell 사용자 흐름 검증 — 사용자가 하듯이 `bin/edge.sh`와 `bin/node.sh`를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 도착하는지 확인하는 기준 검증이다. +- edge-node 개발 진단 흐름 검증 — `bin/edge.sh`와 `bin/node.sh`를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 도착하는지 확인하는 저수준 검증이다. field 사용자 기본 UX는 Edge가 제시한 bootstrap 명령이다. - 보조 E2E smoke — 임시 설정과 mock adapter로 최소 생존을 빠르게 확인하는 보조 검증이다. 이 결과만으로 완료 처리하지 않는다. - OpenAI-compatible Ollama smoke — `scripts/e2e-openai-ollama.sh`로 OpenAI HTTP 입력 표면이 edge service와 node adapter 경로로 수렴하는지 확인하는 보조 검증이다. - Web Portal verify — `apps/web` 변경 시 `npm run verify --prefix apps/web` 기준으로 TypeScript check와 production build를 확인한다. @@ -42,9 +42,9 @@ last_rule_updated_at: 2026-05-27 ## 유지할 패턴 - 테스트는 테스트 파일 변경 여부가 아니라 작업 영향 범위로 결정한다. -- 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 일반 Go 테스트와 `bin/edge.sh` + `bin/node.sh` 기반 bin shell 사용자 흐름을 반드시 검증한다. 보조 E2E smoke는 추가로 수행할 수 있지만 완료 기준이 아니다. +- 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 일반 Go 테스트와 변경 범위에 맞는 full-cycle 실제 구동을 검증한다. repo 내부 edge-node 진단에는 `bin/edge.sh` + `bin/node.sh`를 사용할 수 있지만, field 사용자 기본 UX는 bootstrap 명령으로 확인한다. - 사용자 실행 파이프라인에는 `bin/**`, `apps/*/cmd/**`, `apps/*/internal/bootstrap/**`, edge-node transport/service/registry/input surface, adapter 실행/stream/cancel/status 경로, `configs/**`, `packages/config/**`, `packages/hostsetup/**`, 관련 protobuf 계약 변경이 포함된다. -- bin shell 사용자 흐름 검증은 `bin/edge.sh`와 `bin/node.sh`를 별도 프로세스로 직접 실행하고, edge console prompt에 명령을 한 줄씩 입력한 뒤 기대 출력이 도착한 것을 확인하고 다음 입력으로 넘어간다. +- edge-node 개발 진단 흐름 검증은 `bin/edge.sh`와 `bin/node.sh`를 별도 프로세스로 직접 실행하고, edge console prompt에 명령을 한 줄씩 입력한 뒤 기대 출력이 도착한 것을 확인하고 다음 입력으로 넘어간다. - 메시지 검증 기준은 edge console에서 같은 session으로 메시지 2회를 보내고, 각 요청마다 `[edge] sent`, `[node-*-event] start`, 비어 있지 않은 `[node-*-message]`, `[node-*-event] complete`가 edge 화면에 표시되는 것이다. - 완료 이벤트만으로 정상 판정하지 않는다. node 로컬 출력에 생성된 `[node-message]` payload가 edge console의 `[node-*-message]` 출력에 모두 표시되어야 하며, complete event는 모든 message payload가 edge에 도착한 뒤의 마감 신호로 본다. - command 검증 기준은 edge console에서 `/nodes`와 변경 범위에 닿는 command를 직접 입력하고, node에서 온 결과가 edge 화면에 `[node-*-]` 또는 명확한 성공/unsupported/error 출력으로 표시되는 것이다. CLI 경로 변경 시 최소 `/capabilities`, `/transport`, `/sessions`, persistent profile이면 `/terminate-session`을 확인한다. @@ -54,12 +54,12 @@ last_rule_updated_at: 2026-05-27 - one-line bootstrap/install command는 Jenkins agent 연결처럼 간결해야 한다. 사용자에게 전달하는 명령은 artifact/bootstrap URL이 완성된 한 줄이어야 하며, 사용자가 직접 바꾸는 값은 token 같은 단일 positional 값만 둔다. - one-line bootstrap/install command의 Edge 주소, artifact 주소, target, platform, config path 같은 값은 작업자/Edge/Control Plane이 미리 굽거나 완성해서 제공한다. 사용자 기본 경로에서 `IOP_*=` 같은 named environment parameter나 여러 주소 조합을 직접 입력하게 하지 않는다. - field Node bootstrap의 사용자 명령은 `curl -fsSL <완성된-bootstrap-url> | bash -s ` 형태를 기준으로 한다. 다른 bootstrap/enrollment 작업에서도 같은 수준의 단일 token UX를 우선 적용하고, 예외가 필요하면 사용자에게 먼저 확인한다. -- 상세 수행 절차와 기능별 체크리스트는 `agent-ops/skills/project/e2e-smoke/SKILL.md`를 따른다. -- `make test-e2e`, `scripts/e2e-smoke.sh`, `scripts/e2e-openai-ollama.sh`는 보조 smoke 명령이다. 실행할 수 있으면 보조 확인으로 기록하되, bin shell 사용자 흐름을 대체하지 않는다. +- repo 내부 edge-node 진단의 상세 수행 절차와 기능별 체크리스트는 `agent-ops/skills/project/e2e-smoke/SKILL.md`를 따른다. +- `make test-e2e`, `scripts/e2e-smoke.sh`, `scripts/e2e-openai-ollama.sh`는 보조 smoke 명령이다. 실행할 수 있으면 보조 확인으로 기록하되, full-cycle 실제 구동이나 field bootstrap 검증을 대체하지 않는다. - `bin/build/field-binaries.sh` 변경 시 최소 현재 host target build를 실행하고 산출물 위치와 checksum 생성을 확인한다. - `bin/web.sh` 또는 `apps/web/**` 변경 시 `npm run verify --prefix apps/web`를 실행하고, dev server entrypoint 변경이면 `./bin/web.sh` 기동 가능 여부도 확인한다. - 풀테스트에서는 실제 외부 CLI profile 검증을 필수로 수행한다. 환경, 계정, provider, 원격 endpoint 문제로 호출할 수 없거나 실패한 profile은 누락하지 말고 profile별 실패 또는 blocker로 보고한다. -- 작업 최종 보고에는 실행한 테스트 명령, bin shell 사용자 흐름 수행 여부, 보조 E2E smoke 수행 여부, full-cycle 실제 구동 수행 여부를 명시한다. 수행하지 못한 필수 검증은 이유와 남은 위험을 함께 적는다. +- 작업 최종 보고에는 실행한 테스트 명령, repo 내부 edge-node 진단 수행 여부, 보조 E2E smoke 수행 여부, full-cycle 실제 구동 수행 여부를 명시한다. 수행하지 못한 필수 검증은 이유와 남은 위험을 함께 적는다. ## 기준 출력 예시 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 6c537f8..740942f 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -89,7 +89,7 @@ ## 스킬 라우팅 -- 사용자 실행 파이프라인 검증, bin shell 사용자 흐름, 메시지 2회 왕복, edge command 응답, 보조 E2E smoke, full-cycle 실제 구동, `bin/edge.sh`/`bin/node.sh` 통합 테스트: `agent-ops/skills/project/e2e-smoke/SKILL.md` +- 사용자 실행 파이프라인 검증, repo 내부 edge-node 진단, 메시지 2회 왕복, edge command 응답, 보조 E2E smoke, full-cycle 실제 구동, `bin/edge.sh`/`bin/node.sh` 진단 테스트: `agent-ops/skills/project/e2e-smoke/SKILL.md` - field 테스트 포트, artifact/bootstrap HTTP, one-line Node bootstrap, code-server compose 기반 외부 테스트 환경: `docs/deploy-dev.md`와 `docs/field-bootstrap-work-guide.md` - bootstrap/install UX, Agent Bootstrap, OTO 등록, Control Plane enrollment처럼 사용자가 대상 host에서 복사해 실행하는 명령을 설계하거나 바꿀 때: `agent-ops/rules/project/domain/testing/rules.md`의 one-line bootstrap UX 기준과 `docs/deploy-dev.md`의 field bootstrap 기준을 확인한다. - 반복 작업이 확인되면 `agent-ops/skills/project//SKILL.md`를 생성하고 이 표에 등록한다. diff --git a/agent-ops/skills/project/e2e-smoke/SKILL.md b/agent-ops/skills/project/e2e-smoke/SKILL.md index 080cdd7..2950345 100644 --- a/agent-ops/skills/project/e2e-smoke/SKILL.md +++ b/agent-ops/skills/project/e2e-smoke/SKILL.md @@ -1,14 +1,14 @@ --- name: e2e-smoke version: 1.1.0 -description: bin/edge.sh와 bin/node.sh 기반 bin shell 사용자 흐름 검증, 보조 E2E smoke, 실제 외부 CLI 통합 검증 절차 +description: bin/edge.sh와 bin/node.sh 기반 repo 내부 edge-node 진단, 보조 E2E smoke, 실제 외부 CLI 통합 검증 절차 --- # e2e-smoke ## 목적 -사용자가 실제로 테스트하는 방식에 맞춰 `bin/edge.sh`와 `bin/node.sh`를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 표시되는지 검증한다. `make test-e2e`와 `scripts/e2e-smoke.sh`는 최소 생존을 빠르게 확인하는 보조 smoke일 뿐이며, 사용자 실행 파이프라인 변경의 완료 기준이 아니다. +repo 내부 edge-node 진단이 필요할 때 `bin/edge.sh`와 `bin/node.sh`를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 표시되는지 검증한다. field 사용자 기본 UX는 Edge가 제시한 bootstrap 명령이며, `bin/*` helper를 공식 사용자 경로로 안내하지 않는다. `make test-e2e`와 `scripts/e2e-smoke.sh`는 최소 생존을 빠르게 확인하는 보조 smoke일 뿐이며, 사용자 실행 파이프라인 변경의 완료 기준이 아니다. ## 언제 호출할지 @@ -20,14 +20,14 @@ description: bin/edge.sh와 bin/node.sh 기반 bin shell 사용자 흐름 검증 ## 입력 - `scope`: 검증할 변경 범위와 영향을 받은 도메인 (필수) -- `mode`: `bin-user-flow`, `mock-smoke`, `real-cli`, `full-cycle`, `all` 중 하나 (선택, 기본값: `bin-user-flow`) +- `mode`: `bin-diagnostic`, `mock-smoke`, `real-cli`, `full-cycle`, `all` 중 하나 (선택, 기본값: `bin-diagnostic`) - `profiles`: 검증할 실제 외부 CLI profile 목록. 지정하지 않으면 기준 profile인 `claude`, `antigravity`, `codex`, `opencode`를 대상으로 한다. (선택) - `config_strategy`: 임시 config 파일 또는 환경 변수 override 방식 (선택) ## 먼저 확인할 것 -- [ ] `agent-ops/rules/project/domain/testing/rules.md`를 읽고 이번 작업이 필수 bin shell 사용자 흐름 검증 대상인지 확인한다. -- [ ] `bin/edge.sh`와 `bin/node.sh`가 현재 사용자 실행 entrypoint인지 확인한다. +- [ ] `agent-ops/rules/project/domain/testing/rules.md`를 읽고 이번 작업에 필요한 repo 내부 edge-node 진단 또는 field bootstrap 검증 범위를 확인한다. +- [ ] `bin/edge.sh`와 `bin/node.sh`는 repo 내부 진단 helper이며 field 사용자 기본 entrypoint가 아님을 확인한다. - [ ] `make test-e2e` 같은 고정 smoke 명령은 보조 확인으로만 취급한다. - [ ] 기본 `configs/*.yaml`을 오염시키지 않도록 임시 config 또는 환경 변수 override 전략을 정한다. - [ ] 실제 외부 CLI 검증이 필요한 경우 command 경로, 로그인/계정 상태, provider 설정, workspace 권한이 준비되어 있는지 확인한다. @@ -36,12 +36,12 @@ description: bin/edge.sh와 bin/node.sh 기반 bin shell 사용자 흐름 검증 1. **검증 범위 결정** - 변경 파일이 사용자 실행 파이프라인에 닿는지 확인한다. - - 필수 검증은 `go test ./...` 또는 대상 패키지 테스트와 bin shell 사용자 흐름 검증이다. + - 필수 검증은 `go test ./...` 또는 대상 패키지 테스트와 변경 범위에 맞는 full-cycle 실제 구동이다. repo 내부 edge-node 진단에는 `bin/edge.sh`와 `bin/node.sh`를 사용할 수 있다. - 보조 smoke는 실행할 수 있으면 기록하되, 통과만으로 완료 처리하지 않는다. - 풀테스트에서는 실제 외부 CLI profile 검증을 full-cycle에 포함한다. -2. **bin shell 사용자 흐름 준비** - - edge와 node는 `bin/edge.sh`, `bin/node.sh`를 각각 별도 프로세스로 실행한다. +2. **repo 내부 edge-node 진단 준비** + - edge와 node는 `bin/edge.sh`, `bin/node.sh`를 각각 별도 프로세스로 실행한다. 이 흐름은 내부 진단용이며 사용자-facing field bootstrap 안내가 아니다. - 임시 edge/node config 또는 환경 변수 override를 사용하고, edge listen 주소와 node edge 주소는 충돌을 피하기 위해 임시 포트를 사용한다. - 검증용 target은 변경 범위에 맞춘다. 외부 CLI 자체가 검증 대상이 아니면 deterministic CLI profile을 사용해 메시지 출력 내용을 분명하게 만든다. @@ -114,7 +114,7 @@ terminated session default node=test-node 7. **보조 E2E smoke** - `make test-e2e` 또는 `scripts/e2e-smoke.sh`는 보조 확인으로 실행할 수 있다. - 보조 smoke에서는 mock adapter와 임시 설정/포트를 사용해 외부 CLI 의존성 없이 최소 생존을 확인한다. - - 보조 smoke 통과를 bin shell 사용자 흐름 통과로 대체해 보고하지 않는다. + - 보조 smoke 통과를 repo 내부 edge-node 진단 또는 field bootstrap 검증 통과로 대체해 보고하지 않는다. 8. **CLI profile 실제 구동 검증** - 풀테스트에서는 기준 실제 외부 CLI profile을 한 번씩 실제 구동한다. @@ -124,7 +124,7 @@ terminated session default node=test-node 9. **결과 보고** - 실행한 Go 테스트 명령과 결과를 적는다. - - bin shell 사용자 흐름에서 사용한 config 전략, 메시지 2회 결과, command 응답 결과를 적는다. + - repo 내부 edge-node 진단에서 사용한 config 전략, 메시지 2회 결과, command 응답 결과를 적는다. - 보조 smoke를 실행했다면 별도 항목으로만 적는다. - full-cycle에서 돌린 cycle 목록과 돌리지 못한 cycle 목록을 구분해 적는다. - 필수 검증을 실행하지 못했다면 이유와 남은 위험을 명시한다. @@ -132,12 +132,12 @@ terminated session default node=test-node ## 실행 결과 검증 - [ ] 일반 Go 테스트 또는 대상 패키지 테스트 결과가 보고되었는가 -- [ ] `bin/edge.sh`와 `bin/node.sh`를 각각 실행한 bin shell 사용자 흐름 결과가 보고되었는가 +- [ ] `bin/edge.sh`와 `bin/node.sh`를 각각 실행한 repo 내부 edge-node 진단 결과가 보고되었는가 - [ ] node register와 `/nodes` 결과가 edge 화면에 표시되었는가 - [ ] 같은 session에서 메시지 2회가 각각 sent/start/message/complete로 표시되었는가 - [ ] node 로컬 `[node-message]` payload가 edge `[node-*-message]` 출력에 모두 표시되었는가 - [ ] `/capabilities`, `/transport`, `/sessions`, 관련 command 결과가 edge 화면에 표시되었는가 -- [ ] 보조 smoke를 실행했다면 bin shell 사용자 흐름과 구분해 보고했는가 +- [ ] 보조 smoke를 실행했다면 repo 내부 edge-node 진단 또는 field bootstrap 검증과 구분해 보고했는가 - [ ] 풀테스트에서 실제 외부 CLI profile별 메시지 왕복과 `/status` 결과가 보고되었는가 - 검증 실패 시: 실패한 항목, 관련 로그/출력 요약, 남은 위험을 최종 보고에 포함한다. @@ -146,7 +146,7 @@ terminated session default node=test-node ```text 검증 결과 - Go 테스트: <명령> - <통과|실패|미실행 사유> -- Bin shell 사용자 흐름: <통과|실패|미실행 사유> +- Repo 내부 edge-node 진단: <통과|실패|미실행 사유> - 메시지 왕복: message x2 - <통과|실패|미실행 사유> - Node message relay: node local payload == edge rendered payload - <통과|실패|미실행 사유> - Edge command 응답: /nodes, /capabilities, /transport, /sessions, <관련 command> - <통과|실패|미실행 사유> @@ -160,7 +160,7 @@ terminated session default node=test-node - 사용자 실행 파이프라인에 닿는 변경을 하고 유닛/패키지 테스트만으로 완료 처리하지 않는다. - `make test-e2e`, `scripts/e2e-smoke.sh`, 또는 smoke 통과 출력만으로 완료 처리하지 않는다. -- 관련 작업 후 bin shell 사용자 흐름을 비용이 크다는 이유만으로 생략하지 않는다. +- 관련 작업 후 필요한 full-cycle 실제 구동 또는 repo 내부 edge-node 진단을 비용이 크다는 이유만으로 생략하지 않는다. - 보조 E2E smoke를 외부 CLI 설치, 로그인, 네트워크 계정 상태에 의존하게 만들지 않는다. - 검증을 위해 기본 `configs/*.yaml`을 임시값으로 오염시키지 않는다. - 필수 검증을 실행하지 못했는데 조용히 생략하지 않는다. diff --git a/agent-roadmap/archive/phase/edge-node-execution-foundation/milestones/edge-node-execution-skeleton.md b/agent-roadmap/archive/phase/edge-node-execution-foundation/milestones/edge-node-execution-skeleton.md index 56cf204..53fdfa7 100644 --- a/agent-roadmap/archive/phase/edge-node-execution-foundation/milestones/edge-node-execution-skeleton.md +++ b/agent-roadmap/archive/phase/edge-node-execution-foundation/milestones/edge-node-execution-skeleton.md @@ -30,7 +30,7 @@ Edge-Node 실행 기반 - Node adapter registry와 `adapter + target` 실행 라우팅 - `RunRequest`, `RunEvent`, `CancelRequest`, `NodeCommandRequest`, `NodeCommandResponse` 경로 - CLI adapter 기반 one-shot/persistent session 실행 검증 -- edge-local ops console과 `bin/edge.sh`, `bin/node.sh` 기반 field smoke +- edge-local ops console과 당시 repo 내부 `bin/edge.sh`, `bin/node.sh` 기반 field smoke ## 필수 기능 @@ -43,7 +43,7 @@ Edge-Node 실행 기반 ## 완료 기준 -- [x] `bin/edge.sh`와 `bin/node.sh`를 각각 실행해 node 등록을 확인할 수 있다. +- [x] 당시 repo 내부 `bin/edge.sh`와 `bin/node.sh` 진단 흐름으로 node 등록을 확인할 수 있다. - [x] Edge console에서 두 번의 메시지 실행이 각각 start, non-empty message/delta, complete event를 표시한다. - [x] `/capabilities`, `/transport`, `/sessions` 명령이 node 응답을 표시한다. - [x] persistent profile에서 run cancel과 session terminate의 의미가 구분된다. diff --git a/agent-roadmap/archive/phase/serving-routing-optimization/milestones/field-bootstrap-test-port-readiness.md b/agent-roadmap/archive/phase/serving-routing-optimization/milestones/field-bootstrap-test-port-readiness.md index d87e726..f6e21b5 100644 --- a/agent-roadmap/archive/phase/serving-routing-optimization/milestones/field-bootstrap-test-port-readiness.md +++ b/agent-roadmap/archive/phase/serving-routing-optimization/milestones/field-bootstrap-test-port-readiness.md @@ -85,10 +85,10 @@ field 테스트를 매번 수동 터널과 임시 명령 조합으로 만들지 ## 아카이브 후 참고 메모 - 사용자 정정 사항: Edge-Node 실사용 연결에 외부 공개가 필요한 포트는 `19090` 하나다. `18080`은 bootstrap shell script, `iop-node` binary, checksum을 내려받는 artifact HTTP 포트일 뿐이며 Edge-Node 런타임 포트가 아니다. -- 최종 방향: 외부 bootstrap/artifact 접근은 `toki-labs.com:18080`을 기준으로 유지한다. 생성되는 `node.yaml`의 `transport.edge_addr`만 `toki-labs.com:19090`이 되게 한다. +- 최종 방향: 외부 bootstrap/artifact 접근은 `toki-labs.com:18080`을 기준으로 유지한다. Node 사용자는 별도 설정 파일을 만들거나 관리하지 않고, bootstrap 내부에서 `toki-labs.com:19090`으로 연결되게 한다. - 다음 테스트에서는 `curl http://toki-labs.com:18080/... | bash -s ` 형태로 bootstrap을 받고, script 기본값으로 `toki-labs.com:19090`을 굽는다. - 사용자용 명령은 반드시 artifact URL이 완성된 `curl -fsSL <완성된-bootstrap-url> | bash -s ` 형태로 제공한다. 사용자가 직접 넣는 값은 token 하나뿐이며 `IOP_ARTIFACT_BASE_URL=...`, `IOP_EDGE_ADDR=...`, `IOP_NODE_TOKEN=...` 같은 named parameter를 요구하지 않는다. - 완료 테스트 스냅샷: live artifact version은 `field-live-20260527-19ddd9bd38b7`, node id는 `node-silicon-ollama`, model은 `gemma4:26b`였다. 테스트 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'`. 필요하면 임시 edge/artifact server를 정리하고 새 설정으로 다시 띄운다. -- 권장 재테스트 형태: `ARTIFACT_BASE_URL=http://toki-labs.com:18080`, `BOOTSTRAP_EDGE_ADDR=toki-labs.com:19090`으로 Apple Silicon bootstrap을 생성한다. 사용자에게 주는 실행 명령은 `curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s ` 형태로 제공하고, token은 명령 마지막 positional value 하나로만 받는다. +- 권장 재테스트 형태: 작업자 내부 빌드 설정에서 artifact 주소는 `http://toki-labs.com:18080`, Edge runtime 주소는 `toki-labs.com:19090`으로 굽는다. 사용자에게 주는 실행 명령은 `curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s ` 형태로 제공하고, token은 명령 마지막 positional value 하나로만 받는다. - 작업 가이드 문서: `docs/field-bootstrap-work-guide.md` diff --git a/agent-roadmap/archive/phase/serving-routing-optimization/milestones/model-serving-load-routing.md b/agent-roadmap/archive/phase/serving-routing-optimization/milestones/model-serving-load-routing.md index 528e111..c71b929 100644 --- a/agent-roadmap/archive/phase/serving-routing-optimization/milestones/model-serving-load-routing.md +++ b/agent-roadmap/archive/phase/serving-routing-optimization/milestones/model-serving-load-routing.md @@ -28,7 +28,7 @@ Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소 - Ollama `message.thinking`은 기본적으로 숨기거나 `think:false`로 끄지 않고, OpenWebUI류 UX처럼 thinking 중임을 알 수 있는 별도 reasoning stream으로 보존한다. - Ollama 관련 조회/상태/관리 command를 IOP OpenAI-compatible 표면에서 어디까지 pass-through할지에 대한 1차 기준과 unsupported 응답 정책 - 여러 Node와 여러 model은 자동 라우팅이 아니라 `openai.node`, `openai.models`, 요청 `model`, `openai.target` 조합을 수동으로 바꿔 검증한다. -- `bin/edge.sh`와 `bin/node.sh`를 실제로 연결해 사용자가 직접 재현 가능한 필드 테스트 환경을 문서화한다. +- 당시 repo 내부 `bin/edge.sh`와 `bin/node.sh` 진단 흐름으로 필드 테스트 환경을 문서화한다. - IOP native protocol, A2A, routing 최적화 계층과 OpenAI-compatible 서빙 표면의 책임 경계를 충돌 없이 정리한다. ## 필수 기능 @@ -52,7 +52,7 @@ Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소 - [x] [think-control] `think:false`는 기본값이 아니라 명시 옵션 또는 후속 client별 제어로만 다루며, 기본 UX는 thinking 보존으로 둔다. - [x] [ollama-command-pass-through] Ollama 관련 모델 조회, 상태, 관리 command를 Edge OpenAI-compatible 표면에서 어디까지 pass-through할지 1차 범위가 정의되어 있다. - [x] [openai-ollama-aux-smoke] fake Ollama 기반 보조 smoke가 OpenAI-compatible 입력 표면과 edge-node relay의 최소 생존을 확인한다. -- [x] [toki-labs-field-flow] 공통 필드 테스트 환경에서 `toki-labs` Ollama `gemma4:26b` 모델을 사용해 사용자가 직접 재현 가능한 bin edge-node 흐름이 문서화되고 검증된다. +- [x] [toki-labs-field-flow] 공통 필드 테스트 환경에서 `toki-labs` Ollama `gemma4:26b` 모델을 사용해 당시 repo 내부 bin edge-node 진단 흐름이 문서화되고 검증된다. ### Epic: [protocol-boundary] Protocol Boundary @@ -67,9 +67,9 @@ Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소 - [x] 외부 agent/client가 Edge endpoint를 일반 OpenAI-compatible 또는 Ollama-backed endpoint처럼 설정해 한 차례 모델 조회와 chat completion을 완료할 수 있다. - [x] streaming/non-streaming 응답, thinking/reasoning passthrough, model-to-target 매핑, 1차 option pass-through, unsupported option 응답 정책이 검증되어 있다. - [x] `gemma4:26b`처럼 thinking을 먼저 내보내는 모델에서도 사용자는 thinking 중임을 볼 수 있고, content가 시작되면 답변 stream을 자연스럽게 받을 수 있다. -- [x] `bin/edge.sh`와 `bin/node.sh`를 실제로 연결해 Edge -> Node -> Ollama 흐름을 재현할 수 있다. -- [x] 최종 완료 검증은 fake Ollama smoke가 아니라 사용자가 직접 테스트하는 방식과 같은 `toki-labs` 실제 Ollama 필드 흐름으로 수행된다. -- [x] 공통 필드 테스트 환경의 Node host, Ollama endpoint, model, edge/node 임시 config 기준이 문서화되어 있다. +- [x] 당시 repo 내부 `bin/edge.sh`와 `bin/node.sh` 진단 흐름으로 Edge -> Node -> Ollama 흐름을 재현할 수 있다. +- [x] 최종 완료 검증은 fake Ollama smoke가 아니라 `toki-labs` 실제 Ollama 필드 흐름으로 수행된다. +- [x] 공통 필드 테스트 환경의 Node host, Ollama endpoint, model, 당시 내부 진단 config 기준이 문서화되어 있다. - [x] Node/model 선택은 수동 설정으로 검증하고, 자동 라우팅과 부하 라우팅은 후속 작업으로 분리되어 있다. - [x] 외부 API 표면과 IOP native protocol의 역할이 충돌하지 않는다. - [x] 다음 단계인 model routing/fallback 최적화로 넘어갈 선행 조건이 정의된다. @@ -106,7 +106,7 @@ Edge에 OpenAI API 방식으로 접속한 외부 agent/client가 Edge-Node 소 - 표준선(선택): `think:false`는 테스트 우회 기본값으로 쓰지 않고, 명시 요청 또는 후속 설정 항목으로만 고려한다. - 진행 근거(2026-05-25): `b7d636c`에서 `EventTypeReasoningDelta`, Ollama `message.thinking` 분리 event, OpenAI-compatible `reasoning_content` streaming/non-streaming 응답, fake Ollama smoke의 reasoning 검증이 반영되어 있다. - 검증 근거(2026-05-25): `go test ./apps/edge/internal/openai ./apps/node/internal/adapters/ollama`, `scripts/e2e-openai-ollama.sh` 통과. -- 검증 근거(2026-05-25): 임시 Edge/Node config로 `bin/edge.sh`와 `bin/node.sh`를 실제 실행하고 `http://192.168.0.97:11434`의 `gemma4:26b`를 호출했다. `/v1/models`는 `gemma4:26b`를 반환했고, non-streaming 응답 content는 `IOP_OLLAMA_E2E_OK`, reasoning 길이는 681 bytes였다. streaming SSE는 content delta를 이어 붙였을 때 `IOP_OLLAMA_STREAM_OK`, reasoning 길이는 695 bytes였고 `data: [DONE]`을 확인했다. +- 검증 근거(2026-05-25): 당시 임시 Edge/Node config와 repo 내부 `bin/edge.sh`, `bin/node.sh` 진단 흐름으로 `http://192.168.0.97:11434`의 `gemma4:26b`를 호출했다. `/v1/models`는 `gemma4:26b`를 반환했고, non-streaming 응답 content는 `IOP_OLLAMA_E2E_OK`, reasoning 길이는 681 bytes였다. streaming SSE는 content delta를 이어 붙였을 때 `IOP_OLLAMA_STREAM_OK`, reasoning 길이는 695 bytes였고 `data: [DONE]`을 확인했다. - 검증 메모(2026-05-25): `ssh toki@toki-labs.com` 원격 host는 접근 가능하지만 확인한 기본 경로에는 repo가 없고 `go`도 PATH에 없어, 이번 검증은 로컬 임시 Node가 실제 Ollama endpoint를 호출하는 방식으로 수행했다. - 정책 확정(2026-05-25): OpenAI generation option과 Ollama 관련 command pass-through는 IOP가 별도 의미를 재정의하지 않고 Ollama가 지원하는 형식을 그대로 전달/노출하는 것을 기준으로 한다. - 선행 조건 확정(2026-05-25): routing/fallback 최적화의 route test는 초기에는 하드코딩한다. 모든 에러는 fallback raising 조건이며, 에러 분류는 관측/정책 판단을 위한 구분일 뿐 fallback 트리거 자체를 막지 않는다. diff --git a/apps/edge/README.md b/apps/edge/README.md index e2cc17a..7f0cc30 100644 --- a/apps/edge/README.md +++ b/apps/edge/README.md @@ -26,38 +26,18 @@ ops console은 edge-local diagnostic surface이고, HTTP/API는 central/remote m `internal/events.Bus`는 Edge 안의 in-process fanout과 bounded replay를 담당한다. 현재 replay는 늦게 붙은 console/API handler를 위한 최근 이벤트 버퍼이지 durable history가 아니며, Node local SQLite 실행 이력과 다른 책임이다. 전역 이력 저장, audit, query API는 후속 Control Plane/Portal 경계에서 별도 설계한다. -## 원격 CLI adapter bin shell 사용자 흐름 검증 +## 원격 CLI adapter 개발 진단 흐름 -사용자 실행 파이프라인 검증의 기준은 `make test-e2e`나 smoke 통과가 아니라, 사람이 하듯이 `bin/edge.sh`와 `bin/node.sh`를 각각 실행하고 edge console에서 메시지와 command를 직접 보내 결과가 edge 화면에 표시되는지 확인하는 것이다. +field 사용자 기본 경로는 `iop-edge`가 제시한 bootstrap 명령으로 Node를 연결하는 흐름이다. `bin/edge.sh`와 `bin/node.sh`는 repo 내부 개발 진단 helper이며 공식 사용자 UX로 안내하지 않는다. +개발 진단의 기준은 `make test-e2e`나 smoke 통과만이 아니라, edge console에서 메시지와 command를 직접 보내 결과가 edge 화면에 표시되는지 확인하는 것이다. +구체적인 내부 진단 절차는 `agent-ops/skills/project/e2e-smoke/SKILL.md`로 모은다. `make test-e2e` 명령은 `scripts/e2e-smoke.sh`를 실행하는 보조 smoke이며, 최소 생존 확인에는 쓸 수 있지만 완료 기준을 대체하지 않는다. 실제 외부 프로필(예: `antigravity`)을 보조 smoke로 테스트하려면 `IOP_E2E_PROFILE=antigravity make test-e2e`와 같이 환경 변수를 지정한다. -수동으로 실행하려면 아래 과정을 따른다. - -`bin/edge.sh`는 edge 서버를 열고 입력 프롬프트를 제공한다. -`bin/node.sh`는 원격 edge 주소로 접속해 등록한 뒤, edge에서 보낸 `RunRequest`를 `adapter + target` 실행으로 처리한다. -테스트 파라미터는 `configs/edge.yaml`, `configs/node.yaml`에 하드코딩한다. - **전제 조건**: `configs/edge.yaml`의 `console.target`이 가리키는 CLI profile command가 node 호스트에서 실행 가능해야 한다. 기본 예시는 `opencode`이며, `claude`, `claude-tui`, `antigravity`, `codex`, `cline-dgx` 등으로 바꿀 수 있다. 같은 `cli` 어댑터 안에 `claude`, `claude-tui`, `antigravity`, `codex`, `opencode`, `cline` profile을 포함할 수 있다. 예를 들어 `claude`는 `claude -p` 기반 one-shot profile로 두고, `claude-tui`는 `persistent: true`, `terminal: true`, `mode: "persistent-lazy"`로 첫 요청 시 일반 Claude Code TUI 세션을 띄운다. `antigravity`는 `mode: "antigravity-print"`로 `agy --dangerously-skip-permissions --print `를 실행하고, 같은 IOP session의 다음 요청은 `agy --conversation --print ` 형태로 이어간다. `codex exec --dangerously-bypass-approvals-and-sandbox`, `cline -y --json --config /config/.cline/profiles/ollama-dgx `처럼 다른 headless 조합도 설정할 수 있다. `opencode`는 `mode: "opencode-sse"` profile로 `opencode serve`의 HTTP/SSE 인터페이스를 사용하며, args의 `--model`, `--dangerously-skip-permissions`, `--title` 등은 그대로 유지하면 된다. -실행 순서: - -1. edge 호스트에서 `configs/edge.yaml`의 `server.listen`, `nodes[].token`을 확인한다. 예시 설정은 `console.adapter=cli`, `console.target=opencode`, `console.session_id=default`를 사용한다. -2. node 호스트에서 `configs/node.yaml`의 `transport.edge_addr`를 edge 호스트 주소로, `transport.token`을 edge token과 같게 맞춘다. -3. edge 호스트의 `9090/tcp` 포트를 node 호스트에서 접근 가능하게 연다. -4. edge 호스트에서 `./bin/edge.sh` -5. node 호스트에서 `./bin/node.sh` — edge 포트가 열릴 때까지 최대 30초 기다린 뒤, edge에서 받은 입력을 선택된 `adapter + target`으로 실행한다. -6. edge 콘솔에서 `/nodes`로 node 등록을 확인한다. -7. (선택 사항) node가 여러 대일 경우 `/node `로 대상을 선택한다. 1대일 경우 자동 선택된다. -8. edge 콘솔의 `edge>` 프롬프트에 메시지를 입력한다. -9. 각 메시지마다 `[edge] sent`, `[node{index}-evt] start`, 비어 있지 않은 `[node{index}-msg]`, `[node{index}-evt] complete`가 edge 화면에 표시되는지 확인한다. -10. node 로컬 출력에 생성된 `[node-message]` payload가 edge console의 `[node{index}-msg]` 출력에 모두 표시되었는지 확인한다. complete event만으로 정상 판정하지 않는다. -11. 같은 session에서 두 번째 메시지를 보내 같은 흐름이 다시 표시되는지 확인한다. -12. edge 콘솔에서 `/capabilities`, `/transport`, `/sessions` 등 command를 입력하고 `[node-{alias}-]` 결과가 edge 화면에 도착하는지 확인한다. persistent profile이면 `/terminate-session`도 확인한다. -13. edge 콘솔에서 `/exit` 또는 `quit`로 종료한다. - 기준 출력 예시: ```text @@ -156,8 +136,6 @@ edge-node transport 연결은 **node id당 1개** TCP 연결만 유지한다. 프롬프트 없이 TCP/protobuf edge 서버만 실행하려면 기존처럼 `go run ./apps/edge/cmd/edge serve -c configs/edge.yaml`를 사용한다. -`bin/node.sh`의 edge 대기 시간은 `IOP_NODE_WAIT_TIMEOUT`, 확인 간격은 `IOP_NODE_WAIT_INTERVAL`, 접속 주소는 `IOP_EDGE_ADDR` 환경 변수로 임시 override할 수 있다. - ## Edge Input Surfaces Edge 외부 입력은 OpenAI-compatible HTTP API와 A2A JSON-RPC HTTP API 두 방식으로 정리한다. 둘 다 Edge에서 받은 외부 요청을 내부 `adapter + target` 실행으로 변환하고, 실제 실행은 `apps/edge/internal/service`와 edge-node transport를 통해 처리한다. diff --git a/apps/node/README.md b/apps/node/README.md index e19d11d..3305512 100644 --- a/apps/node/README.md +++ b/apps/node/README.md @@ -21,7 +21,12 @@ internal/ store/ — SQLite 실행 이력 ``` -## 실행 +## 실행 경계 + +field 사용자 기본 경로에서 Node는 별도 설정 파일을 만들거나 편집하지 않는다. +Edge가 제시한 bootstrap 명령 한 줄을 실행하면 Node binary 다운로드, 검증, Edge 연결, foreground 실행까지 이어져야 한다. + +아래 명령은 Node binary 자체의 저수준 개발/진단용 표면이다. 사용자-facing field bootstrap 안내로 쓰지 않는다. ```bash # 빌드 @@ -30,58 +35,22 @@ go build -o bin/node ./apps/node/cmd/node # 버전 확인 ./bin/node version -# 설정 파일 로드 검증 -./bin/node config check --config configs/node.yaml - -# 설정 확인 -./bin/node config print --config configs/node.yaml - -# 서버 실행 -./bin/node serve --config configs/node.yaml +# 저수준 직접 실행은 내부 진단에서만 사용한다. ``` -## 호스트 환경 준비 (setup) +## 호스트 환경 준비 참고 -운영 설치 공식 경로는 `setup` 명령으로 일원화한다. - -```bash -sudo iop-node setup --enable --start -``` - -배포 전에 결과를 검토하려면 `--dry-run`을 쓴다. - -```bash -sudo iop-node setup --dry-run --binary /usr/local/bin/iop-node -``` - -`setup`은 다음을 담당한다. - -- 실행 user/group(`iop`) 준비 -- `/etc/iop`와 `/var/lib/iop/node` 디렉터리 준비 -- 설정 파일이 없을 때만 기본 템플릿 생성 (`--overwrite-config`로 강제 갱신) -- systemd unit 생성 또는 갱신 (`/etc/systemd/system/iop-node.service`) -- `systemctl daemon-reload` -- 옵션에 따른 `--enable`, `--start`, `--restart` - -`setup`의 `--config` 기본값은 `/etc/iop/node.yaml`이다. 개발용 명령(`serve`, `config print/check`)의 root persistent `--config` 기본값(`configs/node.yaml`)과는 다르다. +`setup`은 현재 구현된 host setup 보조 기능이다. field 사용자 기본 경로는 Node setup/config가 아니라 Edge가 제시한 bootstrap 명령이다. +새 사용자-facing 흐름을 설계할 때 이 표면을 기본 경로로 확장하지 않는다. 현재 구현된 node CLI 표면은 다음과 같다. ```text iop-node serve -iop-node setup -iop-node config print -iop-node config check iop-node version ``` -원격 edge에 붙는 수동 테스트는 `configs/node.yaml`의 `transport.edge_addr`와 `transport.token`을 먼저 맞춘 뒤 repo root에서 실행한다. - -```bash -./bin/node.sh -``` - -`bin/node.sh`는 `configs/node.yaml`의 `transport.edge_addr` 포트가 열릴 때까지 최대 30초 기다린 뒤 node를 시작한다. 테스트 중 edge 주소만 임시로 바꾸려면 `IOP_EDGE_ADDR=host:port ./bin/node.sh`를 사용할 수 있다. +원격 edge에 붙는 사용자/field 테스트는 Edge가 제시한 bootstrap 명령을 실행한다. repo root의 `bin/node.sh`는 과거 개발 진단 helper로만 취급하고, 문서나 runbook의 공식 사용자 경로로 안내하지 않는다. edge 예시 설정은 cli adapter의 `opencode` profile을 사용한다. `configs/edge.yaml`의 `console.target`을 `claude`, `claude-tui`, `antigravity`, `codex`, `opencode`, `cline-dgx` 같은 profile 이름으로 바꾸면 같은 실행 파이프라인에서 다른 CLI target을 검증할 수 있다. diff --git a/docs/architecture.md b/docs/architecture.md index b949a0f..1d05c67 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -142,7 +142,7 @@ Edge bootstrap UX는 Jenkins node 연결 방식과 유사하게 둔다. Edge에 Remote terminal bridge UX는 bootstrap과 분리한다. 대상에 agent를 설치할 수 있으면 bootstrap/enrollment를 우선하고, 설치가 어렵거나 일회성 유지보수 대상이면 Edge가 사전에 허용된 Node terminal profile을 통해 대상 terminal을 연다. 이 기능은 target allowlist, credential 관리, timeout, 동시 실행 제한, session audit를 전제로 한다. -운영 CLI는 분기된 설치 방식을 만들지 않는다. 공식 경로는 `iop-edge setup`과 `iop-node setup` 하나로 고정하고, 검토나 CI 확인은 별도 `render` 명령이 아니라 `--dry-run` 옵션으로 흡수한다. +운영 CLI는 분기된 설치 방식을 만들지 않는다. Edge 운영 표면은 `iop-edge` command에 모으고, Node 사용자 연결은 Edge가 제시한 bootstrap 명령 하나로 끝나게 한다. 검토나 CI 확인은 별도 `render` 명령이 아니라 `--dry-run` 옵션으로 흡수한다. ```text build: @@ -156,8 +156,8 @@ edge host: systemd -> iop-edge serve --config /etc/iop/edge.yaml node host: - iop-node setup -> systemd unit + config/data directories [구현 완료] - systemd -> iop-node serve --config /etc/iop/node.yaml + edge bootstrap command -> iop-node binary + runtime state + foreground/system service -> bootstrap-managed node execution oto build host: edge bootstrap command -> oto binary + agent config/service diff --git a/docs/deploy-dev.md b/docs/deploy-dev.md index b3613b3..74fb986 100644 --- a/docs/deploy-dev.md +++ b/docs/deploy-dev.md @@ -108,12 +108,6 @@ dev 초기 단계에서는 repo의 `configs/edge.yaml`을 기준으로 포트와 사용자/field 기본 경로에서 Node는 직접 설정 파일을 만들거나 `iop-node serve --config ...`로 실행하지 않는다. Edge가 제시한 bootstrap 명령을 대상 host에서 실행하면 다운로드, 검증, 연결, 실행까지 이어져야 한다. -repo root에서 수동으로 검증할 때는 기존 helper를 사용할 수 있다. - -```bash -IOP_EDGE_ADDR=:9090 ./bin/node.sh -``` - ## Field 테스트 환경 라우팅 field 테스트의 1차 기준 환경은 `ssh toki@toki-labs.com`의 code-server 컨테이너다. @@ -413,7 +407,7 @@ Mac의 foreground Node process는 `Ctrl-C`로 종료한다. OpenAI-compatible Ollama E2E 서빙 검증은 아래 필드 환경을 공통 기준으로 사용한다. 이 환경은 특정 마일스톤에만 두지 않고, 이후 모델 서빙, routing, fallback, client 통합 검증에서도 재사용한다. `scripts/e2e-openai-ollama.sh` 같은 fake Ollama smoke는 보조 확인이다. -완료 판정은 사용자가 직접 테스트하는 방식과 동일하게 `bin/edge.sh`, `bin/node.sh`, 실제 Ollama endpoint를 연결한 full-cycle 흐름으로 한다. +완료 판정은 `iop-edge` 실행, Edge가 제시한 Node bootstrap 명령, 실제 Ollama endpoint를 연결한 full-cycle 흐름으로 한다. `gemma4:26b`는 thinking을 먼저 stream할 수 있으므로, 기본 검증은 `think:false`로 우회하지 않는다. Edge 응답에서 thinking/reasoning stream과 최종 content stream이 분리되어 보이는지 확인한다. @@ -471,32 +465,17 @@ nodes: edge 실행: ```bash -IOP_EDGE_CONFIG=/tmp/iop-edge-toki-labs.yaml ./bin/edge.sh +iop-edge serve --config /tmp/iop-edge-toki-labs.yaml ``` -node host에 접속한 뒤 node 임시 config를 만든다. +node host에서는 별도 Node config를 만들지 않는다. Edge가 제시한 bootstrap 명령만 실행한다. ```bash ssh toki@toki-labs.com ``` -```yaml -transport: - edge_addr: ":9090" - token: "CHANGE_ME_FIELD_TOKEN" - -logging: - level: "info" - pretty: true - -metrics: - port: 9091 -``` - -node 실행: - ```bash -IOP_NODE_CONFIG=/tmp/iop-node-toki-labs.yaml ./bin/node.sh +curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s CHANGE_ME_FIELD_TOKEN ``` edge host에서 OpenAI-compatible API를 호출해 검증한다. @@ -589,42 +568,8 @@ iop-edge version `setup`은 여러 번 실행해도 같은 결과로 수렴한다. 기존 설정 파일은 기본적으로 덮어쓰지 않고, 강제 갱신이 필요하면 `--overwrite-config`를 지정한다. -## Node setup CLI +## Node host setup note -Node setup CLI는 현재 구현된 host setup 보조 기능이다. field 사용자 기본 경로는 Node setup/config가 아니라 Edge가 제시한 bootstrap 명령이다. -Control Plane 없는 개발 단계에서도 Node별 실행 설정은 Edge config의 `nodes[]`에서 관리한다. - -```bash -sudo iop-node setup --enable --start -``` - -배포 전에 결과를 검토하려면 `--dry-run`을 쓴다. - -```bash -sudo iop-node setup --dry-run --binary /usr/local/bin/iop-node -``` - -`setup`은 다음을 담당한다. - -- 실행 user/group(`iop`) 준비 -- `/etc/iop`와 `/var/lib/iop/node` 디렉터리 준비 -- 설정 파일이 없을 때만 기본 템플릿 생성 (`--overwrite-config`로 강제 갱신) -- systemd unit 생성 또는 갱신 (`/etc/systemd/system/iop-node.service`) -- `systemctl daemon-reload` -- 옵션에 따른 `--enable`, `--start`, `--restart` - -현재 구현상 `setup`의 `--config` 기본값은 `/etc/iop/node.yaml`이고, dev 단계 명령(`serve`, `config print/check`)의 root persistent `--config` 기본값은 `configs/node.yaml`이다. 이 경로는 구현 현황 설명이며 사용자-facing field bootstrap 계약으로 보지 않는다. - -별도 `render`, `service install`, `service status` 명령은 초기 범위에 넣지 않는다. 검토와 CI 확인은 `setup --dry-run`으로 흡수하고, 상태/로그/재시작은 `systemctl`과 `journalctl`을 기준 운영 도구로 둔다. - -현재 구현된 node CLI 표면은 다음과 같다. - -```text -iop-node serve -iop-node setup -iop-node config print -iop-node config check -iop-node version -``` - -`setup`은 여러 번 실행해도 같은 결과로 수렴한다. 기존 설정 파일은 기본적으로 덮어쓰지 않고, 강제 갱신이 필요하면 `--overwrite-config`를 지정한다. +Node setup/config CLI는 현재 구현에 남아 있는 저수준 보조 표면이다. +field 사용자 기본 경로와 다음 개발 방향에서는 Node setup/config를 안내하지 않는다. +Control Plane 없는 개발 단계에서도 Node별 실행 설정은 Edge config의 `nodes[]`에서 관리하고, Node host에서는 Edge가 제시한 bootstrap 명령만 실행한다.