Ongrid

简体中文

English
日本語
한국어
Español
Français
Deutsch
Português
Русский

简体中文

English
日本語
한국어
Español
Français
Deutsch
Português
Русский

Appearance

离线安装 ​

Ongrid 从设计上就支持完全离线安装。每个 release tarball 都包含：

  • ongrid manager docker 镜像，
  • ongrid-web（前端 + nginx）docker 镜像，
  • singchia/frontier broker docker 镜像，
  • 四个 edge 插件二进制（promtail、otelcol-contrib、node_exporter、process_exporter）的 linux/amd64 和 linux/arm64 版本，
  • 每个架构对应的 ongrid-edge 二进制，
  • 可选的离线嵌入模型（fast-bge-small-zh-v1.5）—— 如果你在 make package 之前跑过 make fetch-embedding-model，知识库就能用到。

安装时不会拉 Docker Hub、GitHub 或任何厂商 API。运行时唯一的外部依赖是你配置的 LLM API 端点 —— 完全离线的部署可以把它指向内网的 vLLM / Ollama / OpenRouter 转发。

本页讲的是无法访问公网时的工作流。

在联网主机上下载 tarball ​

在能上网的工作机上：

bash
VER=v0.7.159

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

会拿到两个文件：

ongrid-v0.7.159-linux-amd64.tar.xz          # ~380 MB (xz compressed)
ongrid-v0.7.159-linux-amd64.tar.xz.sha256   # the sidecar

走 Clash 时上传 GitHub

大 release asset 走 Clash 代理常常半路 reset。如果下载中断，加 NO_PROXY=objects.githubusercontent.com 直连。无论如何都要校验 sha256（见下一步）。

校验 sha256 ​

干别的之前先做这件事：

bash
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256
# → ongrid-v0.7.159-linux-amd64.tar.xz: OK

校验失败就不要继续，重新下载。

传输到离线主机 ​

按你站点允许的方式：U 盘、内部制品库、SFTP 经跳板机。两个文件要一起送；到目的地后可以再校验一次 sha256。

bash
# On the destination host:
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256

安装 ​

和服务端安装一样 —— 离线不需要任何特殊参数，安装脚本本身不会外联：

bash
tar xf ongrid-v0.7.159-linux-amd64.tar.xz
cd     ongrid-v0.7.159-linux-amd64
sudo ./install.sh

install.sh 会做：

  • docker load 三个内置镜像（images/ongrid.tar、images/frontier.tar、images/ongrid-web.tar）。
  • 铺设配置、建好主机数据目录、生成自签 TLS 证书（用本机 openssl，不需要外部 CA）。
  • 从模板生成 .env，原地生成强随机密钥，提示输入 ONGRID_PUBLIC_URL。
  • docker compose up -d，轮询 /healthz。

整个过程里你不应该看到任何 "downloading..." 日志。

把 install URL 托管在内网 ​

edge 自己装的时候执行的是 curl https://<manager>/install.sh | bash。它拉的 install.sh 是 manager 自己提供的 —— 具体是 nginx 把 /opt/ongrid/edge/install.sh 静态发出去。edge 安装路径里没有 GitHub 也没有其他外部依赖。

同一个 nginx 还提供：

nginx 上的路径含义
/install.shedge 的 install.sh 脚本。
/edge/ongrid-edge-linux-amd64edge agent 二进制。
/edge/ongrid-edge-linux-arm64同上，arm64。
/edge/promtail-linux-amd64插件二进制。
/edge/otelcol-contrib-linux-amd64插件二进制。
/edge/node_exporter-linux-amd64插件二进制。
/edge/process_exporter-linux-amd64插件二进制。
/edge/apply-pending-upgrade.shADR-024 的 ExecStartPre 钩子。
/edge/edge-bundle-linux-amd64-<ver>.tar.gz升级 bundle。
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256校验文件。

执行 install.sh 时这些都落在 /opt/ongrid/edge/，由 nginx 容器只读提供。除此之外不需要别的。

Edge 安装（离线） ​

只要 edge 能访问 manager，标准的一行命令就能用：

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

如果某台 edge 主机直接连不上 manager，但能访问内网制品镜像站，可以这样：

  1. 把 manager 的 /install.sh 和 /edge/* 镜像到你的内网 web 服务上。
  2. 用那个镜像 URL 跑一行命令。
  3. agent 仍然需要 --server-edge-addr 和 --server-http-addr 指向真正的 manager —— 镜像站只托管安装制品，不承载隧道。

适用于"edge 能到 manager 的 TCP 40012 + 少数几个端口，但 TCP 443 不行，公司又有 web 服务"的场景。

数据面仍需 HTTPS 到 manager

日志和链路从每个 edge 直接推到 https://<manager>/loki/api/v1/push 和 https://<manager>/v1/traces。edge 上不去 443，那些插件就推不上来。Agent 自己看上去会健康（它只要 40012 就行），但数据面静默 —— 务必保证 edge → manager 的 443 是通的。

离线模型 provider ​

默认 ONGRID_*_API_KEY= 槽位指向厂商 URL（OpenAI、Anthropic、智谱…）。要保持离线，请在 Settings → Models 里配一个 Custom（OpenAI 兼容） provider，指向你的内网转发：

  • vLLM —— OPENAI_API_BASE=http://vllm.internal:8000/v1，OPENAI_API_KEY 填个占位。
  • Ollama —— OPENAI_API_BASE=http://ollama.internal:11434/v1。
  • LocalAI / LMStudio —— 同样的模式。
  • OpenRouter（内网） —— 粘贴你的转发 base URL。

Agent 不在乎；OpenAI 兼容的 wire 格式是通用的。然后把新 provider 设为 Default provider，这样所有后端调用（告警调查、翻译、总结）都走它。

详见侧边栏 Models 区的 Custom (OpenAI-compatible) 条目。

离线知识库（不走 GitHub 同步 vault） ​

内置 vault 首启时从 github.com/ongridio/vault 同步。离线站点上不去 GitHub。两种办法：

方案 A —— 把 vault 一起打进 tarball ​

release tarball 里已经把 vault 的基线快照打进了镜像。首启时 manager 直接把它复制进 Qdrant —— 不需要网。你拿到的是基线（发版时点的最近一次完整公开同步），新 playbook 要等下次升级 manager。

方案 B —— 在内网镜像 vault 仓库 ​

  1. 在能联网的主机上 clone 公开 vault：
    bash
    git clone --bare https://github.com/ongridio/vault.git
  2. 推到你的内网 Git：
    bash
    git push --mirror git@git.internal:ops/vault.git
  3. 在 Settings → Knowledge → Vault 里把同步 URL 改成 git@git.internal:ops/vault.git，贴上 SSH deploy key。manager 用 GIT_SSH_COMMAND 绑定 key —— 见 ADR-023。

UI 里点 "Sync vault" 按钮就能按需重新拉。每次拉就是一次 git fetch，路径里没有任何 GitHub 专属代码。

离线升级 ​

跟首次安装一样，安装时不需要联网。流程：

  1. 在联网工作机：gh release download v0.7.160 ... 并校验 sha256。
  2. 传输 tarball。
  3. 在离线主机：
    bash
    tar xf ongrid-v0.7.160-linux-amd64.tar.xz
cd     ongrid-v0.7.160-linux-amd64
sudo ./upgrade.sh
  4. 在 UI 里点 Edges → Upgrade all —— edge 从 https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz 拉新 bundle，然后走标准 ADR-024 stage-then-swap 流程应用。

除了下载 tarball 的工作机，没有任何步骤需要外网。

升级细节见升级。

接下来 ​

  • Models / Custom (OpenAI-compatible) —— 把 vLLM / Ollama / 内网转发接成默认 provider（见侧边栏 Models）。
  • 知识库能力 —— vault 里有什么、怎么加自己的 runbook。
  • On-prem 平台 —— 关于本地化 / 离线部署的更全面说明，含 SELinux、自建 CA、出站代理。