服务端安装（docker compose）

标准安装是一个自包含 tarball + sudo ./install.sh。tarball 里带了所有 docker 镜像（ongrid、ongrid-web、singchia/frontier），所以不需要拉 Docker Hub —— 在受限网络和离线环境里都能装。

离线相关细节参见离线安装。 更短的过流程参见快速开始。 systemd 原生安装（不用 docker）参见Linux server 平台。

前置条件

一台 Linux 主机，要求：

• 至少 4 GB 内存，推荐 8 GB（Prometheus + Loki + Tempo + MySQL + manager 都跑在这里）。
• /var/lib/ongrid（数据根）下至少 20 GB 空闲磁盘。要换地方就用 ONGRID_DATA_DIR=… 调——NFS / iSCSI / NVMe 都行，本质就是一个 bind-mount。
• Docker ≥ 24，带 docker compose v2 子命令（docker compose version 能打印就行）。
• openssl —— install.sh 在 tls.crt / tls.key 不存在时用它签首次启动的自签名 TLS 证书。
• 入站 TCP/443 对你的浏览器和每个 edge 开放。
• 入站 TCP/40012 对每个 edge 开放（frontier broker）。
• 一个所有 edge 都能访问的公网 IP 或域名。这个值进 ONGRID_PUBLIC_URL，是头号最常见的配错点。

别给 ONGRID_PUBLIC_URL 填私网 IP

安装脚本自动嗅一个 IP 并要你确认。如果你接受了 10.x / 192.168.x / 172.16-31.x 而你的 edge 在公网上，日志和链路会静默推送失败。控制面隧道仍然能通（它走另一条经过 nginx 的路），所以 UI 上 edge 看着是健康的——但 Loki 和 Tempo 一直空。

安装

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

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

# Verify the sha256 — the .sha256 sidecar ships with each release.
sha256sum -c "ongrid-${VER}-linux-amd64.tar.xz.sha256"

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

sudo ./install.sh

常用 flag：

Flag	作用
--mode systemd	切到原生 systemd 安装（不用 docker）。派发到 systemd/install-systemd.sh。参见Linux server 平台。
--with-deps	仅 systemd。通过 apt/dnf 自动装 mariadb + nginx + grafana，拉钉死版本的 prom / loki / tempo / qdrant 二进制并 sha256 校验。
--profile monitoring	仅 compose。把 Prometheus 9090 端口暴露到主机（开发笔记本上有用；生产默认不开）。
--no-seed	仅 compose。重新跑装时跳过 admin 引导 banner 输出。
--force	仅 compose。在已有安装上重装（保留 .env 和数据卷）。

install.sh 做了什么

按顺序：

1. 预检。 确认 docker CLI 在 $PATH、daemon 可达、docker compose v2 在位。任何一项不达标就早退。

2. 拉起配置到 ${ONGRID_INSTALL_DIR:-/opt/ongrid}/：

   • docker-compose.yml、.env.example、VERSION、frontier.yaml，
   • prometheus.yml（bind-mount 进 prom 容器的 /etc/prometheus/），
   • prometheus-rules.yml（ADR-026 自观测告警），
   • loki-config.yaml、tempo-config.yaml，
   • grafana/ provisioning，
   • searxng/ 设置，
   • edge/（每架构的 edge 二进制 + 插件二进制 + 升级 bundle）。

3. 建主机数据目录到 ${ONGRID_DATA_DIR:-/var/lib/ongrid}/，按各容器镜像运行的 uid chown：

   • mysql/ → 999:999（mysql:8.0）
   • prometheus/ → 65534:65534（prom 以 nobody 跑）
   • loki/ → 10001:10001
   • tempo/ → 10001:10001
   • grafana/ → 472:472
   • embeddings/ → 65532:65532（manager nonroot 用户）

   首次启动这一步漏了，prom/loki/tempo/grafana 就会以 permission denied on /<datadir> 崩。

4. 拉起捆绑的 embedding 模型给离线 RAG 用 —— /var/lib/ongrid/embeddings/fast-bge-small-zh-v1.5/。如果你已经换上了自定义模型，安装脚本不动它。

5. 刷新 nginx 配置从 tarball 拷过来，并在 ${INSTALL_DIR}/certs/ 没证书时生成有效期 365 天的自签名证书（CN=ongrid，SAN：DNS:ongrid、DNS:localhost、IP:127.0.0.1）。

6. 加载 docker 镜像：通过 docker load 从 images/ongrid.tar、images/frontier.tar、images/ongrid-web.tar 加载。无需 registry 拉取。

7. 创建或复用 .env。 ${INSTALL_DIR}/.env 存在就保留（--force 不覆盖运维改过的 .env）。不存在就从 .env.example 拷一份。然后给空字段填强随机值：

   • MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD —— 24 字符，
   • ONGRID_JWT_SECRET —— 64 字符，
   • ONGRID_ADMIN_PASSWORD —— 20 字符（记录到最后 banner 里），
   • GRAFANA_ADMIN_PASSWORD —— 20 字符。

8. 如果空就提示输入 ONGRID_PUBLIC_URL。30 秒倒计时，默认 = 嗅探出的主机。读 /dev/tty，所以 curl ... | bash 也能交互。

9. docker compose up -d，带 --env-file .env。不传 -f，所以 docker-compose.override.yml 自动加载（你加了 override 也生效）。

10. 轮询 https://localhost/healthz 最多 60 秒，走 nginx。Manager 的 /healthz 在 MySQL 可达且 Agent kernel 接通后返回 200。

11. 打印安装 banner —— Web URL、API URL、隧道端点、引导管理员 email + 密码（只在首次安装时显示）。

安装完之后

你会看到这样的 banner：

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

Install dir:     /opt/ongrid
Version:         v0.7.159

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)

TLS: self-signed cert in /opt/ongrid/certs/ — browsers will warn
      on first visit. Replace tls.crt + tls.key with a real cert and
      'docker compose -f /opt/ongrid/docker-compose.yml restart nginx'.

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

记下管理员密码

引导密码只显示一次。它也存在 /opt/ongrid/.env 里（mode 0600）。两个都丢了，用 reset-admin-password CLI 或直接改 DB 重置——参见首次启动清单。

验证整套栈

# All containers should be Up
sudo docker compose -f /opt/ongrid/docker-compose.yml ps

# Manager health
curl -fk https://localhost/healthz

# Tail manager logs
sudo docker compose -f /opt/ongrid/docker-compose.yml logs -f ongrid

# Browse to the UI
open https://<your-host>/   # accept the TLS warning

换 TLS 证书

自签名证书在试用够用，但每个浏览器都会警告。生产环境放真证书（Let's Encrypt、公司 CA、随便什么）到 /opt/ongrid/certs/：

sudo cp fullchain.pem /opt/ongrid/certs/tls.crt
sudo cp privkey.pem   /opt/ongrid/certs/tls.key
sudo chmod 600        /opt/ongrid/certs/tls.key
sudo chmod 644        /opt/ongrid/certs/tls.crt
sudo docker compose -f /opt/ongrid/docker-compose.yml restart nginx

install.sh 和 upgrade.sh 永不覆盖运维放的证书。

通配符也行

nginx 从 certs/ 提供 *.crt / *.key；容器只认 tls.crt 和 tls.key 这两个文件名。证书管理器（certbot、acme.sh、cert-manager）把规范副本放在别处时，符号链接也行。

各文件落地位置

路径	Owner	用途
/opt/ongrid/docker-compose.yml	root	Compose 定义。
/opt/ongrid/.env	root, 0600	Secrets + 可调参数。
/opt/ongrid/certs/	root, 0700	tls.crt、tls.key。
/opt/ongrid/edge/	root	Edge 二进制、升级 bundle（edge-bundle-<arch>-<ver>.tar.gz）、install.sh、apply-pending-upgrade.sh。在 nginx 下以只读方式挂在 /edge/。
/opt/ongrid/prometheus.yml	root	Prom scrape + remote_write 配置。
/opt/ongrid/grafana/	root	Provisioning yaml（datasource、dashboard）。
/var/lib/ongrid/mysql/	999:999	MySQL 数据。这个要备份。
/var/lib/ongrid/prometheus/	65534:65534	Prom TSDB。默认 90 天保留，20GB 上限。
/var/lib/ongrid/loki/	10001:10001	Loki chunk + index。
/var/lib/ongrid/tempo/	10001:10001	Tempo block。
/var/lib/ongrid/qdrant/	root	向量存储。
/var/lib/ongrid/grafana/	472:472	Grafana 状态（dashboard、用户、SA token）。
/var/lib/ongrid/embeddings/	65532:65532	离线 BGE 模型缓存。
/var/log/ongrid/	混合	Manager 日志文件。

接下来

• 首次启动清单 —— 模型 provider、Prom 保留、公网 URL、时区、第一个 incident。
• Edge 安装 —— 注册第一个 edge。
• 升级 —— upgrade.sh 流程、stage-then-swap、.previous 回滚。
• 环境变量 —— 所有可调的 ONGRID_* 环境变量。