CLI

Ongrid 는 두 개의 바이너리를 배포합니다:

ongrid — 클라우드 매니저. 매니저 컨테이너 안에서 실행됩니다.
ongrid-edge — edge 에이전트. Linux 호스트에서 systemd 서비스로 실행됩니다.

둘 다 플래그가 아니라 환경 변수 (환경 변수) 로 구성하도록 설계되었습니다. CLI 표면은 의도적으로 작습니다 — 버전과 도움말 요약을 출력하는 정도. 프로덕션 배포에서 플래그처럼 보이는 것은 아마도 /etc/ongrid-edge/ongrid-edge.env 나 deploy/docker-compose.yml 에서 ONGRID_* env 로 설정된 것일 가능성이 큽니다.

`ongrid` (매니저)

바이너리가 인식하는 모든 ONGRID_* 환경 변수를 읽고, listener 를 열고, SIGINT / SIGTERM 까지 실행됩니다. 필수 인수도, 서브커맨드도 없습니다.

플래그

매니저는 문서화된 플래그를 노출하지 않습니다. 유일한 argv 처리는 표준 Go 런타임의 것입니다 — 알려지지 않은 플래그는 무시됩니다. 미래의 운영 도구 플래그 (마이그레이션 강제, config 덤프, 부트스트랩 admin 재생성) 는 GitHub 의 ops 라벨로 추적됩니다.

프로세스 모델

text

ongrid
  ├─ HTTP listener on $ONGRID_HTTP_ADDR (:8080)
  ├─ /metrics listener on $ONGRID_METRICS_ADDR (:9100)
  ├─ geminio service-end SDK dial to $ONGRID_FRONTIER_ADDR (frontier:40011)
  ├─ alert evaluator goroutine (interval $ONGRID_ALERT_EVAL_INTERVAL)
  ├─ DB pool sampler (10s tick)
  └─ background investigators (one goroutine per investigation request)

헬스

curl http://localhost:8080/healthz   # always 200 once the server is up
curl http://localhost:8080/readyz    # 200 when DB + frontier dial are healthy

중지 / 재시작

docker compose -f deploy/docker-compose.yml restart ongrid
docker compose -f deploy/docker-compose.yml down
docker compose -f deploy/docker-compose.yml up -d

graceful shutdown: 매니저는 SIGINT / SIGTERM 을 자체 errgroup 의 루트 컨텍스트에 연결합니다. 모든 goroutine 은 컨텍스트 취소 시 멈추며, 진행 중인 HTTP 요청에는 최대 10 초가 주어집니다.

`ongrid-edge` (에이전트)

edge 바이너리는 env 기반 기동이 일어나기 전에 두 개의 플래그를 지원합니다. 이들은 main() 의 가장 위에서 처리되어, 잘못 구성된 호스트에서도 출력 후 종료됩니다.

플래그	별칭	동작
`--version`	`-v`	`ongrid-edge <version>` 출력 후 exit 0.
`--help`	`-h`	`ongrid-edge <version>` 와 systemd 구성에 대한 한 줄 힌트를 출력한 뒤 exit 0.

cmd/ongrid-edge/main.go 에서 그대로:

text

$ ongrid-edge --version
ongrid-edge v0.7.167

$ ongrid-edge --help
ongrid-edge v0.7.167
Run as a systemd service. See /etc/ongrid-edge/ongrid-edge.env for config.

--config /path 플래그는 없습니다. 모든 설정은 환경에서 옵니다. systemd 유닛은 EnvironmentFile= 을 통해 /etc/ongrid-edge/ongrid-edge.env 를 로드합니다. 임시 실행 (macOS 에서의 개발, 디버깅) 시에는 셸에서 직접 설정합니다.

기동에 필요한 env

에이전트는 어쨌든 부팅되지만, 의미 있는 일을 하려면 이 셋이 필요합니다:

export ONGRID_EDGE_CLOUD_ADDR=ongrid.example.com:40012
export ONGRID_EDGE_ACCESS_KEY=<from manager UI>
export ONGRID_EDGE_SECRET_KEY=<from manager UI>

프로세스 모델

text

ongrid-edge
  ├─ tunnel dial to $ONGRID_EDGE_CLOUD_ADDR
  ├─ /metrics + /healthz listener on :9101 (localhost)
  ├─ embedded collector (gopsutil)
  ├─ plugin supervisor (subprocess promtail / otelcol-contrib / node_exporter / process-exporter)
  ├─ skill dispatcher (handles execute_skill RPCs from manager)
  └─ webshell port-forwarder (handles open_shell RPCs from manager)

에이전트는 fork 하지 않습니다. 플러그인은 in-process supervisor 가 관리하는 일급 자식 프로세스입니다. 플러그인이 크래시되면 supervisor 가 지수 백오프로 재시작하고, 다음 하트비트에 실패를 보고합니다 (Edges 페이지에 health.last_error 로 보입니다).

중지 / 재시작

sudo systemctl restart ongrid-edge
sudo systemctl stop ongrid-edge
sudo systemctl status ongrid-edge
journalctl -u ongrid-edge -f

제거

# from a running edge:
curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

바이너리, env 파일, systemd 유닛, /usr/local/lib/ongrid-edge/ 아래의 플러그인 바이너리를 제거하지만 /var/log/ongrid-edge/ 는 보존합니다.

env 를 통한 디버그 플래그

CLI 플래그는 없지만 알아둘 가치가 있는 것들:

변수	효과
`ONGRID_LOG_LEVEL=debug`	slog 를 debug 로 전환; 하트비트 로그량 두 배 증가
`ONGRID_EDGE_PLUGIN_BIN_DIR=...`	플러그인 바이너리 디렉터리 오버라이드 (기본 `/usr/local/lib/ongrid-edge`)
`ONGRID_EDGE_PLUGIN_WORK_DIR=...`	플러그인 런타임 디렉터리 오버라이드 (기본 `/var/lib/ongrid-edge/plugins`)
`ONGRID_EDGE_UPGRADE_STAGE_DIR=""`	ADR-024 whole-bundle 스테이징 비활성 (빈 값으로 설정)
`NO_COLOR=1`	install.sh 출력에서 ANSI 코드 제거 (에이전트가 아닌 설치 스크립트가 사용)

install.sh (curl-pipe 설치 스크립트)

엄밀히는 바이너리가 아니지만, 문서화할 가치가 있는 CLI 가 있습니다. 사용법:

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- \
    --access-key=KEY \
    --secret-key=SECRET \
    --server-edge-addr=<host>:40012 \
    --server-http-addr=<host>:443

플래그

플래그	필수	설명
`--access-key=KEY`	예 (설치)	edge 별 access 키 (매니저 UI 에서)
`--secret-key=SECRET`	예 (설치)	매칭되는 secret
`--server-edge-addr=HOST:PORT`	예 (설치)	터널 엔드포인트 (frontier 브로커)
`--server-http-addr=HOST[:PORT]`	예 (설치)	nginx front door; 바이너리 다운로드와 self-check 에 사용
`--uninstall`	아니오	에이전트 중지 및 제거 (`/var/log/ongrid-edge/` 보존)
`-h`, `--help`	아니오	사용법 출력

읽는 env

변수	기본값	효과
`ONGRID_INSTALL_WAIT`	`20`	성공 선언 전 에이전트가 "registered with cloud" 를 로그할 때까지 대기할 초
`NO_COLOR`	unset	ANSI 색 비활성

Exit 코드

0 — 설치 및 등록 완료 (또는 제거).
1 — 설치는 완료되었지만 등록 실패 (네트워크, 잘못된 키). 진단에는 journalctl -u ongrid-edge -f 를 사용.
2 — 잘못된 호출 (필수 플래그 누락).

함께 보기

환경 변수 — 실제 구성 면.
Linux (edge) — systemd 유닛 상세, 설치 스크립트가 디스크에 떨어뜨리는 것.
REST API — 매니저가 클라이언트에 노출하는 면.

CLI ​

ongrid (매니저) ​

플래그 ​

프로세스 모델 ​

헬스 ​

중지 / 재시작 ​

ongrid-edge (에이전트) ​

기동에 필요한 env ​

프로세스 모델 ​

중지 / 재시작 ​

제거 ​

env 를 통한 디버그 플래그 ​

install.sh (curl-pipe 설치 스크립트) ​

플래그 ​

읽는 env ​

Exit 코드 ​

함께 보기 ​

CLI

`ongrid` (매니저)

플래그

프로세스 모델

헬스

중지 / 재시작

`ongrid-edge` (에이전트)

기동에 필요한 env

프로세스 모델

중지 / 재시작

제거

env 를 통한 디버그 플래그

install.sh (curl-pipe 설치 스크립트)

플래그

읽는 env

Exit 코드

함께 보기