Edge 安装

ongrid-edge 是一个静态 Go 二进制 + 四个插件子进程。没有 compose、没有 DB、没有入站端口——一条到 frontier broker 的出站 TCP 连接，每个插件一条到数据面的出站 HTTPS。

标准安装是从 manager 的 /install.sh 端点 curl-pipe。Manager 把 installer、agent 二进制、插件二进制和升级 hook 都从同一个 /edge/ 静态路径下发，所以运维只需要一条回到 manager 的网络路由。

前置条件

目标主机需要：

Linux（amd64 或 arm64）。macOS 上 edge 能跑，但拿不到日志 + hostmetrics 插件（上游 Grafana / node_exporter 不发 darwin 构建）；参见 macOS edge 开发。
systemd 用来托管服务。
出站 TCP/40012 到 manager（控制面）。
出站 TCP/443 到 manager（数据面——日志 + 链路推送）。
curl 和 root（installer 需要时会通过 sudo re-exec）。
没有特定内存/磁盘下限——agent RSS 远低于 50 MB，再加上插件子进程的占用。

在 UI 里建 edge

登入 manager。
Edges → New edge.
起个名（如 prod-web-01）。可选 description。
按 Create。

详情页这时会显示：

Access key（AK_...）—— 服务端生成，标识 edge。
Secret key（SK_...）—— 只显示一次。丢了就只能轮换。
安装命令 —— 一行 curl ... | sudo bash -s --，里面塞好了 access key、secret key、edge 隧道端点、HTTP 端点。

现在就抓住 secret key

Secret key 只显示一次。装之前丢了就删 edge 重建——比翻 DB 备份安全。

安装命令

从 UI 复制那一行。长这样：

bash

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=203.0.113.10:40012 \
    --server-http-addr=203.0.113.10:443

各 flag 的语义：

--access-key / --secret-key —— geminio 隧道的鉴权材料。Agent 拨号时提交，frontier 找 manager 的 edgeauth 验证。
--server-edge-addr —— 控制面的 host:port。除非你改过，永远是 40012。
--server-http-addr —— 数据面和二进制下载的 host:port。和浏览器访问 UI 用的是同一个 host:port。也可以只填 host（默认 443）。Installer 从 https://<http-addr>/edge/ongrid-edge-<os>-<arch> 下载二进制。

直接跑。如果你没 sudo，installer 会通过 sudo re-exec。

落到磁盘的内容

text

/usr/local/bin/
  └── ongrid-edge                       # the agent binary (mode 0755)

/usr/local/lib/ongrid-edge/
  ├── apply-pending-upgrade.sh          # ADR-024 ExecStartPre hook (mode 0755)
  ├── promtail                          # plugin: logs (Loki push)
  ├── otelcol-contrib                   # plugin: traces (OTLP push)
  ├── node_exporter                     # plugin: hostmetrics
  └── process_exporter                  # plugin: procmetrics

/etc/ongrid-edge/
  └── ongrid-edge.env                   # access/secret keys (mode 0640,
                                        # owner root:ongrid-edge)

/etc/systemd/system/
  └── ongrid-edge.service               # systemd unit

/var/lib/ongrid-edge/                   # StateDirectory, created at start
  └── .upgrade/                         # staged bundles, markers

/var/log/ongrid-edge/                   # plugin stdout/stderr capture
                                        # (the agent itself logs to journal)

Installer 还会：

创建 ongrid-edge 系统用户（无 home、无 shell）。
把 ongrid-edge 加进 adm 和 systemd-journal，让日志插件（promtail）能读 /var/log/*（root:adm 640）和 journal。
systemctl daemon-reload && systemctl enable --now ongrid-edge。

验证

Installer 最多等 20 秒（用 ONGRID_INSTALL_WAIT=N 改）等 agent 把 agent: registered with cloud 写进 journal。健康的安装会打印：

text

[INFO]  waiting for tunnel handshake (up to 20s)...

--- self-check ---
[OK]    plugin binary present: promtail
[OK]    plugin binary present: otelcol-contrib
[OK]    plugin binary present: node_exporter
[OK]    plugin binary present: process_exporter
[OK]    journald readable by ongrid-edge
[OK]    data-plane host 203.0.113.10:443 reachable (TCP)
[OK]    self-check passed

[OK]    installed:    ongrid-edge v0.7.159
[OK]    connected:    edge_id=42 via 203.0.113.10:40012
[OK]    tail logs:    journalctl -u ongrid-edge -f

如果 STATUS=failed 或 pending，installer 会 dump 最近 20 行 journal 并提示你最可能的修法。手动检查：

bash

# Service state
sudo systemctl status ongrid-edge

# Live journal
sudo journalctl -u ongrid-edge -f

# Test the data plane reachability
curl -kI https://203.0.113.10/

# Test the control plane reachability
nc -vz 203.0.113.10 40012

最常见的故障及含义：

症状	可能原因	修法
Journal 里 `unauthorized`	access/secret key 打错或过期	UI 上轮换 edge；用新 key 重跑 installer。
`connection refused on :40012`	frontier broker 没暴露 / 防火墙	查 `iptables` / 云 SG；在 manager 上确认 `docker compose ps frontier`。
Self-check：`plugin binary MISSING`	老安装在插件 bundle 之前装的，或从一台从没跑过 `install.sh` 的 manager curl	重跑安装命令——它每次都会重拉插件二进制。
Self-check：读不了 journal	`ongrid-edge` 没在 `systemd-journal` 组	`sudo usermod -aG systemd-journal ongrid-edge && sudo systemctl restart ongrid-edge`。
Edge "online" 但 Logs/Traces 空	Manager 上 `ONGRID_PUBLIC_URL` 指了内网 IP	改 manager 上的 `/opt/ongrid/.env`；重启 compose。

在 UI 里看

Edges —— edge 名旁边一个绿点。卡片显示 hostname、内核、发行版、总内存、磁盘、agent 版本。
Monitor —— CPU / 内存 / 磁盘 / 负载面板在大约 30 秒内填上。
Logs —— 选这个 edge，看 /var/log/* 和 journald 实时尾。
Topology —— 主机节点出现。

重注册 / 轮换 key

需要轮换 secret key（泄露、丢了 key、manager 重装）时：

UI 里 Edges → <你的 edge> → Rotate keys. 这会作废旧 secret 并显示新的。
复制新的安装命令。还是同一行，只是 --access-key / --secret-key 是新的。
在 edge 主机上重跑安装命令。它会：
- 在覆盖二进制前干净停掉跑着的 ongrid-edge，
- 重拉二进制（让老 edge 跟上 manager 版本），
- 重拉插件二进制，
- 用新 key 重写 /etc/ongrid-edge/ongrid-edge.env（mode 0640，owner root:ongrid-edge），
- systemctl restart ongrid-edge，
- 重跑 self-check。

把 edge 升级到新 manager 也用同一套流程。重注册是幂等的。

卸载

bash

curl -k -sSL https://203.0.113.10/install.sh | sudo bash -s -- --uninstall

停掉 + disable 服务、移除二进制、systemd unit、env 目录。保留 /var/log/ongrid-edge，方便你留插件日志做事后分析。

在企业代理 / 防火墙后

两个出向目的地是：

<manager-host>:40012 —— geminio 隧道，纯 TCP（如果 manager 的 frontier 配了 TLS-on-wire 就上 TLS；OSS 构建是纯 TCP，在 nginx 前置的 geminio 后面）。
<manager-host>:443 —— HTTPS，给插件数据面 + 二进制下载 + 升级 bundle 拉取用。

如果出网走 http 代理，在 /etc/systemd/system/ongrid-edge.service.d/proxy.conf 里设 HTTPS_PROXY：

ini

[Service]
Environment=HTTPS_PROXY=http://proxy.corp:3128
Environment=NO_PROXY=127.0.0.1,localhost

然后 systemctl daemon-reload && systemctl restart ongrid-edge。

接下来

首次启动清单 —— 等几个 edge 接上来之后的运维端配置（告警、通道、知识库）。
升级 —— ongrid-edge 在运维触发下如何自我更新（UI 一键升级）。
平台 / Linux edge —— 发行版矩阵、已验证发行版、SELinux/AppArmor 说明。

Edge 安装 ​

前置条件 ​

在 UI 里建 edge ​

安装命令 ​

落到磁盘的内容 ​

验证 ​

在 UI 里看 ​

重注册 / 轮换 key ​

卸载 ​

在企业代理 / 防火墙后 ​

接下来 ​

Edge 安装

前置条件

在 UI 里建 edge

安装命令

落到磁盘的内容

验证

在 UI 里看

重注册 / 轮换 key

卸载

在企业代理 / 防火墙后

接下来