快速开始

目标：约 10 分钟内完成以下事情……

在单台 Linux 机上通过 docker compose 起整套 Ongrid 栈（manager + frontier broker + Prometheus + Loki + Tempo + Grafana + Qdrant + SearXNG）。
管理员账号通过 HTTPS 登录。
一个 ongrid-edge 注册到你的 manager，开始上报 CPU / 内存 / 磁盘指标，并能在 Monitor 页看到。

想看更详细的步骤，请直接读服务端安装和Edge 安装。

0. 前置条件

一台 Linux 机（已验证 Ubuntu 22.04+、Debian 12+、RHEL/Rocky/Alma 9+）。

至少 4 GB 内存（推荐 8 GB）
/var/lib/ongrid（数据目录）下至少 20 GB 空闲磁盘
root 或 sudo
docker ≥ 24，带 docker compose v2 子命令
openssl（首次启动签自签名 TLS 证书用）
edge 要跑的主机能访问到这台机的 TCP 443 和 40012

本机测试

笔记本上整套跑也可以。但要注意 ONGRID_PUBLIC_URL 默认是笔记本的 LAN IP，所以装在其他机器上的 edge 必须能通过 LAN IP 走 TCP/443 找到它。

1. 安装服务端

标准安装路径是 gh release download 加 sudo ./install.sh。tarball 是自包含的——docker 镜像、edge 二进制、配置文件全都打包好了。

bash

# Pick the latest tag from https://github.com/ongridio/ongrid/releases
VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

tar xf "ongrid-${VER}-linux-amd64.tar.xz"
cd     "ongrid-${VER}-linux-amd64"

sudo ./install.sh

install.sh 按顺序做这些事：

预检。 确认 docker + docker compose v2 在位，daemon 可达。
拉起配置到 /opt/ongrid/（compose 文件、prometheus、loki、tempo、grafana、searxng、edge 资源）。
建数据目录到 /var/lib/ongrid/（mysql、prometheus、loki、tempo、qdrant、grafana、embeddings），并按各容器镜像期望的 uid chown。日志放 /var/log/ongrid/。
签自签名 TLS 证书到 /opt/ongrid/certs/——浏览器第一次会警告。后面换正式证书；参见服务端安装。
加载 docker 镜像（ongrid、ongrid-web、frontier）从 tarball 里——不需要拉 Docker Hub。
填 .env：MYSQL_*、ONGRID_JWT_SECRET、GRAFANA_ADMIN_PASSWORD，以及引导用的 ONGRID_ADMIN_PASSWORD 都填上强随机密码。
提示输入 ONGRID_PUBLIC_URL，30 秒倒计时。这是你的 edge 用来访问这台 manager 数据面的 URL（日志 → Loki、链路 → OTLP push）。交互式终端下这个值填错是 "只有 manager 本机的 edge 能上报日志" 的头号原因，务必确认。参见 ONGRID_PUBLIC_URL。
跑 docker compose up -d 并轮询 https://localhost/healthz 最多 60 秒。
打印 banner：Web URL、API URL、隧道端点、引导管理员密码——只显示一次。

健康的安装结尾长这样：

text

[INFO] ongrid is healthy (took ~14s)

===============================================================
  ongrid installation complete
===============================================================

Web UI:          https://203.0.113.10/
API URL:         https://203.0.113.10/api/v1
Tunnel endpoint: 203.0.113.10:40012   (for edges)

---------------- bootstrap admin ----------------
email:    admin@example.com
password: 9Xp4hKqf1bL2zRq3Wn7v
>> Record this password NOW. It will not be shown again.
-------------------------------------------------

记下管理员密码

引导密码在安装 banner 里只显示一次，也以 ONGRID_ADMIN_PASSWORD 形式存在 /opt/ongrid/.env（chmod 600）。两个都丢了就得从数据库手工重置；参见首次启动清单。

2. 登录

浏览器打开 https://<your-host>/。接受 TLS 警告（或者先换正式证书）。用以下信息登录：

email —— .env 里 ONGRID_ADMIN_EMAIL 填的值（默认 admin@example.com）
password —— 安装 banner 里的那串

首次登录会落到 chat 主页。顶部 model picker 显示 "no provider configured"——继续之前先修这个。

3. 配模型（1 分钟）

进 Settings → Models。任选一个：

OpenAI —— 贴 sk-…，默认模型 gpt-5.4。
Anthropic —— 贴 sk-ant-…，默认 claude-opus-4-7。
Zhipu (GLM) —— 贴 API key，默认 glm-4.7。
DeepSeek、Gemini、Kimi，或 Custom (OpenAI-compatible) —— 其他一切（vLLM、Ollama、OpenRouter、公司中继……）。

按 Save。表单会预注册 provider——不用重启。然后在同一页把 Default provider 设成你刚配的那个。

为什么默认 provider 重要

Default provider 驱动所有后端 LLM 调用（告警调查、翻译、总结）。Chat 页上的 model picker 只覆盖当前对话线程（路由细节参见边栏 Models 区）。

回顶部导航的 Chat，问 "hello"。模型回复了，链路就通了。

4. 注册第一个 edge

侧边栏点 Edges → New edge。填：

Name —— 任意，例如 prod-web-01。
Description —— 可选。

按 Create。详情页给你两样东西：

Access key / secret key —— 服务端生成；secret 只显示一次。
安装命令 —— 一行，长这样：

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

SSH 到要监控的主机（可以就是装 manager 那台——这也是合法 demo），以 root 跑这条命令。

按顺序发生的事：

installer 下载匹配的 ongrid-edge-linux-amd64 二进制，加上四个插件二进制（promtail、node_exporter、process_exporter、otelcol-contrib）和 apply-pending-upgrade.sh hook，落到 /usr/local/lib/ongrid-edge/。
建 ongrid-edge 系统用户，加进 adm 和 systemd-journal 组，让日志插件能读 /var/log/* 和 journal。
落 systemd unit 到 /etc/systemd/system/ongrid-edge.service。
写 /etc/ongrid-edge/ongrid-edge.env，里面是 access/secret key（mode 0640，owner root:ongrid-edge）。
systemctl enable --now ongrid-edge。轮询 journal 找 agent: registered with cloud 这一行，最多 20 秒。
打印自检（插件二进制在不在？journald 能读不？数据面主机能不能通？）。

成功注册的结尾长这样：

text

[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

5. 在 UI 里看

回到浏览器：

Edges —— 你的 edge 在列表里，带绿色 "online" 点。卡片显示 hostname、内核版本、总内存、磁盘、发行版。
Monitor —— 选这个 edge。大约 30 秒内你就能看到 CPU、内存、磁盘、负载、网络 IO 图开始有数据。这些是 Grafana 面板通过 /grafana/ 子路径嵌入页面里的。
Logs —— 选这个 edge。实时 tail /var/log/* 和 systemd journal；搜索栏支持 LogQL。
Topology —— edge 以 host 节点出现。你加更多 edge、或者用 expand_topology 技能探测出服务后，图会逐渐丰富。

6. 问 Agent

回 Chat。试试：

"List my edges and show me which has the highest load."
"Tail /var/log/syslog on prod-web-01 for the last 5 minutes."
"Why did CPU spike on prod-web-01 around 10:42?"

Agent 会调真实工具——list_edges、bash、query_promql、search_logs、find_topology_node 等。对话里每次调用以可折叠 chip 显示；点开能看参数和输出。

接下来

配通道，让 Agent 能在 Slack / Telegram / 飞书 / 钉钉 / 企业微信回消息。
写告警规则 —— Ongrid 开箱即用 6 条主机规则，14 种规则 kind，覆盖 PromQL / log_match / log_volume / trace_latency / trace_error_rate。
接知识库 —— 内置 vault 是离线的；加你自己的 org playbook（Markdown、PDF、DOCX）或同步 Git 仓库。
生产硬化 —— 换掉自签名 TLS 证书、把 ONGRID_PUBLIC_URL 换成真实域名、备份 /var/lib/ongrid、把 default_provider 配好并设预算上限。

卸载

在 manager 上：cd ongrid-vX.Y.Z-linux-amd64 && sudo ./uninstall.sh。在 edge 上：curl -k -sSL https://<server>/install.sh | sudo bash -s -- --uninstall。/var/log/ongrid-edge 下的日志会保留。

快速开始 ​

0. 前置条件 ​

1. 安装服务端 ​

2. 登录 ​

3. 配模型（1 分钟） ​

4. 注册第一个 edge ​

5. 在 UI 里看 ​

6. 问 Agent ​

接下来 ​