CLI

Ongrid поставляет два бинаря:

• ongrid — облачный manager. Запускается внутри контейнера manager'а.
• ongrid-edge — edge-агент. Запускается как systemd-сервис на Linux-хостах.

Оба спроектированы для настройки через environment-переменные (Environment-переменные), не через флаги. Поверхность CLI намеренно крошечная — ровно столько, чтобы напечатать версию и краткую справку. Всё, что выглядит как флаг в production-деплоях, скорее всего было задано как ONGRID_* env в /etc/ongrid-edge/ongrid-edge.env или deploy/docker-compose.yml.

ongrid (manager)

Читает каждую ONGRID_* env-переменную, которую бинарь распознаёт, открывает свои listener'ы и работает до SIGINT / SIGTERM. Нет обязательных аргументов и нет subcommand'ов.

Флаги

Manager не выставляет задокументированных флагов. Единственная обработка argv — стандартная Go-runtime'а: любой неизвестный флаг игнорируется. Будущие ops-tooling флаги (форсирование migration'ов, дамп конфига, регенерация bootstrap-админа) отслеживаются под меткой ops на GitHub.

Модель процесса

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)

Health

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

Stop / restart

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: manager привязывает SIGINT / SIGTERM к root-контексту своего errgroup. Все goroutine'ы останавливаются по cancel'у контекста; in-flight HTTP-запросы получают до 10 секунд на завершение.

ongrid-edge (агент)

Edge-бинарь поддерживает два флага до того, как происходит env-управляемый старт. Они обрабатываются в самом начале main(), так что печатаются и выходят даже на неправильно сконфигурированном хосте.

Флаг	Алиас	Поведение
--version	-v	Печатает ongrid-edge <version> и выходит с 0.
--help	-h	Печатает ongrid-edge <version> плюс однострочную подсказку про конфигурацию systemd, затем выходит с 0.

Дословно из cmd/ongrid-edge/main.go:

$ 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. Каждая настройка приходит из environment. Systemd-юнит загружает /etc/ongrid-edge/ongrid-edge.env через EnvironmentFile=; для ad-hoc запусков (dev на macOS, отладка) вы задаёте их в своём shell.

Обязательный 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>

Модель процесса

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. Плагины — это first-class дочерние процессы, управляемые внутрипроцессным supervisor'ом; если плагин падает, supervisor перезапускает его с экспоненциальным backoff и репортит сбой в следующем heartbeat (видно на странице Edges как health.last_error).

Stop / restart

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

Uninstall

# 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/.

Debug-флаги через env

У них нет CLI-флагов, но они достаточно полезны, чтобы о них знать:

Переменная	Эффект
ONGRID_LOG_LEVEL=debug	переключает slog в debug; удваивает объём логов heartbeat
ONGRID_EDGE_PLUGIN_BIN_DIR=...	переопределяет директорию бинарей плагинов (по умолчанию /usr/local/lib/ongrid-edge)
ONGRID_EDGE_PLUGIN_WORK_DIR=...	переопределяет runtime-директории плагинов (по умолчанию /var/lib/ongrid-edge/plugins)
ONGRID_EDGE_UPGRADE_STAGE_DIR=""	отключает stage'инг полного bundle'а ADR-024 (задайте пустое)
NO_COLOR=1	вырезает ANSI-коды из вывода install.sh (используется инсталлером, не агентом)

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	да (install)	access-ключ per-edge (из UI manager'а)
--secret-key=SECRET	да (install)	соответствующий secret
--server-edge-addr=HOST:PORT	да (install)	endpoint туннеля (frontier-брокер)
--server-http-addr=HOST[:PORT]	да (install)	nginx front door; используется для скачивания бинарей и self-check
--uninstall	нет	остановить и удалить агента (сохраняет /var/log/ongrid-edge/)
-h, --help	нет	печать usage

Env, который он читает

Переменная	По умолчанию	Эффект
ONGRID_INSTALL_WAIT	20	секунд ожидания, чтобы агент залогировал "registered with cloud" перед объявлением успеха
NO_COLOR	unset	отключить ANSI-цвета

Exit-коды

• 0 — установлен и зарегистрирован (или удалён).
• 1 — установка завершена, но регистрация не произошла (сеть, плохие ключи); используйте journalctl -u ongrid-edge -f для диагностики.
• 2 — некорректный вызов (отсутствует обязательный флаг).

См. также

• Environment-переменные — настоящая поверхность конфигурации.
• Linux (edge) — детали systemd-юнита, что инсталлер кладёт на диск.
• REST API — поверхность, которую manager выставляет клиентам.