CLI

Ongrid 发两个二进制：

• ongrid —— 云端 manager。在 manager 容器里跑。
• ongrid-edge —— edge agent。在 Linux host 上作为 systemd 服务跑。

两者都被设计成通过环境变量（环境变量）配置， 不是 flag。CLI 表面故意做小 —— 只够打印版本和帮助摘要。生产部署里看着像 flag 的东西，多半是设在 /etc/ongrid-edge/ongrid-edge.env 或 deploy/docker-compose.yml 里的 ONGRID_* env。

ongrid（manager）

读每个它识别的 ONGRID_* env 变量，开它的 listener，跑到 SIGINT / SIGTERM。没有必填参数，没有子命令。

flag

manager 没暴露记录在案的 flag。argv 处理是标准 Go 运行时的：任何未知 flag 被忽略。未来的运维工具 flag（强制 migration、dump config、再生 bootstrap admin）在 GitHub 上的 ops 标签下跟踪。

进程模型

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

优雅关闭：manager 把 SIGINT / SIGTERM 接到 errgroup 根 context 上。所有 goroutine 在 context 取消时停；在飞的 HTTP 请求最多 10 秒收尾。

ongrid-edge（agent）

edge 二进制在任何 env 驱动启动前支持两个 flag。它们在 main() 最顶处理， 所以即便 host 配错了也能打印并退出。

flag	别名	行为
--version	-v	打印 ongrid-edge <version> 并 0 退出。
--help	-h	打印 ongrid-edge <version> 加一行关于 systemd 配置的 hint，然后 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 flag。每个设置都来自环境。systemd unit 通过 EnvironmentFile= 加载 /etc/ongrid-edge/ongrid-edge.env；ad-hoc 跑 （macOS 上开发、调试）你在 shell 里设。

启动需要的 env

agent 怎样都会启，但只有这三个设了才能干实事：

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)

agent 不 fork。插件是进程内 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 unit、/usr/local/lib/ongrid-edge/ 下的插件 二进制，但保留 /var/log/ongrid-edge/。

通过 env 调试 flag

这些没 CLI flag 但够有用：

变量	效果
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 整包暂存（设空）
NO_COLOR=1	从 install.sh 输出剥 ANSI 码（安装器用，不是 agent）

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

flag

flag	必填	描述
--access-key=KEY	是（安装）	按 edge access key（manager UI 给）
--secret-key=SECRET	是（安装）	匹配的 secret
--server-edge-addr=HOST:PORT	是（安装）	tunnel 端点（frontier broker）
--server-http-addr=HOST[:PORT]	是（安装）	nginx 前门；用于二进制下载和自检
--uninstall	否	停止并删 agent（保留 /var/log/ongrid-edge/）
-h、--help	否	打印用法

它读的 env

变量	默认	效果
ONGRID_INSTALL_WAIT	20	等 agent 在 journal 里打出 "registered with cloud" 才宣告成功的秒数
NO_COLOR	未设	禁用 ANSI 色

退出码

• 0 —— 已安装并注册（或已卸载）。
• 1 —— 安装完成但注册没发生（网络、坏 key）；用 journalctl -u ongrid-edge -f 诊断。
• 2 —— 调用错（缺必填 flag）。

另见

• 环境变量 —— 真正的配置面。
• Linux（edge） —— systemd unit 细节、 安装器在磁盘上落什么。
• REST API —— manager 对 client 暴露的面。