离线 / 私有化

Ongrid 以一个自包含 tarball 发，恰是为了离线能用。没有 apt install、没有目标主机上构建时的 Go module 拉取、运行时没有 Docker Hub pull。落 tarball，跑 install.sh，你就有了一个能用的 manager + edge 队。

走离线要碰的取舍是 LLM provider、RAG 用的 embedding 模型，以及持续升级。这一页是清单。

第 1 步：下 release tarball

在有公网的主机上抓最新 release asset：

gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz'
gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz.sha256'
sha256sum -c ongrid-v0.7.167-linux-amd64.tar.xz.sha256

或者自己 make package 出 tarball。无论哪种，产物是单个 .tar.xz 加它的 .sha256。

把两个文件通过你的离线通道（sneakernet U 盘、内部 artifact 服务器、签名 S3 桶等）搬到目标主机。

第 2 步：tarball 安装

tarball 展开成自包含目录：

text

ongrid-v0.7.167-linux-amd64/
  install.sh
  upgrade.sh
  docker-compose.yml
  images/
    ongrid.tar              # docker image, saved
    ongrid-web.tar
    frontier.tar
    mysql.tar               # bundled so no Docker Hub pull
    prometheus.tar
    loki.tar
    tempo.tar
    grafana.tar
    searxng.tar
  bin/
    linux-amd64/ongrid-edge
    linux-arm64/ongrid-edge
    darwin-amd64/ongrid-edge
    darwin-arm64/ongrid-edge
    linux-amd64/promtail
    linux-arm64/promtail
    linux-amd64/otelcol-contrib
    linux-arm64/otelcol-contrib
    linux-amd64/node_exporter
    linux-arm64/node_exporter
    linux-amd64/process_exporter
    linux-arm64/process_exporter
  edge/
    apply-pending-upgrade.sh
  .cache/
    bge-base-en-v1.5/       # optional offline RAG embedding model

跑：

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

install.sh 把每个 images/*.tar 加载到本地 docker，写一份合理的 .env，通过 docker compose up -d 起栈，打印新 manager 的 URL。主机需要 Docker Engine + Compose v2 —— 见 Linux（服务端）。

完整的逐步带 checksum 和首次启动见离线安装。

第 3 步：镜像到私有 registry（可选）

如果你有私有容器 registry（Harbor / Artifactory / ECR / GCR）、想 docker pull 而不是 docker load，把内置镜像推一次：

for img in images/*.tar; do
  name=$(docker load -i "$img" | awk -F': ' '/Loaded image/ {print $2}')
  registry_tag="registry.internal/${name}"
  docker tag "$name" "$registry_tag"
  docker push "$registry_tag"
done

然后写一个 docker-compose.override.yml 把每个服务指到 registry.internal/... 而不是原镜像，你就能在 N 台主机上部署不再发 tarball。未来升级变成 "拉新 image tag，docker compose up -d"。

第 4 步：离线网里装 edge

curl-pipe 安装器（https://<manager>/install.sh | bash）在离线网里能用，前提是 edge 能到 manager（静态 bundle 走 443、tunnel 走 40012）。安装器从 https://<manager>/edge/ 下 agent 二进制和四个插件二进制，manager 的 nginx 从 bind-mount 的 ./bin/ 目录服务。

edge 通过 HTTPS 到不了 manager —— 比如 edge 在一个只允许 40012 的网段 —— 就手工拷二进制：

# on each edge host
sudo install -m 0755 ongrid-edge /usr/local/bin/ongrid-edge
sudo mkdir -p /usr/local/lib/ongrid-edge
sudo install -m 0755 promtail otelcol-contrib node_exporter process_exporter \
    /usr/local/lib/ongrid-edge/
# then write /etc/ongrid-edge/ongrid-edge.env and the systemd unit
# (see deploy/install/edge/install.sh for the exact unit content)

或者更稳：起一个小的内部 HTTPS 镜像装 ./bin/linux-*/ 的拷贝，把 fork 的 install.sh 指过去。

第 5 步：LLM provider

Ongrid 不内置 LLM。agent kernel 通过 manager 的出站公网连接调上游 provider —— Anthropic、OpenAI、智谱、DeepSeek、Gemini、Kimi 或任何 OpenAI 兼容中继。离线网里你有三个选择：

出站代理。 在 manager 的 env 块设 HTTPS_PROXY=http://your-proxy:3128。所有 provider 调用走代理。
自托管 OpenAI 兼容中继。 在你网里跑 vLLM / TGI / Ollama / one-api，把 ONGRID_OPENAI_BASE_URL 指过去，ONGRID_OPENAI_API_KEY 设成中继要的任何值。这是完全断网装机最常见的模式。
UI 里的 Custom provider。 Settings → Models → Custom（OpenAI 兼容）给你同样的接线，不用重启。

想在中国大陆里对腾讯云托管端点用智谱（GLM），设 ONGRID_ZHIPU_BASE_URL 到区域端点，ONGRID_ZHIPU_API_KEY 到你的 key —— 不要代理，GLM 在中国大陆内可达。

第 6 步：离线 RAG（embedding 模型）

知识库摄入需要 embedding 模型。默认 manager 调 GLM embedding API （embedding-3），需要公网。完全离线部署切到 本地 embedding profile：

ONGRID_EMBEDDING_PROVIDER=local
ONGRID_EMBEDDING_LOCAL_MODEL_PATH=/var/lib/ongrid/embeddings/bge-base-en-v1.5

release tarball 在 .cache/bge-base-en-v1.5/（约 400 MB）发 BAAI/bge-base-en-v1.5 模型。install 脚本首次启动时把它拷到命名卷。如果你构 tarball 时跳了 make fetch-embedding-model，模型缺失 embedding 会失败 —— 跑一次那步再重打包。

默认的 Ongrid 内置 vault（github.com/ongridio/vault）是公开的，含发在内嵌 RAG 种子里的基线 runbook。同步它要能到 GitHub。离线网里你可以：

把 vault vendor 到自己内部 Git 服务器，更新 ONGRID_VAULT_REPO_URL。
或者整体跳过 vault 同步 —— 内嵌种子（约 96 个 playbook）住在二进制里，永远可用。

第 7 步：升级

两条路：

同一 tarball 机制。 在有公网主机上下新 tarball，sneakernet 过去，跑 ./upgrade.sh。这是 install.sh 去掉 bootstrap 的版本 —— 加载镜像 + docker compose up -d。edge agent 在下次重连时拿到匹配的 agent + 插件二进制（ADR-024 整包暂存）。
私有 registry pull。 镜像了（第 3 步）的话， docker compose pull && docker compose up -d 够了。edge 还需要新的 agent + 插件二进制，从 manager 的 /edge/ 静态路径拉 —— 你换掉 tarball 装来的 bin/ 目录时自动更新。

离线不行的

内置 vault 自动同步没镜像 —— vault repo 在 GitHub。
provider 托管 LLM没出站代理或中继 —— 没发本地 LLM。
默认 GLM embedding profile —— 切 local（见第 6 步）。
公开 marketplace 技能安装（ADR-017）—— 指向私有 registry。

其他所有东西，包括完整 agent kernel、告警 evaluator、遥测管线、chat UI，完全离线跑。

离线 / 私有化 ​

第 1 步：下 release tarball ​

第 2 步：tarball 安装 ​

第 3 步：镜像到私有 registry（可选） ​

第 4 步：离线网里装 edge ​

第 5 步：LLM provider ​

第 6 步：离线 RAG（embedding 模型） ​

第 7 步：升级 ​

离线不行的 ​