Linux（edge）

edge agent（ongrid-edge）跑在每台你想让 Ongrid 观测的主机上。Linux 上， 它通过一条 curl-pipe 命令装成 systemd 服务。agent 是单个静态 Go 二进制加四 个插件二进制（promtail、node_exporter、process-exporter、otelcol-contrib）。

架构

GOOS	GOARCH	状态
linux	amd64	一等
linux	arm64	一等

安装器读 uname -m 选匹配的二进制，从 manager 的 /edge/ 静态路径下载：

x86_64 / amd64  → amd64
aarch64 / arm64 → arm64
anything else   → error: "unsupported arch"

支持的发行版

跟服务端一样的测试集。实际只要 systemd 245+（StateDirectory= 能用）和 glibc 2.31+ 都能跑 agent。

发行版	测过
Ubuntu	20.04 LTS、22.04 LTS、24.04 LTS
Debian	11（bullseye）、12（bookworm）
RHEL	8、9
Rocky Linux	8、9
AlmaLinux	8、9
Amazon Linux	2023

如果你的发行版还在用 sysvinit、OpenRC 或 runit，看下面 "non-systemd" 段。

安装器放下什么

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --access-key=... --secret-key=... --server-edge-addr=<host>:40012 --server-http-addr=<host>:443 在磁盘上落下：

路径	用途
/usr/local/bin/ongrid-edge	agent 二进制
/usr/local/lib/ongrid-edge/promtail	日志插件
/usr/local/lib/ongrid-edge/otelcol-contrib	链路插件
/usr/local/lib/ongrid-edge/node_exporter	主机指标插件
/usr/local/lib/ongrid-edge/process_exporter	进程指标插件
/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh	ADR-024 staged-bundle 交换 hook
/etc/ongrid-edge/ongrid-edge.env	access/secret key、cloud 地址（mode 640, root:ongrid-edge）
/etc/systemd/system/ongrid-edge.service	systemd unit
/var/lib/ongrid-edge/	StateDirectory：pending-upgrade 暂存、去重状态
/var/log/ongrid-edge/	本地日志目录（mode 750，owned by ongrid-edge）

会创建一个系统用户 ongrid-edge（无 shell、无 home），加进两个组：adm （让 promtail 能读 mode 是 640 root:adm 的 /var/log/*）和 systemd-journal（让它能读 journal）。

systemd unit

原文摘自 deploy/install/edge/install.sh：

[Unit]
Description=ongrid edge agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/ongrid-edge/ongrid-edge.env
ExecStartPre=-+/usr/local/lib/ongrid-edge/apply-pending-upgrade.sh
ExecStart=/usr/local/bin/ongrid-edge
Restart=always
RestartSec=5
User=ongrid-edge
Group=ongrid-edge
AmbientCapabilities=CAP_NET_ADMIN
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
StateDirectory=ongrid-edge
StateDirectoryMode=0755
ReadWritePaths=/var/log/ongrid-edge
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

要点：

• ProtectSystem=strict 让 /usr、/boot、/etc 只读。agent 从不写 StateDirectory=（/var/lib/ongrid-edge）或 ReadWritePaths= （/var/log/ongrid-edge）之外的地方。
• AmbientCapabilities=CAP_NET_ADMIN 让一些 edge 技能能做只读网络内省 （通过 nft list ruleset 跑 ss -ntlp 风格探针、conntrack 读取）。 agent 自己从不开 raw socket。
• ExecStartPre=-+（- 忽略失败，+ 以 root 跑）接入 ADR-024 staged-bundle 交换。上次启动暂存了升级的话，这个 hook 应用它，然后无论如何退 0。
• StandardOutput=journal 是跟 promtail 的契约 —— agent 自己的日志在 journald 里可读，不在 pid-1 的 stdout 上，promtail 的 journal 源捡起来。

日志源：journald，不是 syslog

Promtail 配成 scrape journald（非持久化 /run/log/journal，持久化 /var/log/journal）。它不采 /var/log/syslog 或 /var/log/messages。 你发行版发 rsyslog 并且你关了持久 journal 的话，把它开起来：

mkdir -p /var/log/journal
systemd-tmpfiles --create --prefix /var/log/journal
systemctl restart systemd-journald

没持久 journal 日志插件照样能跑，但历史按 RAM 限（运行时 journal 在 /run/log/journal）。

non-systemd Linux（sysvinit / OpenRC / runit）

curl-pipe 安装器在缺 systemctl 时硬挂。你仍然可以跑 agent —— 把二进制放到 /usr/local/bin/ongrid-edge，写自己的 init 脚本，导出三个必须的 env （ONGRID_EDGE_CLOUD_ADDR、ONGRID_EDGE_ACCESS_KEY、 ONGRID_EDGE_SECRET_KEY），exec 二进制就完事了。你会失去：

• 崩溃自动重启（换成你的 init 系统提供的）。
• apply-pending-upgrade.sh hook，所以远程整包升级（ADR-024）静默 no-op。
• 插件二进制（安装器也取这些，见上）。

那四个插件二进制也在 https://<manager>/edge/<name>-linux-<arch> 可拿；手 下到你选的目录，再让 ONGRID_EDGE_PLUGIN_BIN_DIR 指过去。

agent 不需要的能力

• 运行时不需要 root（它以 ongrid-edge 用户跑）。
• 不需要 CAP_SYS_ADMIN、CAP_NET_RAW、CAP_SYS_PTRACE。技能要其中任何 一个，cmdpolicy 门会拒绝。
• 不需要 Docker。插件运行时是普通的子进程监管，不是容器。

agent 打开的端口

端口	绑定	为什么
9101	localhost	agent 自己的 /metrics 和 /healthz
9102	localhost	node_exporter（hostmetrics 插件启用时）
9256	localhost	process-exporter（procmetrics 插件启用时）

只有到 manager 40012 端口的出站 tunnel 连接需要穿过你的防火墙。edge 主机不用开任何入站端口。

卸载

curl -k -sSL https://<manager>/install.sh | sudo bash -s -- --uninstall

停服务，删二进制、env 文件、systemd unit。故意留下 /var/log/ongrid-edge/ —— 想清就手动清。